Microsoft Teams has a new, more granular AND resource-specific permissions model for apps! What is Resource-Specific Consent (RSC) and how do I use it?

Exciting news from Microsoft Ignite 2019 that I’m only now getting around to (sorry about that!). There’s a new way to specify application permissions for Microsoft Teams apps which is more granular and allows team owners to consent within the scope of their team. Read on for more about the problem RSC is solving, how it works, and how you can use it in your Microsoft Teams app.

Much of this content is taken from the session BRK3226 - Every team, connected: Develop Microsoft Teams apps with Microsoft Graph, backed up by my own experience trying this stuff out.

What’s the problem?

Today, Microsoft Teams applications can read and manipulate teams via Microsoft Graph, reading messages, changing membership, adding or removing files etc etc. The permissions model for these application is inherited from Microsoft Azure AD and is the same permissions model used through Microsoft 365.  [side: What is Microsoft Graph and Why Do I Care?]

There are two problems with this approach today. Firstly, the permissions are not granular enough – for instance, for an application to read a channel and be able to add a file, it must have Group.ReadWrite.All permission. This is because there is no more granular permission available. However, this permission gives the application full read and write access to all aspect of the underlying Group, including the ability to read and modify areas of the group that have nothing to do with Teams. It’s a very deep scope. This is Problem 1.

Secondly, that permission takes effect across ALL Groups in the organisation. There’s no way to scope a permission to a specific set of Groups (or Teams) to restrict the ability of a certain application. Not only is it a deep scope, it’s also a very wide scope. This is Problem 2.

For IT Admins, both of these problems are real issues in granting admin consent to Teams applications because they are ceding responsibility to the application developer not to do something stupid, whether intentionally or otherwise. [In fact, most developers are also not happy about this state of affairs, they would rather a Least Privileged security model that means they can’t possibly be held responsible for something bad happening!]

There is actually a hidden Problem 3 as well. Even if IT Admins did trust the developers not to misuse their permissions, the whole process of requiring a tenant admin to consent to permissions for Teams apps adds a lead-time into application provisioning. For larger organisations this can be weeks, during which time Team customization is halted or sub-optimal. This has a knock-on effect to user adoption and on-boarding. Anything that can shorten this consent cycle and allow applications to be used by users faster can only help increase adoption and usage.

What is Resource-Specific Consent?

Resource-Specific Consent (RSC) is a solution to Problems 2 and 3 that also solves Problem 1 in its implementation. RSC allows team owners to grant consent to an application accessing/modifying data about that team. In effect, RSC moves the “gate” of consent from admins to owners, because the permission scope is reduced to only that team. This makes sense: tenant admins aren’t the best people to know whether a specific application should have access to data from a specific team, the owners of that team are.

Of course, tenant admins have to buy-in to this approach, and there is a tenant-wide “on/off” switch for this process.

RSC is the brainchild of Bill Bliss (one of the Teams team founders and Platform Architect) who said that he’s been working on this for about 2 years, including 6 months spent convincing the AD Identity Team of the need for this. Fundamentally, it’s a new consent model, so I can imagine there was a healthy amount of push-back, and it’s really great to see that it’s made it over the line and is being implemented.

Solving Problem 1: Granular Permissions

As part of the implementation of RSC, new, more granular permissions were created to more clearly define what an application can do. It’s important to note that these aren’t really Azure AD permissions in the true sense of the word: you won’t find them listed when you go to assign permissions to an Azure App. They are specific to Teams, and specific to RSC. More on how they are used in a moment. The new permissions are:

I know I just said it, but it’s an important point so I’m going to say it again. These new permissions are NOT coming to Azure AD (yet). They are separate, and ONLY available to Teams apps that are installed in the Teams client, not broader apps such as windows services, websites or console apps that are stand-alone or operate outside of Teams. Eventually, I think it would be awesome to see these permissions flow back to Azure AD and become part of the “standard” permission set, rather than only be available to RSC. There are plenty of applications which aren’t Microsoft Teams apps which could benefit from using a more granular permission set.

How do I enable/disable RSC on my tenant (and what’s the default state)?

RSC is a separate “toggle” that a tenant admin can control. Right now it’s not shown by default but you can still see it by following this link, which includes the feature flag: Enterprise Applications User Settings in the Azure portal:

By default, the state is set to whatever the current state of the setting immediately above it (“Users can consent to apps accessing company data on their behalf”) is set to. This means that if your users are already able to consent to apps that use Delegated Permissions, then this setting will be defaulted to Yes.  (The default state for that setting in new tenants is ‘Yes’, so therefore the default state for this new setting will also be ‘Yes’ in new tenants, meaning that if you’ve never touched any of this stuff, it’s probably on!)

As well as just Yes/No, it’s possible to limit this setting to just a set of Security Groups, by choosing “Limited” and then specifying the groups. This might be good if you only want to make this feature available to a set of trusted “Power User” team owners:

You can also toggle this setting via PowerShell, via the Set-MsolCompanySettings cmdlet. Right now, if you go to that page you’ll only see the parameter to set the original setting to allow users to consent to apps using Delegated Permissions (-UsersPermissionToUserConsentToAppEnabled) but there are two new parameters now:

–EnableGroupSpecificConsent, which is a $true or $false setting, and then an optional

–ConstrainGroupSpecificConsentToMembersOfGroupId which allows you to specify the Group IDs of security groups to limit the setting to

Funnily enough, these PowerShell cmdlets are already well documented in a section called Configure group owner consent to apps accessing group data, which include showing how to list and update these settings. (This is also a way for admins to review and if needed, disable this functionality before it fully goes live.)

