Setting up OIDC bearer tokens for the developer API
This guide walks an operator through letting developers authenticate to the
unified API (/v1/*) with a short-lived OIDC bearer token from an identity
provider you already run, instead of a static osk_ API key. It covers
registering an issuer, deciding where authority comes from, registering service
accounts, and — once it works — retiring API keys.
- Developer-facing reference:
../dev-api.md§2 - Scope vocabulary (shared with API keys):
../dev-api.md§3 - SDK usage:
../sdk/getting-started.md
Configure at Admin → OAuth clients (
/oauth-clients). Reading the page is operator-role or higher; every change is admin-only and audited.
This is not the same feature as SSO. That one decides how your staff log into the admin console. This one decides how a developer’s application authenticates to the API. Both talk about “identity providers” and both name Keycloak, Auth0, Okta and Entra ID, so it is worth being sure which one you are configuring — they are separate pages, separate tables and separate settings.
1. Before you start
Section titled “1. Before you start”There is nothing to add to your .env. OpenSteward is only a resource
server here: it verifies tokens using the issuer’s published public keys. It
never mints a token, and there is no client secret of yours for it to store. If
a step ever asks you for one, you are on the wrong page.
Two things do have to be true:
| Requirement | Detail |
|---|---|
| The issuer is reachable from integration-server | It fetches the discovery document and the JWKS itself. Egress from that container to your IdP has to work. |
The issuer URL is https |
Plain http is refused: anyone on the path could swap the discovery document, and with it the signing keys. For a local IdP container during evaluation, set OST_ALLOW_PRIVATE_HOSTS=1 on integration-server — development only. |
Optionally, AUTH_DEV_OAUTH_ENABLED=1 on integration-server turns the feature
on from first boot, before anyone has opened the admin UI. It is only a default;
the auth.dev_oauth_enabled setting below overrides it and is read per request.
2. Register the issuer
Section titled “2. Register the issuer”Admin → OAuth clients → Register issuer.
- Give it a name — it appears in the list and in the audit log.
- Pick your vendor from the dropdown. This only fills in the claim names below; the verifier itself is identical for every issuer.
- Paste the issuer URL and press Test. OpenSteward fetches
{issuer}/.well-known/openid-configuration, checks that the document’s ownissuermatches what you typed, and fills in the JWKS URI. Nothing is saved yet. - Set the audience. See the warning below — this field is not optional.
- Leave Accept tokens from this issuer ticked and save.
The audience is the field that matters. It is the
audvalue a token must carry. Leave it blank or wrong and every token your IdP has ever minted, for any application — including ID tokens — would authenticate here. OpenSteward refuses to save an issuer without one, and the value has to match what your IdP actually puts inaud, not what you wish it would.
Only asymmetric signature algorithms are accepted (RS*, PS*, ES*,
EdDSA). HS256 and none are refused however you fill the form in: with a
published JWKS, an HMAC algorithm lets anyone mint a token using the public
key as the secret.
Keycloak
Section titled “Keycloak”- Create a client in your realm with Client authentication on and
Service accounts roles enabled (this is the
client_credentialsgrant). - Add an audience mapper. Client → Client scopes →
<client>-dedicated → Add mapper → By configuration → Audience, and set Included Custom Audience to the audience you entered above. Without this the token’saudis justaccountand every request is refused — correctly, and with no clue as to why. - Assign the realm roles you want the token to carry, under Service accounts roles.
- Issuer URL:
https://{host}/realms/{realm}. Claims: subjectazp, scopesrealm_access.roles.
realm_access.roles also carries Keycloak’s own bookkeeping roles —
default-roles-{realm}, offline_access, uma_authorization. Registry and
intersect modes ignore them. Token-decides mode would read them as scopes, which
is why that mode wants scope rules (§5) rather than passthrough.
- Create an API in Auth0 and use its Identifier as the audience here.
- Create a Machine to Machine application authorised against that API, and grant it the permissions you want.
- Issuer URL:
https://{tenant}.auth0.com/— with the trailing slash, as Auth0 reports it. Claims: subjectazp, scopesscope.
- Create an API Services application (client credentials).
- Use a custom authorisation server, and set the audience here to that server’s configured audience.
- Issuer URL:
https://{org}.okta.com/oauth2/{authorizationServerId}. Claims: subjectcid, scopesscp.
Microsoft Entra ID
Section titled “Microsoft Entra ID”- Register an application, add an app role, and grant it to the calling
application. App-only tokens carry roles in
roles. - Audience is the target application’s Application ID URI.
- Issuer URL:
https://login.microsoftonline.com/{tenantId}/v2.0. Claims: subjectazp, scopesroles.
The most common Entra failure. A v1.0 token carries
iss: https://sts.windows.net/{tenantId}/even when you configured the v2.0 endpoint, and the issuer check is exact, so it is rejected. Either set"accessTokenAcceptedVersion": 2in the app manifest, or register the v1.0 issuer instead.
Any other provider
Section titled “Any other provider”Pick Generic OIDC. Anything that publishes an OpenID discovery document works. Set the subject and scope claims to whatever your provider actually emits — decode one of its tokens and look, rather than guessing.
3. Decide where authority comes from
Section titled “3. Decide where authority comes from”This is the most consequential choice on the form, and the one to make deliberately. The token proves who is calling; this decides what they may do.
| Mode | Tenant and scopes come from | Revoking access |
|---|---|---|
| Registry (default) | A service account you register here | Immediate — delete the row |
| Registry, narrowed by the token | The row is a ceiling; the token may ask for less | Immediate |
| The token decides | Claims in the token; nothing is registered here | Only when the token expires |
Registry and intersect consult the database on every request, so deleting a service account cuts off a token the developer is already holding — exactly like revoking an API key. Token-decides mode gives that up: a leaked token is live until it expires, and your only lever is disabling the whole issuer.
Choose token-decides when your IdP is genuinely the system of record for who may do what, and you accept that trade. Choose registry otherwise.
4. Grant access
Section titled “4. Grant access”Registry and intersect modes
Section titled “Registry and intersect modes”Admin → OAuth clients → your issuer → Register service account.
- Subject — the value your issuer puts in its subject claim (
azp,cid, …) for that client. In Keycloak and Auth0 this is the client id; decode a real token if you are unsure. - Tenant — which tenant the caller acts as.
- Scopes — the same vocabulary API keys use. See
../dev-api.md§3; the two-axis vertical model applies unchanged, so a caller needsvertical:writefor any non-GETon/v1/{vertical}/*.
A token whose subject is not registered is refused. That is the point: adding a client in your IdP does not by itself grant access to OpenSteward.
Token-decides mode
Section titled “Token-decides mode”Instead of service accounts, set:
- Tenant claim — which claim names the tenant. There is deliberately no default: the tenant now arrives inside the token, so which claim carries it has to be stated rather than guessed.
- Allowed tenants — the values this issuer may assert, one per line. An empty list admits nobody, never everybody. Check that the claim you chose is one your IdP controls and a client cannot set for itself.
- Maximum token lifetime — a token whose
exp - iatexceeds this is refused. It is the only control you have over a credential that cannot be revoked; the default is 3600s.
5. Scope mapping (optional)
Section titled “5. Scope mapping (optional)”With no rules, the token’s scope claim passes through verbatim — right when
your IdP already emits OpenSteward scope names like vertical:accounting.
Add a rule and the behaviour flips: only mapped values survive, and anything
unmapped is dropped rather than passed through. That is what lets you map
your own vocabulary (read:ledger → vertical:accounting) without a client
being able to smuggle a scope in by naming it directly.
6. Retiring API keys
Section titled “6. Retiring API keys”Once tokens work, you can stop accepting osk_ keys at Admin → Settings,
auth.dev_api_keys_enabled = false. Keys then answer
403 API_KEYS_DISABLED.
OpenSteward refuses the change with 409 AUTH_LOCKOUT_REFUSED unless
auth.dev_oauth_enabled is on, an issuer is enabled and able to admit somebody,
and that issuer has already verified a real token. Registering an issuer is
not enough — present a token through it first. If integration-server cannot be
reached to confirm, the change is refused rather than allowed: an unproven setup
is treated as unproven.
Both settings are read per request, so a change applies within about a minute without a redeploy. Turning keys back on is never blocked — that is the recovery move, and it has to work precisely when OAuth is broken.
X-Admin-Secretis never gated by either setting. It stays working with both developer credentials off, and it is how you get back into a deployment whose developer auth has been misconfigured.
7. Verify
Section titled “7. Verify”- Get a token from your IdP the way a developer would — for a service account,
usually the
client_credentialsgrant against its token endpoint. - Call a read endpoint:
Expect
Terminal window curl -H "Authorization: Bearer $TOKEN" \"$BASE/v1/accounting/contacts?connection_id=<uuid>"200. - Try a write the token is not scoped for. Expect
403 INSUFFICIENT_SCOPE— proof the shared scope engine governs it exactly as it governs a key. - Reload Admin → OAuth clients. The banner should now read that OIDC bearer auth is usable, and the issuer’s last verified should be set.
- In registry mode, revoke the service account and retry with the same
still-unexpired token. Expect
401. This is the property registry mode exists for. - Check Admin → Audit log for
oauth_issuer.createandoauth_client.create.
Troubleshooting
Section titled “Troubleshooting”Every verification failure answers the same 401 UNAUTHENTICATED, deliberately:
a more specific error would let anyone with a junk token enumerate your service
accounts. The specific reason is in the integration-server logs — that is
where to look, and it carries neither the token nor its claims.
403 OAUTH_DISABLED—auth.dev_oauth_enabledis off, or no issuer is configured.403 API_KEYS_DISABLED— you turned keys off; the caller needs a token.401on every request, issuer looks right — nine times in ten this is the audience. Decode the token and compareaudto what you registered. On Keycloak, check the audience mapper exists.401and the logs mention the issuer — theissin the token does not exactly equal what you registered. Trailing slashes count. On Entra, see the v1.0/v2.0 note in §2.- Discovery fails on save or Test — integration-server cannot reach the
issuer, the URL is
http, or it resolves to a private address. The last two are refused on purpose;OST_ALLOW_PRIVATE_HOSTS=1relaxes it for local development only. 401for one client but not another — that subject is not registered, or is revoked. Compare the token’s subject claim against the row.403 INSUFFICIENT_SCOPEyou did not expect — in intersect mode the token can only narrow the registered scopes; check both. In token-decides mode with rules configured, an unmapped claim value is dropped.409 AUTH_LOCKOUT_REFUSED— see §6; the message names which condition failed.
Doing it from the CLI
Section titled “Doing it from the CLI”Every step above is scriptable — useful for provisioning a deployment from infrastructure-as-code:
os oauth-clients discover --issuer https://idp.example.com/realms/mainos oauth-clients create-issuer # name, issuer, jwksUri, audience, claims, modeos oauth-clients create-client <issuerId>os oauth-clients create-scope-rule <issuerId>os oauth-clients list-issuersos oauth-clients readiness # the same check §6 runs before letting you disable keysFull flags: ../operations/cli.md.
opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.