Skip to content

stac_auth_proxy.config

Configuration for the STAC Auth Proxy.

CorsSettings

Bases: BaseModel

CORS configuration settings.

Parameters:

Name Type Description Default
allow_origins Sequence[str]
['*']
allow_methods Sequence[str]
['*']
allow_headers Sequence[str]
['*']
allow_credentials bool
True
expose_headers Sequence[str]
[]
max_age int
600
Source code in src/stac_auth_proxy/config.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
class CorsSettings(BaseModel):
    """CORS configuration settings."""

    allow_origins: Sequence[str] = ["*"]
    allow_methods: Sequence[str] = ["*"]
    allow_headers: Sequence[str] = ["*"]
    allow_credentials: bool = True
    expose_headers: Sequence[str] = []
    max_age: int = 600

    @field_validator(
        "allow_origins",
        "allow_methods",
        "allow_headers",
        "expose_headers",
        mode="before",
    )
    @classmethod
    def parse_list(cls, v) -> Sequence[str] | None:
        """Parse a comma-separated string into a list."""
        if isinstance(v, str):
            return [s.strip() for s in v.split(",") if s.strip()]
        return v

parse_list(v) -> Sequence[str] | None classmethod

Parse a comma-separated string into a list.

Source code in src/stac_auth_proxy/config.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
@field_validator(
    "allow_origins",
    "allow_methods",
    "allow_headers",
    "expose_headers",
    mode="before",
)
@classmethod
def parse_list(cls, v) -> Sequence[str] | None:
    """Parse a comma-separated string into a list."""
    if isinstance(v, str):
        return [s.strip() for s in v.split(",") if s.strip()]
    return v

Settings

Bases: BaseSettings

Configuration settings for the STAC Auth Proxy.

Parameters:

Name Type Description Default
upstream_url HttpUrl
required
oidc_discovery_url HttpUrl
required
oidc_discovery_internal_url HttpUrl
required
allowed_jwt_audiences Sequence[str] | None
None
root_path str
''
root_path_skip_prefixes Sequence[str]
()
override_host bool
True
healthz_prefix str
'/healthz'
upstream_timeout float
15.0
wait_for_upstream bool
True
check_conformance bool
True
enable_compression bool
True
proxy_options bool
False
cors CorsSettings

CORS configuration settings.

 <dynamic>
openapi_spec_endpoint str | None
'/api'
openapi_auth_scheme_name str
'oidcAuth'
openapi_auth_scheme_override dict | None
None
swagger_ui_endpoint str | None
'/api.html'
swagger_ui_init_oauth dict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

 <class 'dict'>
