Register Entra service principals with Terraform
Register every agent's Entra service principal in Keycard from one Terraform configuration, so a new agent gets its Application and credential on the next apply.
Run agents as Entra service principals registers each agent in Keycard Console. With many agents, this Terraform configuration does it instead: it creates the app registration that stands for Keycard, looks up each agent’s service principal with the azuread provider, and registers it with the Keycard Terraform provider.
- Terraform Creates the app registration that stands for Keycard, and asks Entra for each agent’s service principal by its client ID.
- Microsoft Entra ID Returns each service principal with its object ID.
- Keycard Gets one Application per agent from Terraform, each with a Workload Identity credential whose subject is that object ID.
Prerequisites
Section titled “Prerequisites”- A Keycard organization where you have the Admin Role, and a Service Account credential for the Keycard provider.
- A Provider in Keycard for your tenant’s v1 issuer,
https://sts.windows.net/<tenant-id>/(see Register your tenant as a Provider). - An app registration for each agent, with its service principal in your tenant.
- Terraform, and the Azure CLI signed in to your tenant with
az login --tenant <tenant-id>. The identity you sign in as must be able to create an app registration and its service principal, and read service principals, in your tenant.
Register the agents
Section titled “Register the agents”-
Save the configuration
Save this as
main.tf:terraform {required_providers {azuread = {source = "hashicorp/azuread"version = "~> 3.0"}keycard = {source = "keycardai/keycard"version = "~> 0.7"}}}variable "zone_id" { type = string }variable "tenant_id" { type = string }variable "identifier_prefix" { type = string } # For example urn:<org>:agentvariable "agent_client_ids" { type = set(string) } # Client IDs of the agents' app registrations# The app registration that stands for Keycard. Leave its access token version at the default.resource "azuread_application" "keycard_audience" {display_name = "Keycard sign-in audience"sign_in_audience = "AzureADMyOrg"lifecycle {ignore_changes = [identifier_uris] # Set by azuread_application_identifier_uri}}resource "azuread_application_identifier_uri" "keycard_audience" {application_id = azuread_application.keycard_audience.ididentifier_uri = "api://${azuread_application.keycard_audience.client_id}"}resource "azuread_service_principal" "keycard_audience" {client_id = azuread_application.keycard_audience.client_id}# The Provider for your tenant's v1 issuer, not the /v2.0 one Entra sign-in usesdata "keycard_provider" "entra" {zone_id = var.zone_ididentifier = "https://sts.windows.net/${var.tenant_id}/"}data "azuread_service_principals" "agents" {client_ids = var.agent_client_idsignore_missing = true}locals {agents = { for sp in data.azuread_service_principals.agents.service_principals : sp.client_id => sp }}resource "keycard_application" "agent" {for_each = local.agentszone_id = var.zone_idname = each.value.display_nameidentifier = "${var.identifier_prefix}:${each.key}"}resource "keycard_application_workload_identity" "agent" {for_each = local.agentszone_id = var.zone_idapplication_id = keycard_application.agent[each.key].idprovider_id = data.keycard_provider.entra.idsubject = each.value.object_id}# The scope each agent requests its Entra token foroutput "keycard_audience_scope" {value = "api://${azuread_application.keycard_audience.client_id}/.default"}If you already created the app registration for Keycard with
az, leave out the threekeycard_audienceresources and the output. Terraform finds your Provider by its identifier, which is its Issuer URL unless you gave the Provider a different one. -
Set the variables
Variable Value zone_idThe first part of your Keycard issuer URL’s host name tenant_idYour tenant ID identifier_prefixThe start of each Application’s identifier. With urn:<org>:agent, an agent’s Application getsurn:<org>:agent:<app-client-id>.agent_client_idsThe client IDs of the agents’ app registrations The azuread provider uses your Azure CLI sign-in. The Keycard provider takes the Service Account’s client ID and secret from
KEYCARD_CLIENT_IDandKEYCARD_CLIENT_SECRET(see Use the credential). -
Apply it
Terminal window terraform initterraform applyEach agent gets an Application named after its service principal, with a Workload Identity credential. The
keycard_audience_scopeoutput is the scope agents request their Entra token for, as in Get a Keycard token in the agent.
Then give each Application access the same way as any agent that acts as itself (see Autonomous Agent Access).
Add and remove agents
Section titled “Add and remove agents”A client ID added to agent_client_ids gets an Application and credential on the next apply, and one removed from it loses them. An app registration deleted in Entra drops out too: with ignore_missing set, Terraform skips a client ID that has no service principal, and the next apply removes its Application and credential. Access still comes from your Access Policies, so give each new Application access the same way as the first.
Verify
Section titled “Verify”Run an agent, then open its Application in Keycard Console and select the Activity tab. Each credential Keycard issued to the agent is listed there.
Clean up
Section titled “Clean up”Run terraform destroy. It removes every Application and credential the configuration created, and the app registration for Keycard if the configuration created it.
Limits
Section titled “Limits”- Terraform registers agents and their credentials. What each agent may reach still comes from your Access Policies.
- The sign-in limits on Run agents as Entra service principals apply here too.
Troubleshooting
Section titled “Troubleshooting”- If an agent’s token request fails with
invalid_client, see Troubleshooting on Run agents as Entra service principals.