# Configure Entra ID client credentials

An app that acquires tokens for itself, or that redeems authorization codes, is a confidential client and needs a client credential. An API that only validates incoming tokens needs none. Each credential method appends an entry to the `ClientCredentials` array that referencing apps receive, such as `AzureAd__ClientCredentials__0__SourceType`. You can configure more than one credential to form a fallback chain.

Aspire doesn't create, store, or rotate client secrets or certificates for you, except for the [local developer certificate](#local-developer-certificate). The other methods describe a secret or certificate that already exists. Managed identity federation uses no secret or certificate. Aspire creates only the federated credential that establishes trust.

## Choose a credential

| Credential | Method | Registrations | Applies when |
| ---------- | ------ | ------------- | ------------ |
| Local developer certificate | `RunWithLocalDeveloperCertificateCredential` | Created | Running |
| Managed identity that Aspire trusts | `PublishWithFederatedManagedIdentityCredential` | Created | Publishing |
| Client secret | `WithClientSecret` | Created and existing | Running and publishing |
| Managed identity that you configured | `WithFederatedManagedIdentityCredential` | Created and existing | Running and publishing |
| Key Vault certificate | `WithCertificateFromKeyVault` | Created and existing | Running and publishing |
| Certificate store | `WithCertificateThumbprint`, `WithCertificateDistinguishedName` | Created and existing | Running and publishing |
| Certificate file or signed assertion file | TypeScript: `withCertificateFromFile`, `withSignedAssertionFile`. C#: `WithCredential` | Created and existing | Running and publishing |

## Local developer certificate

For registrations that Aspire creates, opt in to a short-lived local certificate instead of copying a client secret. Aspire creates the certificate, registers only its public key with Microsoft Entra ID, and passes the private key to referencing apps.

