Aplicativo de desktop que chama APIs Web: chamar uma API Web

Agora que você tem um token, é possível chamar uma API Web protegida.

Chamar uma API da Web

.NET

Propriedades de AuthenticationResult em MSAL.NET

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

No MSAL.NET, AuthenticationResult expõe:

• AccessToken para a API da web acessar recursos. Este parâmetro é uma cadeia de caractere, geralmente um JWT codificado em Base 64. O cliente nunca deve olhar dentro do token de acesso. Não há garantia de que o formato permaneça estável e pode ser criptografado para o recurso. A gravação de 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 usuário. Esse 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 em que o usuário foi encontrado. Para os 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 cliente confidenciais em que tokens são solicitados sem nenhum usuário para o aplicativo, essas informações do usuário são nulas.
• O Scopes para o qual o token foi emitido.
• A ID exclusiva para o usuário.

IAccount

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

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

Propriedade	Descrição
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 ObjectId e TenantId separada por uma vírgula. Eles não são codificados em Base 64.

A interface IAccount 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.

Propriedade	Descrição
Username	Uma cadeia de caracteres que contém o valor de exibição no formato UserPrincipalName (UPN), por exemplo, john.doe@contoso.com. Essa cadeia de caracteres pode ser nula, ao contrário de HomeAccountId e HomeAccountId.Identifier, que não será nula. Esta propriedade substitui a propriedade DisplayableId de IUser nas versões anteriores do MSAL.NET.
Environment	Uma cadeia de caracteres que contém o provedor de identidade para esta conta, por exemplo, login.microsoftonline.com. Esta propriedade substitui aIdentityProvider propriedade de IUser, exceto que IdentityProvidertambém tinha informações sobre o locatário, além do ambiente de nuvem. Aqui, o valor é apenas o host.
HomeAccountId	A ID da conta inicial do usuário. Essa propriedade identifica exclusivamente o usuário nos locatários do Microsoft Entra.

Use o token para chamar uma API protegida

Depois de AuthenticationResult ser retornado pelo MSAL em 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 Web em MSAL para iOS e macOS

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

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

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ê obterá 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. Esse tipo de consentimento é conhecido como consentimento incremental.
• A primeira API não exige autenticação multifator, mas a próxima exige.

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 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óximas etapas

Vá para o próximo artigo neste cenário, vá para produção.