Desktop-App, die Web-APIs aufruft: Aufrufen einer Web-API

Da Sie nun über ein Token verfügen, können Sie eine geschützte Web-API aufrufen.

Aufrufen einer Web-API

.NET

AuthenticationResult-Eigenschaften in MSAL.NET

Die Methoden zum Abrufen von Token geben AuthenticationResult zurück. Bei asynchronen Methoden wird Task<AuthenticationResult> zurückgegeben.

In MSAL.NET macht AuthenticationResult Folgendes verfügbar:

• Das AccessToken, über das die Web-API auf Ressourcen zugreift. Dieser Parameter ist eine Zeichenfolge, in der Regel ein Base64-codiertes JWT. Der Client sollte jedoch niemals Zugriff auf die Informationen im Zugriffstoken erhalten. Die Stabilität des Formats ist nicht garantiert, und das Format kann für die Ressource verschlüsselt werden. Geschriebener Code, der vom Inhalt von Zugriffstoken auf dem Client abhängig ist, stellt eine der häufigsten Ursachen für Fehler und Brüche in der Clientlogik dar. Weitere Informationen finden Sie unter Zugriffstoken.
• Das IdToken für den Benutzer. Dieser Parameter ist ein codiertes JWT. Weitere Informationen finden Sie unter ID-Token.
• ExpiresOn gibt das Datum und die Uhrzeit des Tokenablaufs an.
• Die TenantId enthält den Mandanten, in dem der Benutzer gefunden wurde. Bei Gastbenutzern (Microsoft Entra B2B-Szenarien) entspricht die Mandanten-ID dem Gastmandanten, nicht dem eindeutigen Mandanten. Wenn das Token für einen Benutzer bereitgestellt wird, enthält AuthenticationResult auch Informationen zu diesem Benutzer. Bei Flows für vertrauliche Clients, in denen Token ohne Benutzer für die Anwendung angefordert werden, wird für diese Benutzerinformationen NULL zurückgegeben.
• Die Scopes, für die das Token ausgegeben wurde.
• Die eindeutige ID für den Benutzer

IAccount

MSAL.NET definiert das Konzept eines Kontos über die IAccount-Schnittstelle. Durch diese wichtige Änderung (Breaking Change) wird die richtige Semantik bereitgestellt. Ein und derselbe Benutzer kann über mehrere Konten in unterschiedlichen Microsoft Entra-Verzeichnissen verfügen. Zudem bietet MSAL.NET bessere Informationen für Gastszenarien, weil Informationen zum Stammkonto bereitgestellt werden. Im folgenden Diagramm ist die Struktur der IAccount-Schnittstelle dargestellt.

Die AccountId-Klasse identifiziert ein Konto in einem bestimmten Mandanten mit den in der folgenden Tabelle aufgeführten Eigenschaften.

Eigenschaft	BESCHREIBUNG
TenantId	Eine Zeichenfolgendarstellung für eine GUID, bei der es sich um die ID des Mandanten handelt, in dem sich das Konto befindet.
ObjectId	Eine Zeichenfolgendarstellung für eine GUID, bei der es sich um die ID des Benutzers handelt, der Besitzer des Kontos im Mandanten ist.
Identifier	Eindeutiger Bezeichner für das Konto. Identifier ist die Verkettung von ObjectId und TenantId, durch ein Komma getrennt. Sie sind nicht Base64-codiert.

Die IAccount-Schnittstelle stellt Informationen über ein einziges Konto dar. Ein und derselbe Benutzer kann in verschiedenen Mandanten vorhanden sein, was bedeutet, dass ein Benutzer über mehrere Konten verfügen kann. Die zugehörigen Member sind in der folgenden Tabelle aufgeführt.

Eigenschaft	BESCHREIBUNG
Username	Eine Zeichenfolge, die den anzeigbaren Wert im UPN-Format (UserPrincipalName) enthält, z. B. john.doe@contoso.com. Diese Zeichenfolge kann NULL sein. „HomeAccountId“ und „HomeAccountId.Identifier“ sind dagegen nie NULL. Diese Eigenschaft ersetzt die DisplayableId-Eigenschaft von IUser in früheren Versionen von MSAL.NET.
Environment	Eine Zeichenfolge, die den Identitätsanbieter für dieses Konto (z. B. login.microsoftonline.com) enthält. Diese Eigenschaft ersetzt die IdentityProvider-Eigenschaft von IUser, mit der Ausnahme, dass IdentityProvider zusätzlich zur Cloudumgebung auch Informationen über den Mandanten enthielt. Hier umfasst der Wert nur den Host.
HomeAccountId	Die Konto-ID des Stammkontos für den Benutzer. Diese Eigenschaft identifiziert den Benutzer eindeutig über mehrere Microsoft Entra-Mandanten hinweg.

Verwenden des Tokens zum Aufrufen einer geschützten API

Nachdem das AuthenticationResult von MSAL in result zurückgegeben wurde, müssen Sie es dem HTTP-Autorisierungsheader hinzufügen, bevor Sie den Aufruf zum Zugreifen auf die geschützte Web-API ausführen.

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

Aufrufen einer Web-API in MSAL für iOS und macOS

Diese Methoden zum Abrufen von Token geben ein MSALResult-Objekt zurück. MSALResult stellt die Eigenschaft accessToken bereit, die verwendet werden kann, um eine Web-API aufzurufen. Fügen Sie dem HTTP-Autorisierungsheader ein Zugriffstoken hinzu, bevor der Aufruf zum Zugriff auf die geschützte Web-API erfolgt.

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

Aufrufen mehrerer APIs: Inkrementelle Einwilligung und bedingter Zugriff

Um nach dem Abrufen eines Tokens für die erste API mehrere APIs für denselben Benutzer aufzurufen, rufen Sie AcquireTokenSilent auf. In den meisten Fällen erhalten Sie ein Token für die anderen APIs automatisch.

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

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

Ein Interaktion ist in folgenden Fällen erforderlich:

• Der Benutzer hat der ersten API zugestimmt, muss nun aber weiteren Bereichen zustimmen. Diese Art von Zustimmung wird als inkrementelle Zustimmung bezeichnet.
• Für die erste API war keine mehrstufige Authentifizierung erforderlich, für die nächste wird diese jedoch benötigt.

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

Rufen Sie mithilfe eines HTTP-Clients wie Axios den API-Endpunkt-URI mit einem Zugriffstoken wie dem Autorisierungsbearertoken auf.

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

Nächste Schritte

• Erfahren Sie mehr, indem Sie eine React-Single-Page-Webanwendung (Single-Page Application, SPA) erstellen, die Benutzer bei der folgenden mehrteiligen Lernprogrammreihe anmeldet.

• Erkunden von Desktopcodebeispielen der Microsoft Identity Platform