Edit

Link Azure Active Directory identity with your own identity provider (Preview)

  • Article

Important

Onboarding of new Actionable Messages providers with a Global scope is temporarily paused until Jun 30th, 2024 due to service upgrades. Existing Global scoped providers and onboarding of Organization and Test scope providers are not impacted. For more details, see Frequently asked questions for Actionable Messages.

Action.Http actions in actionable messages include an Azure AD-issued token in the Authorization header, which provides information about the user's identity. However, this information may not be sufficient to authenticate the user to your service. With identity linking, you can signal the Outlook client to present UI to allow the user to authenticate with your service. Once the user authenticates, you can associate their Azure AD identity with your own to allow for seamless authentication for future requests.

Using identity linking

Your service can trigger authentication on any Action.Http action endpoint by returning a 401 Unauthorized response with a ACTION-AUTHENTICATE header. The header contains the authentication URL for your service.

Once authentication is completed, redirect the request to the URL specified in the Identity-Linking-Redirect-Url header sent in the original request.

Identity linking flow

Initial request to your action endpoint

Microsoft servers send an initial POST request to your action endpoint.

POST https://api.contoso.com/myEndpoint
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6...
Identity-Linking-Redirect-Url: https://outlook.office.com/connectors/adelev@contoso.com/723a1c49-f8dc-4063-843e-d4c2b7180b8b/postAuthenticate
Content-Type: application/json

{
  // action body
}

Your service validates the JWT token and extracts the user's identity from the sub claim.

{
  ...
  "sub": "AdeleV@contoso.com",
  "aud": "https://api.contoso.com"
}

Your service finds no user with a linked identity of AdeleV@contoso.com so it persists Identity-Linking-Redirect-Url header value and returns a 401 response.

Note

The exact method you use to persist the redirect URL from the Identity-Linking-Redirect-Url header is dependent on your implementation. If your service uses OAuth, you may save it in the state parameter, for example.

HTTP/1.1 401 Unauthorized
ACTION-AUTHENTICATE: https://identity.contoso.com/authenticate?state=https://outlook.office.com/connectors/adelev@contoso.com/723a1c49-f8dc-4063-843e-d4c2b7180b8b/postAuthenticate

Authentication request

After Outlook receives the 401 with the ACTION-AUTHENTICATE header, it will open a task pane and navigate to the URL from the header.

GET https://identity.contoso.com/authenticate?state=https://outlook.office.com/connectors/adelev@contoso.com/723a1c49-f8dc-4063-843e-d4c2b7180b8b/postAuthenticate

Your service authenticates the user and associates the identity provided by the Azure AD-issued token with the user in your system. Once complete, the service redirects the request to the URL from the Identity-Linking-Redirect-Url header.

HTTP/1.1 302 Found
Location: https://outlook.office.com/connectors/adelev@contoso.com/723a1c49-f8dc-4063-843e-d4c2b7180b8b/postAuthenticate

Retry action

After Outlook receives the redirect back from your authentication server, it immediately retries the original request. This time, because you've associated the Azure AD identity with your own, your endpoint processes the request normally.

Example

You can use the following sample card in the Actionable Message Designer to see this in action. The endpoint in this card will prompt you to login to the Microsoft identity platform and (with your consent) will make a Graph request to get your profile. The code for this endpoint is available as a sample on GitHub.

{
  "hideOriginalBody": true,
  "type": "AdaptiveCard",
  "padding": "none",
  "body": [
    {
      "type": "TextBlock",
      "text": "Identity Linking Demo"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Http",
          "method": "POST",
          "url": "https://amidentitylinking.azurewebsites.net/action",
          "body": "{}",
          "title": "Get User Details",
          "isPrimary": true
        }
      ]
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.0"
}

Client support roadmap

Identity linking is available to a limited set of clients, with support for the feature being added in the future. The following table provides the approximate timeline.

Client Availability
Office 365 ProPlus Available
Outlook on the web for Office 365 Coming soon
Outlook on iOS Coming soon
Outlook on Android Coming soon
Outlook on Mac TBD

Resources