Review or update agent runtime authentication configuration

To interact with Teams, an agent's runtime must authenticate to Agent Communications Service (ACS). The agent authenticates using credentials configured on the Entra ID app registration that is linked to its ACS registration.

The configuration described in this article is related only to agent runtime authentication that is required of all Teams agents. For information about configuring and implementing single sign-on (SSO) or OAuth to authenticate users of an agent and allow them to delegate permissions, see Authenticate users in Microsoft Teams.

The project creation workflow supported by the Teams developer CLI creates all of the configuration covered here. This article can help you to inspect or modify it as needed.

Supported credential types

Teams agent runtimes can authenticate to ACS using two different kinds of credentials:

  • Client secret: A client secret (sometimes called an application password) is configured in the environment variables of the runtime's hosting environment, or in the runtime's deployed configuration file.
  • Managed identities for Azure resources: Requires the agent runtime to be hosted in Azure. The runtime authenticates using a credential securely associated with its Azure hosting environment. Managed identity eliminates the need to handle and secure a client secret. See Managed identities for Azure resources for general information.

Beginning with version 2.1, Teams SDK for .NET authenticates to ACS using the Microsoft Authentication Library (MSAL) and can use any of its supported credential types. See Supported credential types for more information.

By default, new agents created using the Teams developer CLI or the Teams Developer Portal are configured for client secret authentication. For agent runtimes hosted on an Azure compute service, such as Azure App Service, Azure Kubernetes Service, or Azure Virtual Machines, updating your configuration to use a managed identity instead is strongly recommended.

Review or update configuration

Configure the Entra ID app registration

A credential must be associated with agent's Entra ID app registration to enable its use for runtime authentication. To review or update the credentials configured on the agent's Entra ID app registration, see Add and manage app credentials in Microsoft Entra ID.

To use a managed identity for authentication, follow the linked instructions to configure it as a federated identity credential.

Client secrets for an app registration can also be created in Teams Developer Portal or via teams app auth secret create.

Configure the agent runtime

Teams SDK reads runtime configuration information from environment variables. By default, the Teams developer CLI creates projects that will load these values from a .env file on startup.

Set environment variables as follows, depending on the type of authentication credential used:

Authentication type Environment variables
Client secret CLIENT_ID=<app registration client ID>
CLIENT_SECRET=<client secret>
TENANT_ID=<Entra tenant ID>
System-assigned Azure managed identity (via federated identity credentials) CLIENT_ID=<app registration client ID>
MANAGED_IDENTITY_CLIENT_ID=system
TENANT_ID=<Entra tenant ID>
User-assigned Azure managed identity (via federated identity credentials) CLIENT_ID=<app registration client ID>
MANAGED_IDENTITY_CLIENT_ID=<managed identity client ID>
TENANT_ID=<Entra tenant ID>

Beginning with version 2.1, Teams SDK for .NET uses the standard Microsoft.Identity.Web configuration structure in an appsettings.json file for credential configuration. See Configure credentials in appsettings.json for detailed guidance.

Examples:

{
  "AzureAd": {
    "ClientId": <app registration client ID>,
    "TenantId": <tenant ID>,
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": <client secret>
      }
    ]
  }
}

Legacy user-assigned managed identity configuration

Agents that use an Azure AI Bot Service resource configured with the legacy User-Assigned Managed Identity bot type require the following environment variables:

CLIENT_ID=<app registration client ID>
TENANT_ID=<Entra tenant ID>

Agents that use an Azure AI Bot Service resource configured with the legacy User-Assigned Managed Identity bot type require the following configuration:

{
  "AzureAd": {
    "ClientId": "your-client-id-here",
    "TenantId": "your-tenant-id"
  }
}

See About Azure AI Bot Service bot type for more information.

ACS authentication troubleshooting

Missing service principal in tenant

This error occurs when the application has a single-tenant Azure Bot Service (msaAppType: 'SingleTenant') instance, but your app registration has not yet been linked to a Service Principal in the tenant.

[ERROR] Echobot Failed to get bot token on app startup.
[ERROR] Echobot {
[ERROR] Echobot   "error": "invalid_client",
[ERROR] Echobot   "error_description": "AADSTS7000229: The client application 00001111-aaaa-2222-bbbb-3333cccc4444 is missing service principal in the tenant aaaabbbb-0000-cccc-1111-dddd2222eeee. See instructions here: https://go.microsoft.com/fwlink/?linkid=2225119 Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2025-09-18 02:26:20Z",
[ERROR] Echobot   "error_codes": [
[ERROR] Echobot     7000229
[ERROR] Echobot   ],
[ERROR] Echobot   "timestamp": "2025-09-18 02:26:20Z",
[ERROR] Echobot   "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
[ERROR] Echobot   "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
[ERROR] Echobot   "error_uri": "https://login.microsoftonline.com/error?code=7000229"
[ERROR] Echobot }

[ERROR] @teams/app Request failed with status code 401
[ERROR] @teams/app /aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/token
[ERROR] @teams/app {
[ERROR] @teams/app   "error": "invalid_client",
[ERROR] @teams/app   "error_description": "AADSTS7000229: The client application 00001111-aaaa-2222-bbbb-3333cccc4444 is missing service principal in the tenant aaaabbbb-0000-cccc-1111-dddd2222eeee. See instructions here: https://go.microsoft.com/fwlink/?linkid=2225119 Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2025-09-18 01:17:37Z",
[ERROR] @teams/app   "error_codes": [
[ERROR] @teams/app     7000229
[ERROR] @teams/app   ],
[ERROR] @teams/app   "timestamp": "2025-09-18 01:17:37Z",
[ERROR] @teams/app   "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
[ERROR] @teams/app   "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
[ERROR] @teams/app   "error_uri": "https://login.microsoftonline.com/error?code=7000229"
[ERROR] @teams/app }

[ERROR] @teams/app Failed to refresh bot token: Client error '401 Unauthorized' for url 'https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/token'
[ERROR] @teams/app For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401

To solve this problem, create a service principal:

  1. Sign in to Azure Portal Go to https://portal.azure.com and log in with your Azure account.

  2. Navigate to App Registrations In the top search bar, search for App registrations and select it.

  3. Search for your application Use the BOT_ID from your environment file:

    • Local development → env/.env.local
    • Azure deployment → env/.env.dev

  4. Check if a Service Principal exists Open the app registration and verify if a Service Principal is created. If it exists already, you should see an entry for a Managed Application in your local directory.

  5. Create a Service Principal if missing If it doesn't exist, click Create Service Principal. Wait for the page to finish loading.

  6. Restart your app Once the Service Principal is created, restart your application.

See also

For more information about how Teams SDK authenticates inbound communications from ACS, see Teams SDK incoming request authentication.

  • Last updated on