Skip to content

Federated Credentials

Let CI/CD pipelines and automation sign in to Arcane with short-lived OIDC tokens instead of long-lived API keys.

CI jobs exchange their platform’s OIDC token for a short-lived Arcane token. The pipeline needs no Arcane password or API key.

  1. Go to System → Authentication → Federated Credentials.
  2. Select Create Federated Credential.
  3. Fill in the fields below. For issuer and subject values, see Subject formats by provider.
  4. Turn Enabled on. New credentials start off.
  5. Save.

Arcane checks each incoming token’s signature against the issuer’s keys, then its audience and subject against your rule. Matching jobs get an Arcane token with the mapped role.

Field What it does
Name A label to identify the rule.
Issuer The OIDC issuer that signs the workload’s tokens, e.g. https://token.actions.githubusercontent.com. Must be HTTPS.
Audiences Audiences the token may carry. Pick a value you control (your Arcane URL works well) and request the same one in CI.
Subject Claim The token claim to match. Defaults to sub.
Subject Match Which workloads to trust, compared against the subject claim.
Match Type exact for one subject, or glob (*) for a pattern.
Role The Arcane role granted to matching workloads.
Scope Apply the role globally or to a single agent.
Token TTL How long each issued Arcane token lasts, 60–3600 seconds, default 900.
Credential Expires Optional date when the rule stops accepting exchanges.
Enabled Whether the rule currently accepts exchanges.
  • Issuer: https://token.actions.githubusercontent.com
  • Subject examples: repo:OWNER/REPO:ref:refs/heads/main (the main branch), repo:OWNER/REPO:environment:production (a GitHub Environment), repo:OWNER/REPO:pull_request (pull requests)
  • The workflow must request id-token: write permission.
  • Issuer: https://gitlab.com (or your self-hosted GitLab URL)
  • Subject example: project_path:GROUP/PROJECT:ref_type:branch:ref:main
  • Define an id_tokens entry with the audience you configured.

arcane-cli auth federated detects GitHub Actions or GitLab CI and exchanges the platform token. --export prints the Arcane token as a shell variable without saving it to disk.

jobs:
deploy:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- name: Install the Arcane CLI
run: curl -fsSL https://getarcane.app/install-cli.sh | sh
- name: Authenticate and deploy
run: |
eval "$(arcane-cli auth federated --server https://arcane.example.com --audience https://arcane.example.com --export)"
arcane-cli projects up my-app
deploy:
id_tokens:
ARCANE_ID_TOKEN:
aud: https://arcane.example.com
script:
- eval "$(arcane-cli auth federated --audience https://arcane.example.com --token "$ARCANE_ID_TOKEN" --export)"
- arcane-cli projects up my-app

For any other OIDC source, pass the token yourself, or use --token-file <path> or --token-stdin:

Terminal window
arcane-cli auth federated --token "$MY_OIDC_TOKEN" --audience https://arcane.example.com --export
Flag Description
--audience Audience to request and send. Falls back to the federated_audience config value.
--server Arcane server URL to use for this exchange.
--provider auto (default), github, gitlab, or generic.
--token, --token-file, --token-stdin Supply the external token explicitly instead of auto-detecting it.
--export Print export ARCANE_TOKEN=… for reuse by later commands in the same shell.
--json Output the result as JSON.
--persist Save the issued token to the CLI config file (off by default).

Other clients can call /api/auth/federated/token using OAuth 2.0 Token Exchange (RFC 8693).

  • Issued tokens are short-lived (15 minutes by default) and carry only the mapped role.
  • Arcane verifies every token’s signature against the issuer’s published keys, so a workload can’t forge another’s identity.
  • Prefer exact subject matches; use wildcards only for scopes you deliberately trust.
  • Disabling or deleting a credential blocks new exchanges and revokes tokens it already issued.

For roles and agent scopes, see Roles & Permissions.