Resource-specific consent

Note

Resource-specific consent for chat scope is available in public developer preview only.

Resource-specific consent (RSC) is a Microsoft Teams and Microsoft Graph API integration that enables your app to use API endpoints to manage specific resources, either teams or chats, within an organization. The RSC permissions model enables team owners and chat owners to grant consent for an application to access and modify a team's data and a chat's data, respectively.

Note: If a chat has a meeting or a call associated with it, then the relevant RSC permissions apply to those resources as well.

Resource-specific permissions

The granular, Teams-specific, RSC permissions define what an application can do within a specific resource.

Resource-specific permissions for a team

Application permission Action
TeamSettings.Read.Group Get this team's settings.
TeamSettings.ReadWrite.Group Update this team's settings.
ChannelSettings.Read.Group Get this team's channel names, channel descriptions, and channel settings​.
ChannelSettings.ReadWrite.Group Update this team's channel names, channel descriptions, and channel settings.​
Channel.Create.Group Create channels in this team.
Channel.Delete.Group Delete channels in this team.
ChannelMessage.Read.Group Get this team's channel messages.
TeamsAppInstallation.Read.Group Get a list of this team's installed apps.
TeamsTab.Read.Group Get a list of this team's tabs.
TeamsTab.Create.Group Create tabs in this team.
TeamsTab.ReadWrite.Group Update this team's tabs.
TeamsTab.Delete.Group Delete this team's tabs.
TeamMember.Read.Group Get this team's members.
TeamsActivity.Send.Group Create new notifications in the activity feeds of the users in this team.

For more details, see team resource-specific consent permissions.

Resource-specific permissions for a chat

The following table provides resource-specific permissions for a chat:

Application permission Action
ChatSettings.Read.Chat Get this chat's settings.
ChatSettings.ReadWrite.Chat Update this chat's settings.
ChatMessage.Read.Chat Get this chat's messages.
ChatMember.Read.Chat Get this chat's members.
Chat.Manage.Chat Manage this chat.
TeamsTab.Read.Chat Get this chat's tabs.
TeamsTab.Create.Chat Create tabs in this chat.
TeamsTab.Delete.Chat Delete this chat's tabs.
TeamsTab.ReadWrite.Chat Manage this chat's tabs.
TeamsAppInstallation.Read.Chat Get which apps are installed in this chat.
OnlineMeeting.ReadBasic.Chat Read basic properties, such as name, schedule, organizer, join link, and start/end notifications, of a meeting associated with this chat.
Calls.AccessMedia.Chat Access media streams in calls associated with this chat or meeting.
Calls.JoinGroupCalls.Chat Join calls associated with this chat or meeting.
TeamsActivity.Send.Chat Create new notifications in the activity feeds of the users in this chat.

For more details, see chat resource-specific consent permissions.

Note

Resource-specific permissions are only available to Teams apps installed on the Teams client and are currently not part of the Azure Active Directory (AAD) portal.

Enable RSC in your application

  1. Configure consent settings in the AAD portal.
    1. Configure group owner consent settings for RSC in a team.
    2. Configure user consent settings for RSC in a chat.
  2. Register your app with Microsoft identity platform using the AAD portal.
  3. Review your application permissions in the AAD portal.
  4. Obtain an access token from the identity platform.
  5. Update your Teams app manifest.
  6. Install your app directly in Teams.
  7. Check your app for added RSC permissions.
    1. Check your app for added RSC permissions in a team.
    2. Check your app for added RSC permissions in a chat.

You can enable or disable group owner consent directly within the Azure portal:

  1. Sign in to the Azure portal as a Global Administrator or Company Administrator.

  2. Select Azure Active Directory > Enterprise applications > Consent and permissions > User consent settings.

  3. Enable, disable, or limit user consent with the control labeled Group owner consent for apps accessing data. The default is Allow group owner consent for all group owners. For a team owner to install an app using RSC, group owner consent must be enabled for that user.

    Azure RSC team configuration

In addition, you can enable or disable group owner consent using PowerShell, follow the steps outlined in configure group owner consent using PowerShell.

You can enable or disable user consent directly within the Azure portal:

  1. Sign in to the Azure portal as a Global Administrator or Company Administrator.

  2. Select Azure Active Directory > Enterprise applications > Consent and permissions > User consent settings.

  3. Enable, disable, or limit user consent with the control labeled User consent for applications. The default is Allow user consent for apps. For a chat member to install an app using RSC, user consent must be enabled for that user.

    Azure RSC chat configuration

In addition, you can enable or disable user consent using PowerShell, follow the steps outlined in configure user consent using PowerShell.

Register your app with Microsoft identity platform using the AAD portal

The AAD portal provides a central platform for you to register and configure your apps. Your app must be registered in the AAD portal to integrate with the identity platform and call Microsoft Graph APIs. For more information, see register an application with the identity platform.

Warning

An AAD app ID must not be shared across multiple Teams apps. There must be a 1:1 mapping between a Teams app and an AAD app. Attempts to install multiple Teams apps which are associated with the same AAD app ID will cause installation or runtime failures.

Review your application permissions in the AAD portal

  1. Go to the Home > App registrations page and select your RSC app.
  2. Choose API permissions from the left pane and go through the list of Configured permissions for your app. If your app only makes RSC Graph API calls, delete all the permissions on that page. If your app also makes non-RSC calls, keep those permissions as required.

