Skip to content
docs

Bring your identity provider

Plat5 accepts sign-in tokens from any OIDC provider that publishes its signing keys (JWKS). Your services never see the token, so the provider you choose doesn’t change them.

Locally, the CLI runs Plat5 Auth for you. In production, use Plat5 Auth or point the gateway at your own provider.

Gateway settings

Section titled “Gateway settings”
Setting What it is
AUTH_ISSUER The provider’s issuer URL, exactly as it appears in the token’s iss
AUTH_JWKS_URI Where the gateway fetches the provider’s signing keys
AUTH_USER_ID_CLAIM The claim that holds the person’s subject at the provider. Usually sub
AUTH_ALLOWED_AUDIENCES The token audiences your API accepts, comma-separated

Tokens must be signed with a key from the JWKS, have an exp, and carry a kid header.

Examples

Section titled “Examples”
Auth0
AUTH_ISSUER=https://acme.us.auth0.com/
AUTH_JWKS_URI=https://acme.us.auth0.com/.well-known/jwks.json
AUTH_USER_ID_CLAIM=sub
AUTH_ALLOWED_AUDIENCES=https://api.acme.com
Keycloak
AUTH_ISSUER=https://id.acme.com/realms/acme
AUTH_JWKS_URI=https://id.acme.com/realms/acme/protocol/openid-connect/certs
AUTH_USER_ID_CLAIM=sub
AUTH_ALLOWED_AUDIENCES=acme-api
Plat5 Auth
AUTH_ISSUER=https://auth.acme.com
AUTH_JWKS_URI=https://auth.acme.com/.well-known/jwks.json
AUTH_USER_ID_CLAIM=properties.user_id
AUTH_ALLOWED_AUDIENCES=plat5

People

Section titled “People”

The first time someone signs in, Plat5 creates a person and links them to the provider’s issuer and subject. Your services hold Plat5’s user_id, never the provider’s subject.

To add someone to an organization before they’ve signed in, your backend sends their issuer and subject to POST /org/members.

Things to get right

Section titled “Things to get right”
  • The issuer must match exactly. http://localhost:5000 and http://127.0.0.1:5000 are different issuers.
  • The JWKS URL must be reachable from the gateway, usually the provider’s public URL.
  • Sign-in options are the provider’s. Single sign-on, social login and MFA all come from your provider.
  • Moving people between providers means linking their new subject to their existing person. That API is planned; until then, a sign-in from a new provider creates a new person.

More: idp-contract.md.