🚀 Azure AD Service Principal Terraform Module

Composite module that manages an Entra ID service principal (enterprise application) and every credential and grant that hangs off it — client-secret passwords, certificate credentials, a SAML token-signing certificate, delegated OAuth2 permission grants, claims-mapping policy assignments, and app-role assignments — behind one stable, deeply-typed, secure-by-default boundary. Built for azuread v3.x.

This module instantiates an application as a tenant-local service principal (what the Entra admin center calls an Enterprise Application) and wires up everything that lives on that instance:

• 🪪 Service principal (azuread_service_principal.this) — the keystone, linked to an existing application via client_id, with full scalar config (account enabled, app-role-assignment requirement, SSO mode, alternative names, SAML SSO, feature tags).
• 🔐 Password credentials (azuread_service_principal_password.this) — client secrets as a keyed for_each collection, with a forced 1-year default expiry.
• 📜 Certificate credentials (azuread_service_principal_certificate.this) — a for_each collection; the whole input is sensitive because each entry carries credential value.
• 🏷️ Token signing certificate (azuread_service_principal_token_signing_certificate.this) — a single (0-or-1) certificate for signing SAML tokens; Azure AD generates the key pair.
• 🤝 Delegated permission grants (azuread_service_principal_delegated_permission_grant.this) — authorize this SP to call a resource API on behalf of users (OAuth2 delegated consent).
• 🧬 Claims-mapping policy assignments (azuread_service_principal_claims_mapping_policy_assignment.this) — bind claims-mapping policies to this SP.
• 🎟️ App-role assignments (azuread_app_role_assignment.this) — grant an app role of a resource SP to a principal; either side defaults to this SP.

💡 Why it matters: The service principal is where an application actually acts and is granted access inside a tenant — its credentials sign in, its delegated grants consent to APIs, and its app-role assignments are how application permissions are realized. Managing the SP and all its credentials/grants as one typed, secure-by-default module means rotation, consent, and role grants never drift, and downstream role assignments, group membership, and provisioning jobs compose off one predictable contract.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

terraform-azuread-service-principal sits directly downstream of terraform-azuread-application — it consumes that module's client_id — and feeds role assignments, provisioning, and claims policies.

flowchart TD
 app["terraform-azuread-application<br/>(app registration — emits client_id)"]
 sp["terraform-azuread-service-principal<br/>(SP + creds + grants + assignments)"]
 grp["terraform-azuread-group"]
 dir["terraform-azuread-directory-role"]
 ap["terraform-azuread-access-package"]
 sync["terraform-azuread-synchronization"]
 claims["terraform-azuread-claims-mapping-policy"]

 app -->|client_id| sp
 claims -->|claims_mapping_policy_id| sp
 sp -->|object_id| dir
 sp -->|object_id| grp
 sp -->|object_id| ap
 sp -->|object_id / id| sync

 style sp fill:#8957E5,color:#fff
 style app fill:#0078D4,color:#fff

Every resource hangs off the keystone azuread_service_principal.this. Child resources wire to it via its resource ID (azuread_service_principal.this.id, form /servicePrincipals/{object_id}) or its object ID (azuread_service_principal.this.object_id).

flowchart TD
 this["azuread_service_principal.this<br/>(keystone)"]

 tspw["time_static.password<br/>(for_each, expiry anchor)"]
 tscert["time_static.certificate<br/>(for_each, expiry anchor)"]
 pw["azuread_service_principal_password.this<br/>(for_each)"]
 cert["azuread_service_principal_certificate.this<br/>(for_each, sensitive)"]
 tsc["azuread_service_principal_token_signing_certificate.this<br/>(0-or-1, SAML)"]
 dpg["azuread_service_principal_delegated_permission_grant.this<br/>(for_each)"]
 cmp["azuread_service_principal_claims_mapping_policy_assignment.this<br/>(for_each)"]
 ara["azuread_app_role_assignment.this<br/>(for_each)"]

 this -->|.id| pw
 this -->|.id| cert
 this -->|.id| tsc
 this -->|.object_id| dpg
 this -->|.id| cmp
 this -->|.object_id| ara
 tspw -.->|rfc3339 expiry anchor| pw
 tscert -.->|rfc3339 expiry anchor| cert

 style this fill:#0078D4,color:#fff

