App desktop che chiama le API Web: Chiamare un'API Web

Ora che si ha un token, è possibile chiamare un'API Web protetta.

Chiamare un'API Web

.NET

Proprietà AuthenticationResult in MSAL.NET

I metodi per acquisire i token restituiscono AuthenticationResult. Per i metodi asincroni, restituisce Task<AuthenticationResult>.

In MSAL.NET, AuthenticationResult espone:

• AccessToken per l’API Web per accedere alle risorse. Questo parametro è una stringa, in genere un token JWT con codifica Base 64. Il client non deve mai guardare all'interno del token di accesso. Non è garantito che il formato rimanga stabile e può essere crittografato per la risorsa. La scrittura di codice dipendente dal contenuto del token di accesso nel client è una delle principali fonti di errori e interruzioni per la logica client. Per altre informazioni, vedere la pagina relativa ai Token di accesso.
• IdToken per l'utente. Questo parametro è un token JWT codificato. Per ulteriori informazioni, vedere ID token.
• ExpiresOn indica la data e l'ora di scadenza del token.
• TenantId contiene il tenant in cui è stato trovato l'utente. Per gli utenti guest (scenari B2B con Microsoft Entra), l'ID tenant è il tenant guest, non il tenant univoco. Quando il token viene recapitato per un utente, AuthenticationResult contiene anche informazioni su questo utente. Per i flussi client riservati in cui vengono richiesti token senza utente per l'applicazione, queste informazioni sull'utente sono null.
• Il Scopes per cui è stato emesso il token.
• ID univoco per l'utente.

IAccount

MSAL.NET definisce la nozione di un account tramite l'interfaccia IAccount. Questa modifica che causa un'interruzione fornisce la semantica corretta. Lo stesso utente può avere diversi account, in directory Microsoft Entra diverse. MSAL.NET offre inoltre informazioni più complete negli scenari guest, perché sono disponibili informazioni sull'account principale. Il diagramma seguente illustra la struttura dell'interfaccia IAccount.

La classe AccountId identifica un account in un tenant specifico con le proprietà illustrate nella tabella seguente.

Proprietà	Descrizione
TenantId	Rappresentazione di stringa per un GUID, ovvero l'ID del tenant in cui risiede l'account.
ObjectId	Rappresentazione di stringa per un GUID, ovvero l'ID dell'utente proprietario dell'account nel tenant.
Identifier	Identificativo univoco globale per l'account. Identifier è la concatenazione di ObjectId e TenantId separate da una virgola. Non sono codificati in Base 64.

L'interfaccia IAccount rappresenta informazioni su un singolo account. Lo stesso utente può essere presente in tenant diversi, il che significa che un utente può avere più account. I relativi membri sono illustrati nella tabella seguente.

Proprietà	Descrizione
Username	Stringa che contiene il valore visualizzabile in formato UserPrincipalName (UPN), come ad esempio john.doe@contoso.com. Questa stringa può essere null, a differenza di HomeAccountId e HomeAccountId.Identifier, che non sarà null. Questa proprietà sostituisce la proprietà DisplayableId di IUser nelle versioni precedenti di MSAL.NET.
Environment	Stringa che contiene il provider di identità per questo account, ad esempio login.microsoftonline.com. Questa proprietà sostituisce la proprietà IdentityProvider di IUser, ad eccezione del fatto che IdentityProvider aveva anche informazioni sul tenant, oltre all'ambiente cloud. In questo caso, il valore è solo l'host.
HomeAccountId	ID account dell'account home per l'utente. Questa proprietà identifica in modo univoco l'utente nei tenant di Microsoft Entra.

Usare il token per chiamare un'API protetta

Dopo che AuthenticationResult è stato restituito da MSAL in result, aggiungerlo all'intestazione di autorizzazione HTTP prima di effettuare la chiamata per accedere all'API Web protetta.

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

Chiamare un'API Web in MSAL per iOS e macOS

I metodi per acquisire i token restituiscono un oggetto MSALResult. MSALResult espone una accessToken proprietà che può essere usata per chiamare un'API Web. Aggiungere un token di accesso all'intestazione di autorizzazione HTTP prima di effettuare la chiamata per accedere all'API Web protetta.

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

Chiamare diverse API: consenso incrementale e accesso condizionale

Per chiamare diverse API per lo stesso utente, dopo aver ottenuto un token per la prima API, chiamare AcquireTokenSilent. Si otterrà un token per le altre API in modo invisibile all'utente nella maggior parte dei casi.

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

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

L'interazione è necessaria nei casi seguenti:

• L'utente ha concesso il consenso per la prima API, ma deve ora fornirlo per altri ambiti. Questo tipo di consenso è noto come consenso incrementale.
• La prima API non richiedeva l'autenticazione a più fattori, ma quella successiva.

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 un client HTTP come Axios, chiamare l'URI dell'endpoint API con un token di accesso come connessione di autorizzazione.

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

Passaggi successivi

• Per ulteriori informazioni, creare un'applicazione a pagina singola (SPA) che effettua l'accesso degli utenti nella seguente serie di esercitazioni in più parti.

• Esplorare gli esempi di codice desktop di Microsoft Identity Platform