Link Azure Active Directory identity with your own identity provider (Preview)
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
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for