Skip to content

Commit aa96681

Browse files
alukachalukach
committed
update docs
1 parent 600c224 commit aa96681

File tree

1 file changed

+60
-58
lines changed

1 file changed

+60
-58
lines changed

‎docs/configuration.md‎

Lines changed: 60 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -8,57 +8,57 @@ The application is configurable via environment variables.
88

99
: STAC API URL
1010

11-
**Type:** HTTP(S) URL
12-
**Required:** Yes
11+
**Type:** HTTP(S) URL
12+
**Required:** Yes
1313
**Example:** `https://your-stac-api.com/stac`
1414

1515
### `WAIT_FOR_UPSTREAM`
1616

1717
: Wait for upstream API to become available before starting proxy
1818

19-
**Type:** boolean
20-
**Required:** No, defaults to `true`
19+
**Type:** boolean
20+
**Required:** No, defaults to `true`
2121
**Example:** `false`, `1`, `True`
2222

2323
### `CHECK_CONFORMANCE`
2424

2525
: Ensure upstream API conforms to required conformance classes before starting proxy
2626

27-
**Type:** boolean
28-
**Required:** No, defaults to `true`
27+
**Type:** boolean
28+
**Required:** No, defaults to `true`
2929
**Example:** `false`, `1`, `True`
3030

3131
### `ENABLE_COMPRESSION`
3232

3333
: Enable response compression
3434

35-
**Type:** boolean
36-
**Required:** No, defaults to `true`
35+
**Type:** boolean
36+
**Required:** No, defaults to `true`
3737
**Example:** `false`, `1`, `True`
3838

3939
### `HEALTHZ_PREFIX`
4040

4141
: Path prefix for health check endpoints
4242

43-
**Type:** string
44-
**Required:** No, defaults to `/healthz`
43+
**Type:** string
44+
**Required:** No, defaults to `/healthz`
4545
**Example:** `''` (disabled)
4646

4747
### `OVERRIDE_HOST`
4848

4949
: Override the host header for the upstream API
5050

51-
**Type:** boolean
52-
**Required:** No, defaults to `true`
51+
**Type:** boolean
52+
**Required:** No, defaults to `true`
5353
**Example:** `false`, `1`, `True`
5454

5555
### `ROOT_PATH`
5656

5757
: Path prefix for the proxy API
5858

59-
**Type:** string
60-
**Required:** No, defaults to `''` (root path)
61-
**Example:** `/api/v1`
59+
**Type:** string
60+
**Required:** No, defaults to `''` (root path)
61+
**Example:** `/api/v1`
6262
**Note:** This is independent of the upstream API's path. The proxy will handle removing this prefix from incoming requests and adding it to outgoing links.
6363

6464
## Authentication
@@ -67,31 +67,31 @@ The application is configurable via environment variables.
6767

6868
: OpenID Connect discovery document URL
6969

70-
**Type:** HTTP(S) URL
71-
**Required:** Yes
70+
**Type:** HTTP(S) URL
71+
**Required:** Yes
7272
**Example:** `https://auth.example.com/.well-known/openid-configuration`
7373

7474
### `OIDC_DISCOVERY_INTERNAL_URL`
7575

7676
: Internal network OpenID Connect discovery document URL
7777

78-
**Type:** HTTP(S) URL
79-
**Required:** No, defaults to the value of `OIDC_DISCOVERY_URL`
78+
**Type:** HTTP(S) URL
79+
**Required:** No, defaults to the value of `OIDC_DISCOVERY_URL`
8080
**Example:** `http://auth/.well-known/openid-configuration`
8181

8282
### `DEFAULT_PUBLIC`
8383

8484
: Default access policy for endpoints
8585

86-
**Type:** boolean
87-
**Required:** No, defaults to `false`
86+
**Type:** boolean
87+
**Required:** No, defaults to `false`
8888
**Example:** `false`, `1`, `True`
8989

9090
### `PRIVATE_ENDPOINTS`
9191

9292
: Endpoints explicitly marked as requiring authentication and possibly scopes
9393

94-
**Type:** JSON object mapping regex patterns to HTTP methods OR tuples of an HTTP method and string representing required scopes
94+
**Type:** JSON object mapping regex patterns to HTTP methods OR tuples of an HTTP method and string representing required scopes
9595
**Required:** No, defaults to the following:
9696
```json
9797
{
@@ -107,12 +107,14 @@ The application is configurable via environment variables.
107107

108108
: Endpoints explicitly marked as not requiring authentication, used when `DEFAULT_PUBLIC == False`
109109

110-
**Type:** JSON object mapping regex patterns to HTTP methods
110+
**Type:** JSON object mapping regex patterns to HTTP methods
111111
**Required:** No, defaults to the following:
112112
```json
113113
{
114+
"^/$": ["GET"],
114115
"^/api.html$": ["GET"],
115116
"^/api$": ["GET"],
117+
"^/conformance$": ["GET"],
116118
"^/docs/oauth2-redirect": ["GET"],
117119
"^/healthz": ["GET"]
118120
}
@@ -122,8 +124,8 @@ The application is configurable via environment variables.
122124

123125
: Enable authentication extension in STAC API responses
124126

125-
**Type:** boolean
126-
**Required:** No, defaults to `true`
127+
**Type:** boolean
128+
**Required:** No, defaults to `true`
127129
**Example:** `false`, `1`, `True`
128130

129131
## OpenAPI / Swagger UI
@@ -132,30 +134,30 @@ The application is configurable via environment variables.
132134

133135
: Path of OpenAPI specification, used for augmenting spec response with auth configuration
134136

135-
**Type:** string or null
136-
**Required:** No, defaults to `null` (disabled)
137-
**Example:** `/api`
137+
**Type:** string or null
138+
**Required:** No, defaults to `/api`
139+
**Example:** `''` (disabled)
138140

