Microsoft Azure Integration - Create an Azure AD Application with API Permissions

Last modified on 2023/01/26 14:09

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. Open url.png 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

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.
         App registrations.png

2. Click + New registration.

The properties window will appear.
         App registration - Creation.png

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.

Best Practice icon.png  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).

Best Practice icon.png  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.
    App registration - App with IDs created.png

5. Retrieve the IDs required for configuring your third-party product.

  • Hover over the relevant ID and click Copy icon.png 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.
         Certificates and secrets - Creation.png

The properties window will appear.
         Certificates and secrets - Properties.png

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.

Best Practice icon.png  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.
    Certificates and secrets - Secret client created.png

4. Retrieve the client secret required for configuring your third-party product.

Caution: The value of the new client secret can be retrieved only during this step. Once you move on to the next step, the client secret will be hidden using the * character. If you lose the client secret, you must regenerate a new one.

  • Click Copy icon.png 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.
         User management - Add user - Add assignment - AST example.png

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.
         User management - Managed application in local directory option.png

A window displaying the application's local properties will appear.

2. Select Properties in the left pane.

          User management - Managed application in local directory properties.png

3. Select Yes in the User assignment required? field.

4. Click Save.

          User management - User assignment required property.png
 

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.
         User management - Add user.png

  • The window for adding an assignment will appear.
  • The list of users declared for the tenant will appear.
    User management - Add user - Add assignment.png

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.

Best Practice icon.png  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.
         User management - Add user - Assignment added.png

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.
    Open url.png 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.

          API permissions.png

2. Click + Add a permission.

The list of APIs whose permission can be requested will appear.
         API permissions - Creation.png

3. Select the API you want.

example  Technical Support Agent ==> Microsoft Graph Mail API

API permissions - Selection MS Graph API.png

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. Open url.png 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.
         API permissions - Selection MS Graph API - Application permissions.png

or

Select Delegated permissions for the ROPC mode.

          API permissions - Selection MS Graph API - Delegated permissions.png

The list of permissions available for the selected API and type of permission will appear.
         API permissions - List.png

Step 3: Select the required permissions.

example  Permissions required for using the Microsoft Graph Mail API with the Technical Support Agent. Open url 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. Open url.png See Microsoft Bookings integration.

1. Select the relevant permissions.

Best Practice icon.png  Use the search field to filter permissions.

example  Search for mail permissions required by the Technical Support Agent

API permissions - MS Graph with Application permission - Permission readwrite selected.png

2. Click Add permissions.
The list of permissions authorizing your Azure AD application to use the API by will be refreshed.
         API permissions - MS Graph with Application permission - Permission readwrite added.png

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.
    API permissions - MS Graph with Application permission - API permissions granted.png
  • The third-party product can now obtain a token for accessing the API and for using API resources.

    example

AccountFreeCreation

How to create a free Azure account

1. Go to the Microsoft Azure website.

2. Click Start free.

          Microsoft Flow - Free account.png

3. Log in to your professional Microsoft account.
         Microsoft Flow - Login account.png

4. Enter the login information.
         Microsoft Flow - Account creation - Identification 1.png

5. Click Next.

6. Tick the I agree box.
         Microsoft Flow - Account creation - Identification 2.png

7. Click Sign up.

Tags:
Powered by XWiki © EasyVista 2022