Identity and IAM

cyoda-go is an OAuth 2.0 authorization server; this page is the operator’s reference for the IAM admin surface that configures it on a self-hosted instance — which external identities to trust, which keys sign and verify tokens, and which machine-to-machine clients exist. For the conceptual model (token issuance, on-behalf-of exchange, federation), see Authentication and identity; for the managed equivalent, see Cyoda Cloud → identity and entitlements.

All paths below are admin endpoints and require an administrative token. The REST API reference carries the authoritative request/response schemas; this page covers what each group is for and how the pieces fit together. Run cyoda help auth against your binary for the version-specific detail.

OIDC provider trust

Register the external OpenID Connect issuers a tenant should trust. Each registration is validated against its discovery document, and incoming tokens are checked against the local issuer first, then each registered provider in turn.

| Method & path | Purpose | | --- | --- | | GET /oauth/oidc/providers | List registered providers. | | POST /oauth/oidc/providers | Register a provider. | | PATCH /oauth/oidc/providers/{id} | Update a registration. | | POST /oauth/oidc/providers/{id}/invalidate | Stop trusting a provider (reversible). | | POST /oauth/oidc/providers/{id}/reactivate | Resume trusting it. | | DELETE /oauth/oidc/providers/{id} | Remove a registration. | | POST /oauth/oidc/providers/reload | Re-fetch provider metadata (JWKS) cluster-wide. |

A registration describes how to trust the issuer:

{
  "wellKnownConfigUri": "https://your-idp/.well-known/openid-configuration",
  "issuers": ["https://your-idp/"],
  "expectedAudiences": ["cyoda-prod"],
  "rolesClaim": "realm_access.roles"
}

• wellKnownConfigUri (required) — the provider’s OIDC discovery endpoint. cyoda-go fetches the JWKS and metadata from it.
• issuers — allowed iss values. When omitted, the iss claim must match the discovery document’s issuer exactly.
• expectedAudiences — accepted aud values. When several tenants share one IdP, set a distinct audience per registration — this is what disambiguates tokens; ambiguous tokens are rejected rather than guessed. When omitted, the audience is not checked and issuer binding is the only trust anchor.
• rolesClaim — the claim that carries roles, overriding the global default (CYODA_OIDC_ROLES_CLAIM, typically roles). Per-provider override accommodates IdP variation — Keycloak uses realm_access.roles, Cognito uses cognito:groups. Object-nested claims are supported.

Note

OIDC registration requires a UUID-formatted tenant. Deployments that bootstrapped on the literal string default-tenant must migrate to a tenant UUID before registering a provider.

JWT signing keys

cyoda-go signs the tokens it issues with asymmetric keypairs and can also trust externally injected public keys. Both are managed under /oauth/keys.

Signing keypairs

| Method & path | Purpose | | --- | --- | | GET /oauth/keys/keypair/current | The active signing keypair (public part). | | POST /oauth/keys/keypair | Create / rotate a keypair. | | POST /oauth/keys/keypair/{keyId}/invalidate | Invalidate a keypair (with grace). | | POST /oauth/keys/keypair/{keyId}/reactivate | Reactivate it. | | DELETE /oauth/keys/keypair/{keyId} | Delete it. |

Trusted external keys

The /oauth/keys/trusted/* endpoints register public keys from an external issuer so cyoda-go accepts tokens signed elsewhere. The same invalidate / reactivate / delete lifecycle applies.

Defaults changed in v0.8.1

• Signing keys expire after a default 365 days and must be rotated. The startup banner warns for the final 30 days before expiry — wire rotation into your operations.
• Only RS256 is accepted for signing and verification. Other algorithms are rejected at runtime.
• Trusted-key registration is off by default. Opt in explicitly with CYODA_IAM_TRUSTED_KEY_REGISTRATION_ENABLED=true.

Machine-to-machine clients

Manage the technical-user clients that authenticate with the OAuth 2.0 client-credentials grant (see machine-to-machine credentials).

| Method & path | Purpose | | --- | --- | | GET /clients | List M2M clients. | | POST /clients | Create a client. | | PUT /clients/{clientId}/secret | Rotate the client secret. | | DELETE /clients/{clientId} | Delete a client. |

Creation returns the credential once, in RFC 7591 form — capture the secret at creation time:

{
  "client_id": "abc523BCD",
  "client_secret": "…",
  "client_id_issued_at": 1709913600,
  "client_secret_expires_at": 0
}

Configuration

The IAM behaviours above are governed by CYODA_* configuration; the authoritative key list lives in the binary (cyoda help config). The settings most likely to affect an upgrade:

| Variable | Effect | | --- | --- | | CYODA_IAM_TRUSTED_KEY_REGISTRATION_ENABLED | Enables the trusted-key endpoints. Default false. | | CYODA_OIDC_ROLES_CLAIM | Default JWT claim read for roles when a provider sets no rolesClaim. |

See Configuration for the configuration model and Authentication and identity for the concepts.