Azure AD integration
Azure Active Directory (Azure AD) enhances user management by enabling Single Sign-On (SSO) and personalized app experiences through the use of organizational data APIs. This integration also offers IT administrators comprehensive control over application and resource access, using advanced security features like Multi-Factor Authentication (MFA) and conditional access.
Key Features:
- SSO for Seamless Access: Azure AD supports integration with over 2,800 pre-configured Software as a Service (SaaS) applications, simplifying access management across systems.
- Security and Personalization: Use organization-specific data to create secure, tailored experiences.
Yellow.ai Compatibility:
Yellow.ai comes pre-integrated with:
- Active Directory Federation Services (ADFS)
- Generic OAuth implementation
This ensures secure authentication while supporting diverse organizational needs.
Authentication Flow:
When ADFS is enabled:
- The bot redirects you to the Active Directory login page for credential input.
- AD validates the credentials.
- Upon successful authentication, ADFS triggers a callback to Yellow.ai to indicate the result.
- If authentication succeeds, ADFS generates:
- An authentication token
- A refresh token
- The token’s time-to-live (TTL)
These tokens allow secure access while maintaining control over session duration.
App Registration on Azure AD
To connect Azure AD with your Yellow.ai bot, you must first register an app in Azure AD and retrieve the following details:
- Client ID (Application ID)
- Tenant ID
- Client Secret
Steps to Configure the App in Azure AD
Log in to Azure Portal and navigate to Active Directory > App Registrations.
Register a new application for the chatbot (if not already registered).
Copy and save the Application/Client ID and Tenant ID from the Overview section.
Navigate to Certificates & Secrets:
- Click New Client Secret.
- Provide a description and set the expiration to Never.
- Click Add, and copy the generated Client Secret for future use.
Go to Authentication:
- Click Add a Platform > Web.
- Add the Redirect URL:
https://app.yellowmessenger.com/integrations/azureauth/ - Click Save.
Configure Permissions:
- Navigate to API Permissions > Add Permission.
- Add the following common permissions and grant Admin Consent:
Scope Description openid, email, profile, User.Read Retrieve login details and user profiles using Graph API. offline_access Required for refresh token retrieval. User.Read.All Read user profiles in the tenant. Calendars.ReadWrite Modify user calendars and meetings. For more details, refer to the Graph Permissions Guide.
Steps to Integrate Azure App with Yellow.ai Bot
In the Yellow.ai platform, navigate to the Development or Staging environment:
- Go to Extensions > Integrations > Tools & Utilities > Azure.
- Use the search box if needed.
In the Account Name field, provide a unique name for the integration (use lowercase alphanumeric characters and underscores only).
Enter the following details obtained from Azure AD:
- Tenant ID
- Client ID
- Client Secret
Set the API version to v2.0.
Specify the required Scope (e.g.,
Calendars.ReadWrite offline_access User.Read).Click Connect.
To connect additional accounts, click + Add Account and repeat the steps above. A maximum of 15 accounts can be added.
Authentication Workflow
When a user initiates authentication via Azure AD:
- The bot redirects the user to the Active Directory login page.
- After entering their credentials, AD validates them.
- Upon successful authentication, Azure AD sends a callback to Yellow.ai with:
- Access Token
- Refresh Token
- Token Expiry Details
Access Token Usage
The Access Token allows secure access to resources within the permissions granted. Note: Tokens expire in 1 hour but can be refreshed using the Refresh Token for up to 90 days.
Retrieve User Profile via Graph API
To fetch user details using the Access Token, send a GET request to the Microsoft Graph API:
Request:
curl --location --request GET 'https://graph.microsoft.com/v1.0/me' \
--header 'Authorization: Bearer {accessToken}'
Response Example:
{
"@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
Resources for Exploration
This version ensures clarity, professionalism, and adherence to documentation standards. It is structured for easy navigation and a seamless user experience.
App Registration on AAD
For connecting Azure AD with YM bot, following details need to be obtained using AD App registration:
- Client ID / Application ID
- Tenant ID
- Client Secret
Steps to configure App in Azure AD
Go to portal.azure.com > Active Directory > App Registrations.
Register a new app for the chatbot (if not already registered)
Copy and Save the Application/Client ID and tenant ID from overview section.
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.
Goto Authentication > Add a platform > Web > Add the redirect URL > Save.
Redirect-Url: https://app.yellowmessenger.com/integrations/azureauth/
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 integrate Azure app with yellow.ai bot:
On the Cloud platform, navigate to Development/Staging environment and go to Extensions > Integrations > Tools & Utilities > Azure. Alternatively, you can use the Search box to find a specific integration.
In Give account name, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (
_).Enter the obtained Tenant ID, Client ID, Client Secret.
Enter the API version to v2.0
Enter the required scope.
Click Connect.
- If you want to connect multiple accounts, click + Add account and proceed with the previous steps. You can add a maximum of 15 accounts.
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:
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