ℹ️ data.azuread_client_config.current, data.azuread_service_principal.lookup, and data.azuread_service_principals.lookup are intentionally not wired into the diagram above — per main.tf they are standalone read-only lookups (feeding only the current_object_id/tenant_id/*_lookups outputs) and do not participate in the keystone's resource graph.

Resource inventory (7 resource types):

• azuread_service_principal.this — keystone (enterprise application instance)
• azuread_service_principal_password.this — client secrets (for_each)
• azuread_service_principal_certificate.this — certificate credentials (for_each, sensitive input)
• azuread_service_principal_token_signing_certificate.this — SAML token signing certificate (0-or-1)
• azuread_service_principal_delegated_permission_grant.this — delegated OAuth2 grants (for_each)
• azuread_service_principal_claims_mapping_policy_assignment.this — claims-mapping policy assignments (for_each)
• azuread_app_role_assignment.this — app-role assignments (for_each)

Data sources: azuread_client_config (current caller), azuread_service_principal (single lookup, for_each), azuread_service_principals (bulk lookup, for_each).

From providers.tf:

ℹ️ The module declares the provider requirement only — it configures no provider "azuread" {} block, so it composes cleanly under any root provider configuration. data.azuread_client_config.current works without module-level provider config.

ℹ️ hashicorp/time dependency: the azuread provider deprecated the native end_date_relative field on azuread_service_principal_password and azuread_service_principal_certificate. To preserve the relative-expiry convenience (and the 1-year default) without a deprecation warning, the module captures a stable per-credential timestamp via time_static and renders it into an absolute end_date with timeadd. The anchor is captured once at create, so there is no plan drift. The module's public end_date_relative input is unchanged.

⚠️ v3.x naming & derivation: the SP links to its application via client_id (not the legacy application_id). A service principal has no settable display_name — it is derived from the linked application and exposed only as an output. Child credentials link to the SP by its resource ID (azuread_service_principal.this.id); grants and app-role assignments link by object ID (azuread_service_principal.this.object_id).

The Terraform service principal must hold these before apply will succeed (sourced from SCOPE.md, enriched with Microsoft Learn).

⚠️ Admin consent required. All of the above are application permissions and require tenant admin consent. When Terraform runs as a user principal instead of an SP, the user needs the Application Administrator (or Cloud Application Administrator / Global Administrator) directory role.

⚠️ Member-affecting, immediate, irreversible. Granting a delegated permission for all users (omitting user_object_id → tenant-wide admin consent) and creating app-role assignments take effect immediately and are not subject to review (MS Learn). Route these to an admin / Compliance review before apply.

ℹ️ No P1/P2 license is required for service principal management itself. (Downstream consumers such as PIM or Conditional Access require Entra ID P2 — those live in other modules.)

terraform-azuread-service-principal/
├── providers.tf # Terraform >= 1.12.0, azuread >= 2.0, < 4.0 (no provider block)
├── variables.tf # deeply-typed object schemas, optional defaults, validation {}
├── main.tf # total renderer: keystone + 6 child resources + 2 time_static helpers + 3 data sources
├── outputs.tf # object_id (primary), client_id, sensitive credential outputs
├── SCOPE.md # cross-module contract + Graph API permissions
└── README.md # this file

module "sp" {
  source = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"

  client_id = module.app.client_id # from terraform-azuread-application

  # Keep the Terraform SP as an owner so it can manage the SP after creation.
  owners = [module.sp.current_object_id]
}

ℹ️ Self-referencing module.sp.current_object_id works because the value comes from the azuread_client_config data source (known at plan time), not from the SP resource.

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  description                   = "Member portal enterprise application"
  login_url                     = "https://portal.example.com/sso/start"
  preferred_single_sign_on_mode = "saml" # one of: oidc, password, saml, notSupported
  notification_email_addresses  = ["sso-admins@financialpartners.com"]
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  passwords = {
    primary = {
      display_name      = "primary-secret"
      end_date_relative = "4320h" # 180 days — under Microsoft's 12-month recommendation
    }
  }
}

# Store the write-only value immediately — it cannot be re-read.
output "sp_secret" {
  value     = module.sp.passwords["primary"].value
  sensitive = true
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  certificates = {
    signing = {
      value    = file("${path.module}/certs/sp-public.pem") # public cert (.pem/.cer/.crt)
      type     = "AsymmetricX509Cert"                       # or "Symmetric"
      encoding = "pem"                                      # one of: pem, base64, hex
    }
  }
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  preferred_single_sign_on_mode = "saml"
  notification_email_addresses  = ["sso-admins@financialpartners.com"]

  saml_single_sign_on = {
    relay_state = "https://portal.example.com/landing"
  }

  token_signing_certificate = {
    display_name = "CN=casey-portal-saml-signing" # MUST start with "CN="
    end_date     = "2027-06-18T00:00:00Z"
  }
}

output "saml_thumbprint" {
  value = module.sp.token_signing_certificate.thumbprint
}

# The resource API's service principal — here, Microsoft Graph.
data "azuread_service_principal" "msgraph" {
  client_id = "00000003-0000-0000-c000-000000000000"
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  delegated_permission_grants = {
    graph_user_read = {
      resource_service_principal_object_id = data.azuread_service_principal.msgraph.object_id
      claim_values                         = ["User.Read", "openid", "profile"]
      # user_object_id OMITTED -> admin consent for ALL users (tenant-wide)
    }
  }
}

# (a) THIS SP as the PRINCIPAL — grant a Microsoft Graph application permission to this SP.
data "azuread_service_principal" "msgraph" {
  client_id = "00000003-0000-0000-c000-000000000000"
}

variable "loan_admins_group_object_id" { type = string } # (b) principal for the second assignment

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  app_role_assignments = {
    graph_user_read_all = {
      # principal_object_id OMITTED -> defaults to THIS service principal
      resource_object_id = data.azuread_service_principal.msgraph.object_id
      app_role_id        = "df021288-bdef-4463-88db-98f22de89214" # User.Read.All (application)
    }
    # (b) THIS SP as the RESOURCE — assign a role this app exposes to a group.
    loan_admin_for_group = {
      # resource_object_id OMITTED -> defaults to THIS service principal
      principal_object_id = var.loan_admins_group_object_id
      app_role_id         = module.sp.app_role_ids["Loan.Admin"] # a role this app exposes
    }
  }
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  claims_mapping_policy_assignments = {
    employee_claims = {
      claims_mapping_policy_id = module.claims_policy.id # from terraform-azuread-claims-mapping-policy
    }
  }
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  feature_tags = {
    enterprise = true # WindowsAzureActiveDirectoryIntegratedApp
    hide       = true # HideApp — invisible in My Apps / Office 365 launcher
  }
  # Do NOT also set var.tags — the two are mutually exclusive (validated).
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  passwords = {
    # Keys are STABLE identifiers — renaming a key destroys & recreates that secret.
    api-primary = {
      display_name      = "api-primary"
      end_date_relative = "8760h" # 1 year
    }
    api-secondary = {
      display_name      = "api-secondary"
      end_date_relative = "8760h"
    }
    batch-runner = {
      display_name = "batch-runner"
      end_date     = "2027-01-01T00:00:00Z" # absolute expiry (don't combine with end_date_relative)
    }
  }
}

output "sp_secret_key_ids" {
  value = module.sp.password_key_ids # non-sensitive, safe to log
}

variable "secret_rotation_id" {
  type    = string
  default = "2026-q2" # bump this token (or wire to time_rotating.id) to force a new secret
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  passwords = {
    primary = {
      display_name        = "primary-secret"
      end_date_relative   = "8760h" # 1 year
      rotate_when_changed = { rotation = var.secret_rotation_id }
    }
  }
}

data "azuread_client_config" "current" {}

variable "sp_admin_user_object_id" { type = string }    # e.g. an IT owner of this app
variable "app_admins_group_object_id" { type = string } # e.g. an "SP admins" security group

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  owners = [
    data.azuread_client_config.current.object_id, # the Terraform SP — retains management rights
    var.sp_admin_user_object_id,                  # named human owner
    var.app_admins_group_object_id,               # named group owner
  ]
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  description = "Production confidential client — certificate auth only, no client secrets."

  account_enabled              = true
  app_role_assignment_required = true # require explicit assignment (secure default, shown for intent)

  # Prefer certificate credentials over client secrets in production
  certificates = {
    signing = {
      value             = file("${path.module}/certs/prod-public.pem")
      type              = "AsymmetricX509Cert"
      encoding          = "pem"
      end_date_relative = "8760h"
    }
  }

  feature_tags = {
    hide = true # not surfaced to end users in My Apps
  }

  owners = [module.sp.current_object_id] # Terraform SP retains management rights
}

module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id

  service_principal_lookups = {
    msgraph = { client_id = "00000003-0000-0000-c000-000000000000" }
  }

  service_principals_lookups = {
    portals    = { display_names = ["casey-member-portal", "casey-admin-portal"] }
    everything = { return_all = true } # cannot combine with ignore_missing
  }
}

output "msgraph_object_id" {
  value = module.sp.service_principal_lookups["msgraph"].object_id
}

# --- Upstream: the application registration ----------------------------------
module "app" {
  source       = "git::https://github.com/microsoftexpert/terraform-azuread-application?ref=v1.0.0"
  display_name = "casey-loan-origination-api"
  owners       = [module.app.current_object_id]
}

# --- The resource API's SP (Microsoft Graph) ---------------------------------
data "azuread_service_principal" "msgraph" {
  client_id = "00000003-0000-0000-c000-000000000000"
}

# --- This module: the service principal --------------------------------------
module "sp" {
  source    = "git::https://github.com/microsoftexpert/terraform-azuread-service-principal?ref=v1.0.0"
  client_id = module.app.client_id # <-- wired from the application module

  app_role_assignment_required = true
  owners                       = [module.sp.current_object_id]

  # Grant this SP an application permission on Microsoft Graph
  app_role_assignments = {
    graph_user_read_all = {
      resource_object_id = data.azuread_service_principal.msgraph.object_id
      app_role_id        = "df021288-bdef-4463-88db-98f22de89214" # User.Read.All
    }
  }

  passwords = {
    primary = { display_name = "primary-secret", end_date_relative = "8760h" }
  }
}

# --- Downstream: provisioning job keyed by the SP ----------------------------
module "sync" {
  source               = "git::https://github.com/microsoftexpert/terraform-azuread-synchronization?ref=v1.0.0"
  service_principal_id = module.sp.object_id # <-- this module's primary output
}

# --- Downstream: store the write-only secret in Key Vault --------------------
resource "azurerm_key_vault_secret" "sp" {
  name         = "loan-api-sp-secret"
  value        = module.sp.passwords["primary"].value # sensitive -> sensitive
  key_vault_id = var.kv_id
}

saml_single_sign_on = object({ # default null (0-or-1 block)
  relay_state = optional(string)
})

feature_tags = object({ # default null (0-or-1 block); EXCLUSIVE with tags
  custom_single_sign_on = optional(bool, false)
  enterprise            = optional(bool, false)
  gallery               = optional(bool, false)
  hide                  = optional(bool, false)
})

tags = set(string) # default []; EXCLUSIVE with feature_tags

token_signing_certificate = object({ # default null (0-or-1 resource)
  display_name = optional(string)    # MUST start with "CN=" when set
  end_date     = optional(string)
})

passwords = map(object({ # default {}
  display_name        = optional(string)
  end_date            = optional(string)
  end_date_relative   = optional(string, "8760h")
  start_date          = optional(string)
  rotate_when_changed = optional(map(string), {})
}))

certificates = map(object({ # default {} — SENSITIVE
  value             = string
  type              = optional(string, "AsymmetricX509Cert") # AsymmetricX509Cert | Symmetric
  encoding          = optional(string, "pem")                # pem | base64 | hex
  end_date          = optional(string)
  end_date_relative = optional(string, "8760h")
  start_date        = optional(string)
  key_id            = optional(string)
}))

delegated_permission_grants = map(object({ # default {}
  resource_service_principal_object_id = string
  claim_values                         = set(string)
  user_object_id                       = optional(string) # omit -> admin consent for ALL users
}))

claims_mapping_policy_assignments = map(object({ # default {}
  claims_mapping_policy_id = string
}))

app_role_assignments = map(object({ # default {}
  app_role_id         = optional(string, "00000000-0000-0000-0000-000000000000")
  principal_object_id = optional(string) # omit -> THIS SP
  resource_object_id  = optional(string) # omit -> THIS SP
}))

service_principal_lookups = map(object({ # default {}
  client_id    = optional(string)
  display_name = optional(string)
  object_id    = optional(string)
}))

service_principals_lookups = map(object({ # default {}
  client_ids     = optional(list(string))
  display_names  = optional(list(string))
  object_ids     = optional(list(string))
  return_all     = optional(bool, false)
  ignore_missing = optional(bool, false)
}))

timeouts = object({ # default {}
  create = optional(string), read = optional(string)
  update = optional(string), delete = optional(string)
})

for_each = toset(nonsensitive(keys(var.certificates)))

resource "azurerm_key_vault_secret" "sp" {
  name         = "loan-api-sp-secret"
  value        = module.sp.passwords["primary"].value # sensitive flows to sensitive
  key_vault_id = var.kv_id
}

cd C:\GitHubCode\newazureadmodules\terraform-azuread-service-principal
terraform init -backend=false
terraform validate
terraform fmt -check

Outputs:

object_id = "9d44a0f2-...-7b21"
client_id = "b1e9...c0de"
display_name = "casey-loan-origination-api"
type = "Application"
tenant_id = "72f988bf-...-2d7cd011db47"
current_object_id = "0a7b...f31c"
password_key_ids = { "primary" = "a93c...0011" }
app_role_assignment_ids = { "graph_user_read_all" = "k3jf...Zx9" }
passwords = (sensitive value)
token_signing_certificate = {
 "key_id" = "5f2b...88a1"
 "thumbprint" = "A1B2C3D4E5F6..."
 "start_date" = "2026-06-18T00:00:00Z"
 "end_date" = "2027-06-18T00:00:00Z"
}