Skip to content

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.

  1. Terraform Creates the app registration that stands for Keycard, and asks Entra for each agent’s service principal by its client ID.
  2. Microsoft Entra ID Returns each service principal with its object ID.
  3. Keycard Gets one Application per agent from Terraform, each with a Workload Identity credential whose subject is that object ID.
  • 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.
  1. 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>:agent
    variable "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.id
    identifier_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 uses
    data "keycard_provider" "entra" {
    zone_id = var.zone_id
    identifier = "https://sts.windows.net/${var.tenant_id}/"
    }
    data "azuread_service_principals" "agents" {
    client_ids = var.agent_client_ids
    ignore_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.agents
    zone_id = var.zone_id
    name = each.value.display_name
    identifier = "${var.identifier_prefix}:${each.key}"
    }
    resource "keycard_application_workload_identity" "agent" {
    for_each = local.agents
    zone_id = var.zone_id
    application_id = keycard_application.agent[each.key].id
    provider_id = data.keycard_provider.entra.id
    subject = each.value.object_id
    }
    # The scope each agent requests its Entra token for
    output "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 three keycard_audience resources and the output. Terraform finds your Provider by its identifier, which is its Issuer URL unless you gave the Provider a different one.

  2. Set the variables

    Variable Value
    zone_id The first part of your Keycard issuer URL’s host name
    tenant_id Your tenant ID
    identifier_prefix The start of each Application’s identifier. With urn:<org>:agent, an agent’s Application gets urn:<org>:agent:<app-client-id>.
    agent_client_ids The 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_ID and KEYCARD_CLIENT_SECRET (see Use the credential).

  3. Apply it

    Terminal window
    terraform init
    terraform apply

    Each agent gets an Application named after its service principal, with a Workload Identity credential. The keycard_audience_scope output 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).

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.

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.

Run terraform destroy. It removes every Application and credential the configuration created, and the app registration for Keycard if the configuration created it.

  • 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.
  • If an agent’s token request fails with invalid_client, see Troubleshooting on Run agents as Entra service principals.

Did this recipe work for you?