Microsoft 标识平台和 OAuth 2.0 SAML 持有者断言流Microsoft identity platform and OAuth 2.0 SAML bearer assertion flow

当客户端需要使用现有的信任关系时,你可以通过 OAuth 2.0 SAML 持有者断言流使用 SAML 断言请求 OAuth 访问令牌。The OAuth 2.0 SAML bearer assertion flow allows you to request an OAuth access token using a SAML assertion when a client needs to use an existing trust relationship. 应用于 SAML 断言的签名提供已授权应用的身份验证。The signature applied to the SAML assertion provides authentication of the authorized app. SAML 断言是标识提供者颁发的 XML 安全令牌,由服务提供者使用。A SAML assertion is an XML security token issued by an identity provider and consumed by a service provider. 出于安全相关的目的,该服务提供者依赖于其内容来识别断言的使用者。The service provider relies on its content to identify the assertion’s subject for security-related purposes.

SAML 断言将发布到 OAuth 令牌终结点。The SAML assertion is posted to the OAuth token endpoint. 该终结点根据应用的先前审批状态处理断言并颁发访问令牌。The endpoint processes the assertion and issues an access token based on prior approval of the app. 客户端不需要具有或存储刷新令牌,也不需要将客户端密码传递给令牌终结点。The client isn’t required to have or store a refresh token, nor is the client secret required to be passed to the token endpoint.

可以使用 SAML 持有者断言流在不提示用户输入凭据的情况下,从 Microsoft Graph API(仅支持委托的权限)提取数据。SAML Bearer Assertion flow is useful when fetching data from Microsoft Graph APIs (which only support delegated permissions) without prompting the user for credentials. 在此方案中,客户端凭据授予(最适合后台进程)不起作用。In this scenario the client credentials grant, which is preferred for background processes, does not work.

对于执行基于浏览器的交互式登录以获取 SAML 断言,然后要添加对 OAuth 所保护 API(例如 Microsoft Graph)的访问权限的应用程序,可以发出 OAuth 请求来获取 API 的访问令牌。For applications that do interactive browser-based sign-in to get a SAML assertion and then want to add access to an OAuth protected API (such as Microsoft Graph), you can make an OAuth request to get an access token for the API. 将浏览器重定向到 Azure AD 以便对用户进行身份验证时,浏览器将从 SAML 登录中拾取会话,而用户无需输入其凭据。When the browser is redirected to Azure AD to authenticate the user, the browser will pick up the session from the SAML sign-in and the user doesn't need to enter their credentials.

对于使用已联合到 Active Directory 的标识提供者(例如 Azure Active Directory 联合身份验证服务 (ADFS))进行身份验证的用户,也支持 OAuth SAML 持有者断言流。The OAuth SAML Bearer Assertion flow is also supported for users authenticating with identity providers such as Active Directory Federation Services (ADFS) federated to Azure Active Directory. 可在 OAuth 流中使用从 ADFS 获取的 SAML 断言对用户进行身份验证。The SAML assertion obtained from ADFS can be used in an OAuth flow to authenticate the user.

OAuth 流

使用 SAML 持有者断言的调用关系图Call Graph using SAML bearer assertion

现在,让我们了解如何以编程方式实际提取 SAML 断言。Now let us understand on how we can actually fetch SAML assertion programatically. 此方法已使用 ADFS 进行测试。This approach is tested with ADFS. 不过,此方法也适用于支持以编程方式返回 SAML 断言的任何标识提供者。However, this works with any identity provider that supports the return of SAML assertion programatically. 基本过程是:获取 SAML 断言,获取访问令牌,然后访问 Microsoft Graph。The basic process is: get a SAML assertion, get an access token, and access Microsoft Graph.

先决条件Prerequisites

在授权服务器/环境 (Microsoft 365) 与标识提供者或 SAML 2.0 持有者断言 (ADFS) 颁发者之间建立信任关系。Establish a trust relationship between the authorization server/environment (Microsoft 365) and the identity provider, or issuer of the SAML 2.0 bearer assertion (ADFS).

