Получение маркеров для вызова веб-API с помощью приложения управляющей программы

Статья
04/09/2024

После создания конфиденциального клиентского приложения можно получить для него токен, вызвав AcquireTokenForClient, передав область и при необходимости обновив токен.

Области запроса

Область запросов для потока учетных данных клиента — это имя ресурса с добавлением /.default. Эта нотация сообщает идентификатору Microsoft Entra использовать разрешения на уровне приложения, объявленные статически во время регистрации приложения. Кроме того, эти разрешения API должны быть предоставлены администратором арендатора.

Ниже приведен пример определения область для веб-API в рамках конфигурации в файле appsettings.json. Этот пример взят из примера кода управляющей программы консоли .NET на GitHub.

{
    "AzureAd": {
        // Same AzureAd section as before.
    },

    "MyWebApi": {
        "BaseUrl": "https://localhost:44372/",
        "RelativePath": "api/TodoList",
        "RequestAppToken": true,
        "Scopes": [ "[Enter here the scopes for your web API]" ]
    }
}

final static String GRAPH_DEFAULT_SCOPE = "https://graph.microsoft.com/.default";

const tokenRequest = {
    scopes: [process.env.GRAPH_ENDPOINT + '.default'], // e.g. 'https://graph.microsoft.com/.default'
};

В MSAL Python файл конфигурации выглядит как представленный ниже фрагмент кода.

{
    "scope": ["https://graph.microsoft.com/.default"],
}

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

Ресурсы Azure Active Directory (v1.0)

Областью, используемой для учетных данных клиента, всегда должен быть ИД ресурса, за которым следует /.default.

Внимание

Когда MSAL запрашивает маркер доступа для ресурса, который принимает маркер доступа версии 1.0, идентификатор Microsoft Entra анализирует нужную аудиторию из запрошенного область, принимая все до последней косой черты и используя его в качестве идентификатора ресурса. Если, как и База данных SQL Azure (https://database.windows.net), ресурс ожидает аудиторию, которая заканчивается косой чертой (для Базы данных SQL Azure https://database.windows.net/), необходимо запросить область https://database.windows.net//.default. (Обратите внимание на двойную косую черту.) См. также описание ошибки MSAL.NET № 747: Resource url's trailing slash is omitted, which caused sql auth failure.

AcquireTokenForClient API

Чтобы получить маркер для приложения, использовать AcquireTokenForClient или его эквивалент, в зависимости от платформы.

При использовании Microsoft.Identity.Web вам не нужно получать маркер. Вы можете использовать API более высокого уровня, как показано в вызове веб-API из приложения управляющей программы. Если вы используете пакет SDK, для которого требуется маркер, в следующем фрагменте кода показано, как получить этот маркер.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

// In the Program.cs, acquire a token for your downstream API

var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
ITokenAcquirer acquirer = tokenAcquirerFactory.GetTokenAcquirer();
AcquireTokenResult tokenResult = await acquirer.GetTokenForUserAsync(new[] { "https://graph.microsoft.com/.default" });
string accessToken = tokenResult.AccessToken;

Это код взят из примеров разработки в MSAL Java.

private static IAuthenticationResult acquireToken() throws Exception {

     // Load token cache from file and initialize token cache aspect. The token cache will have
     // dummy data, so the acquireTokenSilently call will fail.
     TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

     IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);
     ConfidentialClientApplication cca =
             ConfidentialClientApplication
                     .builder(CLIENT_ID, credential)
                     .authority(AUTHORITY)
                     .setTokenCacheAccessAspect(tokenCacheAspect)
                     .build();

     IAuthenticationResult result;
     try {
         SilentParameters silentParameters =
                 SilentParameters
                         .builder(SCOPE)
                         .build();

         // try to acquire token silently. This call will fail since the token cache does not
         // have a token for the application you are requesting an access token for
         result = cca.acquireTokenSilently(silentParameters).join();
     } catch (Exception ex) {
         if (ex.getCause() instanceof MsalException) {

             ClientCredentialParameters parameters =
                     ClientCredentialParameters
                             .builder(SCOPE)
                             .build();

             // Try to acquire a token. If successful, you should see
             // the token information printed out to console
             result = cca.acquireToken(parameters).join();
         } else {
             // Handle other exceptions accordingly
             throw ex;
         }
     }
     return result;
 }

Следующий фрагмент кода иллюстрирует получение маркера в конфиденциальном клиентском приложении MSAL Node:

try {
    const authResponse = await cca.acquireTokenByClientCredential(tokenRequest);
    console.log(authResponse.accessToken) // display access token
} catch (error) {
    console.log(error);
}

