API 管理身份验证策略API Management authentication policies

本主题提供以下 API 管理策略的参考。This topic provides a reference for the following API Management policies. 有关添加和配置策略的信息,请参阅 API 管理中的策略For information on adding and configuring policies, see Policies in API Management.

身份验证策略Authentication policies

使用基本方法进行身份验证Authenticate with Basic

通过 authentication-basic 策略使用基本身份验证方法向后端服务进行身份验证。Use the authentication-basic policy to authenticate with a backend service using Basic authentication. 此策略有效地将 HTTP 授权标头设置为与策略中提供的凭据对应的值。This policy effectively sets the HTTP Authorization header to the value corresponding to the credentials provided in the policy.

策略语句Policy statement

<authentication-basic username="username" password="password" />

示例Example

<authentication-basic username="testuser" password="testpassword" />

元素Elements

名称Name 说明Description 必须Required
authentication-basicauthentication-basic 根元素。Root element. Yes

属性Attributes

名称Name 说明Description 必须Required 默认Default
usernameusername 指定基本凭据的用户名。Specifies the username of the Basic credential. Yes 空值N/A
passwordpassword 指定基本凭据的密码。Specifies the password of the Basic credential. Yes 空值N/A

使用情况Usage

此策略可在以下策略范围中使用。This policy can be used in the following policy sections and scopes.

  • 策略节: 入站Policy sections: inbound

  • 策略范围: 所有范围Policy scopes: all scopes

使用客户端证书进行身份验证Authenticate with client certificate

通过 authentication-certificate 策略使用客户端证书向后端服务进行身份验证。Use the authentication-certificate policy to authenticate with a backend service using client certificate. 需要首先将证书安装到 API 管理,并由其指纹进行标识。The certificate needs to be installed into API Management first and is identified by its thumbprint.

策略语句Policy statement

<authentication-certificate thumbprint="thumbprint" certificate-id="resource name"/>

示例Examples

在此示例中,客户端证书是由其指纹标识的:In this example, the client certificate is identified by its thumbprint:

<authentication-certificate thumbprint="CA06F56B258B7A0D4F2B05470939478651151984" />

在此示例中,客户端证书是由资源名称标识的:In this example, the client certificate is identified by the resource name:

<authentication-certificate certificate-id="544fe9ddf3b8f30fb490d90f" />  

在此示例中,客户端证书是在策略中设置的,而不是从内置证书存储中检索到的:In this example, the client certificate is set in the policy rather than retrieved from the built-in certificate store:

<authentication-certificate body="@(context.Variables.GetValueOrDefault<byte[]>("byteCertificate"))" password="optional-certificate-password" />

元素Elements

名称Name 说明Description 必须Required
authentication-certificateauthentication-certificate 根元素。Root element. Yes

属性Attributes

名称Name 说明Description 必须Required 默认Default
thumbprintthumbprint 客户端证书的指纹。The thumbprint for the client certificate. 必须提供 thumbprintcertificate-idEither thumbprint or certificate-id must be present. 空值N/A
certificate-idcertificate-id 证书资源名称。The certificate resource name. 必须提供 thumbprintcertificate-idEither thumbprint or certificate-id must be present. 空值N/A
bodybody 字节数组形式的客户端证书。Client certificate as a byte array. No 空值N/A
passwordpassword 客户端证书的密码。Password for the client certificate. 如果在 body 中指定的证书受密码保护,则使用。Used if certificate specified in body is password protected. 空值N/A

使用情况Usage

此策略可在以下策略范围中使用。This policy can be used in the following policy sections and scopes.

  • 策略节: 入站Policy sections: inbound

  • 策略范围: 所有范围Policy scopes: all scopes

使用托管标识进行身份验证Authenticate with managed identity