Combine the method with [managed identity federation](#managed-identity-federation) so the app has a credential both locally and when deployed. The local method does nothing when you publish.

```typescript title="apphost.mts"
const entraWeb = await builder.addEntraIdApplication("entra-web")
    .runWithLocalDeveloperCertificateCredential()
    .publishWithFederatedManagedIdentityCredential();

const web = await builder.addDotnetProject("web", "../Web/Web.csproj");
await web.withReference(entraWeb);
```

```csharp title="AppHost.cs"
var entraWeb = builder.AddEntraIdApplication("entra-web")
    .RunWithLocalDeveloperCertificateCredential()
    .PublishWithFederatedManagedIdentityCredential();

builder.AddDotnetProject("web", "../Web/Web.csproj")
    .WithReference(entraWeb);
```

:::caution[Use separate development and production registrations]
Give each developer a distinct `Azure:TenantResourceSuffix`, and use a different suffix or registration name for production. Registrations are tenant-scoped, so different resource groups don't isolate them. The suffix is empty by default, so a run without one targets the registration whose `uniqueName` matches the resource name. Never use a production registration with this feature. If you can, use a separate development tenant.

If a run reaches a production registration, it replaces that registration's certificate credentials, which breaks apps that use them, and the local private key can authenticate as the production app. Publishing doesn't remove the developer key. [Delete the certificate credential](/integrations/security/microsoft-entra-id/lifecycle-and-permissions/#revoke-what-remains) yourself.
:::

- The certificate is valid for 48 hours. Aspire renews it when the AppHost starts and 24 hours or less remain. There's no background renewal, so restart long development sessions before the certificate expires.
- Aspire stores the certificate, including its private key, at `dev-certs/Entra/<resource-name>.pfx` in the AppHost's Aspire store. The file isn't password protected. File system permissions limit access to your user account, so any process that runs as you can read it. Aspire doesn't delete the file when you remove the call or the resource. Delete the file to discard the local credential.
- Each run replaces all certificate credentials on the registration with the current certificate. Don't add other certificates to a development registration, and restart sessions that use the old certificate after a renewal.
- Referencing apps receive the certificate as a base64-encoded secret in `ClientCredentials`, with `SourceType` set to `Base64Encoded`. Base64 isn't encryption, so don't log the value.
- The identity that provisions the registration needs the delegated `Application.ReadWrite.All` permission, or `Application.ReadWrite.OwnedBy` for a registration that it owns. For more information, see [Required permissions](/integrations/security/microsoft-entra-id/lifecycle-and-permissions/#required-permissions).
- Deleting the Azure resource group doesn't delete the registration. For more information, see [Clean up registrations](/integrations/security/microsoft-entra-id/lifecycle-and-permissions/#clean-up-registrations).

## Managed identity federation

For deployed apps, use a federated identity credential so that no secret is stored. The registration trusts a user-assigned managed identity, and the app authenticates as the registration by using that identity.

### Create the trust for a registration that Aspire creates

`PublishWithFederatedManagedIdentityCredential` makes the registration trust the managed identity of each app that references it.

```typescript title="apphost.mts"
const entraWeb = await builder.addEntraIdApplication("entra-web")
    .publishWithFederatedManagedIdentityCredential();

const web = await builder.addDotnetProject("web", "../Web/Web.csproj");
await web.withReference(entraWeb);
```

```csharp title="AppHost.cs"
var entraWeb = builder.AddEntraIdApplication("entra-web")
    .PublishWithFederatedManagedIdentityCredential();

builder.AddDotnetProject("web", "../Web/Web.csproj")
    .WithReference(entraWeb);
```

Referencing the registration makes the app need a user-assigned managed identity when published, the same way that referencing an Azure resource does. The app uses the identity it already has, for example from `WithAzureUserAssignedIdentity`. Otherwise the Azure environment creates one, which requires a compute environment that supports managed identities such as `AddAzureContainerAppEnvironment`.

For each trusted identity, Aspire adds a federated credential to the registration, and the app receives the identity's client ID as `ManagedIdentityClientId`. Managed identity federation supports the Azure public, US Government, and China clouds.

Managed identities exist only in Azure, so this method has no effect when you run the AppHost. Use the local developer certificate or another credential for local development.

### Trust specific apps or identities

Pass a compute resource or a user-assigned identity to limit the trust. A compute resource that you pass must also reference the registration, and only that resource receives the credential.

```typescript title="apphost.mts"
// Trust one app.
const entraWeb = await builder.addEntraIdApplication("entra-web");
const web = await builder.addDotnetProject("web", "../Web/Web.csproj");
await web.withReference(entraWeb);
await entraWeb.publishWithFederatedManagedIdentityCredential({ identity: web });

// Trust one explicit identity.
const identity = await builder.addAzureUserAssignedIdentity("web-identity");
const entraAdmin = await builder.addEntraIdApplication("entra-admin")
    .publishWithFederatedManagedIdentityCredential({ identity });

const admin = await builder.addDotnetProject("admin", "../Admin/Admin.csproj");
await admin.withAzureUserAssignedIdentity(identity);
await admin.withReference(entraAdmin);
```

```csharp title="AppHost.cs"
// Trust one app.
var entraWeb = builder.AddEntraIdApplication("entra-web");
var web = builder.AddDotnetProject("web", "../Web/Web.csproj")
    .WithReference(entraWeb);

entraWeb.PublishWithFederatedManagedIdentityCredential(web);

// Trust one explicit identity.
var identity = builder.AddAzureUserAssignedIdentity("web-identity");
var entraAdmin = builder.AddEntraIdApplication("entra-admin")
    .PublishWithFederatedManagedIdentityCredential(identity);

builder.AddDotnetProject("admin", "../Admin/Admin.csproj")
    .WithAzureUserAssignedIdentity(identity)
    .WithReference(entraAdmin);
```

With an explicit identity, every app that references the registration must use that identity. Publishing fails with an error that names the app if a trusted app has no managed identity or doesn't use the identity that the registration trusts.

The federated credential only changes how the app authenticates as itself. Interactive user sign-in still needs a [redirect URI](/integrations/security/microsoft-entra-id/redirect-uris-and-sign-in/) registered on the registration. Derive it from the web app's endpoint with `WithRedirectUris`, which uses the compute environment's host when deployed.

### Use a managed identity trust that you created

`PublishWithFederatedManagedIdentityCredential` throws for [existing registrations](/integrations/security/microsoft-entra-id/existing-registrations/). For those, create the trust yourself, then call `WithFederatedManagedIdentityCredential` with the managed identity's client ID. This method only configures the app, and it applies when you run locally as well as when you publish.

```typescript title="apphost.mts"
await entraWeb.withFederatedManagedIdentityCredential("00001111-aaaa-2222-bbbb-3333cccc4444");
```

```csharp title="AppHost.cs"
entraWeb.WithFederatedManagedIdentityCredential("00001111-aaaa-2222-bbbb-3333cccc4444");
```

Add a federated credential to the registration with these values. Otherwise, token requests fail with `AADSTS700213`.

- Set the issuer to the tenant's v2.0 endpoint, which is `https://login.microsoftonline.com/{tenantId}/v2.0` in the Azure public cloud.
- Set the subject to the identity's principal ID, also called its object ID.
- Set the audience to the token exchange audience of the cloud, which is `api://AzureADTokenExchange` in the Azure public cloud.

Pass the identity's client ID, not its principal ID, to `WithFederatedManagedIdentityCredential`. In other clouds, also set the token exchange audience, and the token exchange authority if it differs from the app's authority. In TypeScript, pass an options object such as `{ tokenExchangeUrl: "api://AzureADTokenExchangeUSGov" }` that can also contain `tokenExchangeAuthority`. In C#, create an `EntraIdFederatedIdentityCredential` with the identity's client ID, set its `TokenExchangeUrl` and `TokenExchangeAuthority` properties, and pass it to `WithCredential` instead. For more information, see [Configure an application to trust a managed identity](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-config-app-trust-managed-identity).

Federation authenticates as the app registration by using a managed identity assertion. To acquire a token directly as the managed identity instead, see [Application roles](/integrations/security/microsoft-entra-id/app-roles/).

## Client secret

`WithClientSecret` passes a secret parameter to the app. The parameter must be created as a secret.

```typescript title="apphost.mts"
import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const tenantId = await builder.addParameter("entra-tenant-id");
const webClientId = await builder.addParameter("entra-web-client-id");
const webSecret = await builder.addParameter("entra-web-secret", { secret: true });

const entraWeb = await builder.addExistingEntraIdApplication("entra-web", tenantId, webClientId);
await entraWeb.withClientSecret(webSecret);

await builder.build().run();
```

```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var tenantId = builder.AddParameter("entra-tenant-id");
var webClientId = builder.AddParameter("entra-web-client-id");
var webSecret = builder.AddParameter("entra-web-secret", secret: true);

var entraWeb = builder.AddExistingEntraIdApplication("entra-web", tenantId, webClientId)
    .WithClientSecret(webSecret);

// After adding all resources, run the app...
builder.Build().Run();
```

## Certificate from Azure Key Vault

Reference a Key Vault that you model in the AppHost instead of hard-coding its URL. This requires the [Azure Key Vault hosting integration](/integrations/cloud/azure/azure-key-vault/azure-key-vault-host/). This example continues the [client secret](#client-secret) example, which defines `tenantId` and `webClientId`.

```typescript title="apphost.mts"
const vault = await builder.addAzureKeyVault("vault");

const entraWeb = await builder.addExistingEntraIdApplication("entra-web", tenantId, webClientId)
    .withCertificateFromKeyVault(vault, "MyCert");

const web = await builder.addDotnetProject("web", "../Web/Web.csproj");
await web.withReference(entraWeb);
```

```csharp title="AppHost.cs"
var vault = builder.AddAzureKeyVault("vault");

var entraWeb = builder.AddExistingEntraIdApplication("entra-web", tenantId, webClientId)
    .WithCertificateFromKeyVault(vault, "MyCert");

builder.AddDotnetProject("web", "../Web/Web.csproj")
    .WithReference(entraWeb);
```

The certificate must already exist in the vault with an exportable private key, and its public key must already be registered on the Entra ID application. This helper doesn't create the certificate or upload the public key. Microsoft.Identity.Web always retrieves the latest certificate version and has no setting to select a specific one.

### Role assignments for certificate access

Reading the certificate requires the **Key Vault Certificate User** role, which Aspire grants automatically when you pass a Key Vault resource:

- When you run the AppHost, Aspire grants the role to your developer identity.
- When you publish, Aspire grants the role to every app that references the Entra ID application. The publish target must support role assignments, such as `AddAzureContainerAppEnvironment`. Otherwise publishing fails with a "does not support role assignments" error.

:::caution[Use a dedicated vault for Entra ID certificates]
The role is assigned on the whole vault, not on one certificate. It lets each identity that receives it read every certificate in the vault and retrieve private keys for exportable certificates. Keep Entra ID client certificates in a vault that holds nothing else, or manage the role assignments yourself.
:::

To manage the roles yourself:

- When you publish, call `WithRoleAssignments` for the vault on an app before it references the Entra ID application. Explicit assignments replace the automatic one, and an empty role list grants none.
- When you run locally, call `ClearDefaultRoleAssignments` on the vault before `WithCertificateFromKeyVault`, and assign roles yourself.

For more information, see [Azure role assignments](/integrations/cloud/azure/role-assignments/).

You can model an existing vault with `RunAsExisting` or `PublishAsExisting`. Its access policies or RBAC configuration must allow certificate retrieval.

### Use a vault URL

When the vault is managed outside the AppHost, pass its URL instead. Aspire grants no roles in this case, so configure access and identity yourself.

```typescript title="apphost.mts"
await entraWeb.withCertificateFromKeyVault("https://myvault.vault.azure.net", "MyCert");
```

```csharp title="AppHost.cs"
entraWeb.WithCertificateFromKeyVault("https://myvault.vault.azure.net", "MyCert");
```

## Certificate from the certificate store

Use a thumbprint or a distinguished name to locate a certificate in the store on the machine that runs the app.

```typescript title="apphost.mts"
await entraWeb.withCertificateThumbprint("CurrentUser/My", "ABC123...");

// Or locate the certificate by subject.
await entraWeb.withCertificateDistinguishedName("CurrentUser/My", "CN=MyCert");
```

```csharp title="AppHost.cs"
entraWeb.WithCertificateThumbprint("CurrentUser/My", "ABC123...");

// Or locate the certificate by subject.
entraWeb.WithCertificateDistinguishedName("CurrentUser/My", "CN=MyCert");
```

## Certificate file or signed assertion file

The file paths identify files on the referencing app's file system, not files that the AppHost reads. A certificate password must be a secret parameter. File credentials aren't recommended for production.

```typescript title="apphost.mts"
const certificatePassword = await builder.addParameter("certificate-password", { secret: true });

await entraWeb.withCertificateFromFile("/certs/client.pfx", { password: certificatePassword });
await entraWeb.withSignedAssertionFile({ filePath: "/tokens/assertion" });
```

```csharp title="AppHost.cs"
using Aspire.Hosting.Azure;

var certificatePassword = builder.AddParameter("certificate-password", secret: true);

entraWeb
    .WithCredential(new EntraIdFileCertificateCredential
    {
        FilePath = "/certs/client.pfx",
        Password = certificatePassword.Resource
    })
    .WithCredential(new EntraIdSignedAssertionFileCredential { FilePath = "/tokens/assertion" });
```

Omit the file path of a signed assertion file to use the referencing app's `AZURE_FEDERATED_TOKEN_FILE` setting. In C#, use `WithCredential` for credential types that don't have a dedicated method.

## Send the certificate chain

`WithSendX5C` sends the `x5c` claim, which carries the public certificate, with token requests. Entra ID can then validate the certificate by subject name and issuer, which simplifies certificate rollover. This works only when the registration trusts the certificate's subject name and issuer. Otherwise, Entra ID accepts only certificates registered on the application. `WithSendX5C` applies only to certificate-based credentials and increases the size of each token request, so it's opt-in.

```typescript title="apphost.mts"
await entraWeb.withSendX5C();
```

```csharp title="AppHost.cs"
entraWeb.WithSendX5C();
```

## See also

- [Existing registrations](/integrations/security/microsoft-entra-id/existing-registrations/)
- [Lifecycle and permissions](/integrations/security/microsoft-entra-id/lifecycle-and-permissions/)
- [Azure Key Vault integration](/integrations/cloud/azure/azure-key-vault/azure-key-vault-host/)
- [Certificate credentials](https://learn.microsoft.com/entra/identity-platform/certificate-credentials)
- [Update application (Microsoft Graph)](https://learn.microsoft.com/graph/api/application-update)