139141
### `OPENAPI_AUTH_SCHEME_NAME`
140142

141143
: Name of the auth scheme to use in the OpenAPI spec
142144

143-
**Type:** string
144-
**Required:** No, defaults to `oidcAuth`
145+
**Type:** string
146+
**Required:** No, defaults to `oidcAuth`
145147
**Example:** `jwtAuth`
146148

147149
### `OPENAPI_AUTH_SCHEME_OVERRIDE`
148150

149151
: Override for the auth scheme in the OpenAPI spec
150152

151-
**Type:** JSON object
152-
**Required:** No, defaults to `null` (disabled)
153-
**Example:**
153+
**Type:** JSON object
154+
**Required:** No, defaults to `null` (disabled)
155+
**Example:**
154156
```json
155157
{
156-
"type": "http",
157-
"scheme": "bearer",
158-
"bearerFormat": "JWT",
158+
"type": "http",
159+
"scheme": "bearer",
160+
"bearerFormat": "JWT",
159161
"description": "Paste your raw JWT here. This API uses Bearer token authorization.\n"
160162
}
161163
```
@@ -164,16 +166,16 @@ The application is configurable via environment variables.
164166

165167
: Path of Swagger UI, used to indicate that a custom Swagger UI should be hosted, typically useful when providing accompanying `SWAGGER_UI_INIT_OAUTH` arguments
166168

167-
**Type:** string or null
168-
**Required:** No, defaults to `null` (disabled)
169-
**Example:** `/api.html`
169+
**Type:** string or null
170+
**Required:** No, defaults to `/api.html`
171+
**Example:** `''` (disabled)
170172

171173
### `SWAGGER_UI_INIT_OAUTH`
172174

173175
: Initialization options for the [Swagger UI OAuth2 configuration](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/) on custom Swagger UI
174176

175-
**Type:** JSON object
176-
**Required:** No, defaults to `null` (disabled)
177+
**Type:** JSON object
178+
**Required:** No, defaults to `null` (disabled)
177179
**Example:** `{"clientId": "stac-auth-proxy", "usePkceWithAuthorizationCodeGrant": true}`
178180

179181
## Filtering
@@ -182,62 +184,62 @@ The application is configurable via environment variables.
182184

183185
: CQL2 expression generator for item-level filtering
184186

185-
**Type:** JSON object with class configuration
186-
**Required:** No, defaults to `null` (disabled)
187+
**Type:** JSON object with class configuration
188+
**Required:** No, defaults to `null` (disabled)
187189
**Example:** `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter`
188190

189191
### `ITEMS_FILTER_ARGS`
190192

191193
: Positional arguments for CQL2 expression generator
192194

193-
**Type:** List of positional arguments used to initialize the class
194-
**Required:** No, defaults to `[]`
195+
**Type:** List of positional arguments used to initialize the class
196+
**Required:** No, defaults to `[]`
195197
**Example:** `["org1"]`
196198

197199
### `ITEMS_FILTER_KWARGS`
198200

199201
: Keyword arguments for CQL2 expression generator
200202

201-
**Type:** Dictionary of keyword arguments used to initialize the class
202-
**Required:** No, defaults to `{}`
203+
**Type:** Dictionary of keyword arguments used to initialize the class
204+
**Required:** No, defaults to `{}`
203205
**Example:** `{"field_name": "properties.organization"}`
204206

205207
### `ITEMS_FILTER_PATH`
206208

207209
: Regex pattern used to identify request paths that require the application of the items filter
208210

209-
**Type:** Regex string
210-
**Required:** No, defaults to `^(/collections/([^/]+)/items(/[^/]+)?$|/search$)`
211+
**Type:** Regex string
212+
**Required:** No, defaults to `^(/collections/([^/]+)/items(/[^/]+)?$|/search$)`
211213
**Example:** `^(/collections/([^/]+)/items(/[^/]+)?$|/search$|/custom$)`
212214

213215
### `COLLECTIONS_FILTER_CLS`
214216

215217
: CQL2 expression generator for collection-level filtering
216218

217-
**Type:** JSON object with class configuration
218-
**Required:** No, defaults to `null` (disabled)
219+
**Type:** JSON object with class configuration
220+
**Required:** No, defaults to `null` (disabled)
219221
**Example:** `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter`
220222

221223
### `COLLECTIONS_FILTER_ARGS`
222224

223225
: Positional arguments for CQL2 expression generator
224226

225-
**Type:** List of positional arguments used to initialize the class
226-
**Required:** No, defaults to `[]`
227+
**Type:** List of positional arguments used to initialize the class
228+
**Required:** No, defaults to `[]`
227229
**Example:** `["org1"]`
228230

229231
### `COLLECTIONS_FILTER_KWARGS`
230232

231233
: Keyword arguments for CQL2 expression generator
232234

233-
**Type:** Dictionary of keyword arguments used to initialize the class
234-
**Required:** No, defaults to `{}`
235+
**Type:** Dictionary of keyword arguments used to initialize the class
236+
**Required:** No, defaults to `{}`
235237
**Example:** `{"field_name": "properties.organization"}`
236238

237239
### `COLLECTIONS_FILTER_PATH`
238240

239241
: Regex pattern used to identify request paths that require the application of the collections filter
240242

241-
**Type:** Regex string
242-
**Required:** No, defaults to `^/collections(/[^/]+)?$`
243-
**Example:** `^.*?/collections(/[^/]+)?$`
243+
**Type:** Regex string
244+
**Required:** No, defaults to `^/collections(/[^/]+)?$`
245+
**Example:** `^.*?/collections(/[^/]+)?$`

0 commit comments

Comments
 (0)