Use existing Entra app in TeamsFx

This section explains how to connect Microsoft Entra ID to your TeamsFx project, either by using an existing Entra app registration or creating a new one. Follow the steps to set the necessary authentication settings and TeamsFx values before you run or deploy your agent or app.

Create a Microsoft Entra app

1. Go to the Azure portal and select Microsoft Entra ID.

2. Select App Registrations > New registration to create a new Microsoft Entra app. Add the following details:

   1. Name: The name for your configuration app.
   2. Supported account types: Select Account in this organizational directory only.
   3. Leave the Redirect URL field blank for now.
   4. Select Register.

3. After the app is registered, you're taken to its Overview page. Copy the Application (client) ID, Object ID, and Directory (tenant) ID for later use. Verify that the Supported account types is set to My organization only.

Create client secret for Microsoft Entra app (optional)

1. Go to app's Certificates & secrets page, select Client Secret and select New client secret. Select the following details:

   1. Description: The description of your client secret.
   2. Expires: The expire time of your client secret.
   3. Select Add.

2. When the client secret is added, press the copy button under the Value column to copy the Client Secret.

Create access as user scope for Microsoft Entra app (optional)

1. Go to app's Expose an API page, select Add a scope under Scopes defined by this API, and following the given steps:

   1. Select Save and continue.
   2. Scope name: Fill in access_as_user.
   3. Who can consent?: Choose Admins and users.
   4. Admin consent display name: Fill in Teams can access app’s web APIs.
   5. Admin consent description: Fill in Allows Teams to call the app’s web APIs as the current user.
   6. User consent display name: Fill in Teams can access app’s web APIs and make requests on your behalf.
   7. User consent description: Fill in Enable Teams to call this app’s web APIs with the same rights that you have.
   8. State: Choose Enabled.
   9. Select Add scope.

2. On the same page, select Add a client application under Authorized client applications, and add the following details:

   1. Client ID: Fill in 1fec8e78-bce4-4aaf-ab1b-5451cc387264 which is Client ID for Microsoft Teams on mobile and client.
   2. Authorized scopes: Choose the existing access_as_user scope.
   3. Select Add application.

3. Select Add a client application and add the details:

   1. Client ID: Fill in 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 which is Client ID for Teams on web.
   2. Authorized scopes: Choose the existing access_as_user scope.
   3. Select Add application.

4. Go to app's Manifest page, copy the id under oauth2Permissions as Access As User Scope ID.

Get existing Microsoft Entra app information

If you have an already registered Azure app, you can reuse it in your TeamsFx project instead of creating a new registration. Before you start, capture the required configuration values from the existing app registration so you can add them to your TeamsFx project.

1. Go to the Azure portal and select Microsoft Entra ID.

2. Select App Registrations and and find your existing Microsoft Entra app.

3. Go to app's Overview page, copy the Application (client) ID, Object ID, and Directory (tenant) ID; it's needed later.

4. Verify that the Supported account types is set to My organization only.

5. Go to app's Overview page, copy the Application (client) ID, Object ID, and Directory (tenant) ID for later use. Verify that the Supported account types is set to My organization only.

6. Go to app's Certificates & secrets page, press the copy button under the Value column to copy the Client Secret.

   Note

   If you can't copy the secret, follow the instructions to create a new client secret.

7. Go to app's Expose an API page. If the access_as_user scope is already defined and the two Teams client IDs are pre-authorized, open Manifest and copy the id value under oauth2Permissions and enter it as the Access As User Scope ID.

Set Entraa app information in TeamsFx project

Add the information you saved from the Microsoft Entra app to your TeamsFx project.

1. Open m365agents.yml and find the aadApp/create action.

2. Find the environment variable names that store information for Microsoft Entra app in the writeToEnvironmentFile property. Following are the default writeToenvironmentFile definitions if you create projects using Microsoft 365 Agents Toolkit (previously known as Teams Toolkit):

    writeToEnvironmentFile:
      clientId: AAD_APP_CLIENT_ID
      clientSecret: SECRET_AAD_APP_CLIENT_SECRET
      objectId: AAD_APP_OBJECT_ID
      tenantId: AAD_APP_TENANT_ID
      authority: AAD_APP_OAUTH_AUTHORITY
      authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST
   

3. Add values for each environment variable from step 2.

   1. Add the following environment variables and their values to env\.env.{env} file.

      AAD_APP_CLIENT_ID=<value of Microsoft Entra application's client id (application id)> # example: 00000000-0000-0000-0000-000000000000
      AAD_APP_OBJECT_ID=<value of Microsoft Entra application's object id> # example: 00000000-0000-0000-0000-000000000000
      AAD_APP_TENANT_ID=<value of Microsoft Entra's (tenant) id> # example: 00000000-0000-0000-0000-000000000000
      AAD_APP_OAUTH_AUTHORITY=<value of Microsoft Entra's authority> # example: https://login.microsoftonline.com/<Directory (tenant) ID>
      AAD_APP_OAUTH_AUTHORITY_HOST=<host of Microsoft Entra's authority> # example: https://login.microsoftonline.com
      AAD_APP_ACCESS_AS_USER_PERMISSION_ID=<id of access_as_user permission> # example: 00000000-0000-0000-0000-000000000000
      

      AAD_APP_OAUTH_AUTHORITY_HOST is the Microsoft Entra authority host (for example, https://login.microsoftonline.com) that your agent or bot uses as the OAuth 2.0 sign-in endpoint. For environment-specific endpoints, see Microsoft Entra authentication endpoints.

   2. If your agent or app requires a Microsoft Entra app client secret, add the following environment variable and its value to env\.env.{env}.user file.

      SECRET_AAD_APP_CLIENT_SECRET=<value of Microsoft Entra application's client secret>
      

      Note

      Remember to update the environment variable names given in the examples if you use different names in writeToEnvironmentFile.

4. Open the Agents Toolkit extension and select Provision in the cloud. Wait until your project is successfully provisioned.

Upload Microsoft Entra app manifest to Azure portal

If Agents Toolkit doesn't update the Microsoft Entra app, an error message appears:

Insufficient privileges to complete the operation.

If you see this message, update Microsoft Entra app permission and follow the instructions to update permission.

1. Find the Microsoft Entra app manifest under build/aad.manifest.{env}.json.

2. Copy the content from the manifest file.

3. Go to the Azure portal and select Microsoft Entra ID.

4. Select App Registrations and find your existing Microsoft Entra app.

5. Go to app's Manifest page, paste the manifest content into the editor and select Save to save the changes.

See also

• Build your first agent
• Create a new Teams app