Run agents as Entra service principals
Let an agent that runs as a Microsoft Entra app registration authenticate to Keycard with its service principal's own Entra token. Keycard stores no secret for it.
An agent that runs as a Microsoft Entra app registration can sign in to Keycard with the Entra token it already gets for its service principal, so Keycard stores no secret for it. An app registration that signs in with a client secret today needs no change. For agents created from an Entra Agent ID blueprint, see Authenticate Entra Agent ID agents.
- Agent Signs in to Entra as its app registration, with a client secret or a token from a managed identity the app registration trusts.
- Microsoft Entra ID Returns an app-only token for the app registration that stands for Keycard. Its
issis your tenant’s v1 issuer, and itssubis the service principal’s object ID. - Agent Sends that token to Keycard as its client assertion.
- Keycard Matches the issuer and subject to a Workload Identity credential, and issues an access token for the Resource the agent asked for when your Access Policies permit it.
Prerequisites
Section titled “Prerequisites”- A Keycard organization where you have the Admin Role.
- A Provider in Keycard for your tenant’s v1 issuer,
https://sts.windows.net/<tenant-id>/(see Register your tenant as a Provider). One that serves your managed identities or Entra Agent ID agents serves service principals too. - An app registration for each agent, with its service principal in your tenant (see Microsoft’s Register an application).
- Permission to create one more app registration and its service principal in your tenant, for the app that stands for Keycard.
- The Azure CLI, signed in to your tenant with
az login --tenant <tenant-id>. - For a federated identity credential, a user-assigned managed identity attached to the Azure service the agent runs on, such as Container Apps, App Service, or a virtual machine.
- For a federated identity credential, permission to add credentials to the app registration, for example as its owner.
- The Resource the agent will call, registered in Keycard.
Create an app registration for Keycard
Section titled “Create an app registration for Keycard”Agents request their Entra tokens for one app registration that stands for Keycard. A token for it carries no roles or scopes, so it works only at Keycard, and one app registration serves every agent in your tenant. To create it with Terraform instead, see Register Entra service principals with Terraform.
-
Create the app registration
Terminal window az ad app create --display-name "<display-name>" --sign-in-audience AzureADMyOrgName it for Keycard, such as
Keycard sign-in audience. TheappIdin the output is its client ID, written<keycard-audience-app-id>on this page. Don’t give it a secret, API permissions, or app roles, and leave its access token version at the default: tokens for an app set to version 2 carry the/v2.0issuer, which your Provider for the v1 issuer doesn’t match. -
Set its App ID URI
Terminal window az ad app update --id <keycard-audience-app-id> --identifier-uris api://<keycard-audience-app-id> -
Create its service principal
Terminal window az ad sp create --id <keycard-audience-app-id>
Choose how the agent signs in to Entra
Section titled “Choose how the agent signs in to Entra”With a client secret
Section titled “With a client secret”Nothing changes on the agent’s app registration. The agent passes your tenant ID, the app registration’s client ID, and the secret to Entra as it does today. Continue with Register the service principal in Keycard.
With a federated identity credential
Section titled “With a federated identity credential”-
Find the managed identity’s IDs
Terminal window az identity show --resource-group <resource-group> --name <managed-identity-name> --query principalId -o tsvaz identity show --resource-group <resource-group> --name <managed-identity-name> --query clientId -o tsvThe principal ID is the federated identity credential’s subject. The client ID is what the agent passes when it requests the managed identity’s token.
-
Trust the managed identity
Add a federated identity credential to the app registration:
Terminal window az ad app federated-credential create --id <app-client-id> --parameters '{"name": "<credential-name>","issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0","subject": "<managed-identity-principal-id>","audiences": ["api://AzureADTokenExchange"]}'The managed identity must be in the app registration’s tenant (see Microsoft’s Configure an application to trust a managed identity). Once the agent signs in this way, you can delete the app registration’s client secrets if nothing else uses them.
Register the service principal in Keycard
Section titled “Register the service principal in Keycard”-
Find the service principal’s object ID
Terminal window az ad sp show --id <app-client-id> --query id -o tsvThis is the
subof the agent’s Entra tokens. It is neither the app registration’s client ID nor the app registration’s own object ID. In the Microsoft Entra admin center, it’s the Object ID on the app’s Enterprise applications page, not the one on its App registrations page. -
Create an Application for the agent
In Keycard Console, navigate to Applications → Add Application and name it after the agent. Console also requires an Identifier, such as
urn:<org>:agent:<app-client-id>, and your Access Policies name the Application by it. Don’t generate a client ID and secret for it. -
Add a Workload Identity credential
On the Application’s Application Credentials tab, click Add credential and choose Workload Identity:
Field Value Provider The Provider whose Issuer URL is https://sts.windows.net/<tenant-id>/Subject The service principal’s object ID If Keycard signs people in with Entra, it also has a Provider for
https://login.microsoftonline.com/<tenant-id>/v2.0. Don’t choose that one: the agent’s tokens carry the v1 issuer, so a credential on the/v2.0Provider never matches them. Console marks Subject optional. Set it anyway, because a credential with no subject matches no token.
Then give the Application access the same way as any agent that acts as itself. For MCP tools behind a Gateway, that is an Access Policy that names the Application’s identifier, as Autonomous Agent Access describes. Tool-level rules work the same way with the Application as principal, so agents behind one Gateway can each be permitted different tools (see Allow or deny specific tools).
Don’t add a server with per-tool rules to the agent’s Dependencies tab. While the managed default-app-direct-access Policy is in the active Policy Set, a dependency permits the agent every action on that Resource.
Get a Keycard token in the agent
Section titled “Get a Keycard token in the agent”The agent requests an app-only Entra token for the app registration that stands for Keycard, then sends it to Keycard. These Python examples use azure-identity for Entra and httpx for Keycard:
pip install azure-identity httpximport os
import httpxfrom azure.identity import ClientSecretCredential
credential = ClientSecretCredential( tenant_id=os.environ["ENTRA_TENANT_ID"], client_id=os.environ["ENTRA_CLIENT_ID"], client_secret=os.environ["ENTRA_CLIENT_SECRET"],)entra_token = credential.get_token("api://<keycard-audience-app-id>/.default").token
response = httpx.post( f"{os.environ['KEYCARD_ISSUER'].rstrip('/')}/oauth/2/token", data={ "grant_type": "client_credentials", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": entra_token, "resource": os.environ["KEYCARD_RESOURCE_URL"], }, headers={"User-Agent": "<agent-name>"},)response.raise_for_status()access_token = response.json()["access_token"]import os
import httpxfrom azure.identity import ClientAssertionCredential, ManagedIdentityCredential
managed_identity = ManagedIdentityCredential(client_id=os.environ["MANAGED_IDENTITY_CLIENT_ID"])
# The managed identity's token stands in for the app registration's secret.credential = ClientAssertionCredential( tenant_id=os.environ["ENTRA_TENANT_ID"], client_id=os.environ["ENTRA_CLIENT_ID"], func=lambda: managed_identity.get_token("api://AzureADTokenExchange/.default").token,)entra_token = credential.get_token("api://<keycard-audience-app-id>/.default").token
response = httpx.post( f"{os.environ['KEYCARD_ISSUER'].rstrip('/')}/oauth/2/token", data={ "grant_type": "client_credentials", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": entra_token, "resource": os.environ["KEYCARD_RESOURCE_URL"], }, headers={"User-Agent": "<agent-name>"},)response.raise_for_status()access_token = response.json()["access_token"]| Variable | Value |
|---|---|
ENTRA_TENANT_ID |
Your tenant ID |
ENTRA_CLIENT_ID |
The app registration’s client ID |
ENTRA_CLIENT_SECRET |
With a client secret: the app registration’s client secret |
MANAGED_IDENTITY_CLIENT_ID |
With a federated identity credential: the managed identity’s client ID, not its principal ID |
KEYCARD_ISSUER |
Your Keycard Issuer URL, from Settings → Connection |
KEYCARD_RESOURCE_URL |
The Resource the agent needs a token for |
Replace <keycard-audience-app-id> with the client ID of the app registration for Keycard, then send the access token to the Resource as a bearer token. The Keycard request needs no client ID, because Keycard finds the Application from the token.
Verify
Section titled “Verify”Run the agent, then open its Application in Keycard Console and select the Activity tab. Each credential Keycard issued to the agent is listed there. Through a Gateway, a call to a tool the agent’s Access Policies don’t permit fails with access denied by policy for <upstream-mcp-url>, where <upstream-mcp-url> is the upstream’s Resource identifier.
Cut off an agent
Section titled “Cut off an agent”To stop one agent at once, delete its Workload Identity credential on the Application’s Application Credentials tab. Its next token request fails with invalid_client, and through a Gateway a token it already holds stops working on its next call. A server that checks Keycard tokens itself, with no token exchange, accepts a token the agent already holds until it expires. Other agents keep working, because each has its own credential.
To restore the agent, add the credential again.
Clean up
Section titled “Clean up”- In Keycard Console, delete each agent’s Workload Identity credential and its Application.
- In Entra, delete the app registration that stands for Keycard if no other agent uses it, and any federated identity credentials you added for this recipe.
Limits
Section titled “Limits”- With a client secret, the agent still holds an Entra secret, and anyone who reads it can get Entra tokens as the app registration and, through them, Keycard tokens as its Application. The secret stays yours to rotate in Entra. With a federated identity credential, neither the agent nor Keycard holds a secret.
- Anyone who can add a credential to the app registration, or use the managed identity it trusts, can sign in as this Application.
- Each service principal is its own Application. A credential matches one subject, and object IDs are GUIDs with no common prefix, so a wildcard subject can’t cover several. To register many at once, use Terraform.
- A server that checks Keycard tokens itself, with no token exchange, accepts a token the agent already holds until it expires, even after you cut the agent off.
Troubleshooting
Section titled “Troubleshooting”invalid_client: No token application credential configured for provider ‘…’ and subject ‘…’
Section titled “invalid_client: No token application credential configured for provider ‘…’ and subject ‘…’”No Workload Identity credential matches the token. The message shows the issuer and subject Keycard read from the token, so compare them with the Provider’s Issuer URL and the credential’s Subject. The Subject must be the service principal’s object ID, not the app registration’s client ID or object ID. If the issuer ends in /v2.0, the agent requested its token for an app set to access token version 2: request it for api://<keycard-audience-app-id>/.default, and leave that app’s access token version at the default.
Entra refuses the token request with a federated identity credential
Section titled “Entra refuses the token request with a federated identity credential”The federated identity credential’s subject must be the managed identity’s principal ID, and the agent must pass the managed identity’s client ID. They are different values, and each place takes a different one. The managed identity must also be in the app registration’s tenant.
Entra refuses the token request with AADSTS5000211
Section titled “Entra refuses the token request with AADSTS5000211”A tenant restrictions policy, added to the request by the network or device the agent runs on, doesn’t allow the tenant. Microsoft documents that tenant restrictions v2 blocks service principal sign-ins as well as people’s. It also notes that a blocked service principal sign-in is logged only in the tenant that received the request (see Tenant restrictions v2 and service principals). Whoever manages that policy decides which tenants it allows.
The agent gets a Keycard token, but a tool is refused or missing
Section titled “The agent gets a Keycard token, but a tool is refused or missing”No Access Policy permits the agent’s Application for that upstream or tool. See Troubleshooting in Autonomous Agent Access.