通过 authentication-managed-identity 策略使用托管标识向后端服务进行身份验证。Use the authentication-managed-identity policy to authenticate with a backend service using the managed identity. 此策略实质上使用托管标识从 Azure Active Directory 获取访问令牌以访问指定资源。This policy essentially uses the managed identity to obtain an access token from Azure Active Directory for accessing the specified resource. 成功获取令牌后,策略将使用 Bearer 方案在 Authorization 标头中设置令牌的值。After successfully obtaining the token, the policy will set the value of the token in the Authorization header using the Bearer scheme.

系统分配的标识和多个用户分配的标识都可用来请求令牌。Both system-assigned identity and any of the multiple user-assigned identity can be used to request token. 如果未提供 client-id,则采用系统分配的标识。If client-id is not provided system-assigned identity is assumed. 如果提供了 client-id 变量,则从 Azure Active Directory 为该用户分配标识请求令牌If the client-id variable is provided token is requested for that user-assigned identity from Azure Active Directory

策略语句Policy statement

<authentication-managed-identity resource="resource" client-id="clientid of user-assigned identity" output-token-variable-name="token-variable" ignore-error="true|false"/>  

示例Example

使用托管标识向后端服务进行身份验证Use managed identity to authenticate with a backend service

<authentication-managed-identity resource="https://microsoftgraph.chinacloudapi.cn"/> 
<authentication-managed-identity resource="https://management.chinacloudapi.cn/"/> <!--Azure Resource Manager-->
<authentication-managed-identity resource="https://vault.azure.cn"/> <!--Azure Key Vault-->
<authentication-managed-identity resource="https://servicebus.chinacloudapi.cn/"/> <!--Azure Service Bus-->
<authentication-managed-identity resource="https://storage.azure.cn/"/> <!--Azure Blob Storage-->
<authentication-managed-identity resource="https://database.chinacloudapi.cn/"/> <!--Azure SQL-->
<authentication-managed-identity resource="api://Client_id_of_Backend"/> <!--Your own Azure AD Application-->

使用托管标识并手动设置标头Use managed identity and set header manually

<authentication-managed-identity resource="api://Client_id_of_Backend"
   output-token-variable-name="msi-access-token" ignore-error="false" /> <!--Your own Azure AD Application-->
<set-header name="Authorization" exists-action="override">
   <value>@("Bearer " + (string)context.Variables["msi-access-token"])</value>
</set-header>

在发送请求策略中使用托管标识Use managed identity in send-request policy

<send-request mode="new" timeout="20" ignore-error="false">
    <set-url>https://example.com/</set-url>
    <set-method>GET</set-method>
    <authentication-managed-identity resource="ResourceID"/>
</send-request>

元素Elements

名称Name 说明Description 必须Required
authentication-managed-identityauthentication-managed-identity 根元素。Root element. Yes

属性Attributes

名称Name 说明Description 必须Required 默认Default
resourceresource 字符串。String. Azure Active Directory 中的目标 Web API(受保护的资源)的应用 ID。The App ID of the target web API (secured resource) in Azure Active Directory. Yes 空值N/A
client-idclient-id 字符串。String. Azure Active Directory 中的用户分配标识的应用 ID。The App ID of the user-assigned identity in Azure Active Directory. No 系统分配的标识system-assigned identity
output-token-variable-nameoutput-token-variable-name 字符串。String. 上下文变量的名称,它将令牌值接收为对象类型 stringName of the context variable that will receive token value as an object type string. No 空值N/A
ignore-errorignore-error 布尔值。Boolean. 如果设置为 true,即使未获得访问令牌,策略管道也将继续执行。If set to true, the policy pipeline will continue to execute even if an access token is not obtained. No falsefalse

使用情况Usage

此策略可在以下策略范围中使用。This policy can be used in the following policy sections and scopes.

  • 策略节: 入站Policy sections: inbound

  • 策略范围: 所有范围Policy scopes: all scopes

后续步骤Next steps

有关如何使用策略的详细信息,请参阅:For more information working with policies, see: