Skip to content

Commit 8a82d3d

Browse files
alukachalukach
committed
docs(config): cleanup formatting
1 parent a8c1370 commit 8a82d3d

File tree

1 file changed

+92
-90
lines changed

1 file changed

+92
-90
lines changed

‎docs/user-guide/configuration.md‎

Lines changed: 92 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -8,100 +8,102 @@ The application is configurable via environment variables.
88

99
: STAC API URL
1010

11-
**Type:** HTTP(S) URL
12-
**Required:** Yes
13-
**Example:** `https://your-stac-api.com/stac`
11+
- **Type:** HTTP(S) URL
12+
- **Required:** Yes
13+
- **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`
21-
**Example:** `false`, `1`, `True`
19+
- **Type:** boolean
20+
- **Required:** No, defaults to `true`
21+
- **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`
29-
**Example:** `false`, `1`, `True`
27+
- **Type:** boolean
28+
- **Required:** No, defaults to `true`
29+
- **Example:** `false`, `1`, `True`
3030

3131
### `ENABLE_COMPRESSION`
3232

3333
: Enable response compression
3434

35-
**Type:** boolean
36-
**Required:** No, defaults to `true`
37-
**Example:** `false`, `1`, `True`
35+
- **Type:** boolean
36+
- **Required:** No, defaults to `true`
37+
- **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`
45-
**Example:** `''` (disabled)
43+
- **Type:** string
44+
- **Required:** No, defaults to `/healthz`
45+
- **Example:** `''` (disabled)
4646

4747
### `OVERRIDE_HOST`
4848

49-
: Override the host header for the upstream API
49+
: Override the host header before forwarding requests to the upstream API.
50+
51+
- **Type:** boolean
52+
- **Required:** No, defaults to `true`
53+
- **Example:** `false`, `1`, `True`
5054

51-
**Type:** boolean
52-
**Required:** No, defaults to `true`
53-
**Example:** `false`, `1`, `True`
5455

5556
### `ROOT_PATH`
5657

5758
: Path prefix for the proxy API
5859

59-
**Type:** string
60-
**Required:** No, defaults to `''` (root path)
61-
**Example:** `/api/v1`
62-
**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.
60+
- **Type:** string
61+
- **Required:** No, defaults to `''` (root path)
62+
- **Example:** `/api/v1`
63+
64+
> [!NOTE]
65+
> 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.
6366

6467
## Authentication
6568

6669
### `OIDC_DISCOVERY_URL`
6770

6871
: OpenID Connect discovery document URL
6972

70-
**Type:** HTTP(S) URL
71-
**Required:** Yes
72-
**Example:** `https://auth.example.com/.well-known/openid-configuration`
73+
- **Type:** HTTP(S) URL
74+
- **Required:** Yes
75+
- **Example:** `https://auth.example.com/.well-known/openid-configuration`
7376

7477
### `OIDC_DISCOVERY_INTERNAL_URL`
7578

7679
: Internal network OpenID Connect discovery document URL
7780

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

8285
### `ALLOWED_JWT_AUDIENCES`
8386

8487
: Unique identifier(s) of API resource server(s)
8588

86-
**Type:** string
87-
**Required:** No
88-
**Example:** `https://auth.example.audience.1.net,https://auth.example.audience.2.net`
89-
**Note:** A comma-separated list of the intended recipient(s) of the JWT. At least one audience value must match the `aud` (audience) claim present in the incoming JWT. If undefined, the API will not impose a check on the `aud` claim
89+
- **Type:** string
90+
- **Required:** No
91+
- **Example:** `https://auth.example.audience.1.net,https://auth.example.audience.2.net`
9092

9193
### `DEFAULT_PUBLIC`
9294

9395
: Default access policy for endpoints
9496

95-
**Type:** boolean
96-
**Required:** No, defaults to `false`
97-
**Example:** `false`, `1`, `True`
97+
- **Type:** boolean
98+
- **Required:** No, defaults to `false`
99+
- **Example:** `false`, `1`, `True`
98100

