Service Account Identities (OIDC)

📷

Requires an upgraded subscription

This feature is available with our Team and Enterprise plans. View our plans or book a demo for more details.

Identities allow a service account to authenticate to Doppler via OIDC without using a static API token. Any tool that can generate OIDC tokens (e.g., CI tools like GitHub or GitLab) is compatible with Doppler.

Use the service account detail page to configure an identity. Then, utilize the Doppler CLI, API, or GitHub Secrets Fetch Action in order to authenticate via identity auth using an OIDC token generated by your CI tool.

Configure the identity

1. Visit the service account detail page in Doppler
2. Click "new identity" in the Service Account Identities section
3. Select your provider (or provide a custom Discovery URL - you can verify the discovery data by clicking on the generated link below the field)
4. Configure the claims that Doppler will validate in the token signed by your OIDC provider. OIDC auth requests for this identity will validate that all of the claim rules are met.
   1. Avoid wildcards if possible as simpler/exact match rules are simplest to configure and reason about.
   2. Audience and subject claims are required. Additional custom claims can be added as desired (e.g., GitLab provides a custom claim environment).
   3. For each claim field, additional value options can be specified. One option must match for every configured claim in order for an identity auth request to succeed.
   4. Examples of the formats provided for your provider are displayed below the inputs. For example, GitHub has multiple formats for Subject depending on the context (e.g., environment vs pull request). The docs links in the provider section provides further detail.
5. After creating the identity, the identity's ID will be displayed. This is a configuration value, not a secret, that will be utilized during identity authentication.

Authentication with an identity

1. GitHub via the Secrets Fetch Action
   1. Configure your GitHub Action as noted in the Secrets Fetch Action README .
2. Any OIDC provider via the Doppler CLI
   1. Retrieve an OIDC token from your OIDC provider (e.g., $CIRCLE_OIDC_TOKEN_V2 or GitHub's getIDToken()). See the providers OIDC documentation for details (direct links provided from the Service Account Identity edit drawer).
   2. Authenticate via the OIDC token string from your CI provider: doppler oidc login --scope=. --identity=00000000-0000-0000-0000-000000000000 --token=$CIRCLE_OIDC_TOKEN_V2
   3. Use the CLI as desired, for example: doppler secrets --project example --config dev
   4. (Optional) The short lived API token can be revoked when you are finished. This is not necessary, as the tokens expire quickly and you should not persist them. doppler oidc logout --scope=.
3. Any OIDC provider via the Doppler API
   1. Retrieve an OIDC token from your OIDC provider (e.g., $CIRCLE_OIDC_TOKEN_V2 or GitHub's getIDToken()). See the providers OIDC documentation for details (direct links provided from the Service Account Identity edit drawer).
   2. Make a POST request to https://api.doppler.com/v3/auth/oidc with JSON body with the properties identity (Identity ID from the Doppler Dashboard) and token (the OIDC token string from your CI provider).
   3. The response JSON contains tokenwhich is a short lived API token that can be used as a Bearer token when using the Doppler API. The response also contains the expiration date/time expires_at.
   4. (Optional) The short lived API token can be revoked just like other Doppler API tokens when you are finished. This is not typically necessary, as the tokens expire quickly and you should not persist them.