Documentation
SupportStatusCommunitySign Up
Start typing to search…

GitHub OIDC Examples

Examples of different ways to use OIDC with GitHub

Customizing your GitHub OIDC subject claim

📘

You'll need a GitHub API token with read/write access on the Actions repository permission for this step. Replace any references to $GH_TOKEN with this token.

GitHub supports a variety of potential subject claims you can use. By default, GitHub only includes the repository claim (which is shortened to repo in the sub field itself). If you want to take advantage of additional claims, then you need to set the customization template via API. The short version of this is that you can fetch the existing template for a particular repo (it can also be set at the organization level, but we'll just show the repo variant here). Be sure to replace any occurrences of $OWNER and $REPO with the org/user name and repo name respectively.

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  --url "https://api.github.com/repos/$OWNER/$REPO/actions/oidc/customization/sub"

If you haven't modified it yet, then it'll probably look like this:

{
  "use_default": true
}

To set a custom template, you set use_default to false and pass in an include_claim_keys array:

curl -L \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  --url "https://api.github.com/repos/$OWNER/$REPO/actions/oidc/customization/sub" \
  -d '{"use_default":false,"include_claim_keys":["repository","event_name"]}'

Include the subject claims you want included in the sub field of the OIDC JWT token that GitHub generates. This is then used by Doppler to verify that authorization should be granted to a Service Account Identity. Note that if this request is successful you get an empty response (e.g., { }) from GitHub's API. You can verify it worked by using the earlier fetch request above.

🚧

If you're getting 404 Not Found responses from GitHub's API when executing the above commands, then double-check that the GitHub access token you're using has access to the repository you're referencing in the API call. If the token doesn't have access GitHub will just respond with a 404.

Configuring Doppler Service Account Identity


Using OIDC authentication

There are a couple different methods you can use OIDC authentication with Doppler. In all cases, the operation must happen from inside your GitHub Action workflow (i.e., the curl commands below will not work if run locally). In most cases, using the Doppler Secrets Fetch Action is recommended.

📘

In the examples below, we've stored the Doppler Service Account Identity ID as a GitHub Action variable that's then accessed with ${{ vars.DOPPLER_SERVICE_IDENTITY_ID }}.

Doppler Secrets Fetch Action (recommended)

👍

This method is recommended due to both ease of use and also because the Secrets Fetch action automatically masks the secrets it fetches intelligently (the DOPPLER_* managed secrets along with any secrets with the unmasked Doppler secret visibility are left unmasked in GitHub).

You can use Doppler's official Secrets Fetch action in your GitHub Action workflow in conjunction with OIDC to fetch secrets without having to store a static Doppler token in your GitHub Action secrets. To do that, make sure your workflow has the id-token: write permission (which is required to fetch the GitHub provided OIDC token) and then add a step in your workflow like this:

- uses: dopplerhq/[email protected]
  id: doppler
  with:
    auth-method: oidc        
    doppler-identity-id: ${{ vars.DOPPLER_SERVICE_IDENTITY_ID }}
    doppler-project: <your-project-name>
    doppler-config: <your-config-name>
    # optionally you can have the secrets injected as environment variables.
    # you can also access secrets that are fetched via the step outputs using
    # something like ${{ steps.doppler.outputs.DOPPLER_PROJECT }}
    inject-env-vars: true

Here's an example workflow showing how you might use this:

name: OIDC Fetch Action Test

on: workflow_dispatch

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required to request an OIDC token
    steps:
      - uses: dopplerhq/[email protected]
        id: doppler
        with:
          auth-method: oidc        
          doppler-identity-id: ${{ vars.DOPPLER_SERVICE_IDENTITY_ID }}
          doppler-project: <your-project-name>
          doppler-config: <your-config-name>
          inject-env-vars: true 
      - name: Fetch secrets
        run: printenv | grep DOPPLER

Using the Doppler CLI

🚧

Note that any secrets you fetch using this method are not automatically masked, so if they're printed in output, they'll show up in plain text. You can find information on how to manually mask values in GitHub Action workflows here.

From within a GitHub Action workflow, you can use Doppler via an OIDC token by using the special ACTIONS_ID_TOKEN_REQUEST_TOKEN and ACTIONS_ID_TOKEN_REQUEST_URL environment variables GitHub automatically injects into every GitHub Action workflow.

Use the temporary request token GitHub provides to fetch a GitHub OIDC token:

TOKEN=$(curl -s -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
  --url "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=https://github.com/$OWNER")

You can then use jq to pull out the actual OIDC token:

OIDC_TOKEN=$(echo $TOKEN | jq -r '.value')

From there, you would authenticate the Doppler CLI in your GitHub Action workflow using a command like this:

doppler oidc login --scope=. --identity=${{ vars.DOPPLER_SERVICE_IDENTITY_ID }} --token=$OIDC_TOKEN

Here's an example workflow to show how it would all come together:

name: OIDC CLI Test

on: workflow_dispatch

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required to request an OIDC token
    steps:
      - name: Get OIDC token
        id: get_token
        run: |
          TOKEN=$(curl -s -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
                       "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=https://github.com/$GITHUB_REPOSITORY_OWNER")
          echo "OIDC_TOKEN=$(echo $TOKEN | jq -r '.value')" >> $GITHUB_ENV
      - name: Install Doppler CLI
        uses: dopplerhq/cli-action@v3
      - name: Login with OIDC token
        run: doppler oidc login --scope=. --identity=${{ vars.DOPPLER_SERVICE_IDENTITY_ID }} --token=$OIDC_TOKEN
      - name: Fetch secrets
        run: doppler run -p example -c dev -- printenv | grep DOPPLER

Updated 2 days ago