99101
### `PRIVATE_ENDPOINTS`
100102

101103
: Endpoints explicitly marked as requiring authentication and possibly scopes
102104

103-
**Type:** JSON object mapping regex patterns to HTTP methods OR tuples of an HTTP method and string representing required scopes
104-
**Required:** No, defaults to the following:
105+
- **Type:** JSON object mapping regex patterns to HTTP methods OR tuples of an HTTP method and string representing required scopes
106+
- **Required:** No, defaults to the following:
105107
```json
106108
{
107109
"^/collections$": ["POST"],
@@ -116,8 +118,8 @@ The application is configurable via environment variables.
116118

117119
: Endpoints explicitly marked as not requiring authentication, used when `DEFAULT_PUBLIC == False`
118120

119-
**Type:** JSON object mapping regex patterns to HTTP methods
120-
**Required:** No, defaults to the following:
121+
- **Type:** JSON object mapping regex patterns to HTTP methods
122+
- **Required:** No, defaults to the following:
121123
```json
122124
{
123125
"^/$": ["GET"],
@@ -133,122 +135,122 @@ The application is configurable via environment variables.
133135

134136
: Enable authentication extension in STAC API responses
135137

136-
**Type:** boolean
137-
**Required:** No, defaults to `true`
138-
**Example:** `false`, `1`, `True`
138+
- **Type:** boolean
139+
- **Required:** No, defaults to `true`
140+
- **Example:** `false`, `1`, `True`
139141

140142
## OpenAPI / Swagger UI
141143

142144
### `OPENAPI_SPEC_ENDPOINT`
143145

144146
: Path of OpenAPI specification, used for augmenting spec response with auth configuration
145147

146-
**Type:** string or null
147-
**Required:** No, defaults to `/api`
148-
**Example:** `''` (disabled)
148+
- **Type:** string or null
149+
- **Required:** No, defaults to `/api`
150+
- **Example:** `''` (disabled)
149151

150152
### `OPENAPI_AUTH_SCHEME_NAME`
151153

152154
: Name of the auth scheme to use in the OpenAPI spec
153155

154-
**Type:** string
155-
**Required:** No, defaults to `oidcAuth`
156-
**Example:** `jwtAuth`
156+
- **Type:** string
157+
- **Required:** No, defaults to `oidcAuth`
158+
- **Example:** `jwtAuth`
157159

158160
### `OPENAPI_AUTH_SCHEME_OVERRIDE`
159161

160162
: Override for the auth scheme in the OpenAPI spec
161163

162-
**Type:** JSON object
163-
**Required:** No, defaults to `null` (disabled)
164-
**Example:**
165-
```json
166-
{
167-
"type": "http",
168-
"scheme": "bearer",
169-
"bearerFormat": "JWT",
170-
"description": "Paste your raw JWT here. This API uses Bearer token authorization.\n"
171-
}
172-
```
164+
- **Type:** JSON object
165+
- **Required:** No, defaults to `null` (disabled)
166+
- **Example:**
167+
```json
168+
{
169+
"type": "http",
170+
"scheme": "bearer",
171+
"bearerFormat": "JWT",
172+
"description": "Paste your raw JWT here. This API uses Bearer token authorization.\n"
173+
}
174+
```
173175

174176
### `SWAGGER_UI_ENDPOINT`
175177

176178
: 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
177179

178-
**Type:** string or null
179-
**Required:** No, defaults to `/api.html`
180-
**Example:** `''` (disabled)
180+
- **Type:** string or null
181+
- **Required:** No, defaults to `/api.html`
182+
- **Example:** `''` (disabled)
181183

182184
### `SWAGGER_UI_INIT_OAUTH`
183185

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

186-
**Type:** JSON object
187-
**Required:** No, defaults to `null` (disabled)
188-
**Example:** `{"clientId": "stac-auth-proxy", "usePkceWithAuthorizationCodeGrant": true}`
188+
- **Type:** JSON object
189+
- **Required:** No, defaults to `null` (disabled)
190+
- **Example:** `{"clientId": "stac-auth-proxy", "usePkceWithAuthorizationCodeGrant": true}`
189191

190192
## Filtering
191193

192194
### `ITEMS_FILTER_CLS`
193195

194196
: CQL2 expression generator for item-level filtering
195197

196-
**Type:** JSON object with class configuration
197-
**Required:** No, defaults to `null` (disabled)
198-
**Example:** `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter`
198+
- **Type:** JSON object with class configuration
199+
- **Required:** No, defaults to `null` (disabled)
200+
- **Example:** `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter`
199201

200202
### `ITEMS_FILTER_ARGS`
201203

202204
: Positional arguments for CQL2 expression generator
203205

204-
**Type:** List of positional arguments used to initialize the class
205-
**Required:** No, defaults to `[]`
206-
**Example:** `["org1"]`
206+
- **Type:** List of positional arguments used to initialize the class
207+
- **Required:** No, defaults to `[]`
208+
- **Example:** `["org1"]`
207209

208210
### `ITEMS_FILTER_KWARGS`
209211

210212
: Keyword arguments for CQL2 expression generator
211213

212-
**Type:** Dictionary of keyword arguments used to initialize the class
213-
**Required:** No, defaults to `{}`
214-
**Example:** `{"field_name": "properties.organization"}`
214+
- **Type:** Dictionary of keyword arguments used to initialize the class
215+
- **Required:** No, defaults to `{}`
216+
- **Example:** `{"field_name": "properties.organization"}`
215217

216218
### `ITEMS_FILTER_PATH`
217219

218220
: Regex pattern used to identify request paths that require the application of the items filter
219221

220-
**Type:** Regex string
221-
**Required:** No, defaults to `^(/collections/([^/]+)/items(/[^/]+)?$|/search$)`
222-
**Example:** `^(/collections/([^/]+)/items(/[^/]+)?$|/search$|/custom$)`
222+
- **Type:** Regex string
223+
- **Required:** No, defaults to `^(/collections/([^/]+)/items(/[^/]+)?$|/search$)`
224+
- **Example:** `^(/collections/([^/]+)/items(/[^/]+)?$|/search$|/custom$)`
223225

224226
### `COLLECTIONS_FILTER_CLS`
225227

226228
: CQL2 expression generator for collection-level filtering
227229

228-
**Type:** JSON object with class configuration
229-
**Required:** No, defaults to `null` (disabled)
230-
**Example:** `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter`
230+
- **Type:** JSON object with class configuration
231+
- **Required:** No, defaults to `null` (disabled)
232+
- **Example:** `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter`
231233

232234
### `COLLECTIONS_FILTER_ARGS`
233235

234236
: Positional arguments for CQL2 expression generator
235237

236-
**Type:** List of positional arguments used to initialize the class
237-
**Required:** No, defaults to `[]`
238-
**Example:** `["org1"]`
238+
- **Type:** List of positional arguments used to initialize the class
239+
- **Required:** No, defaults to `[]`
240+
- **Example:** `["org1"]`
239241

240242
### `COLLECTIONS_FILTER_KWARGS`
241243

242244
: Keyword arguments for CQL2 expression generator
243245

244-
**Type:** Dictionary of keyword arguments used to initialize the class
245-
**Required:** No, defaults to `{}`
246-
**Example:** `{"field_name": "properties.organization"}`
246+
- **Type:** Dictionary of keyword arguments used to initialize the class
247+
- **Required:** No, defaults to `{}`
248+
- **Example:** `{"field_name": "properties.organization"}`
247249

248250
### `COLLECTIONS_FILTER_PATH`
249251

250252
: Regex pattern used to identify request paths that require the application of the collections filter
251253

252-
**Type:** Regex string
253-
**Required:** No, defaults to `^/collections(/[^/]+)?$`
254-
**Example:** `^.*?/collections(/[^/]+)?$`
254+
- **Type:** Regex string
255+
- **Required:** No, defaults to `^/collections(/[^/]+)?$`
256+
- **Example:** `^.*?/collections(/[^/]+)?$`

0 commit comments

Comments
 (0)