使用您自己的标识提供程序链接 Azure Active Directory 标识(预览)Link Azure Active Directory identity with your own identity provider (Preview)

操作。可操作邮件中的 Http 操作包括标头中的 AAD 颁发令牌 Authorization ,其中提供了有关用户标识的信息。Action.Http actions in actionable messages include an AAD-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. 通过标识链接,您可以通知 Outlook 客户端显示 UI,以允许用户通过您的服务进行身份验证。With identity linking, you can signal the Outlook client to present UI to allow the user to authenticate with your service. 一旦用户进行身份验证,您就可以将其 AAD 标识与您自己关联起来,以允许对将来的请求进行无缝身份验证。Once the user authenticates, you can associate their AAD identity with your own to allow for seamless authentication for future requests.

使用标识链接Using identity linking

Action.Http 的服务通过返回 401 Unauthorized 带有标头的响应来触发任何操作终结点上的身份验证 ACTION-AUTHENTICATEYour service can trigger authentication on any Action.Http action endpoint by returning a 401 Unauthorized response with a ACTION-AUTHENTICATE header. 标头包含服务的身份验证 URL。The header contains the authentication URL for your service.

身份验证完成后,将请求重定向到在 Identity-Linking-Redirect-Url 原始请求中发送的标头中指定的 URL。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 服务器向您的操作终结点发送初始 POST 请求。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
}

您的服务将验证 JWT 令牌,并从声明中提取用户的标识 subYour service validates the JWT token and extracts the user's identity from the sub claim.

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

您的服务找不到具有链接标识的用户 AdeleV@contoso.com ,因此它将保留 Identity-Linking-Redirect-Url 标头值并返回 401 响应。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.

备注

您用来保存标头中的重定向 URL 的确切方法 Identity-Linking-Redirect-Url 取决于您的实现。The exact method you use to persist the redirect URL from the Identity-Linking-Redirect-Url header is dependent on your implementation. 如果服务使用 OAuth,则可以将其保存在 state 参数中,例如。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

在 Outlook 接收到 401 ACTION-AUTHENTICATE 邮件头后,它将打开一个任务窗格,并导航到邮件头中的 URL。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

您的服务对用户进行身份验证,并将 AAD 颁发的令牌提供的标识与系统中的用户相关联。Your service authenticates the user and associates the identity provided by the AAD-issued token with the user in your system. 完成后,服务会将请求重定向到标头中的 URL Identity-Linking-Redirect-UrlOnce 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

在 Outlook 从身份验证服务器收到重定向回后,它会立即重试原始请求。After Outlook receives the redirect back from your authentication server, it immediately retries the original request. 这次,由于你已将 AAD 标识与您自己关联,因此终结点通常会处理请求。This time, because you've associated the AAD identity with your own, your endpoint processes the request normally.

示例Example

您可以使用卡片样本中的以下示例卡来查看此操作。You can use the following sample card in the Card Playground to see this in action. 此卡片中的终结点将提示你登录 Microsoft identity platform,(同意)将发出图形请求获取你的配置文件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. 此终结点的代码可用作GitHub上的示例。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.

ClientClient 供应情况Availability
Office 365 专业增强版Office 365 ProPlus 可用Available
Office 365 Outlook 网页版Outlook on the web for Office 365 即将推出Coming soon
iOS 版 OutlookOutlook on iOS 即将推出Coming soon
Android 版 OutlookOutlook on Android 即将推出Coming soon
Mac 版 OutlookOutlook on Mac 待定TBD

资源Resources