Important

The AAD portal cannot be used to request RSC permissions. RSC permissions are currently exclusive to Teams applications installed in the Teams client and are declared in the Teams app manifest (JSON) file.

Obtain an access token from the Microsoft identity platform

To make Graph API calls, you must obtain an access token for your app from the identity platform. Before your app can get a token from the identity platform, it must be registered in the AAD portal. The access token contains information about your app and the permissions it has for the resources and APIs available through Microsoft Graph.

You must have the following values from the AAD registration process to retrieve an access token from the identity platform:

  • The Application ID assigned by the app registration portal. If your app supports single sign-on (SSO) you must use the same Application ID for your app and SSO.
  • The Client secret/password or a public or private key pair that is Certificate. This is not required for native apps.
  • A Redirect URI or reply URL for your app to receive responses from AAD.

For more information, see get access on behalf of a user and get access without a user.

Update your Teams app manifest

The RSC permissions are declared in your app manifest JSON file. Add a webApplicationInfo key to your app manifest with the following values:

Name Type Description
id String Your AAD app ID. For more information, see register your app in the AAD portal.
resource String This field has no operation in RSC, but must be added and have a value to avoid an error response; any string will do.
applicationPermissions Array of strings RSC permissions for your app. For more information, see resource-specific permissions.

Important

Non-RSC permissions are stored in the Azure portal. Do not add them to the app manifest.

Example for RSC in a team

"webApplicationInfo": {
    "id": "XXxxXXXXX-XxXX-xXXX-XXxx-XXXXXXXxxxXX",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
        "TeamSettings.Read.Group",
        "TeamSettings.ReadWrite.Group",
        "ChannelSettings.Read.Group",
        "ChannelSettings.ReadWrite.Group",
        "Channel.Create.Group",
        "Channel.Delete.Group",
        "ChannelMessage.Read.Group",
        "TeamsAppInstallation.Read.Group",
        "TeamsTab.Read.Group",
        "TeamsTab.Create.Group",
        "TeamsTab.ReadWrite.Group",
        "TeamsTab.Delete.Group",
        "TeamMember.Read.Group",
        "TeamsActivity.Send.Group"
    ]
  }

Example for RSC in a chat

"webApplicationInfo": {
    "id": "XXxxXXXXX-XxXX-xXXX-XXxx-XXXXXXXxxxXX",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
        "ChatSettings.Read.Chat",
        "ChatSettings.ReadWrite.Chat",
        "ChatMessage.Read.Chat",
        "ChatMember.Read.Chat",
        "Chat.Manage.Chat",
        "TeamsTab.Read.Chat",
        "TeamsTab.Create.Chat",
        "TeamsTab.Delete.Chat",
        "TeamsTab.ReadWrite.Chat",
        "TeamsAppInstallation.Read.Chat",
        "OnlineMeeting.ReadBasic.Chat",
        "Calls.AccessMedia.Chat",
        "Calls.JoinGroupCalls.Chat",
        "TeamsActivity.Send.Chat"
    ]
  }

Note

If the app is meant to support installation in both team and chat scopes, then both team and chat permissions can be specified in the same manifest under applicationPermissions.

Sideload your app in Teams

If your Teams admin allows custom app uploads, you can sideload your app directly to a specific team or chat.

Check your app for added RSC permissions

Important

The RSC permissions are not attributed to a user. Calls are made with app permissions, not user delegated permissions. The app can be allowed to perform actions that the user cannot, such as deleting a tab. You must review the team owner's or chat owner's intent for your use before making RSC API calls. For more information, see Microsoft Teams API overview.

After the app has been installed to a resource, you can use Graph Explorer to view the permissions that have been granted to the app in the resource.

Check your app for added RSC permissions in a team

  1. Get the team's groupId from Teams.

  2. In Teams, select Teams from the leftmost pane.

  3. Select the team where the app is to be installed.

  4. Select the ellipses ●●● for that team.

  5. Select Get link to team from the team drop-down menu.

  6. Copy and save the groupId value from the Get a link to the team pop-up dialog box.

  7. Sign in to Graph Explorer.

  8. Make a GET call to this endpoint: https://graph.microsoft.com/beta/teams/{teamGroupId}/permissionGrants. The clientAppId field in the response will map to the webApplicationInfo.id specified in the Teams app manifest.

    Graph explorer response to GET call for team RSC permissions

For more information on how to get details of the apps installed in a specific team, see get the names and other details of apps installed in the specified team.

Check your app for added RSC permissions in a chat

  1. Get the chat thread ID from the Teams web client.

  2. In the Teams web client, select Chat from the leftmost pane.

  3. Select the chat where the app is installed from the drop-down menu.

  4. Copy the web URL and save the chat thread ID from the string.

    Chat thread ID from web URL

  5. Sign in to Graph Explorer.

  6. Make a GET call to the following endpoint: https://graph.microsoft.com/beta/chats/{chatId}/permissionGrants. The clientAppId field in the response will map to the webApplicationInfo.id specified in the Teams app manifest.

    Graph explorer response to GET call for chat RSC permissions

For more information on how to get details of apps installed in a specific chat, see get the names and other details of apps installed in the specified chat.

Code sample

Sample name Description .NET Node.js
Resource-Specific Consent (RSC) Use RSC to call Graph APIs. View View

See also