Skip to content

docs: updated docs for backend envs #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JanssenBrm merged 1 commit into from
Jan 21, 2026
Merged

docs: updated docs for backend envs #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion app/config/settings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ def load_backends_auth_config(self):
if not getattr(backend, field, None):
raise ValueError(
f"Backend '{host}' must define '{field}' when "
f"OPENEO_AUTH_METHOD={backend.auth_method}"
f"AUTH_METHOD={backend.auth_method}"
)
self.backend_auth_config[host] = BackendAuthConfig(**cfg)
except Exception:
Expand Down
51 changes: 24 additions & 27 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,26 @@
The Dispatcher can be configured using environment variables. These variables can be set directly in your shell or defined in a `.env` file for convenience.
Below are the key settings that can be adjusted to tailor the Dispatcher's behavior to your needs.

| Environment Variable | Description | Values | Default Value |
| ------------------------ | ----------------------------------------------------------- | ----------------------------------------- | ------------------ |
| **General Settings** | | | |
| `APP_NAME` | The name of the application. | Text | APEx Dispatch API |
| `APP_DESCRIPTION` | A brief description of the application. | Text | "" |
| `APP_ENV` | The environment in which the application is running | `development` / `production` | development |
| `CORS_ALLOWED_ORIGINS` | Comma-separated list of allowed origins for CORS. | Text | "" |
| **Database Settings**|||
| `DATABASE_URL` | The database connection URL. | Text | "" |
| **Keycloak Settings** | | | |
| `KEYCLOAK_HOST` | The hostname of the Keycloak server. | Text | localhost |
| `KEYCLOAK_REALM` | The Keycloak realm to use for authentication. | Text | "" |
| `KEYCLOAK_CLIENT_ID` | The client ID registered in Keycloak. | Text | "" |
| `KEYCLOAK_CLIENT_SECRET` | The client secret for the Keycloak client. | Text | "" |
| **openEO Settings** | | | |
| `OPENEO_AUTH_METHOD` | The authentication method to use for openEO backends. | `USER_CREDENTIALS` / `CLIENT_CREDENTIALS` | `USER_CREDENTIALS` |
| `OPENEO_BACKEND_CONFIG` | JSON string defining the configuration for openEO backends. | JSON | `{}` |
| Environment Variable | Description | Values | Default Value |
| ------------------------ | ------------------------------------------------------------------ | ----------------------------- | ----------------- |
| **General Settings** | | | |
| `APP_NAME` | The name of the application. | Text | APEx Dispatch API |
| `APP_DESCRIPTION` | A brief description of the application. | Text | "" |
| `APP_ENV` | The environment in which the application is running | `development` / `production` | development |
| `CORS_ALLOWED_ORIGINS` | Comma-separated list of allowed origins for CORS. | Text | "" |
| **Database Settings** | | | |
| `DATABASE_URL` | The database connection URL. | Text | "" |
| **Keycloak Settings** | | | |
| `KEYCLOAK_HOST` | The hostname of the Keycloak server. | Text | localhost |
| `KEYCLOAK_REALM` | The Keycloak realm to use for authentication. | Text | "" |
| `KEYCLOAK_CLIENT_ID` | The client ID registered in Keycloak. | Text | "" |
| `KEYCLOAK_CLIENT_SECRET` | The client secret for the Keycloak client. | Text | "" |
| **Backend Settings** | | | |
| `BACKENDS` | JSON string defining the configuration for the supported backends. | JSON | `{}` |


## openEO Backend Configuration
The `OPENEO_BACKEND_CONFIG` environment variable allows you to specify the configuration for multiple openEO backends in JSON format.
## Backend Configuration
The `BACKENDS` environment variable allows you to specify the configuration for multiple backends, to support within the Dispatcher API in JSON format.
Here is an example of how to structure this configuration:

```json
Expand All @@ -39,12 +38,12 @@ Here is an example of how to structure this configuration:
...
}
```
Each backend configuration can include the following fields:
Each backend is configured by including a new key based on the backend URL. For each provided URL, the specific backend configuration can include the following fields:

- `auth_method`: The authentication method to use for the openEO backend. This value can either be `USER_CREDENTIALS` or `CLIENT_CREDENTIALS`. The default value is set to `USER_CREDENTIALS`.
- `client_credentials`: The client credentials for authenticating with the openEO backend. This is required if the `OPENEO_AUTH_METHOD` is set to `CLIENT_CREDENTIALS`. It is a single string in the format `oidc_provider/client_id/client_secret` that should be split into its components when used.
- `token_provider`: The provider refers to the OIDC IDP alias that needs to be used to exchange the incoming token to an external token. This is required if the `OPENEO_AUTH_METHOD` is set to `USER_CREDENTIALS`. For example, if you have a Keycloak setup with an IDP alias `openeo-idp`, you would set this field to `openeo-idp`. This means that when a user authenticates with their token, the Dispatcher will use the `openeo-idp` to exchange the user's token for a token that is valid for the openEO backend.
- `token_prefix`: An optional prefix to be added to the token when authenticating (e.g., "CDSE"). The prefix is required by some backends to identify the token type. This will be prepended to the exchanged token when authenticating with the openEO backend.
- `auth_method`: The authentication method to use for the backend. This value can either be `USER_CREDENTIALS` or `CLIENT_CREDENTIALS`. The default value is set to `USER_CREDENTIALS`.
- `client_credentials`: The client credentials for authenticating with the backend. This is required if the `auth_method` is set to `CLIENT_CREDENTIALS`. It is a single string in the format `oidc_provider/client_id/client_secret` that should be split into its components when used.
- `token_provider`: The provider refers to the OIDC IDP alias that needs to be used to exchange the incoming token to an external token. This is required if the `auth_method` is set to `USER_CREDENTIALS`. For example, if you have a Keycloak setup with an IDP alias `backend-idp`, you would set this field to `backend-idp`. This means that when a user authenticates with their token, the Dispatcher will use the `backend-idp` to exchange the user's token for a token that is valid for the corresponding backend.
- `token_prefix`: An optional prefix to be added to the token when authenticating (e.g., "CDSE"). The prefix is required by some backends to identify the token type. This will be prepended to the exchanged token when authenticating with the backend.

## Example Configuration
Here is an example of setting the environment variables in a `.env` file:
Expand All @@ -67,7 +66,5 @@ KEYCLOAK_CLIENT_ID=apex-client-id
KEYCLOAK_CLIENT_SECRET=apex-client-secret


# openEO Settings
OPENEO_AUTH_METHOD=USER_CREDENTIALS
OPENEO_BACKENDS='{"https://openeo.backend1.com" {"auth_method": "CLIENT_CREDENTIALS", "client_credentials": "oidc_provider/client_id/secret_secret"}, "https://openeo.backend2.com" {"auth_method": "USER_CREDENTIALS", "token_provider": "backend", "token_prefix": "oidc/backend"}}'
BACKENDS='{"https://openeo.backend1.com" {"auth_method": "CLIENT_CREDENTIALS", "client_credentials": "oidc_provider/client_id/secret_secret"}, "https://openeo.backend2.com" {"auth_method": "USER_CREDENTIALS", "token_provider": "backend", "token_prefix": "oidc/backend"}}'
```