门户中注册应用程序:Register the application in the portal:

  1. 登录到门户的应用注册边栏选项卡(请注意,我们将对图形 API 使用 v2.0 终结点,因此需要在此门户中注册应用程序。Sign in to the app registration blade of the portal (Please note that we are using the v2.0 endpoints for Graph API and hence need to register the application in this portal. 否则可以使用 Azure Active Directory 中的注册)。Otherwise we could have used the registrations in Azure active directory).
  2. 选择“新注册”。Select New registration.
  3. “注册应用程序”页出现后,请输入应用程序的注册信息:When the Register an application page appears, enter your application's registration information:
    1. 名称:输入一个会显示给应用用户的有意义的应用程序名称。Name - Enter a meaningful application name that will be displayed to users of the app.
    2. 支持的帐户类型 - 选择希望应用程序支持的帐户。Supported account types - Select which accounts you would like your application to support.
    3. 重定向 URI (可选) - 选择要生成的应用的类型:“Web”或“公共客户端(移动和桌面)”,然后输入应用程序的重定向 URI (或回复 URL)。Redirect URI (optional) - Select the type of app you're building, Web, or Public client (mobile & desktop), and then enter the redirect URI (or reply URL) for your application.
    4. 完成后,选择“注册”。When finished, select Register.
  4. 请记下应用程序(客户端)ID。Make a note of the application (client) ID.
  5. 在左窗格中,选择“证书和密码”。In the left pane, select Certificates & secrets. 在“客户端密码”部分中,单击“新建客户端密码” 。Click New client secret in the Client secrets section. 复制新客户端密码,在离开边栏选项卡后,你将无法进行检索。Copy the new client secret, you won't be able to retrieve when you leave the blade.
  6. 在左窗格中,选择“API 权限”,然后选择“添加权限”。In the left pane, select API permissions and then Add a permission. 依次选择“Microsoft Graph”、“委托的权限”和“Tasks.read”,因为我们打算使用 Outlook 图形 API。Select Microsoft Graph, then delegated permissions, and then select Tasks.read since we intend to use the Outlook Graph API.

安装 Postman(测试示例请求所需的工具)。Install Postman, a tool required to test the sample requests. 稍后可以将请求转换为代码。Later, you can convert the requests to code.

从 ADFS 获取 SAML 断言Get the SAML assertion from ADFS

使用 SOAP 信封创建对 ADFS 终结点的 POST 请求,以提取 SAML 断言:Create a POST request to the ADFS endpoint using SOAP envelope to fetch the SAML assertion:

获取 SAML 断言

标头值:Header values:

标头值

ADFS 请求正文:ADFS request body:

ADFS 请求正文

成功发布此请求后,你应会收到来自 ADFS 的 SAML 断言。Once this request is posted successfully, you should receive a SAML assertion from ADFS. 只需提供 SAML:Assertion 标记数据,请将其转换为 base64 编码,以便在后续请求中使用。Only the SAML:Assertion tag data is required, convert it to base64 encoding to use in further requests.

使用 SAML 断言获取 OAuth2 令牌Get the OAuth2 token using the SAML assertion

在此步骤中,使用 ADFS 断言响应提取 OAuth2 令牌。In this step, fetch an OAuth2 token using the ADFS assertion response.

  1. 按如下所示创建包含标头值的 POST 请求:Create a POST request as shown below with the header values:

    POST 请求

  2. 在请求的正文中,替换 client_id、client_secret和 assertion (在上一步骤中获取的 base64 编码 SAML 断言):In the body of the request, replace client_id, client_secret, and assertion (the base64 encoded SAML assertion obtained the previous step):

    请求正文

  3. 成功发出请求后,你将收到来自 Azure Active Directory 的访问令牌。Upon successful request, you will receive an access token from Azure active directory.

使用 Oauth 令牌获取数据Get the data with the Oauth token

收到访问令牌后,调用图形 API(在此示例中为 Outlook 任务)。After receiving the access token, call the Graph APIs (Outlook tasks in this example).

  1. 使用上一步骤中提取的访问令牌创建 GET 请求:Create a GET request with the access token fetched in the previous step:

    GET 请求

  2. 成功发出请求后,你将收到 JSON 响应。Upon successful request, you will receive a JSON response.

后续步骤Next steps

了解不同的身份验证流和应用程序方案Learn about the different authentication flows and application scenarios.