Skip to main content

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:

  1. The bot redirects you to the Active Directory login page for credential input.
  2. AD validates the credentials.
  3. Upon successful authentication, ADFS triggers a callback to Yellow.ai to indicate the result.
  4. 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:

  1. Client ID (Application ID)
  2. Tenant ID
  3. Client Secret

Steps to Configure the App in Azure AD​

  1. Log in to Azure Portal and navigate to Active Directory > App Registrations.

  2. Register a new application for the chatbot (if not already registered).

  3. Copy and save the Application/Client ID and Tenant ID from the Overview section.

  4. 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.

  5. Go to Authentication:

    • Click Add a Platform > Web.
    • Add the Redirect URL:
      https://app.yellowmessenger.com/integrations/azureauth/
    • Click Save.

  6. Configure Permissions:

    • Navigate to API Permissions > Add Permission.
    • Add the following common permissions and grant Admin Consent:
    ScopeDescription
    openid, email, profile, User.ReadRetrieve login details and user profiles using Graph API.
    offline_accessRequired for refresh token retrieval.
    User.Read.AllRead user profiles in the tenant.
    Calendars.ReadWriteModify user calendars and meetings.

    For more details, refer to the Graph Permissions Guide.

Steps to Integrate Azure App with Yellow.ai Bot​

  1. 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.

  2. In the Account Name field, provide a unique name for the integration (use lowercase alphanumeric characters and underscores only).

  3. Enter the following details obtained from Azure AD:

    • Tenant ID
    • Client ID
    • Client Secret

  4. Set the API version to v2.0.

  5. Specify the required Scope (e.g., Calendars.ReadWrite offline_access User.Read).

  6. Click Connect.

  7. 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:

  1. The bot redirects the user to the Active Directory login page.
  2. After entering their credentials, AD validates them.
  3. 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.

Obtain Azure AD Login URL​

To trigger the Azure AD login redirect from a flow, use app.azure.auth():

let consent = "&prompt=login";  // prompt=login allows user to choose a login account

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

Response​

Once authentication completes, the callback event carries the token payload:

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"
    }
  }
}

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​

  1. Get User Events
  2. Send Email on Behalf of a User
  3. Retrieve User Tasks
  4. Update Password

Resources for Exploration​

References​

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