Bureaublad-app die web-API's aanroept: een web-API aanroepen

Nu u een token hebt, kunt u een beveiligde web-API aanroepen.

Een web-API aanroepen

.NET

AuthenticationResult-eigenschappen in MSAL.NET

De methoden voor het verkrijgen van tokens retourneren AuthenticationResult. Voor niet-synchrone methoden wordt Task<AuthenticationResult> geretourneerd.

In MSAL.NET stelt AuthenticationResult het volgende beschikbaar:

• AccessToken voor de web-API voor toegang tot bronnen. Deze parameter is een tekenreeks, meestal een met Base64 gecodeerde JWT. De client mag nooit in het toegangstoken kijken. De indeling blijft niet gegarandeerd stabiel en kan worden versleuteld voor de resource. Het schrijven van code die afhankelijk is van de inhoud van het toegangstoken op de client, is een van de grootste bronnen van fouten en onderbrekingen van clientlogica. Zie Toegangstokens voor meer informatie.
• IdToken voor de gebruiker. Deze parameter is een gecodeerde JWT. Zie ID-tokens voor meer informatie.
• ExpiresOn geeft de datum en tijd aan waarop het token verloopt.
• TenantId bevat de tenant waarin de gebruiker is gevonden. Voor gastgebruikers in Microsoft Entra B2B-scenario's is de tenant-id de gasttenant, niet de unieke tenant. Wanneer de token voor een gebruiker wordt geleverd, bevat AuthenticationResult ook informatie over deze gebruiker. Voor vertrouwelijke clientstromen waarbij tokens worden aangevraagd zonder gebruiker voor de toepassing, is deze gebruikersinformatie null.
• De Scopes waarvoor de token is uitgegeven.
• De unieke id voor de gebruiker.

IAccount

MSAL.NET definieert het begrip van een account via de IAccount-interface. Deze belangrijke wijziging biedt de juiste semantiek. Dezelfde gebruiker kan verschillende accounts hebben, in verschillende Microsoft Entra-mappen. MSAL.NET biedt ook betere informatie in het geval van gastscenario's, omdat informatie over het homeaccount wordt verstrekt. Het volgende diagram toont de structuur van de IAccount-interface.

De klasse AccountId identificeert een account in een specifieke tenant met de eigenschappen in de volgende tabel.

Eigenschappen	Beschrijving
TenantId	Een tekenreeksweergave voor een GUID, wat de id is van de tenant waarin het account zich bevindt.
ObjectId	Een tekenreeksweergave voor een GUID, wat de id is van de gebruiker die het account in de tenant bezit.
Identifier	Unieke id voor het account. Identifier is de samenvoeging van ObjectId en TenantId gescheiden door een komma. Deze zijn niet met Base64 gecodeerd.

De IAccount-interface vertegenwoordigt informatie over één account. Dezelfde gebruiker kan aanwezig zijn in verschillende tenants. Dit betekent dat een gebruiker meerdere accounts kan hebben. De leden ervan worden weergegeven in de volgende tabel.

Eigenschappen	Beschrijving
Username	Een tekenreeks die de weergavewaarde bevat in UPN-indeling (UserPrincipalName), bijvoorbeeld john.doe@contoso.com. Deze tekenreeks kan null zijn, in tegenstelling tot HomeAccountId en HomeAccountId.Identifier, die niet null zijn. Deze eigenschap vervangt de eigenschap DisplayableId van IUser eerdere versies van MSAL.NET.
Environment	Een tekenreeks die de id-provider voor dit account bevat, bijvoorbeeld login.microsoftonline.com. Deze eigenschap vervangt de eigenschap IdentityProvider van IUser, behalve dat IdentityProvider ook informatie over de tenant had, naast de cloudomgeving. Hier is de waarde alleen de host.
HomeAccountId	De account-id van het homeaccount voor de gebruiker. Deze eigenschap identificeert de gebruiker uniek in Microsoft Entra-tenants.

Het token gebruiken om een beveiligde API aan te roepen

Nadat AuthenticationResult is geretourneerd door MSAL in result, voegt u deze toe aan de HTTP-autorisatieheader voordat u de aanroep uitvoert voor toegang tot de beveiligde web-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

Een web-API aanroepen in MSAL voor iOS en macOS

De methoden voor het verkrijgen van tokens retourneren een MSALResult object. MSALResult maakt een accessToken eigenschap beschikbaar die kan worden gebruikt om een web-API aan te roepen. Voeg een toegangstoken toe aan de HTTP-autorisatieheader voordat u de aanroep uitvoert voor toegang tot de beveiligde web-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()

Verschillende API's aanroepen: incrementele toestemming en voorwaardelijke toegang

Als u meerdere API's voor dezelfde gebruiker wilt aanroepen, roept u een token voor de eerste API aan AcquireTokenSilent. Meestal krijgt u een token voor de andere API's.

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

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

Interactie is vereist wanneer:

• De gebruiker toestemming heeft gegeven voor de eerste API, maar nu toestemming moet geven voor meer bereiken. Dit soort toestemming wordt incrementele toestemming genoemd.
• De eerste API vereist geen meervoudige verificatie, maar de volgende wel.

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

Roep met behulp van een HTTP-client zoals Axios de API-eindpunt-URI aan met een toegangstoken als autorisatiebeer.

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

Volgende stappen

• Meer informatie vindt u door een React-toepassing met één pagina (SPA) te bouwen waarmee gebruikers worden aangemeld in de volgende reeks meerdelige zelfstudies.

• Voorbeelden van bureaubladcode voor Microsoft Identity Platform verkennen