Permissions o365 – individual authentication and bulk authentication

This document details the permissions and user role required to connect to TTR for both our SaaS product and our self-hosted solution.

Self-hosted: This document details the steps of creating an Azure APP to access O365 Mail APIs, configuring a TTR portal instance to communicate with the Azure APP and then having the customer authenticate with an O365 account with limited admin permissions to perform a bulk upload of O365 agents.

If the customer is to be hosted on their own platform a new Azure App needs to be created

If the customer is to be hosted on the portal.timetoreply™.com SaaS platform jump directly to step 6 of this document as you will leverage off the existing Azure app created for the TTR SaaS portal.

  1. Create a standard Azure app under App Registrations under Azure Active Directory

Set the supported account type as “Accounts in this organizational directory only“

  1. Add the following redirect-URLs
  • https://portal-url/account/microsoft/auth
  • https://portal-url/msgraph-auth
  • https://portal-url/msgraph-re-auth
  • https://portal-url/tools/agents/msgraph-store-bulk
  • https://portal-url/msgraph-grant-admin-permission

Replace ‘portal-url’ with the actual URL of the customer’s hosted web portal

  1. In Authentication Settings, tick the following checkboxes under Advanced Settings

Access Tokens

ID Tokens

  1. Under API permissions add the following MS Graph API scopes

Application Permissions

  • Mail.ReadBasic.All: Allows the app to read basic mail properties in all mailboxes without a signed-in user. Includes all properties except body, previewBody, attachments and any extended properties.
  • User.Read.All: Allows the app to read user profiles without a signed in user.
  • Directory.Read.All: Allows the app to read data in your organization’s directory, such as users, groups and apps, without a signed-in user.

Delegated Permissions

  • Mail.ReadBasic: Allows the app to read email in the signed-in user’s mailbox except body, previewBody, attachments and any extended properties.
  • Offline_access: Allows the app to see and update the data you gave it access to, even when users are not currently using the app. This does not give the app any additional permissions.
  • User.Read: Allows users to sign-in to the app, and allows the app to read the profile of signed-in users. It also allows the app to read basic company information of signed-in users.

 

  1. Under Certificates & Secrets generate a new client secret

Make sure to copy the secret as it will be required to configure the customer’s TTR instance to connect to their Azure App.

  1. In Azure AD assign the ‘Privileged role administrator’ role to an account

Note: The account must have an O365 license assigned. Alternatively, you can use your super admin credentials. The timetoreply™ system does not store username or password information for administrator accounts. You can read about how the tokens are stored below.

This account can then be used to authenticate via the TTR portal to perform O365 bulk agent additions for your domain.

Once authenticated an access token is stored in the portal database

A user_principal_name of Company Master is created which is linked to the relevant company ID & the access token is stored under this Company Master.

  1. Add the Application Client ID & Secret to environment file used by the portal.

This step will need to be performed by a Developer or Deployment specialist that has access to the customers server:

The following parameters will be set

  • MS_GRAPH_CLIENT_ID=’Azure Application ID
  • MS_GRAPH_CLIENT_SECRET=’Azure Application Secret
  • MS_GRAPH_REDIRECT=https://portal-url/account/microsoft/auth
  • MS_GRAPH_REDIRECT_FOR_INVITE=https://portal-url/msgraph-auth
  • MS_GRAPH_REDIRECT_FOR_REAUTH=https://portal-url/msgraph-re-auth
  • MS_GRAPH_REDIRECT_FOR_BULK=https://portal-url/tools/agents/msgraph-store-bulk
  • MS_GRAPH_REDIRECT_FOR_ADMIN=https://portal-url/msgraph-grant-admin-permission

More detail about the privileged role administrator role:

This role grants the ability to manage assignments for all Azure AD roles including the Global Administrator role. This role does not include any other privileged abilities in Azure AD like creating or updating users. However, users assigned to this role can grant themselves or other additional privileges by assigning additional roles.

Permissions

Actions Description
microsoft.aad.privilegedIdentityManagement/allEntities/allTasks Create and delete all resources, and read and update standard properties in microsoft.aad.privilegedIdentityManagement.
microsoft.directory/servicePrincipals/appRoleAssignedTo/allTasks Read and configure servicePrincipals.appRoleAssignedTo property in Azure Active Directory.
microsoft.directory/servicePrincipals/oAuth2PermissionGrants/allTasks Read and configure servicePrincipals.oAuth2PermissionGrants property in Azure Active Directory.
microsoft.directory/administrativeUnits/allProperties/allTasks Create and manage administrative units (including members)
microsoft.directory/roleAssignments/allProperties/allTasks Create and manage role assignments.
microsoft.directory/roleDefinitions/allProperties/allTasks Create and manage role definitions.

 

Tokens

After a customer has authenticated using a Privileged Administrator account via the timetoreply™ Portal, a token is stored for that administrator account in the database. The timetoreply™ system does not store username or password information for administrator accounts. Each time the ‘O365 Agent Bulk Add’ section is accessed the token is invoked to poll the domain. For Agents added via the bulk add method, as well as those added individually, a token created is for their individual account.

Tokens created for agents added via the bulk add method become the child to the parent token created by the administrator account used to authenticate for the Office 365 domain. Once the timetoreply™ solution is deployed, external access to the application database will be closed off by the customer. Tokens generated by the timetoreply™ system will never leave the customer’s network and will be inaccessible externally.

Token access can be revoked at any time from the o365 admin dashboard or via the TTR dashboard (Settings -> Email Service Authentication -> View Microsoft Authentications -> Delete the relevant credential.)

Permission reference: https://developer.microsoft.com/en-us/graph/docs/concepts/permissions_reference