OIDC

Using OIDC tokens allows your CI jobs to authenticate with emulator.wtf without having to use API tokens via secrets in your CI config. Instead of an API token a temporary signed OIDC token is created instead by your CI provider (GitHub, CircleCI, etc). This reduces key exfiltration and misconfiguration risk and removes the need for API token rotation.

To enable OIDC, you’ll need owner level access to emulator.wtf and create a new configuration on the OIDC configurations page. Note down the OIDC configuration ID value, you’ll need this later when setting up your CI configuration. Depending on the CI provider you can limit access to emulator.wtf to specific accounts, repositories or branches.

Info

Currently, only OIDC tokens provided by GitHub Actions are supported. We’re working on adding additional OIDC integrations in the near future

GitHub

To use an OIDC configuration in GitHub you’ll need to use the emulator-wtf/configure-credentials@v1 GitHub action.

The action needs id-token: write permission to generate the OIDC token. If you previously had no permissions: section in your workflow file at all you’ll probably also want to add the contents: read permission, otherwise repository checkout will fail.

With the permission set, invoke the action with the oidc-configuration-id you got when creating the OIDC configuration in emulator.wtf UI:

- uses: emulator-wtf/configure-credentials@v1
  with:
    oidc-configuration-id: **OIDC-CONFIGURATION-ID-GOES-HERE**

After invoking that action a temporarily valid EW_API_TOKEN will be set and you’ll be able to use ew-cli, the emulator.wtf Gradle plugin or our GitHub actions without having to explicitly set the token.

A full example GitHub workflow using OIDC with emulator.wtf:

name: Test workflow
permissions:
  contents: read
  id-token: write
on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v5
    - uses: actions/setup-java@v5
      with:
        distribution: 'zulu'
        java-version: '24'
    - uses: emulator-wtf/configure-credentials@v1
      with:
        oidc-configuration-id: **OIDC-CONFIGURATION-ID-GOES-HERE**
    - run: ./gradlew testWithEmulatorWtf

Info

Why is there an OIDC configuration ID and is it considered secret?

By providing emulator.wtf an OIDC configuration ID at authentication time you prove the ownership of the repository and the associated CI job.

We don’t consider the OIDC configuration ID as a secret, but it still might be prudent to use your CI provider’s secrets facility to configure it. We definitely don’t recommend checking it in together with the code itself. It’s better to use CI parameters or environment variables if not outright secrets here for additional flexibility.

If you are missing a CI provider here, have any issues or questions, let us know at support@emulator.wtf.