Aplicación de escritorio que llama a las API web: Llamada a una API de web

Ahora que dispone de un token, puede llamar a una API web protegida.

Llamada a una API de web

.NET

Propiedades de AuthenticationResult en MSAL.NET

Los métodos para adquirir tokens devuelven AuthenticationResult. En el caso de los métodos asincrónicos, se devuelve Task<AuthenticationResult>.

En MSAL.NET, AuthenticationResult expone:

• AccessToken para que la API web acceda a los recursos. Este parámetro es una cadena, normalmente un JWT con codificación en Base 64. El cliente nunca debe mirar dentro del token de acceso. No se garantiza que el formato permanezca estable y se pueda cifrar para el recurso. La escritura de código que depende del contenido de un token de acceso del cliente constituye una de las fuentes de errores y de interrupciones de la lógica de cliente más habituales. Para más información, consulte Tokens de acceso.
• IdToken del usuario. Este parámetro es un JWT codificado. Para más información, consulte Tokens de id.
• ExpiresOn indica el día y la hora a la que expira el token.
• TenantId indica el inquilino en el que se encontró el usuario. Para usuarios invitados en escenarios Microsoft Entra B2B, el id. de inquilino es el inquilino invitado, no el inquilino único. Cuando se entrega el token para un usuario, AuthenticationResult también contiene información sobre dicho usuario. Para los flujos de cliente confidenciales en los que se solicitan tokens sin usuario para la aplicación, esta información de usuario está vacía.
• Los Scopes para los que se emitió el token.
• El identificador único del usuario.

IAccount

MSAL.NET define la noción de una cuenta mediante la interfaz IAccount. Este cambio importante proporciona la semántica correcta. El mismo usuario puede tener varias cuentas, en diferentes directorios de Microsoft Entra. También MSAL.NET proporciona mejor información en el caso de escenarios de invitado ya que se proporciona información de la cuenta doméstica. En el siguiente diagrama se muestra la estructura de la interfaz IAccount.

La clase AccountId identifica una cuenta en un inquilino específico con las propiedades que se muestran en la tabla siguiente.

Propiedad	Descripción
TenantId	Representación de una cadena en un GUID, que es el identificador del inquilino donde reside la cuenta.
ObjectId	Representación de una cadena en un GUID, que es el identificador del usuario a quien pertenece la cuenta en el inquilino.
Identifier	Identificador único de la cuenta. Identifier es la concatenación de ObjectId y TenantId, separados por una coma. No están codificados en Base 64.

La interfaz IAccount representa información sobre una sola cuenta. El mismo usuario puede estar presente en distintos inquilinos, es decir, un usuario puede tener varias cuentas. Sus miembros se muestran en la siguiente tabla.

Propiedad	Descripción
Username	Una cadena que contiene el valor que se puede mostrar en formato UserPrincipalName (UPN), por ejemplo, john.doe@contoso.com. Esta cadena puede ser NULL, a diferencia de HomeAccountId y HomeAccountId.Identifier que no serán NULL. Esta propiedad reemplaza la propiedad DisplayableId de IUser en versiones anteriores de MSAL.NET.
Environment	Una cadena que contiene el proveedor de identidades de esta cuenta, por ejemplo, login.microsoftonline.com. Esta propiedad reemplaza la propiedad IdentityProvider de IUser, salvo que IdentityProvider también tenía información sobre el inquilino además del entorno de nube. Aquí, el valor es solo el host.
HomeAccountId	El identificador de la cuenta de inicio del usuario. Esta propiedad identifica unívocamente al usuario a través de los inquilinos de Microsoft Entra.

Uso del token para llamar a una API protegida

Después de que MSAL devuelva AuthenticationResult en result, agréguelo al encabezado de autorización HTTP antes de realizar la llamada para acceder a la API 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

Llamada a una API web en MSAL para iOS y macOS

Los métodos para adquirir tokens devuelven un objeto MSALResult. MSALResult expone una propiedad accessToken que se puede usar para llamar a una API web. Agregue un token de acceso al encabezado de autorización HTTP antes de realizar la llamada para acceder a la 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()

Llamada a varias API: consentimiento incremental y acceso condicional

Para llamar a varias API para el mismo usuario después de obtener un token para la primera API, llame a AcquireTokenSilent. Obtendrá un token para las otras API, en modo silencioso la mayor parte de las veces.

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

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

La interacción es necesaria en los siguientes casos:

• El usuario ha dado su consentimiento para la primera API, pero ahora debe dar su consentimiento para más ámbitos. Este tipo de consentimiento se conoce como consentimiento incremental.
• La primera API no requería autenticación multifactor, pero la siguiente sí.

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

Si usa un cliente HTTP como Axios, llame al URI del punto de conexión de la API con un token de acceso como el portador de autorización.

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

Pasos siguientes

Avance al siguiente artículo de este escenario, Paso a producción.