diff --git a/docs/docs/deployment-self-hosting/core-configuration/environment-variables.md b/docs/docs/deployment-self-hosting/core-configuration/environment-variables.md index b411b447b4ec..4eab085eafb3 100644 --- a/docs/docs/deployment-self-hosting/core-configuration/environment-variables.md +++ b/docs/docs/deployment-self-hosting/core-configuration/environment-variables.md @@ -38,6 +38,9 @@ relevant section below for more details. - `ORGANISATION_NAME`: Organisation name to use for the default organisation. - `PROJECT_NAME`: Project name to use for the default project. - `ENABLE_GZIP_COMPRESSION`: If Django should gzip compress HTTP responses. Defaults to `False`. +- `TRUST_RELATIONSHIP_ACCESS_TOKEN_LIFETIME_SECONDS`: Lifetime of access tokens minted by the OIDC trust relationship + token exchange. Defaults to `3600`. +- `OIDC_TOKEN_EXCHANGE_THROTTLE_RATE`: Rate limit for the OIDC token exchange endpoint. Defaults to `60/min`. - `GOOGLE_ANALYTICS_KEY`: If Google Analytics is required, add your tracking code. - `GOOGLE_SERVICE_ACCOUNT`: Service account JSON for accessing the Google API, used for getting usage of an organisation - needs access to analytics.readonly scope. diff --git a/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/authentication.md b/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/authentication.md index b3c0fa25b865..e9e137bd3628 100644 --- a/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/authentication.md +++ b/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/authentication.md @@ -3,26 +3,96 @@ title: Authentication sidebar_label: Authentication --- -To interact with the Admin API, you need to authenticate your requests using an API Token associated with your Organisation. +To interact with the Admin API, you need to authenticate your requests using an API Token associated with your +Organisation, or a short-lived access token obtained through an [OIDC trust relationship](#oidc-trust-relationships). ## Generating an API Token You can generate an API Token from the **Organisation Settings** page in the Flagsmith dashboard. -1. Click on your Organisation name in the top navigation panel. -2. Go to the **API Keys** tab. -3. Click **Create API Key**. +1. Click on your Organisation name in the top navigation panel. +2. Go to the **API Access** tab. +3. Click **Create API Key**. Give your key a descriptive name so you can remember what it's used for. ## Using the API Token -Once you have your token, you need to include it in your API requests as an `Authorization` header. The token should be prefixed with `Api-Key`. +Once you have your token, you need to include it in your API requests as an `Authorization` header. The token should be +prefixed with `Api-Key`. ```bash Authorization: Api-Key ``` -This token grants access to manage all projects within that organisation, so be sure to keep it secure and never expose it in client-side applications. +This token grants access to manage all projects within that organisation, so be sure to keep it secure and never expose +it in client-side applications. -For SaaS customers, the base URL for the Admin API is `https://api.flagsmith.com/`. If you are self-hosting, you will need to use your own API URL. \ No newline at end of file +For SaaS customers, the base URL for the Admin API is `https://api.flagsmith.com/`. If you are self-hosting, you will +need to use your own API URL. + +## OIDC trust relationships + +Trust relationships let a workload that already has an OIDC identity — for example, a GitHub Actions job — call the +Admin API without any stored secrets. The workload exchanges its OIDC token for a short-lived Flagsmith access token, in +the same way cloud providers implement workload identity federation. + +### Configuring a trust relationship + +1. Click on your Organisation name in the top navigation panel. +2. Go to the **API Access** tab. +3. Under **Trust relationships**, click **Add trust relationship** and pick a provider. + +#### GitHub Actions + +The GitHub Actions form only asks for a repository and, optionally, a GitHub environment: + +- **Repository**: with the Flagsmith GitHub integration installed, pick the repository from a list — the trust + relationship then pins the repository's immutable ID, which is robust against renames. Without the integration, type + the owner and name, which are matched against the token's `repository` claim. +- **GitHub environment**: if set, tokens must carry the matching `environment` claim, so the workflow job must run in + that GitHub environment. +- **Is admin / roles**: the permissions granted to exchanged tokens — either full organisation admin, or a set of RBAC + roles, exactly as with Master API Keys. + +The form shows a ready-made workflow snippet reflecting your configuration. + +#### Other OIDC providers + +The freeform option supports any OIDC identity provider, such as GitLab CI or Kubernetes: + +- **Trusted issuer URL**: the OIDC issuer. The issuer must serve OIDC discovery metadata over HTTPS. +- **Expected audience**: the `aud` claim the token must carry. Each issuer and audience pair must be unique, so use a + distinct audience per trust relationship. +- **Claim matching rules**: additional claims the token must match. Values support `*` wildcards, and a rule matches if + any of its values match. All rules must match. +- **Is admin / roles**: as above. + +### Exchanging a token + +`POST /api/v1/auth/oidc/token/` with the OIDC token in the request body: + +```bash +curl -X POST 'https://api.flagsmith.com/api/v1/auth/oidc/token/' \ + -H 'Content-Type: application/json' \ + -d '{"token": ""}' +``` + +A successful exchange returns a short-lived access token: + +```json +{ + "access_token": "", + "token_type": "Bearer", + "expires_in": 3600 +} +``` + +Use it as a bearer token on Admin API requests: + +```bash +Authorization: Bearer +``` + +Access tokens expire after one hour by default. Deleting a trust relationship, or changing its roles, applies to +already-issued tokens immediately. Exchanged tokens cannot manage API keys or trust relationships.