Use existing Entra app in TeamsFx

This section provides information for using existing Microsoft Entra app or manually creates Microsoft Entra app for TeamsFx project. Follow the instruction and make sure all required info is properly set in your TeamsFx project.

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:

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

3. When the app is registered, you're taken to the app's Overview page. Copy the Application (client) ID, Object ID, and Directory (tenant) ID; it's needed later. 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.

   • Description: The description of your client secret.
   • Expires: The expire time of your client secret.
   • 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.

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

2. On the same page, select Add a client application under Authorized client applications.

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

3. Select again on Add a client application.

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

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

Get necessary info from existing Microsoft Entra app

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

2. Select App Registrations 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. Verify that the Supported account types is set to My organization only.

4. 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, please follow the instruction to create a new client secret.

5. Go to apps Expose an API page. If you've already added access_as_user scope under Scopes defined by this API and pre-auth the two Teams Client Ids, go to app's Manifest page, copy the id under oauth2Permissions as Access As User Scope ID.

Set necessary info in TeamsFx project

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

2. Find the environment variable names that store information for Microsoft Entra app in the writeToEnvironmentFile property. Below are the default writeToenvironmentFile definition if you create projects using 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 below 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
      

   2. If your application requires a Microsoft Entra app client secret, add below 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 in the examples if you use different names in writeToEnvironmentFile.

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

Upload Microsoft Entra app manifest to Azure portal

If Teams Toolkit fails to update Microsoft Entra app, an error message appears:

Insufficient privileges to complete the operation.

If you see the above 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 in 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.