Configuring Azure AD for Teams

To use the Teams Collector, you must first authenticate the application using an Azure AD registered application. The following article provides details on setting up an application in Azure AD to support this authentication method.

Required Permissions for Teams

Retrieving information via Graph API requires authentication; this is achieved via an Azure Registered Application. Using the Client Credentials flow (communicating with the Graph API), we are seen as an application rather than a user. Currently, the Collector only supports Client Secrets with no support for Certificates at this time.

NOTE: All the M365 Collectors use the same API and authentication mechanism; therefore, a single registered application can be configured for all the specific Collectors (SharePoint, Teams, and OneDrive) for that M365 subscription.

The Azure registered application's access to the target repository is controlled via the API permissions assigned to the application in the Azure portal.

The following permissions are required:

• Team.ReadBasic.All
• Channel.ReadBasic.All
• Files.Read.All
• ChannelMessage.Read.All(*Requires Extra Approval detailed below)

IMPORTANT: These permissions are required to be added as Graph -> application permissions (as some legacy systems use the same naming convention), NOT delegated permissions.

Registering an Azure Application for a Teams Tenant

1. Log in to Azure AD as a user with permission to add and update App Registrations, then navigate to App Registrations. (Searching for "App Registration" also works).

2. Choose + Add.

3. Enter the name of the app.

4. Choose Accounts in this organizational directory only as the Supported account types and leave the Redirect URL blank.

5. Click Register.

6. Select API permissions.

7. Select + Add a permission.

8. Under Microsoft APIs, select Microsoft Graph and select Application Permissions.

9. Next, search for the Team.ReadBasic.All permission and select it.

    a. Search for the Channel.ReadBasic.All permission and select it.

    b. Search for the Files.Read.All permission and select it.

    c. Search for the ChannelMessage.Read.All permission and select it

NOTE: See the Extra Approval section for important information regarding this permission.

10. Click Add Permissions.

11. Select Grant admin consent for the domain for the chosen permissions.

12. Select Certificates & secrets.

13. Select Client Secrets.

14. Click New Client Secret, give a brief description, and select a time for the expiration of Client Secret.

15. Click Add.

IMPORTANT: Client secret values can only be viewed immediately after creation! Be sure to save the Value before leaving the page.

 

Extra Approval

To successfully retrieve Teams channel messages via the Graph API, a customer must first apply and be granted protected API access for an application-only context (i.e., the Azure registered application that is submitted via this form (see Requesting Extra Approval for Protected APIs from Microsoft for further information on this form).

NOTE: Applications are reviewed by Microsoft every Wednesday, and approvals are deployed every Friday or Monday (except during major holiday weeks in the US).

If you do not receive a notification informing you that your application has been successfully granted, you should attempt to retry feature extraction at intervals after the approval period has surpassed to see if the error has cleared. We suggest that customers contact Microsoft support for any further details on chasing applications.

Any errors related to the API permissions will be reflected in the Audit message that is produced by the Collector for the specific data source after Discovery/Feature Extraction:

1. If the Azure registered application is missing the  ChannelMessage.Read.All permission:
   

   Inaccessible: Code: Forbidden
   Message: Missing role permissions on the request. API requires one of 'ChannelMessage.Read.All, ChannelMessage.Read.Group'. Roles on the request 'Channel.ReadBasic.All, Files.Read.All, Team.ReadBasic.All'. 

2. If the Azure registered application has theChannelMessage.Read.All, but the extra approval process has yet to be carried out (either via the customer not submitting the form or Microsoft is yet to process the form):
   

   Inaccessible: Code: Forbidden
   Message: Invoked API requires Protected API access in application-only context when not using Resource Specific Consent. Visit https://docs.microsoft.com/en-us/graph/teams-protected-apis for more details.text when not using Resource Specific Consent. Visit https://docs.microsoft.com/en-us/graph/teams-protected-apis for more details.