enable_authentication_extension bool
True
default_public bool
False
public_endpoints dict[str, Sequence[Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']]]
{'^/$': ['GET'], '^/api.html$': ['GET'], '^/api$': ['GET'], '^/conformance$': ['GET'], '^/docs/oauth2-redirect': ['GET'], '^/healthz': ['GET'], '^/_mgmt/ping': ['GET'], '^/_mgmt/health': ['GET'], '^/_mgmt/metrics': ['GET']}
private_endpoints dict[str, Sequence[Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'] | tuple[Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], str]]]
{'^/collections$': ['POST'], '^/collections/([^/]+)$': ['PUT', 'PATCH', 'DELETE'], '^/collections/([^/]+)/items$': ['POST'], '^/collections/([^/]+)/items/([^/]+)$': ['PUT', 'PATCH', 'DELETE'], '^/collections/([^/]+)/bulk_items$': ['POST']}
items_filter _ClassInput | None
None
items_filter_path str
'^(/collections/([^/]+)/items(/[^/]+)?$|/search$)'
collections_filter _ClassInput | None
None
collections_filter_path str
'^/collections(/[^/]+)?$'
Source code in src/stac_auth_proxy/config.py 
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
class Settings(BaseSettings):
    """Configuration settings for the STAC Auth Proxy."""

    # External URLs
    upstream_url: HttpUrl
    oidc_discovery_url: HttpUrl
    oidc_discovery_internal_url: HttpUrl
    allowed_jwt_audiences: Optional[Sequence[str]] = None

    root_path: str = ""
    # NoDecode: pydantic-settings JSON-decodes Sequence fields before validators,
    # which rejects the documented comma-separated env form (/raster,/vector).
    root_path_skip_prefixes: Annotated[Sequence[str], NoDecode] = ()
    override_host: bool = True
    healthz_prefix: str = Field(pattern=_PREFIX_PATTERN, default="/healthz")
    upstream_timeout: float = 15.0
    wait_for_upstream: bool = True
    check_conformance: bool = True
    enable_compression: bool = True
    proxy_options: bool = False
    cors: CorsSettings = Field(default_factory=CorsSettings)

    # OpenAPI / Swagger UI
    openapi_spec_endpoint: Optional[str] = Field(
        pattern=_PREFIX_PATTERN, default="/api"
    )
    openapi_auth_scheme_name: str = "oidcAuth"
    openapi_auth_scheme_override: Optional[dict] = None
    swagger_ui_endpoint: Optional[str] = Field(
        pattern=_PREFIX_PATTERN, default="/api.html"
    )
    swagger_ui_init_oauth: dict = Field(default_factory=dict)

    # Auth
    enable_authentication_extension: bool = True
    default_public: bool = False
    public_endpoints: EndpointMethods = {
        r"^/$": ["GET"],
        r"^/api.html$": ["GET"],
        r"^/api$": ["GET"],
        r"^/conformance$": ["GET"],
        r"^/docs/oauth2-redirect": ["GET"],
        r"^/healthz": ["GET"],
        r"^/_mgmt/ping": ["GET"],
        r"^/_mgmt/health": ["GET"],
        r"^/_mgmt/metrics": ["GET"],
    }
    private_endpoints: EndpointMethodsWithScope = {
        # https://github.com/stac-api-extensions/collection-transaction/blob/v1.0.0-beta.1/README.md#methods
        r"^/collections$": ["POST"],
        r"^/collections/([^/]+)$": ["PUT", "PATCH", "DELETE"],
        # https://github.com/stac-api-extensions/transaction/blob/v1.0.0-rc.3/README.md#methods
        r"^/collections/([^/]+)/items$": ["POST"],
        r"^/collections/([^/]+)/items/([^/]+)$": ["PUT", "PATCH", "DELETE"],
        # https://stac-utils.github.io/stac-fastapi/api/stac_fastapi/extensions/third_party/bulk_transactions/#bulktransactionextension
        r"^/collections/([^/]+)/bulk_items$": ["POST"],
    }

    # Filters
    items_filter: Optional[_ClassInput] = None
    items_filter_path: str = r"^(/collections/([^/]+)/items(/[^/]+)?$|/search$)"
    collections_filter: Optional[_ClassInput] = None
    collections_filter_path: str = r"^/collections(/[^/]+)?$"

    model_config = SettingsConfigDict(
        env_nested_delimiter="_",
    )

    @model_validator(mode="before")
    @classmethod
    def _default_oidc_discovery_internal_url(cls, data: Any) -> Any:
        """Set the internal OIDC discovery URL to the public URL if not set."""
        if not data.get("oidc_discovery_internal_url"):
            data["oidc_discovery_internal_url"] = data.get("oidc_discovery_url")
        return data

    @field_validator("allowed_jwt_audiences", mode="before")
    @classmethod
    def parse_audience(cls, v) -> Sequence[str] | None:
        """Parse a comma separated string list of audiences into a list."""
        return str2list(v)

    @field_validator("root_path_skip_prefixes", mode="before")
    @classmethod
    def parse_root_path_skip_prefixes(cls, v) -> Sequence[str]:
        """
        Parse and normalize path prefixes that should not get ``ROOT_PATH`` added.

        Accepts a comma-separated string or sequence. Drops empty entries and
        trailing slashes. Each prefix must start with ``/``. A bare ``/`` is
        rejected because it would match every path.
        """
        values = str2list(v)
        if not values:
            return ()

        prefixes: list[str] = []
        for value in values:
            prefix = value.strip().rstrip("/")
            if not prefix:
                if value.strip():
                    raise ValueError(f"Path prefix {value!r} would match every path")
                continue
            if not prefix.startswith("/"):
                raise ValueError(f"Path prefix {value!r} must start with '/'")
            prefixes.append(prefix)
        return tuple(prefixes)

parse_audience(v) -> Sequence[str] | None classmethod

Parse a comma separated string list of audiences into a list.

Source code in src/stac_auth_proxy/config.py 
148
149
150
151
152
@field_validator("allowed_jwt_audiences", mode="before")
@classmethod
def parse_audience(cls, v) -> Sequence[str] | None:
    """Parse a comma separated string list of audiences into a list."""
    return str2list(v)

parse_root_path_skip_prefixes(v) -> Sequence[str] classmethod

Parse and normalize path prefixes that should not get ROOT_PATH added.

Accepts a comma-separated string or sequence. Drops empty entries and trailing slashes. Each prefix must start with /. A bare / is rejected because it would match every path.

Source code in src/stac_auth_proxy/config.py 
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
@field_validator("root_path_skip_prefixes", mode="before")
@classmethod
def parse_root_path_skip_prefixes(cls, v) -> Sequence[str]:
    """
    Parse and normalize path prefixes that should not get ``ROOT_PATH`` added.

    Accepts a comma-separated string or sequence. Drops empty entries and
    trailing slashes. Each prefix must start with ``/``. A bare ``/`` is
    rejected because it would match every path.
    """
    values = str2list(v)
    if not values:
        return ()

    prefixes: list[str] = []
    for value in values:
        prefix = value.strip().rstrip("/")
        if not prefix:
            if value.strip():
                raise ValueError(f"Path prefix {value!r} would match every path")
            continue
        if not prefix.startswith("/"):
            raise ValueError(f"Path prefix {value!r} must start with '/'")
        prefixes.append(prefix)
    return tuple(prefixes)

str2list(x: str | Sequence[str] | None) -> Sequence[str] | None

Convert string to list based on , delimiter.

Source code in src/stac_auth_proxy/config.py 
20
21
22
23
24
25
26
27
28
def str2list(x: str | Sequence[str] | None) -> Sequence[str] | None:
    """Convert string to list based on , delimiter."""
    if isinstance(x, str):
        if x.startswith("["):
            return json.loads(x)
        else:
            return [s.strip() for s in x.split(",")]

    return x