Skip to content

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.

  1. Agent Signs in to Entra as its app registration, with a client secret or a token from a managed identity the app registration trusts.
  2. Microsoft Entra ID Returns an app-only token for the app registration that stands for Keycard. Its iss is your tenant’s v1 issuer, and its sub is the service principal’s object ID.
  3. Agent Sends that token to Keycard as its client assertion.
  4. 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.
  • 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.

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.

  1. Create the app registration

    Terminal window
    az ad app create --display-name "<display-name>" --sign-in-audience AzureADMyOrg

    Name it for Keycard, such as Keycard sign-in audience. The appId in 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.0 issuer, which your Provider for the v1 issuer doesn’t match.

  2. Set its App ID URI

    Terminal window
    az ad app update --id <keycard-audience-app-id> --identifier-uris api://<keycard-audience-app-id>
  3. Create its service principal

    Terminal window
    az ad sp create --id <keycard-audience-app-id>

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.

  1. Find the managed identity’s IDs

    Terminal window
    az identity show --resource-group <resource-group> --name <managed-identity-name> --query principalId -o tsv
    az identity show --resource-group <resource-group> --name <managed-identity-name> --query clientId -o tsv

    The 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.

  2. 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.

  1. Find the service principal’s object ID

    Terminal window
    az ad sp show --id <app-client-id> --query id -o tsv

    This is the sub of 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.

  2. 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.

  3. 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.0 Provider 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.

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:

Terminal window
pip install azure-identity httpx
import os
import httpx
from 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"]
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.

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.

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.

  1. In Keycard Console, delete each agent’s Workload Identity credential and its Application.
  2. 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.
  • 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.

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.

Did this recipe work for you?