Aplicativo de área de trabalho que chama APIs da Web: chame uma API da Web

Agora que você tem um token, pode chamar uma API da Web protegida.

Chamar uma API Web

.NET

AuthenticationResult propriedades em MSAL.NET

Os métodos para adquirir tokens retornam AuthenticationResult. Para métodos assíncronos, Task<AuthenticationResult> retorna.

Em MSAL.NET, AuthenticationResult expõe:

• AccessToken para a API da Web acessar recursos. Este parâmetro é uma cadeia de caracteres, geralmente um JWT codificado em Base-64. O cliente nunca deve olhar para dentro do token de acesso. Não é garantido que o formato permaneça estável e pode ser criptografado para o recurso. Escrever código que depende do conteúdo do token de acesso no cliente é uma das maiores fontes de erros e quebras de lógica do cliente. Para obter mais informações, consulte Tokens de acesso.
• IdToken para o utilizador. Este parâmetro é um JWT codificado. Para obter mais informações, consulte Tokens de ID.
• ExpiresOn informa a data e a hora em que o token expira.
• TenantId Contém o locatário no qual o usuário foi encontrado. Para usuários convidados em cenários B2B do Microsoft Entra, a ID do locatário é o locatário convidado, não o locatário exclusivo. Quando o token é entregue para um usuário, AuthenticationResult também contém informações sobre esse usuário. Para fluxos de clientes confidenciais em que os tokens são solicitados sem usuário para o aplicativo, essas informações do usuário são nulas.
• O Scopes para o qual o token foi emitido.
• O ID exclusivo para o usuário.

IAccount

MSAL.NET define a noção de uma conta através da IAccount interface. Esta mudança de rutura fornece a semântica correta. O mesmo usuário pode ter várias contas, em diferentes diretórios do Microsoft Entra. Além disso, MSAL.NET fornece melhores informações no caso de cenários de convidados, porque as informações da conta doméstica são fornecidas. O diagrama a seguir mostra a estrutura da IAccount interface.

A AccountId classe identifica uma conta em um locatário específico com as propriedades mostradas na tabela a seguir.

Property	Description
TenantId	Uma representação de cadeia de caracteres para um GUID, que é a ID do locatário onde a conta reside.
ObjectId	Uma representação de cadeia de caracteres para um GUID, que é a ID do usuário que possui a conta no locatário.
Identifier	Identificador exclusivo da conta. Identifieré a concatenação de e TenantId separada ObjectId por uma vírgula. Eles não são codificados na Base 64.

A IAccount interface representa informações sobre uma única conta. O mesmo usuário pode estar presente em diferentes locatários, o que significa que um usuário pode ter várias contas. Seus membros são mostrados na tabela a seguir.

Property	Description
Username	Uma cadeia de caracteres que contém o valor exibível no formato UPN (UserPrincipalName), por exemplo, john.doe@contoso.com. Essa cadeia de caracteres pode ser null, ao contrário de HomeAccountId e HomeAccountId.Identifier, que não serão nulos. Esta propriedade substitui a DisplayableId propriedade de IUser em versões anteriores do MSAL.NET.
Environment	Uma cadeia de caracteres que contém o provedor de identidade para essa conta, por exemplo, login.microsoftonline.com. Esta propriedade substitui a IdentityProvider propriedade da , exceto que IdentityProvider também tinha informações sobre o inquilino, além do ambiente de IUsernuvem. Aqui, o valor é apenas o host.
HomeAccountId	O ID da conta inicial do usuário. Essa propriedade identifica exclusivamente o usuário entre os locatários do Microsoft Entra.

Usar o token para chamar uma API protegida

Depois AuthenticationResult de ser retornado pelo MSAL no result, adicione-o ao cabeçalho de autorização HTTP antes de fazer a chamada para acessar a API da Web protegida.

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

Chamar uma API da Web no MSAL para iOS e macOS

Os métodos para adquirir tokens retornam um MSALResult objeto. MSALResult expõe uma accessToken propriedade que pode ser usada para chamar uma API da Web. Adicione um token de acesso ao cabeçalho de autorização HTTP antes de fazer a chamada para acessar a API da Web protegida.

Objectivo-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];

Rápido:

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()

Chamar várias APIs: Consentimento incremental e Acesso Condicional

Para chamar várias APIs para o mesmo usuário, depois de obter um token para a primeira API, chame AcquireTokenSilent. Você receberá um token para as outras APIs silenciosamente na maioria das vezes.

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

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

A interação é necessária quando:

• O usuário consentiu para a primeira API, mas agora precisa consentir para mais escopos. Este tipo de consentimento é conhecido como consentimento incremental.
• A primeira API não exigia autenticação multifator, mas a próxima sim.

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

Usando um cliente HTTP como o Axios, chame o URI do ponto de extremidade da API com um token de acesso como portador de autorização.

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()

Próximos passos

Passe para o próximo artigo neste cenário, Mover para a produção.