Skip to main content

365|2CM Azure App Registration

Raise a support ticket

OVERVIEW​

To use 365|2CM you are required to register the application on Azure Active Directory. The registration will be used to acquire an access token to make web API requests to access certain Microsoft resources for a tenant (organisation).

APP REGISTRATION USING THE WEB PORTAL​

  1. Sign in to Azure web portal using the link below https://azure.microsoft.com/en-gb/features/azure-portal/

  2. Once signed in, click on the Azure Active Directory button

    image.png

  3. Click on the App Registrations option from the left menu

    image.png

  4. Click on the New registration button

    image.png

  5. Enter 365|2CM into the name input field

    image.png

  6. Under Supported account types section enabled Accounts in this organizational directory option

    image.png

  7. Select Single-page application (SPA) from the drop-down menu and type in the hostname configured for 365|2CM followed by /3652CM/

    Note

    The URI is case sensitive, the route must match exactly the pattern below where the only variable that needs to be replaced is the hostname. Please include the trailing slash in the URL. Example: https://hostname/3652CM/

    2022-01-27_13-54-16.png  

  8. Click on the Register button

    2022-10-14_17-00-13.png

GRANTING API PERMISSION​

The application will require various API permissions, please follow the steps below to add the required permission for 365|2CM.

  1. Click on the API permissions option from the left menu

    image.png

  2. Click on the Add Permissions button

    image.png  

  3. When the right-hand permission panel appears, click on Microsoft Graph (This will be at the very top)

    image.png

  4. Click on Application permissions

    image.png

  5. Using the select permission window, add the following permissions to the application

  • Files.ReadWrite.All

  • Sites.Read.All

    image.png

  1. Scroll down to the bottom of the panel and click the Add Permission button

    image.png

  2. Go back and repeat Steps 2 and 3 except this time select Delegate permissions

    2022-01-28_16-39-49.png

  3. Using the select permissions window and add the following permissions to the application

  • Channel.ReadBasic.All
  • ChannelMessage.Read.All
  • Chat.Read
  • Group.Read.All
  • Sites.Read.All
  • TeamMember.Read.All
  • User.ReadBasic.All
  • User.Read (If not already added)
  1. Scroll down to the bottom of the panel and click the Add permissions button

    image.png

  2. An Azure administrator will need to grant permission for the application to access the resources by clicking on the Grant Permission button

  3. Once granted the status will update to Green, indicating the permission has been successfully granted

    2023-01-17_9-13-08.png

    Note

    Do not remove the default user.read delegated permission

    Note

    Note if users are still receiving the below message upon the first login then an Azure Administrator will need to complete the first login and grant consent from the Microsoft login pop-up instead.

    image.png

API PERMISSION USAGE​

NAMETYPEDESCRIPTIONCONSENT REQUIREDUSAGE
Sites.Read.AllApplicationRead and write items in all site collectionsYesThis permission is used to iterate over each site and library using the application permissions. This is required by the background scheduler to target specific sites so that the document can be moved across to Content Manager
Sites.Read.AllDelegatedRead items in all site collectionsYesUsed to display all sites that the logged in user has access to in the Sites page of 365|2CM
Files.ReadWrite.AllApplicationRead and write files in all site collectionsYesThis permission is used by the background scheduler to move documents from Sharepoint to Content Manager.
Group.Read.AllDelegateRead all groupsYesRequired for showing a list of all Teams available for the organization and for archiving Teams Channel Posts
Channel.ReadBasic.AllDelegateRead basic information from channelsYesRequired for archiving all channel posts from a Team
ChannelMessages.Read.AllDelegateRead all channel posts from a Teams channelYesRequired for archiving all channel posts from a Team
TeamMember.Read.AllDelegateGet the number of members in a TeamsYesRequired for generating Teams Channel post
Chat.ReadDelegateRead Personal Chat MessagesYesRequired for archiving Teams Chats
User.ReadBasic.AllDelegateGets the basic details of a 365 UserYesRequired for retrieving the names of the Recipients in a personal Teams Chat
User.ReadDelegateRead basic information for logged in userNoDefault permission set by Azure, used to allow user to sign in