# The pattern to acquire a token looks like this.
result = None

# First, the code looks up a token from the cache.
# Because we're looking for a token for the current app, not for a user,
# use None for the account parameter.
result = app.acquire_token_silent(config["scope"], account=None)

if not result:
    logging.info("No suitable token exists in cache. Let's get a new one from Azure AD.")
    result = app.acquire_token_for_client(scopes=config["scope"])

if "access_token" in result:
    # Call a protected API with the access token.
    print(result["token_type"])
else:
    print(result.get("error"))
    print(result.get("error_description"))
    print(result.get("correlation_id"))  # You might need this when reporting a bug.

using Microsoft.Identity.Client;

// With client credentials flows, the scope is always of the shape "resource/.default" because the
// application permissions need to be set statically (in the portal or by PowerShell), and then granted by
// a tenant administrator.
string[] scopes = new string[] { "https://graph.microsoft.com/.default" };

AuthenticationResult result = null;
try
{
 result = await app.AcquireTokenForClient(scopes)
                  .ExecuteAsync();
}
catch (MsalUiRequiredException ex)
{
    // The application doesn't have sufficient permissions.
    // - Did you declare enough app permissions during app creation?
    // - Did the tenant admin grant permissions to the application?
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
    // Invalid scope. The scope has to be in the form "https://resourceurl/.default"
    // Mitigation: Change the scope to be as expected.
}

AcquireTokenForClient использует кэш токенов приложений

В MSAL.NET AcquireTokenForClient использует кэш токенов приложений. (Все остальные методы AcquireTokenXX используют кэш токенов пользователя.) Не вызывайте AcquireTokenSilent перед вызовом AcquireTokenForClient, так как AcquireTokenSilent использует кэш токенов пользователя. AcquireTokenForClient самостоятельно проверяет и обновляет кэш токенов приложения.

Протокол

Если у вас еще нет библиотеки для выбранного языка, вы можете использовать протокол напрямую.

Первый сценарий: доступ к запросу токена с помощью общего секрета

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=A1b-C2d_E3f.H4i,J5k?L6m!N7o-P8q_R9s.T0u
&grant_type=client_credentials

Второй сценарий: доступ к запросу токена с помощью сертификата

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=aaaaaaaa-0b0b-...
&grant_type=client_credentials

Дополнительные сведения см. в документации к протоколу: платформа удостоверений Майкрософт и поток учетных данных клиента OAuth 2.0.

Устранение неполадок

Вы использовали область resource/.default?

Если появляется сообщение об ошибке, указывающее на недопустимую область, вероятно, вы не использовали область resource/.default.

Если при вызове API возникал ошибка Недостаточно привилегий для выполнения операции, администратор клиента должен предоставить приложению разрешения.

Если вы не предоставляете согласие администратора приложению, вы получите следующую ошибку:

Failed to call the web API: Forbidden
Content: {
  "error": {
    "code": "Authorization_RequestDenied",
    "message": "Insufficient privileges to complete the operation.",
    "innerError": {
      "request-id": "<guid>",
      "date": "<date>"
    }
  }
}

Выберите один из следующих параметров в зависимости от роли.

Глобальный администратор клиента

Для глобального администратора клиента перейдите в корпоративные приложения в Центре администрирования Microsoft Entra. Выберите регистрацию приложения и выберите разрешения в разделе "Безопасность " в левой области. Затем выберите большую кнопку с подписью Grant admin consent for {Tenant Name} (где {Имя клиента} — имя каталога).

Обычный пользователь

Для стандартного пользователя клиента попросите глобального Администратор istrator предоставить приложению согласие администратора. Для этого укажите следующий URL-адрес администратора:

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

В URL-адресе:

Замените Enter_the_Tenant_Id_Here идентификатором или именем клиента (например, contoso.microsoft.com).
Enter_the_Application_Id_Here — это идентификатор приложения (клиента) для зарегистрированного приложения.

Ошибка AADSTS50011: No reply address is registered for the application может отображаться после предоставления согласия приложению с помощью предыдущего URL-адреса. Эта ошибка возникает, так как приложение и URL-адрес не имеют URI перенаправления. Это сообщение можно проигнорировать.

Вы вызываете собственный API?

Если управляющая программа вызывает собственный веб-API и вам не удалось добавить разрешение на регистрацию приложения управляющей программы, необходимо добавить роли приложения в регистрацию приложения веб-API.

Следующие шаги

Перейдите к следующей статье в этом сценарии, Вызов веб-API.