Azure AD

Introduction

Azure AD enables features like SSO and for personalizing the app experiences using existing organization data through APIs. For IT admins, it allows complete control over access to applications and resources utilizing security controls like MFA and conditional access.

Simplify single sign-on. Azure AD supports more than 2,800 pre-integrated software as a service (SaaS) applications.

Yellow.ai comes pre-built with the ADFS (Active Directory Federation Services) integration and generic OAuth implementation.

If ADFS is enabled for authentication, the bot will redirect the user to the AD (Active Directory) login page, wherein the user will need to provide their credentials and once AD authenticates the user, a callback is triggered by ADFS to YM indicating the success or failure of the authentication. When the authentication is successful, ADFS provides the authentication token along with a refresh token and time to live for the token.

App Registration on AAD

For connecting Azure AD with YM bot, following details need to be obtained using AD App registration:

1. Client ID / Application ID
2. Tenant ID
3. Client Secret

Steps to configure App in Azure AD:

Step 1: Go to portal.azure.com > Active Directory > App Registrations.

Step 2: Register a new app for the chatbot (if not already registered)

Step 3: Copy and Save the Application/Client ID and tenant ID from overview section.

Step 4: Go to Certificates & Secrets > New client secret > Fill the description & select expires to Never, After clicking on Add button a Client Secret will be generated, save the value of the Client Secret.

Step 5: Goto Authentication > Add a platform > Web > Add the redirect url > Save. Redirect-Url: https://app.yellowmessenger.com/integrations/azureauth/

Step 6: Add / Remove permission and Grant Admin consent for the App. Goto API Permissions > Add the required permissions.

Common permission:

Scope	Description
openid, email, profile, User.Read	Used to retrieve login details & their profile using Graph Api
offline_access	Required to obtain refresh token
User.Read.All	Read profile of all the user in the tenant.
Calendars.ReadWrite	Edit User’s calendar / meetings

Graph Permission: https://docs.microsoft.com/en-us/graph/permissions-reference

Steps to configure registered app in YM bot:

1. Go to the YM bot > Configuration > Integrations > Azure Active Directory
2. Enter the obtained Tenant ID, Client ID, Client Secret
3. Enter the API version to v2.0
4. Enter the required scope > Save

5. If you have multiple accounts, follow the above mentioned steps to add each of them.

note

1. Enter a unique name for each account to easily identify them within the yellow.ai platform. It is recommended to use a name that aligns with its purpose for better usability.
2. You can add a maximum of 15 accounts.
3. In a two-tier environment, such as bots with only Development/Live environments, you can add account names only in the development mode. Once added and flows have been built, in the Live mode, you can only choose the account names and not edit them.
4. In a three-tier environment, such as bots with Staging/Sandbox/Production modes, in Staging and Sandbox modes, you can add and edit new accounts. However, in Production, only the account details added in Staging will be available. You can only map in the production environment.

Obtain Azure AD Login url:

let consent = "&prompt=login"  //prompt=login allow user to choose a logging account

{
   "title": "Login",
   "url": app.azure.auth() + consent                     
}

Response

app.log(app.data)
{
   "event": {
       "code": "azure-auth-success",
       "data": {
           "token_type": "Bearer",
           "scope": "Calendars.ReadWrite email openid profile User.Read",
           "expires_in": 3599,
           "ext_expires_in": 3599,
           "access_token": "eyJ0eXXXXXXXXXXXXXXXXX",
           "refresh_token": "aiJ0eXXXXXXXXXXXXXXXX"
       }
   }
 }

Access Token can be used to get access to resources of allowed applications. Expire time : 1 hour.

Azure allows an expired access-token to be refreshed using the Refresh Token for a maximum period of time of 90 days.

Retrieve user profile using AD refresh token & Graph Api

Request

curl --location --request GET 'https://graph.microsoft.com/v1.0/me' \
--header 'Authorization: Bearer {accessToken}' \

Response

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "businessPhones": [],
    "displayName": "Shubhi Saxena",
    "givenName": "Shubhi",
    "jobTitle": null,
    "mail": "[email protected]",
    "mobilePhone": null,
    "surname": "Saxena",
    "userPrincipalName": "[email protected]",
    "id": "e4a5dbe5-4750-41e7-8axxxxxxxxx"
}

Other useful Graph APIs:

1. Get events of user
2. Send email on behalf of user
3. Load tasks of user
4. Update password

Graph APIs: https://docs.microsoft.com/en-US/graph/api/overview?view=graph-rest-1.0

Graph Explorer: https://developer.microsoft.com/en-us/graph/graph-explorer

References

1. Azure ADFS
2. Active Directory authentication
3. Graph APIs
4. App Registration