EXPOSE THE API​

Applying a custom scope to the registration will prevent unauthorized access to the 365|2CM API endpoints.

  1. In the Left Menu, click on Expose an API

    2022-08-04_11-11-50.png

  2. Next to the Application ID URI click on Set

    2022-08-04_11-13-18.png

  3. Click Save

    Note

    Do not Change the Application ID URI. It must be in the following format: api://{client id}

    2022-08-04_11-14-32.png

  4. Click Add a scope

    2022-08-04_11-17-32.png

  5. Specify the values below in the Add a scope window, then click Add scope

    Note

    The scope must be named Grant.Access

    FieldValue
    Scope NameGrant.Access
    Who can consent?Admins and users
    Admin Consent display nameGrant Access to 3652CM
    Admin consent descriptionGrant Access to 3652CM
    StateEnabled

    image-9C39SFQK.png

  6. Once the scope has been added, click on API permissions

    2022-08-04_11-30-18.png

  7. Click on Add a permission

    image.png

  8. Click My APIs

    image.png

  9. Click on the previously created 365|2CM Azure app registration

    image.png

  10. Click on the Grant.Access scope and then click Add permissions at the bottom of the screen

    image.png

  11. Click on Grant admin consent

    2022-08-04_11-37-57.png

GATHERING APP DETAILS​

Please follow the steps below to retrieve the Application ID, Tenant ID and Redirect URL on the Azure portal. These values are required for the installation.

  1. Once signed into the Azure portal click on Azure Active Directory

    image.png

  2. Click on App registrations

    image.png

  3. Click on the required application (365|2CM created previously)

    image.png

  4. Click on Overview

    image.png

  5. Copy the Application (client) ID and Directory (tenant) ID and note them down.

    2023-12-04_16-42-49.png

  6. Click on Redirect URIs from the overview page

    image.png

  7. And then copy and note down the Redirect URI value

image.png

CERTIFICATE BASED AUTHENTICATION​

The background scheduler component of the application utilizes certificate-based authentication to verify its identity to Microsoft Azure. As such you will need to register a certificate for your application on Azure AD. You can choose to use an existing certificate if you have one (the same certificate used for the 3652CM site) otherwise you can create/purchase a new certificate for this purpose. Please follow the steps below on how to upload a certificate:

  1. After obtaining a copy of your certificate (.pfx), install the certificate to the Certificate Manager tool under local machine on the server the application will be installed on

    Certificates

  2. Ensure the certificate has been given a friendly name, this is required when installing the app to the server

    2020-09-01_14-25-22.jpg

  3. Please ensure the account that will be running the application pool for the application has access to the certificate private key

  4. Right-click the certificate > All Task > Manage Private Key

    image.png

  5. Grant the account running the app pool full control permission on the certificate

  6. Export the public key from the certificate using this guide (https://docs.microsoft.com/en-us/azure/application-gateway/certificates-for-backend-authentication), you will only need to complete steps 1 to 7 in the Export authentication certificate (for v1 SKU) section

  7. Upload your certificate public key (.CER) to Microsoft Azure for the 365|2CM application by going to the Certificates & secrets section

    Certificates2

VALUES REQUIRED FOR INSTALLATION​

The following values will be required for the installation of 365|2CM. Please ensure that the person responsible for the installation has these values.

  • Redirect URI
  • Application ID
  • Tenant ID
  • Certificate Friendly Name
NameDescription
Redirect URIThe URI where Azure will send the authentication payload upon successful authentication.
Application IDApplication's unique identifier on AzureAD.
Tenant IDThe organization tenant's unique identifier on AzureAD.
Certificate Friendly NameThe friendly name of the nominated certificate (.pfx) installed on the machine. This certificate is used to prove the application's identity by encrypting the application's claims in the form of a JWT token.

ENDPOINTS​

All valid endpoints for the registered application can be seen via the Azure web portal.

  1. Select the registered application on Azure

  2. From the Overview page select Endpoints

    2020-11-27_11-02-10.jpg