> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withrelic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OIDC Trust Policies

> Secure your CI/CD pipelines with OIDC identity verification on top of service accounts.

OIDC trust policies add identity verification to service accounts. When configured, a service account only works when the request includes a valid OIDC token from a trusted CI/CD provider. Even if the service token leaks, it's useless outside the trusted environment.

## How It Works

1. You create a service account with an OIDC policy (or add one later via the dashboard)
2. The policy specifies which CI provider and identity can use this service account
3. At runtime, the CLI auto-detects the OIDC token from the CI environment
4. The server validates both the service token AND the OIDC token before returning secrets

Neither credential is sufficient alone — the service token handles decryption, the OIDC token proves identity.

## Setup

### GitHub Actions

<Steps>
  <Step title="Create a service account with OIDC">
    ```bash theme={null}
    relic service-account create \
      --name "github-deploy" \
      --github your-org/your-repo \
      --branch main
    ```

    Omit `--branch` to allow all branches. Store the service token in your repository's secrets as `RELIC_SERVICE_TOKEN`.
  </Step>

  <Step title="Add permissions to your workflow">
    Your GitHub Actions workflow needs `id-token: write` permission:

    ```yaml theme={null}
    permissions:
      id-token: write
      contents: read
    ```
  </Step>

  <Step title="Run with secrets">
    ```yaml theme={null}
    - name: Deploy with secrets
      env:
        RELIC_SERVICE_TOKEN: ${{ secrets.RELIC_SERVICE_TOKEN }}
      run: relic run -e production -- npm run deploy
    ```

    The OIDC token is auto-detected and sent with the request.
  </Step>
</Steps>

### GitLab CI

<Steps>
  <Step title="Create a service account with OIDC">
    ```bash theme={null}
    relic service-account create \
      --name "gitlab-deploy" \
      --gitlab your-group/your-project \
      --branch main
    ```
  </Step>

  <Step title="Add id_tokens to your CI config">
    ```yaml theme={null}
    deploy:
      stage: deploy
      id_tokens:
        RELIC_OIDC_TOKEN:
          aud: relic
      script:
        - relic run -e production -- npm run deploy
      variables:
        RELIC_SERVICE_TOKEN: $RELIC_SERVICE_TOKEN
    ```
  </Step>
</Steps>

### Other Providers

For CI providers that support OIDC but aren't auto-detected, set the `RELIC_OIDC_TOKEN` environment variable manually:

```yaml theme={null}
env:
  RELIC_SERVICE_TOKEN: ${{ secrets.RELIC_SERVICE_TOKEN }}
  RELIC_OIDC_TOKEN: ${{ steps.get-token.outputs.token }}
```

## Managing OIDC Policies

### Add via CLI (at creation time)

```bash theme={null}
relic service-account create --name "deploy" --github myorg/myrepo --branch main
```

Or for GitLab:

```bash theme={null}
relic service-account create --name "deploy" --gitlab mygroup/myproject --branch main
```

### Add or update via dashboard

OIDC policies can be configured from the web dashboard without re-creating the service account. Navigate to your project's service accounts, click "Add OIDC" or "Edit OIDC", select the provider, and enter your organization, repository, and branch.

### Remove OIDC policy

To remove an OIDC policy and fall back to token-only authentication, click "Remove" in the OIDC dialog on the dashboard.

## Subject Patterns

Subject patterns control which CI identities can use the service account.

| Pattern | Matches |
| - | - |
| `repo:org/repo:ref:refs/heads/main` | Exact match — only main branch |
| `repo:org/repo:*` | Any branch or event in the repo |
| `repo:org/*:ref:refs/heads/main` | Main branch of any repo in the org |

## Auto-Detection

The CLI automatically detects OIDC tokens in supported environments:

| Provider | Detection Method |
| - | - |
| GitHub Actions | Requests token via `ACTIONS_ID_TOKEN_REQUEST_URL` |
| GitLab CI | Reads `CI_JOB_JWT_V2` or `RELIC_OIDC_TOKEN` |
| Other | Reads `RELIC_OIDC_TOKEN` environment variable |

## Security Model

* **Service token alone**: authenticates + decrypts (works without OIDC)
* **Service token + OIDC**: authenticates via both, decrypts with token. If OIDC is configured, both are required.
* **OIDC token alone**: not sufficient — the token is for identity only, not decryption

This preserves Relic's end-to-end encryption while adding CI identity verification. The server never sees your secrets in plaintext.

<Warning>
  OIDC doesn't eliminate the need for `RELIC_SERVICE_TOKEN`. The token is still required for
  client-side decryption. OIDC adds a second authentication factor that proves the request comes
  from a trusted CI environment.
</Warning>

## Comparison

| Setup | Env vars needed | Identity verified | E2E encrypted |
| - | - | - | - |
| API key (legacy) | `RELIC_API_KEY` + `RELIC_PASSWORD` | No | Yes |
| Service token only | `RELIC_SERVICE_TOKEN` | No | Yes |
| Service token + OIDC | `RELIC_SERVICE_TOKEN` | Yes | Yes |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.