As a Teams developer, how do I set up RSC?

Because the permissions described above aren’t really part of the Azure AD permission set, you can’t add them to an application from Azure AD in the ‘normal’ way. Instead, you declare them as part of the application’s manifest JSON file.

Aside: what’s the application’s manifest JSON file?

If you haven’t been doing Teams development since the very beginning you might not be aware of the manifest. Every Teams application (whether it’s a tab, a bot, an extension or a combination of different capabilities) has a manifest file which describes it to Teams. Under the covers, this is a JSON file, but for a while now the much easier way to create manifests has been to use App Studio, which abstracts the process and creates the JSON file for you.

However, when changes are very new (like this) and require a change to the schema, it can take a little while before App Studio catches up. In that interim period, it’s possible to take advantage of new features by editing the JSON file manually. The manifest schema is published on Microsoft Docs (although as I post this, even that schema hasn’t been updated with this change!)

To do this, add a webApplicationInfo section, provide your application ID (the Azure AD application ID), and specify your permissions. In my case, I’m asking for 3 permissions – reading the team’s setting, deleting channels, and deleting tabs:

{
  "$schema": ".../MicrosoftTeams.schema.json",
  ...
   "webApplicationInfo": {
      "id": "db5c3ee6-4180-4b81-b080-a3ce61e16b66",
      "resource": "something",
      "applicationPermissions": [
          "TeamsSettings.Read.Group",
	  "Channel.Delete.Group",
	  "TeamsTab.Delete.Group"
      ]
  },
  ...
}

If you’re eagle-eyed, you might notice that there is a key-value pair in there that doesn’t make sense: “resource”:”something”.  That’s not actually used by RSC and is only there to make the schema parser in Teams happy: right now it expects that if you’re going to have WebApplicationInfo section then you should also have a resource entry. I expect this change in the future.

Be aware that once you add this extra section into you manifest, you won’t be able to use App Studio – if you attempt to import the manifest back in, you’ll get an error (because App Studio doesn’t yet know about applicationPermissions):

Expect this to be fixed soon. However, if you sideload the app directly into Microsoft Teams, you’ll see that the standard ‘Add’ dialog has been expanded to include the specific permissions I specified:

As a team owner, I can add this app and in doing so it will have the permissions listed in just this team, and I can do all this without needing admin consent! This is the real value in RSC – being able to go directly from developer to user, via a team owner that is empowered to provide just enough consent for the application to do work within a known area.

How does it work?

As a developer, you should continue to authenticate with Graph in the normal way as before, getting an access token for your application and making API calls. What changes is how Graph authorizes your follow-on requests for data/action. (note: this is my understanding of the process, I reserve the right to edit and update if I get corrected!)

Without RSC:

An application makes an API call to delete a tab, with a valid Application ID and valid bearer token. Graph checks the API Permissions listed in Azure AD to see if the application has permissions to perform this action (in this case the ubiquitous Group.ReadWrite.All). If so, the action happens, if not a 401 is returned.

With RSC:

An application makes an API call to delete a tab, with a valid Application ID and valid bearer token. Rather than checking API Permissions, Graph checks with Microsoft Teams, taking the tab being deleted, working backwards to the owning team and then seeing if any team owner has authorised that application to perform that action on that team. If so, the action happens, if not a 401 is returned.

Side Note: when a team owner adds an application which includes RSC, in Azure AD you’ll see a permission Group.Selected applied to the application. This is used to “tell” Azure AD that it needs to do additional checks for RSC, but it’s also a good way for IT Admins to know that RSC is in play for this application (because right now the RSC permissions are not surfaced in Azure AD).

Gotchas

If all this sounds really exciting then I agree, it is. It’s going to make it much easier for applications to get the permissions they need. However, there are some things to look out for.

The first one is that RSC is not live yet. It’s coming really soon though. Based on this session at Ignite 2019, it should go into Beta early January 2020 – so it’s worth trying now to see if it’s working for you. GA is expected to happen late Q1 / early Q2 depending on feedback. There is an entry for this on the Microsoft 365 Roadmap as well should you wish to track it there.

Right now, there are some things you can’t do via RSC, such as creating teams or installing other app, and there are some caveats. Straight from BRK3226, these are:

Finally, it’s worth pointing out that there really isn’t any documentation for this right now, though I’m sure that’ll be addressed really soon.

Not just for Teams!

The other exciting thing about RSC is that it isn’t just going to be constrained to Microsoft Teams. Buried in the Ignite 2019: Microsoft Graph News blog post is the line: We expect to roll out resource-specific consent more broadly across the Microsoft 365 platform in the future. This means that Teams is leading the way in defining a new and exciting way of thinking about how security in Microsoft 365 works.

Written by Tom Morgan

Tom is a Microsoft Teams Platform developer and Microsoft MVP who has been blogging for over a decade. Find out more.

---

Buy the book: Building and Developing Apps & Bots for Microsoft Teams. Now available to purchase online with free updates.

Related posts:

Creating a Microsoft Teams IVR Bot Part 1 – Registration and Security Using the Microsoft Teams BETA Graph API calls? They may be about to break on you… 3 API calls going away soon Teams Dev Project: Expose existing LOB apps in Teams for users to share easily with Compose Extensions How to: Show/Hide Apps on the Teams Main Menu (including hiding Activity, Chat, Teams, Calendar, Calls & Files!) with App Setup Policy 5 reasons you should be building apps on Microsoft Teams