RSC docs refresh - #14313
Conversation
Acrolinx ScorecardsWe currently enforce a minimum score of 80. Click the scorecard links for each article to review the Acrolinx feedback on grammar, spelling, punctuation, writing style, and terminology: More info about Acrolinx Use the Acrolinx extension, or sidebar, in Visual Studio Code to check spelling, grammar, style, tone, clarity, and key terminology when you're creating or updating content. For more information, see Use the Visual Studio Code extension to run Acrolinx locally. |
|
Learn Build status updates of commit dd39762: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
| @@ -1,2 +1,2 @@ | |||
| --- | |||
| title: Test RSC Permissions Using Postman | |||
There was a problem hiding this comment.
A couple years back, Postman was purged from internal usage for SFI reasons, described publicly in https://www.leeholmes.com/security-risks-of-postman/, and there was a loosely-coordinated effort to remove anything that looked like recommendation or endorsement from docs too. Should consider it here.
|
|
||
| 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. For more information, see [enable resource-specific consent in Teams](../rsc/resource-specific-consent.md). | ||
|
|
||
| RSC permissions are only available to Teams apps installed on the Teams client and aren't part of the Microsoft Entra admin center and are declared in the app manifest (previously called Teams app manifest) (JSON) file. You can manage RSC permissions for Teams apps in Developer Portal from the **Permissions** section under **Configure**. |
There was a problem hiding this comment.
| Within the Microsoft 365 apps ecosystem, RSC permissions are unique to Teams apps. RSC permissions cannot be declared or configured in the Microsoft Entra admin center, they must be declared within an app's manifest and can be managed from the Teams Developer Portal. |
|
|
||
| ### Microsoft Graph API permission | ||
|
|
||
| Graph API permissions are managed in Microsoft Entra ID. For your app to access data in Microsoft Graph, the user or administrator must grant it the correct permissions via a consent process. For more information, see [Microsoft Graph permissions](/graph/permissions-reference). |
There was a problem hiding this comment.
"Graph API permissions are managed in Microsoft Entra ID". I thought this just got done saying RSC was used to manage permissions to Graph API endpoints, and RSC is not part of Entra?
There was a problem hiding this comment.
The permissions are associated with your entra id I believe.
|
|
||
| ## Microsoft Entra ID | ||
|
|
||
| Microsoft Entra ID is a cloud-based identity and access management service. This service helps your employees access external resources, such as Microsoft 365, the Azure portal, and thousands of other SaaS applications. For more information, see [Microsoft Entra ID](/azure/active-directory/fundamentals/active-directory-whatis). |
There was a problem hiding this comment.
All pages need to define "resource".
There was a problem hiding this comment.
Also we say "external" resources, but then proceed to talk about Microsoft resources? Is that considered external?
|
|
||
| ## 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. For more information, see [enable resource-specific consent in Teams](../rsc/resource-specific-consent.md). |
There was a problem hiding this comment.
"RSC is a Microsoft Teams and Microsoft Graph API integration" Other page says it's a framework.
Is the fact that it "uses API endpoints" relevant to the concept, or is it an implementation detail?
|
|
||
| Graph API permissions are managed in Microsoft Entra ID. For your app to access data in Microsoft Graph, the user or administrator must grant it the correct permissions via a consent process. For more information, see [Microsoft Graph permissions](/graph/permissions-reference). | ||
|
|
||
| ## Capability wise management |
There was a problem hiding this comment.
As a new developer, I don't understand anything in this section. Why is it called "Capability wise management"? What is a bot or messaging extension, what is a connector, why do I care about their IDs, and what does any of this have to do with developing a Teams agent/bot/app?
|
|
||
| Resource-specific consent (RSC) is an authorization framework built by Microsoft Teams and Microsoft identity platform that allows for granting scoped access to an app. | ||
|
|
||
| Through RSC, an authorized user can give an app access to the data of a specific instance of a resource type. They don't need to give app access to every instance of the resource type in the entire tenant. |
There was a problem hiding this comment.
Again, needs "resource" defined, this is too abstract.
"An authorized user can give an app access" This makes it sounds like RSC permissions are like mobile app permissions, where an app can declare that it needs, say, camera or location access, and a user of the app can grant or revoke those permissions to the installed app at any time. But I don't think that's the idea? A scenario that follows this through from developer config and implementation, through admin activities, to user install and usage would help.
|
|
||
| Through RSC, an authorized user can give an app access to the data of a specific instance of a resource type. They don't need to give app access to every instance of the resource type in the entire tenant. | ||
|
|
||
| For example, a person who owns both team A and team B can decide to give Contoso app access to the data of only team A and not team B. The same concept of scoped data access applies to chats and meetings as well. |
There was a problem hiding this comment.
This is still way too abstract, it needs to be tied to a realistic user scenario in Teams.
|
|
||
| # Resource-specific consent for your Teams app | ||
|
|
||
| Resource-specific consent (RSC) is an authorization framework built by Microsoft Teams and Microsoft identity platform that allows for granting scoped access to an app. |
There was a problem hiding this comment.
I'm developing a Teams app - is this important to my app or not? I can't tell if this is like an opt-in thing for increasing transparency and user trust or if it's a critical app permissions mechanism so that my app can do anything useful in Teams. If it's the latter, the whole RSC concept probably needs to be promoted up out of the "Integrate Microsoft Graph" TOC section.
| * Application: The app accesses data without the presence of a signed-in user. | ||
| * Delegated: The app only accesses data in the context of a signed-in user's sessions. It doesn't allow access in the absence of a signed-in user. | ||
|
|
||
| | | Application context RSC permissions | Delegated context RSC permissions | |
There was a problem hiding this comment.
This table is information-free
|
|
||
| Following are the types of RSC permissions: | ||
|
|
||
| 1. The resource type on which data access is being granted: |
There was a problem hiding this comment.
This seems to mostly be relevant to where/how an app is installed (team; chat; personal), it should be clearer about that.
|
|
||
| 1. The mode of data access: | ||
| * Application: The app accesses data without the presence of a signed-in user. | ||
| * Delegated: The app only accesses data in the context of a signed-in user's sessions. It doesn't allow access in the absence of a signed-in user. |
There was a problem hiding this comment.
"presence" and "absence", what exactly do these mean? Is this about whether the app does something on behalf of a user vs. using its own identity?
| * [Supported RSC permissions](#supported-rsc-permissions) | ||
| * [Grant RSC permissions to an app](grant-resource-specific-consent.md) | ||
|
|
||
| ## Types of RSC permissions |
There was a problem hiding this comment.
Very abstract, needs concrete examples.
|
|
||
| ### Basic RSC Permissions | ||
|
|
||
| A limited set of RSC permissions have been reviewed by Microsoft privacy and security teams and have been deemed low risk. These permissions can be consented to at all times by any user when they install and use an app. The following low-risk basic permissions are always consented to upon installation. |
There was a problem hiding this comment.
"These permissions can be consented to at all times by any user when they install and use an app." > "The following low-risk basic permissions are always consented to upon installation." Which one? Per the comment about the mobile app permissions analogy above, is there a concept of installing an app without granting it specific permissions?
|
|
||
| ### RSC-based data access APIs | ||
|
|
||
| Microsoft Graph SDK, Microsoft Bot Framework SDK, and Microsoft TeamsJS client library support fine-grained data access through RSC. The supported modes and resource types vary across the API surfaces. |
There was a problem hiding this comment.
Teams SDK?
What kind of "data" and "data access" are we talking about?
| |Application| • Microsoft Graph <br> • Microsoft Bot Framework | >=v1.6 | Teams, chats, and meetings | • Microsoft Graph-based controls for chats and meetings <br> • Microsoft Entra admin center-based controls for Teams |• Team: A team owner or member <br> • Chat: A chat member <br> • Meeting: A meeting organizer or presenter | | ||
| | Delegated | Microsoft Teams Client | >=v1.12 | Teams, chats, meetings, and users | Always on | Any user authorized to install an app in the specific scope. | | ||
|
|
||
| > [!NOTE] |
There was a problem hiding this comment.
Wasn't this what the whole previous section was about?
|
|
||
| Microsoft Graph SDK, Microsoft Bot Framework SDK, and Microsoft TeamsJS client library support fine-grained data access through RSC. The supported modes and resource types vary across the API surfaces. | ||
|
|
||
| | RSC mode | Supported SDKs | App manifest version | Resource types | RSC-related controls for the entire tenant | Who can consent to RSC permissions? | |
There was a problem hiding this comment.
I'm not sure what information this table is trying to convey
| * [RSC permissions for user access](#rsc-permissions-for-user-access): Includes permission for users to access different resources. | ||
|
|
||
| > [!NOTE] | ||
| > The features associated with some permissions listed here might not be generally available (GA). |
| | `ChannelMember.ReadWrite.Group` | Read and write the members of this team's channels.|NA |NA | | ||
| | `ChannelMember.Read.Group` | Read the members of this team's channels. |NA |NA | | ||
|
|
||
| For more information, see [team resource-specific consent permissions](/graph/permissions-reference#team-resource-specific-consent-permissions). |
There was a problem hiding this comment.
Broken link anchor
|
|
||
| For more information, see [chat resource-specific consent permissions](/graph/permissions-reference#chat-resource-specific-consent-permissions). | ||
|
|
||
| > [!TIP] |
There was a problem hiding this comment.
This seems like it was put in this location randomly
|
|
||
| # Preapproval of RSC permissions | ||
|
|
||
| Resource-Specific Consent (RSC) permissions preapproval provides admins with granular control over the RSC permissions an app can request upon installation. RSC permissions are granted to an app at the time the app gets installed. Through the use of pre-approval policies, admins can declare ahead of time the maximum permissions an app can request from the end user and be consented to during installation time. |
There was a problem hiding this comment.
"control over the RSC permissions an app can request", or "control over which apps can be installed depending on the RSC permissions they request"?
|
|
||
| For an RSC permission pre-approval policy to take effect for an app, the admin must ensure that the app is enabled (installable) in their organization. If the app is not installable, then the permission pre-approval for that specific app becomes irrelevant. For more information on enabling apps in Teams Admin Center, see [managing apps in Teams Admin Center](/microsoftteams/apps-in-teams). | ||
|
|
||
| Admins can create a detailed preapproval policy, based on the app ID, permissions, and the sensitivity of the accessed data. Preapproval of RSC permissions are designed for admins seeking to create advanced custom policies for their organization. |
There was a problem hiding this comment.
Needs a concrete example scenario
|
|
||
| Preapproval of RSC permissions are managed through Microsoft Graph PowerShell. You can learn more about managing Microsoft Teams with PowerShell [here](/powershell/microsoftgraph/get-started). | ||
|
|
||
| To create, manage, and delete RSC preapproval policies, you must grant the following permissions to the PowerShell cmdlet: |
There was a problem hiding this comment.
Which cmdlet? Is the following an example or an instruction? Section needs rewrite
| @@ -1,2 +1,2 @@ | |||
| --- | |||
| title: Preapproval of RSC permissions | |||
There was a problem hiding this comment.
This whole article seems like it needs to go in the admin docs, but information about its existence (maybe just in the form of a scenario, if nothing else) should stay in the developer overview. For that reason I'm not reviewing this one in great detail.
| 1. [Install your app in a team, chat, or user](#install-your-app-in-a-team-chat-or-user) | ||
| 1. [Verify app RSC permission granted to your app](#verify-app-rsc-permission-granted-to-your-app) | ||
|
|
||
| ## Add RSC permissions to your Teams app |
There was a problem hiding this comment.
This article has talked about "granting" and "adding permissions", but from the developer perspective I think it's more like "configuring", "declaring" or "requesting"? Looking at the language around iOS app entitlements/capabilities might help.
|
|
||
| To add RSC permissions to your app, follow these steps: | ||
|
|
||
| 1. [Register your app with Microsoft identity platform using the Microsoft Entra admin center](#register-your-app-with-microsoft-identity-platform-using-the-azure-ad-portal). |
There was a problem hiding this comment.
What if I'm just using TDP? Can I not use RSC if I don't have an app registration in Entra? There's no mention of TDP here.
|
|
||
| <br> | ||
|
|
||
| <details> |
There was a problem hiding this comment.
Remove use of <details>, it's not expected for the platform. Probably use tabs instead.
|
|
||
| To install your app on which you've enabled RSC permission in a team, chat, or user, follow these steps: | ||
|
|
||
| 1. Ensure that you've configured [consent settings](#configure-consent-settings) for team, chat, or user. |
There was a problem hiding this comment.
Rework this; shortened lists with anchor links to subsections below are an antipattern.
| > * Teams Administrator | ||
| > * Privileged Role Administrator | ||
|
|
||
| ### Configure consent settings |
There was a problem hiding this comment.
Is this admin guidance?
| <br> | ||
| </details> | ||
|
|
||
| ## Install your app in a team, chat, or user |
There was a problem hiding this comment.
This looks like user-perspective activity? If it's useful for a developer, maybe it belongs in the "Test RSC Permissions" article as a client-based approach, in addition to the Postman API-based approach?
What happens with entitlement declarations when the app is installed to a different resource type? Like, if my app uses TeamSettings.Read.Group but the user installs it to a chat, are those permissions just irrelevant?
|
|
||
| If your Teams admin allows custom app uploads, you can [upload your custom app](~/concepts/deploy-and-publish/apps-upload.md) directly to a specific team, chat, or user. | ||
|
|
||
| ## Verify app RSC permission granted to your app |
There was a problem hiding this comment.
This seems like an alternate version of what's already in the "Test RSC Permissions" article.
| |`ChannelMeetingTranscript.Read.Group`|Read the transcripts of all channel meetings associated with this team.| NA | Supported | | ||
| |`ChannelMeetingNotification.Send.Group`|Send notifications in all the channel meetings associated with this team.| NA | Supported | | ||
| |`ChannelMessage.Read.Group`|Read this team's channel messages. | NA | Supported | | ||
| |`ChannelMessage.Send.Group`|Send messages to this team's channels. | NA | Supported | |
There was a problem hiding this comment.
Feedback/bug item on this just pinged on today:
| * [Microsoft Entra ID](#azure-active-directory) | ||
| * [Resource-specific consent (RSC)](#resource-specific-consent) | ||
|
|
||
| :::image type="content" source="../../assets/images/teams-app-permissions-3.png" alt-text="The screenshot describes the different Teams app permissions." border="false"::: |
There was a problem hiding this comment.
Can we change manifest to app manifest or teams app manifest in this diagram. Also, rsc permissions dont show up on the tokens like the classic orgwide permissions. Is there a way to add that context in here?
|
|
||
| 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. For more information, see [enable resource-specific consent in Teams](../rsc/resource-specific-consent.md). | ||
|
|
||
| RSC permissions are only available to Teams apps installed on the Teams client and aren't part of the Microsoft Entra admin center and are declared in the app manifest (previously called Teams app manifest) (JSON) file. You can manage RSC permissions for Teams apps in Developer Portal from the **Permissions** section under **Configure**. |
There was a problem hiding this comment.
Can we also add a link to Teams manifest documentation. I think this is the page https://learn.microsoft.com/en-us/microsoftteams/platform/teams-sdk/teams/manifest
3 participants
Getting the five primary RSC docs into a PR for collaborative review and update.
ADO: None, this is being tracked in this group chat.
Previews: