Настольное приложение, которое обращается к веб-API: вызов веб-API

применяется к: арендаторы рабочей силы внешние клиенты (подробнее)

Теперь у вас есть токен и вы можете вызвать защищенный веб-API.

Вызов веб-API

.NET

Свойства объекта AuthenticationResult в MSAL.NET

Методы получения токенов возвращают объект AuthenticationResult. Для асинхронных методов возвращается Task<AuthenticationResult>.

MSAL.NET AuthenticationResult предоставляет следующие параметры:

• AccessToken для веб-API для доступа к ресурсам. Это строковый параметр, который обычно представляет собой маркер JWT в кодировке Base-64. Клиент никогда не должен считывать содержимое маркера доступа. Стабильность формата не гарантируется, а он может быть зашифрован для ресурса. Написание кода, который зависит от содержимого маркера доступа на стороне клиента, является одним из основных источников для ошибок и сбоев в логике клиента. Дополнительные сведения см. в разделе Маркеры доступа.
• IdToken — предназначается для пользователя. Этот параметр является зашифрованным маркером JWT. Дополнительные сведения см. в разделе Маркеры идентификации.
• ExpiresOn — сообщает дату и время истечения срока действия маркера.
• TenantId — содержит сведения о клиенте, в котором был найден пользователь. Для гостевых пользователей в сценариях Microsoft Entra B2B идентификатор клиента является гостевым клиентом, а не уникальным клиентом. При передаче маркера для пользователя в объекте AuthenticationResult также содержится информация об этом пользователе. Для потоков конфиденциальных клиентов, где токены запрашиваются для приложения без участия пользователя, информация о пользователе будет отсутствовать.
• Scopes для которого был выдан токен.
• Уникальный идентификатор пользователя.

IAccount

В MSAL.NET понятие учетной записи определяется через интерфейс IAccount. Такое радикальное изменение обеспечивает правильную семантику. Один и тот же пользователь может иметь несколько учетных записей в разных каталогах Microsoft Entra. Также MSAL.NET предоставляет более подробные сведения в сценариях с гостевым входом благодаря добавлению информации о домашней учетной записи. Структура интерфейса IAccount представлена на следующей схеме.

Класс AccountId определяет учетную запись в конкретном клиенте с помощью свойств, приведенных в следующей таблице.

Свойство	Описание
TenantId	Строковое представление идентификатора GUID, которое является идентификатором клиента, где находится учетная запись.
ObjectId	Строковое представление идентификатора GUID, являющееся идентификатором пользователя, которому принадлежит учетная запись в клиенте.
Identifier	Уникальный идентификатор для учетной записи. Identifier является объединением ObjectId и TenantId, разделенных запятой. Они не закодированы с помощью Base 64.

Интерфейс IAccount предоставляет сведения об одной учетной записи. Один и тот же пользователь может быть в разных арендаторах, это означает, что у пользователя может быть несколько учетных записей. Члены показаны в следующей таблице.

Свойство	Описание
Username	Строка с отображаемым значением в формате UserPrincipalName (UPN), например john.doe@contoso.com. Эта строка может иметь значение NULL, в отличие от свойств HomeAccountId и HomeAccountId.Identifier, у которых не может быть значения NULL. Это свойство заменяет свойство DisplayableId в IUser из предыдущих версий MSAL.NET.
Environment	Строка с поставщиком удостоверений для этой учетной записи, например login.microsoftonline.com. Это свойство заменяет свойство IdentityProvider у IUser, за исключением того, что свойство IdentityProvider также содержало информацию об арендаторе в дополнение к данным об облачной среде. Здесь значение состоит только из хоста.
HomeAccountId	Идентификатор домашней учетной записи пользователя. Это свойство однозначно идентифицирует пользователя в клиентах Microsoft Entra.

Используйте маркер для вызова защищенного API

После того как AuthenticationResult возвращается MSAL в переменную result, ее нужно добавить в HTTP-заголовок авторизации перед тем, как делать вызов для доступа к защищенному веб-API.

httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);

// Call the web API.
HttpResponseMessage response = await _httpClient.GetAsync(apiUri);
...

Java

HttpURLConnection conn = (HttpURLConnection) url.openConnection();

PublicClientApplication pca = PublicClientApplication.builder(clientId)
        .authority(authority)
        .build();

// Acquire a token, acquireTokenHelper would call publicClientApplication's acquireTokenSilently then acquireToken
// see https://github.com/Azure-Samples/ms-identity-java-desktop for a full example
IAuthenticationResult authenticationResult = acquireTokenHelper(pca);

// Set the appropriate header fields in the request header.
conn.setRequestProperty("Authorization", "Bearer " + authenticationResult.accessToken);
conn.setRequestProperty("Accept", "application/json");

String response = HttpClientHelper.getResponseStringFromConn(conn);

int responseCode = conn.getResponseCode();
if(responseCode != HttpURLConnection.HTTP_OK) {
    throw new IOException(response);
}

JSONObject responseObject = HttpClientHelper.processResponse(responseCode, response);

MacOS

Вызов веб-API в MSAL для iOS и macOS

Методы получения маркеров возвращают объект MSALResult. MSALResult предоставляет свойство accessToken, которое можно использовать для вызова веб-API. Добавьте маркер доступа в заголовок авторизации HTTP, прежде чем выполнять запрос на доступ к защищенному веб-API.

Objective-C.

NSMutableURLRequest *urlRequest = [NSMutableURLRequest new];
urlRequest.URL = [NSURL URLWithString:"https://contoso.api.com"];
urlRequest.HTTPMethod = @"GET";
urlRequest.allHTTPHeaderFields = @{ @"Authorization" : [NSString stringWithFormat:@"Bearer %@", accessToken] };

NSURLSessionDataTask *task =
[[NSURLSession sharedSession] dataTaskWithRequest:urlRequest
     completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {}];
[task resume];

Swift:

let urlRequest = NSMutableURLRequest()
urlRequest.url = URL(string: "https://contoso.api.com")!
urlRequest.httpMethod = "GET"
urlRequest.allHTTPHeaderFields = [ "Authorization" : "Bearer \(accessToken)" ]

let task = URLSession.shared.dataTask(with: urlRequest as URLRequest) { (data: Data?, response: URLResponse?, error: Error?) in }
task.resume()

Вызов нескольких API: добавочное согласие и условный доступ

Чтобы вызвать несколько API для одного пользователя, после получения токена для первого API вызовите AcquireTokenSilent. В большинстве случаев токен для других API выдается незаметно.

var result = await app.AcquireTokenXX("scopeApi1")
                      .ExecuteAsync();

result = await app.AcquireTokenSilent("scopeApi2")
                  .ExecuteAsync();

Взаимодействие необходимо, если:

• Пользователь предоставил согласие для первого API, а теперь ему требуется согласие для других областей. Такой тип согласия называется добавочным согласием.
• Первый API не требует многофакторной проверки подлинности, но следующий требует.

var result = await app.AcquireTokenXX("scopeApi1")
                      .ExecuteAsync();

try
{
 result = await app.AcquireTokenSilent("scopeApi2")
                  .ExecuteAsync();
}
catch(MsalUiRequiredException ex)
{
 result = await app.AcquireTokenInteractive("scopeApi2")
                  .WithClaims(ex.Claims)
                  .ExecuteAsync();
}

Node.js

С помощью клиента HTTP, например Axios, вызовите API по URI конечной точки, передав маркер доступа как носитель авторизации.

const axios = require('axios');

async function callEndpointWithToken(endpoint, accessToken) {
    const options = {
        headers: {
            Authorization: `Bearer ${accessToken}`
        }
    };

    console.log('Request made at: ' + new Date().toString());

    const response = await axios.default.get(endpoint, options);

    return response.data;
}

Python

endpoint = "url to the API"
http_headers = {'Authorization': 'Bearer ' + result['access_token'],
                'Accept': 'application/json',
                'Content-Type': 'application/json'}
data = requests.get(endpoint, headers=http_headers, stream=False).json()

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

• Узнайте больше, создавая одностраничное приложение на React, которое выполняет вход пользователей, в следующей серии руководств.

• Изучение платформы удостоверений Microsoft с настольными примерами кода