接受 v1.0 令牌中的 Web API 的范围Scopes for a web API accepting v1.0 tokens

OAuth2 权限是适用于开发人员的 Azure Active Directory (Azure AD) (v1.0) Web API(资源)应用程序向客户端应用程序公开的权限范围。OAuth2 permissions are permission scopes that a Azure Active Directory (Azure AD) for developers (v1.0) web API (resource) application exposes to client applications. 在许可期间,可将这些权限范围授予客户端应用程序。These permission scopes may be granted to client applications during consent. 请参阅 Azure Active Directory 应用程序清单参考中有关 oauth2Permissions 的部分。See the section about oauth2Permissions in the Azure Active Directory application manifest reference.

将请求访问权限范围限定为 v1.0 应用程序的特定 OAuth2 权限Scopes to request access to specific OAuth2 permissions of a v1.0 application

若要获取 v1.0 应用程序(例如 Microsoft Graph API,网址为 https://microsoftgraph.chinacloudapi.cn) 的特定范围的令牌,请将所需资源标识符与该资源所需的 OAuth2 权限进行连接以创建范围。To acquire tokens for specific scopes of a v1.0 application (for example the Microsoft Graph API, which is https://microsoftgraph.chinacloudapi.cn), create scopes by concatenating a desired resource identifier with a desired OAuth2 permission for that resource.

例如,若要以用户的身份访问应用 ID URI 为 ResourceId 的 v1.0 Web API,请执行以下操作:For example, to access on behalf of the user a v1.0 web API where the app ID URI is ResourceId:

var scopes = new [] {  ResourceId+"/user_impersonation"};
var scopes = [ ResourceId + "/user_impersonation"];

若要使用 Microsoft Graph API (https://microsoftgraph.chinacloudapi.cn/) 通过 MSAL.NET Azure AD 进行读取和写入,请按以下示例所示创建范围列表:To read and write with MSAL.NET Azure AD using the Microsoft Graph API (https://microsoftgraph.chinacloudapi.cn/), create a list of scopes as shown in the following examples:

string ResourceId = "https://microsoftgraph.chinacloudapi.cn/";
var scopes = new [] { ResourceId + "Directory.Read", ResourceID + "Directory.Write"}
var ResourceId = "https://microsoftgraph.chinacloudapi.cn/";
var scopes = [ ResourceId + "Directory.Read", ResourceID + "Directory.Write"];

若要写入对应于 Azure 资源管理器 API (https://management.core.chinacloudapi.cn/) 的范围,请求以下范围(请注意有两个斜杠):To write the scope corresponding to the Azure Resource Manager API (https://management.core.chinacloudapi.cn/), request the following scope (note the two slashes):

var scopes = new[] {"https://management.core.chinacloudapi.cn//user_impersonation"};
var result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();

// then call the API: https://management.chinacloudapi.cn/subscriptions?api-version=2016-09-01

备注

使用两个斜杠是因为 Azure 资源管理器 API 要求在其受众声明 (aud) 中使用一个斜杠,然后使用一个斜杠来分隔 API 名称与范围。Use two slashes because the Azure Resource Manager API expects a slash in its audience claim (aud), and then there is a slash to separate the API name from the scope.

下面是 Azure AD 使用的逻辑:The logic used by Azure AD is the following:

  • 对于使用 v1.0 访问令牌(只能使用此类令牌)的 ADAL (Azure AD v1.0) 终结点,aud=resourceFor ADAL (Azure AD v1.0) endpoint with a v1.0 access token (the only possible), aud=resource
  • 对于要求资源访问令牌接受 v2.0 令牌的 MSAL(Microsoft 标识平台),aud=resource.AppIdFor MSAL (Microsoft identity platform) asking an access token for a resource accepting v2.0 tokens, aud=resource.AppId
  • 对于要求资源访问令牌接受 v1.0 令牌的 MSAL(v2.0 终结点)(与上面的情况相同),Azure AD 将提取最后一个斜杠前面的所有内容并将其用作资源标识符,以分析请求的范围中的所需受众。For MSAL (v2.0 endpoint) asking an access token for a resource that accepts a v1.0 access token (which is the case above), Azure AD parses the desired audience from the requested scope by taking everything before the last slash and using it as the resource identifier. 因此,如果 https://database.chinacloudapi.cn 预期的受众为“https://database.chinacloudapi.cn/”,则需要请求的范围为“https://database.chinacloudapi.cn//.default”。Therefore, if https://database.chinacloudapi.cn expects an audience of "https://database.chinacloudapi.cn/", you'll need to request a scope of "https://database.chinacloudapi.cn//.default". 另请参阅 GitHub 问题 #747:将省略资源 URL 的尾部斜杠,因为该斜杠会导致 SQL 身份验证失败See also GitHub issue #747: Resource url's trailing slash is omitted, which caused sql auth failure.

将请求访问权限范围限定为 v1.0 应用程序的所有权限Scopes to request access to all the permissions of a v1.0 application

例如,若要获取 v1.0 应用程序的所有静态范围的令牌,请将“.default”追加到 API 的应用 ID URI:If you want to acquire a token for all the static scopes of a v1.0 application, append ".default" to the app ID URI of the API:

ResourceId = "someAppIDURI";
var scopes = new [] {  ResourceId+"/.default"};
var ResourceId = "someAppIDURI";
var scopes = [ ResourceId + "/.default"];

针对客户端凭据流/守护程序应用的请求的范围Scopes to request for a client credential flow/daemon app

使用客户端凭据流时,要传递的范围也是 /.defaultIn the case of client credential flow, the scope to pass would also be /.default. 这会让 Azure AD 知道管理员在应用程序注册中许可的所有应用级权限。This tells to Azure AD: "all the app-level permissions that the admin has consented to in the application registration.