Edit

Edit Azure AD manifest

  • Article

Teams Toolkit now manages Azure Active Directory (Azure AD) application with the manifest file as the source of truth during your Teams application development lifecycle.

Customize Azure AD manifest template

You can customize Azure AD manifest template to update Azure AD application.

  1. Open aad.template.json in your project.

    Screenshot shows the template.

  2. Update the template directly or reference values from another file. Following are the customization scenarios:

    Add an application permission

    If the Teams application requires more permissions to call an API with additional permissions, you need to update requiredResourceAccess property in the Azure AD manifest template. You can see the following example for this property:

            "requiredResourceAccess": [
{
        "resourceAppId": "Microsoft Graph",
        "resourceAccess": [
            {
                "id": "User.Read", // For Microsoft Graph API, you can also use uuid for permission id
                "type": "Scope" // Scope is for delegated permission
            },
            {
                "id": "User.Export.All",
                "type": "Role" // Role is for application permission
            }
        ]
    },
    {
        "resourceAppId": "Office 365 SharePoint Online",
        "resourceAccess": [
            {
                    "id": "AllSites.Read",
            "type": "Scope"
            }
        ]
    }
]

    The following list provides different property IDs and their usage:

    • The resourceAppId property is used for different APIs. For Microsoft Graph and Office 365 SharePoint Online, enter the name directly instead of UUID, and for other APIs use UUID.

    • The resourceAccess.id property is used for different permissions. For Microsoft Graph and Office 365 SharePoint Online, enter the permission name directly instead of UUID, and for other APIs use UUID.

    • The resourceAccess.type property is used for delegated permission or application permission. Scope means delegated permission and Role means application permission.

    Pre-authorize a client application

    You can use preAuthorizedApplications property to authorize a client application to indicate that the API trusts the application. Users don't consent when the client calls exposed API. You can see the following example for this property:

    
      "preAuthorizedApplications": [
      {
          "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
          "permissionIds": [
               "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
           ]
      }
      ...
  ]

    preAuthorizedApplications.appId property is used for the application you want to authorize. If you don't know the application ID and know only the application name, use the following steps to search application ID:

    1. Go to Azure portal and open Application Registrations.

    2. Select All applications and search for the application name.

    3. Select the application name and get the application ID from the overview page.

    Update redirect URL for authentication response

    Redirect URLs are used while returning authentication responses such as tokens after successful authentication. You can customize redirect URLs using property replyUrlsWithType. For example, to add https://www.examples.com/auth-end.html as redirect URL, you can add it as the following example:

        "replyUrlsWithType": [
       ...
     {
         "url": "https://www.examples.com/auth-end.html",
         "type": "Spa"
     }
]

  3. Update Azure AD application changes for local or remote environment.

    1. Select Preview CodeLens in aad.template.json.

      Screenshot shows the preview.

    2. Select local or dev environment.

      Screenshot shows the environment list.

    3. Select Deploy Azure AD Manifest CodeLens in aad.local.json or aad.dev.json.

      Screenshot shows the deploy option highlighted.

    4. The changes for Azure AD application used in local or dev environment are deployed.

    5. Additionally, you can open the command palette and select Teams: Update Azure Active Directory App to update Azure AD app. Screenshot shows the Command Palette option.

Azure AD manifest template placeholders

The Azure AD manifest file contains placeholder arguments with {{...}} statements, it's replaced during build for different environments. You can reference to environment variables with the placeholder arguments.

Reference environment variable in Azure AD manifest template

You don't need to enter permanent values in Azure AD manifest template and Azure AD manifest template file supports reference environment variable values. You can use the syntax ${{YOUR_ENV_VARIABLE_NAME}} in the tool as parameter values to resolve the current environment variable values.

Edit and preview Azure AD manifest with CodeLens

Azure AD manifest template file has CodeLens to review and edit the code.

Azure AD manifest template file

There's a preview CodeLens at the beginning of the Azure AD manifest template file. Select the CodeLens to generate an Azure AD manifest based as per your environment.

Screenshot shows the preview of add codelens.

Placeholder argument CodeLens

Placeholder argument CodeLens helps you to see the values for local debug and develop your environment. If you hover the mouse on the placeholder argument, it shows tooltip box for the values of all the environments.

Screenshot shows the add arguments.

Required resource access CodeLens

Azure AD manifest template in Teams Toolkit also supports user readable strings for Microsoft Graph and Office 365 SharePoint Online permissions. The official Azure AD manifest schema, which is the resourceAppId and resourceAccess in requiredResourceAccess property supports only the UUID. If you enter UUID, the CodeLens shows user readable strings, otherwise it shows the UUID.

Screenshot shows the add resource to required resource access.

Pre-authorized applications CodeLens

CodeLens shows the application name for the pre-authorized application ID for the preAuthorizedApplications property.

View Azure AD application on the Azure portal

  1. Copy the Azure AD application client ID from .env.xxx () file in the AAD_APP_CLIENT_ID property.

    Screenshot shows the client ID.

    Note

    xxx in the client ID indicates the environment name where you have deployed the Azure AD application.

  2. Go to Azure portal and sign in to Microsoft 365 account.

    Note

    Ensure that login credentials of Teams application and M365 account are the same.

  3. Open App Registrations page and search the Azure AD application using client ID that you copied before.

    Screenshot shows the client ID under All applications tab.

  4. Select Azure AD application from search result to view the detailed information.

  5. In Azure AD app information page, select the Manifest menu to view manifest of this application. The schema of the manifest is same as the one in aad.template.json file. For more information about manifest, see Azure AD app manifest.

    Screenshot shows the Manifest screen.

  6. You can select Other Menu to view or configure Azure AD application through its portal.

Use an existing Azure AD application

You can use the existing Azure AD application for the Teams project. For more information, see use an existing Azure AD application for your Teams application.

Azure AD application in Teams application development lifecycle

You need to interact with Azure AD application during various stages of your Teams application development lifecycle.

  1. To create Project

    You can create a project with Teams Toolkit that comes with single sign-on (SSO) support by default such as SSO-enabled tab. For more information on how to create a new app, see create new Teams application using Teams Toolkit. An Azure AD manifest file is automatically created for you in aad.template.json. Teams Toolkit creates or updates the Azure AD application during local development or while you move the application to the cloud.

  2. To add SSO to your bot or tab

    After you create a Teams application without built-in SSO, Teams Toolkit progressively helps you to add SSO for the project. As a result, an Azure AD manifest file is automatically created for you in aad.template.json.

    Teams Toolkit creates or updates the Azure AD application during next local development session or while you move the application to the cloud.

  3. To build locally

    Teams Toolkit performs the following functions during local development:

    • Read the .env.local file to find an existing Azure AD application. If an Azure AD application already exists, Teams Toolkit reuses the existing Azure AD application. Otherwise, you need to create a new application using the aad.template.json file.

    • Initially ignores some properties in the manifest file that requires more context, such as replyUrls property that requires a local development endpoint during the creation of a new Azure AD application with the manifest file.

    • After the local dev environment starts successfully, the Azure AD application's identifierUris, replyUrls, and other properties that aren't available during creation stage are updated accordingly.

    • The changes you've done to your Azure AD application are loaded during next local development session. You can see Azure AD application changes applied manually.

  4. To provision for cloud resources

    You need to provision cloud resources and deploy your application while moving your application to the cloud. At stages, such as local debug, Teams Toolkit:

    • Reads the .env.{env} file to find an existing Azure AD application. If an Azure AD application already exists, Teams Toolkit reuses the existing Azure AD application. Otherwise, you need to create a new application using the aad.template.json file.

    • Ignores some properties in the manifest file initially that requires more context such as replyUrls property. This property requires frontend or bot endpoint during the creation of a new Azure AD application with the manifest file.

    • Completes other resources provision, then Azure AD application's identifierUris, and replyUrls are updated according to the correct endpoints.

  5. To build application

    • The cloud command deploys your application to the provisioned resources. It doesn't include deploying Azure AD application changes you've made.

    • Teams Toolkit updates the Azure AD application according to the Azure AD manifest template file.

Limitations

  1. Teams Toolkit extension doesn't support all the properties listed in Azure AD manifest schema.

    The following table lists the properties that aren't supported in Teams Toolkit extension:

    Not supported properties Reason
    passwordCredentials Not allowed in manifest
    createdDateTime Read-only and can't change
    logoUrl Read-only and can't change
    publisherDomain Read-only and can't change
    oauth2RequirePostResponse Doesn't exist in Graph API
    oauth2AllowUrlPathMatching Doesn't exist in Graph API
    samlMetadataUrl Doesn't exist in Graph API
    orgRestrictions Doesn't exist in Graph API
    certification Doesn't exist in Graph API

  2. Currently, requiredResourceAccess property is used for user readable resource application name or permission name strings only for Microsoft Graph and Office 365 SharePoint Online APIs. You need to use UUID for other APIs. Perform the following steps to retrieve IDs from Azure portal:

    1. Register a new Azure AD application on Azure portal.
    2. Select API permissions from the Azure AD application page.
    3. Select add a permission to add the permission you need.
    4. Select Manifest from the requiredResourceAccess property, where you can find the IDs of API, and the permissions.

See also