Microsoft Azure Integration - Create an Azure AD Application with API Permissions
Client applications may need to authenticate to use a third-party product or access an API.
Some of the authentication mechanisms require you to first create an application and register it on the Azure portal, then grant it permissions. This integration details step by step all the actions you need to perform to create an Azure AD application with permissions.
Use cases
- The Technical Support Agent (AST) accesses the Microsoft email server using the Microsoft Graph Mail API (OAuth 2.0 modern authentication).
Permissions must be given to allow the Technical Support Agent to consult emails using this API.
- Microsoft Bookings is a solution for planning and managing business customer appointments using a shared calendar.
Access to data is performed using the Microsoft Bookings API in Microsoft Graph and requires permissions to call the API.
See Microsoft Bookings integration.
Microsoft Azure - Definitions
- Tenant
- A tenant is a dedicated Azure AD service instance that an organization owns and in which its Azure AD applications are stored.
- This environment is identified in a unique way via an ID (Directory or Tenant ID).
- Each organization can have multiple tenants.
- Azure AD applications
- An Azure AD application is an application registered on the Azure portal enabling the Microsoft platform to provide identity and access management services.
- Each application is defined in a given tenant (Azure environment) and identified in a unique way via an ID (Client ID).
- By default, an Azure AD application registered in a tenant is available to all tenant users who are able to authenticate. This Azure portal functionality is used to restrict access to a specific group of users in the tenant.
- API permissions authorizing the Azure AD application to access API resources
- Application permissions for CC (Client Credentials) mode. This enables a third-party product to authenticate using its own credentials without any user interaction or consent (access without user sign-in).
- Delegated permissions for ROPC (Resource Owner Password Credentials) mode. This enables a third-party product to access the API via the consent granted by the user when signing in (access with user sign-in).
Integration Process
You create an Azure AD application with permissions in three main steps.
Step 1: Register an Azure AD application on the Microsoft Azure portal.
Step 2: Declare the users authorized to use the Azure AD application.
Step 3: Add permissions authorizing the Azure AD application to use an API.
Step-by-Step Integration Process
Prerequisites
- You must have an Azure subscription. If this is not the case, you can create a free account, or you can buy an Azure Pay-As-You-Go subscription. See the procedure.
- You must have the relevant accounts and access rights to the services you want to interface on the Azure portal.
Notes
- You should save the IDs throughout the entire procedure. They will be required when configuring the use of the Azure AD application in the third-party product.
Register an Azure AD application on the Azure portal
RegisterApp_Procedure
Step 1: Access the Azure portal.
1. Log in to the Azure portal using your Azure account.
2. (optional) Select the relevant environment if you have multiple tenants.
Step 2: Register a new application on the Azure portal and retrieve the ID.
1. Search for the App registrations service in the list of Azure services or click the link below to access the service directly.
Microsoft Azure: App registrations
The list of Azure AD applications previously registered on the Azure portal will appear.
2. Click + New registration.
The properties window will appear.
3. Specify the information required for registering the application.
- Name: Name of the application. Note: This name is not used by the third-party product.
Enter a meaningful name that will enable you to identify the application easily in the dashboard on the Azure portal.
- Supported account types: Used to specify who can use the new application.
- Select the option called Accounts in this organizational directory only. This means that only accounts in your organization will be able to access the application (multitenant or single tenant).
Select the option called Accounts in any organizational directory only if you want to provide the application to several organizations, e.g. as a SaaS service (multitenant).
- Redirect URI: Type of application and redirect URI where the Azure portal should send security tokens after authentication.
Note: For the Technical Support Agent (AST), select the type of application called Public client/Native.
4. Click Register.
- The Azure AD application will be created and registered on the Azure portal.
- Its IDs will be displayed.
5. Retrieve the IDs required for configuring your third-party product.
- Hover over the relevant ID and click
to copy it.- ID of the new Azure AD application: Application (client) ID value
- Tenant ID: Directory (tenant) ID) value
- You can paste it in a text editor for later use.
or - You can go directly to your third-party product and paste it in the relevant ID field.
Step 3: Create and retrieve the client secret of the Azure AD application.
Prerequisite Check that the new Azure AD application is declared as a private client.
- Select Authentication in the left pane.
- Check that the value in Advanced settings > Treat application as a public client is No.
1. Select Certificates & secrets in the left pane and click + New client secret.
The properties window will appear.
2. Specify the information required for creating the client secret.
- Description: Description of the client secret. Note: The default value will be used if you do not specify this field.
- Expires: Select the validity end date for the client secret.
Select Never to avoid renewing the client secret as well as the risk of forgetting to do so.
3. Click Add.
- The client secret will be generated.
- Its value will be displayed.
4. Retrieve the client secret required for configuring your third-party product.
- Click to copy the client secret from the Value field in the Client Secrets section.
- You can paste it in a text editor for later use.
or - You can go directly to your third-party product and paste it in the relevant field.
EndRegisterApp_Procedure
Declare the users authorized to use the Azure AD application
Note: By default, the new Azure AD application is available to all tenant users who are able to authenticate.
example Technical Support Agent ==> Declare the email address of the user authorized to access the Technical Support Agent inbox. This is the one specified in the Login field in the Technical Support Agent window.
Step 1: Enable user assignment for the Azure AD application.
1. Select Overview in the left pane and click the name of your Azure AD application in Essentials > Managed application in local directory.
A window displaying the application's local properties will appear.
2. Select Properties in the left pane.
3. Select Yes in the User assignment required? field.
4. Click Save.
Step 2: Declare the users authorized to use the Azure AD application.
1. Select Users and groups in the left pane and click + Add User.
- The window for adding an assignment will appear.
- The list of users declared for the tenant will appear.
2. Select the users authorized to use the application and click Select.
The users will appear in the Selected Items list found at the bottom of the window.
Use the search field to find the relevant users.
3. Click Assign.
The list of users and groups authorized to use the Azure AD application will be refreshed.
Add permissions authorizing the Azure AD application to use an API
API permissions are required in order to authorize the Azure AD application to access API resources. Microsoft offers a list of APIs whose configuration will depend on whether it is application permissions (CC mode) or delegated permissions (ROPC mode).
Note: The Microsoft Graph Mail API is the one used by the Technical Support Agent for accessing inboxes via the Microsoft email server. This API can also be used for other purposes.
See:
Step 1: Select the API to be used by the Azure AD application.
1. Go to the Home page of your Azure AD application using the breadcrumb at the top of the window. Select API permissions in the left pane.
2. Click + Add a permission.
The list of APIs whose permission can be requested will appear.
3. Select the API you want.
example Technical Support Agent ==> Microsoft Graph Mail API
Step 2: Select the type of permission.
example Type of permission for using the Microsoft Graph Mail API with the Technical Support Agent
- Office 365 protocol: Delegated permissions only (ROPC mode)
- Microsoft Graph protocol: Application permissions (CC mode) or delegated permissions (ROPC mode)
example Type of permission for using the Microsoft Bookings API for accessing customer and business calendars. See Microsoft Bookings integration.
- Delegated permissions only
Note: The type of permission depends on whether or not user sign-in is required.
1. Select Application permissions for the CC mode.
or
Select Delegated permissions for the ROPC mode.
The list of permissions available for the selected API and type of permission will appear.
Step 3: Select the required permissions.
example Permissions required for using the Microsoft Graph Mail API with the Technical Support Agent. See List of permissions for the Microsoft Graph Mail API.
- Office 365 protocol:
- Only delegated permissions (ROPC mode)
- User.Read, IMAP.AccessAsUser.All, offline.access
- Microsoft Graph protocol:
- Application permissions (CC mode) or delegated permissions (ROPC mode)
- User.Read, Mail.ReadWrite, offline.access and optionally Mail.ReadWrite.Shared
example Permissions required for using the Microsoft Bookings API for accessing customer and business calendars. See Microsoft Bookings integration.
1. Select the relevant permissions.
Use the search field to filter permissions.
example Search for mail permissions required by the Technical Support Agent
2. Click Add permissions.
The list of permissions authorizing your Azure AD application to use the API by will be refreshed.
Step 4: Grant administrator consent for permissions.
1. Click Grant admin consent for <votre locataire>.
Note: The button will be grayed out if you do not have the relevant rights to perform the actions in this step. In this case, you should ask the administrator of your tenant to grant consent.
- The list of permissions granted to your Azure AD application will be refreshed.
- The third-party product can now obtain a token for accessing the API and for using API resources.
example
- The Technical Support Agent can access the dedicated inboxes and retrieve messages.
- The Microsoft Graph gateway is enabled and allows access to customer and business calendars. See Microsoft Bookings integration.
AccountFreeCreation
How to create a free Azure account
1. Go to the Microsoft Azure website.
2. Click Start free.
3. Log in to your professional Microsoft account.
4. Enter the login information.
5. Click Next.
6. Tick the I agree box.
7. Click Sign up.