OIDC Client Authentication

When a confidential OIDC client exchanges a code for tokens, it has to authenticate itself to Permiso. The default way to do this is with a client secret. As an alternative, Permiso also supports federated client credentials, which let a client authenticate using a JWT signed by a trusted external issuer instead of a stored secret.

This is useful for workloads that already have a way to prove their identity without a long-lived secret — for example, a CI/CD pipeline that gets a short-lived OIDC token from its platform (GitHub Actions, GitLab CI, a cloud provider, etc.) and can present that token to Permiso instead of managing a client secret.

How it works

You register one or more federated identities on the OIDC client, each describing a trusted external issuer.
Your workload obtains a JWT from that issuer (its own OIDC provider).

Instead of sending a client_secret, your app sends that JWT as a client_assertion when calling the token endpoint:

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<the JWT from your issuer>

Permiso looks at the iss (issuer) claim in the JWT, matches it against the federated identities configured for the client, fetches that issuer’s JWKS, and verifies the JWT’s signature, audience, and subject.
If verification succeeds, the client is authenticated — no client secret is involved.

Configuring a federated identity

From the OIDC client’s settings, under Federated Client Credentials, add an identity with:

Field	Description
Issuer	The `iss` value of the JWTs your workload will present, e.g. `https://token.actions.githubusercontent.com`
Subject	The expected `sub` claim in the JWT. Defaults to the client ID if left blank, per RFC 7523
Audience	The expected `aud` claim in the JWT. Defaults to your Permiso instance URL if left blank
JWKS URL	Where to fetch the issuer’s signing keys from. Defaults to `<issuer>/.well-known/jwks.json` if left blank

You can register multiple federated identities on the same client, for example to trust more than one issuer.

Verification details

The JWT’s signature is verified against the issuer’s JWKS, with the signing algorithm inferred from the matched key.
The aud and sub claims must match the configured (or default) audience and subject exactly.
A small clock skew is tolerated when checking expiry and not-before claims.
If no federated identity is configured for the JWT’s issuer, or verification fails for any reason, authentication is rejected.

When to use this vs. a client secret

Use a client secret for most confidential clients — it’s simpler and works everywhere. Federated client credentials are worth setting up when your workload already receives short-lived, provider-issued OIDC tokens and you’d rather not store or rotate a long-lived secret at all.