KERNEL_API_KEY in Key Vault or your app settings.
Entra differs from the other providers in one way: the token’s audience is an app registration in your tenant, not https://auth.onkernel.com. You create that app registration once, and your workloads request tokens for it.
Before you start
- You’re an organization admin in KERNEL.
- You can create app registrations in your Entra tenant.
- Your workload has a managed identity, or a service principal with its own credentials.
Configure Entra
1
Create an app registration for the audience
In the Azure portal, create an app registration that stands for KERNEL in your tenant, and give it an Application ID URI of
api://<client ID>. Note its Application (client) ID and your Directory (tenant) ID.2
Find out which token version you get
Entra issues v1.0 or v2.0 tokens, and the two have different issuers and audiences:
Tokens are v1.0 unless the app registration sets
requestedAccessTokenVersion to 2. Managed identity tokens default to v1.0.3
Find the workload's object ID
Note the Object (principal) ID of the managed identity or service principal your workload runs as. The rule pins this ID.
Configure KERNEL
1
Register your tenant as an issuer
In the dashboard, open Keys > Workload identity, click Connect workload, and select the Microsoft Entra tile.
- Enter your Directory (tenant) ID.
- Under Token issuer, select v1 (sts.windows.net) or v2.0 (login.microsoftonline.com) to match your tokens.
- Click Apply and continue.
2
Name the workload in a rule
Under Match conditions:
Under Authorization, choose the Project, the Permissions, and the Token lifetime.
3
Pick a service account and enable
Choose or create a service account, click Create rule, then turn on the issuer and the rule in the Test step. Copy the rule ID (
wifr_...).4
Allow token reuse if your workload caches tokens
Entra tokens are single-use in KERNEL by default. The Azure Identity libraries and managed identity endpoints cache a token and return the same one until it nears expiry, so a second exchange with it is refused.If your workload gets its token that way, open the Issuers tab, select Edit on the issuer, and turn off Enforce single-use tokens (JTI replay protection). The token can then be exchanged until it expires.
Configure your workload
The SDKs have no built-in Entra source, because the audience is yours. Pass a callback that returns a token for your app registration. These examples use the Azure Identity library and a v1.0 audience:<client ID>/.default instead.
What KERNEL accepts
An Entra rule accepts only an application’s own token:-
A token with delegated scopes is refused. If the token carries an
scpclaim, it was issued to a signed-in user, and it never matches. - The tenant is pinned. KERNEL adds the issuer’s tenant ID to the rule’s conditions, so a token from another tenant doesn’t match.
-
Pin the object ID where you can. A rule that names the object ID (
oid) needs no extra Entra configuration. -
A rule keyed only on a client ID needs
idtyp. If you create a rule through the API that names onlyappidorazp, KERNEL also requires the token’sidtypclaim to beapp. Entra doesn’t emitidtypunless you add it as an optional claim on the audience app registration:Until you do, that rule rejects every token.
- Entra’s token ID is
uti. KERNEL uses it, notjti, for single-use checks. - Switching between v1.0 and v2.0 changes both
issandaud. If you change the app registration’s token version, change the issuer and the rule’s expected audience together. - Long-lived tokens need a higher limit. By default, KERNEL accepts an Entra token only if its lifetime,
expminusiat, is 7,500 seconds or less. If your tokens live longer, raise Maximum token lifetime (hours) on the issuer, up to 24 hours.
Next steps
- Reference: Microsoft Entra match fields
- Troubleshooting: what a refused exchange means
- Move a workload from an API key