Share via

Aufrufen einer Web-API aus einer mobilen App

  • Artikel

Nachdem Ihre App einen Benutzer angemeldet und Token erhalten hat, macht die Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL) Informationen über den Benutzer, die Umgebung des Benutzers und die ausgestellten Token verfügbar. Ihre App kann diese Werte verwenden, um eine Web-API aufzurufen oder dem Benutzer eine Willkommensnachricht anzuzeigen.

In diesem Artikel betrachten wir zuerst das MSAL-Ergebnis. Dann befassen wir uns damit, wie ein Zugriffstoken von AuthenticationResult oder result zum Aufrufen einer geschützten Web-API verwendet wird.

MSAL-Ergebnis

MSAL stellt die folgenden Werte bereit:

  • AccessToken ruft geschützte Web-APIs in einer HTTP-Beareranforderung auf.
  • IdToken enthält nützliche Informationen über den angemeldeten Benutzer. Diese Informationen beinhalten den Namen des Benutzers, den Basismandanten und einen eindeutigen Bezeichner für die Speicherung.
  • ExpiresOn ist die Ablaufzeit des Tokens. MSAL übernimmt die automatische Aktualisierung einer App.
  • TenantId ist der Bezeichner des Mandanten, bei dem der Benutzer angemeldet ist. Für Gastbenutzer in Microsoft Entra B2B identifiziert dieser Wert den Mandanten, bei dem sich der Benutzer angemeldet hat. Der Wert identifiziert nicht den Basismandanten des Benutzers.
  • Scopes gibt die Bereiche an, die mit dem Token erteilt wurden. Bei den gewährten Bereichen kann es sich um eine Teilmenge der von Ihnen angeforderten Bereiche handeln.

MSAL stellt auch eine Abstraktion für einen Account-Wert bereit. Ein Account-Wert stellt das Konto dar, mit dem der aktuelle Benutzer angemeldet ist:

  • HomeAccountIdentifier bezeichnet den Basismandanten des Benutzers.
  • UserName ist der bevorzugte Benutzername des Benutzers. Bei Azure AD B2C-Benutzern kann dieser Wert leer sein.
  • AccountIdentifier bezeichnet den angemeldeten Benutzer. In den meisten Fällen stimmt dieser Wert mit dem Wert HomeAccountIdentifier überein, es sei denn, der Benutzer ist Gast in einem anderen Mandanten.

Aufrufen einer API

Wenn Sie über das Zugriffstoken verfügen, können Sie eine Web-API aufrufen. Ihre App verwendet das Token, um eine HTTP-Anforderung zu generieren und die Anforderung dann auszuführen.

Android

        RequestQueue queue = Volley.newRequestQueue(this);
        JSONObject parameters = new JSONObject();

        try {
            parameters.put("key", "value");
        } catch (Exception e) {
            // Error when constructing.
        }
        JsonObjectRequest request = new JsonObjectRequest(Request.Method.GET, MSGRAPH_URL,
                parameters,new Response.Listener<JSONObject>() {
            @Override
            public void onResponse(JSONObject response) {
                // Successfully called Graph. Process data and send to UI.
            }
        }, new Response.ErrorListener() {
            @Override
            public void onErrorResponse(VolleyError error) {
                // Error.
            }
        }) {
            @Override
            public Map<String, String> getHeaders() throws AuthFailureError {
                Map<String, String> headers = new HashMap<>();

                // Put access token in HTTP request.
                headers.put("Authorization", "Bearer " + authResult.getAccessToken());
                return headers;
            }
        };

        request.setRetryPolicy(new DefaultRetryPolicy(
                3000,
                DefaultRetryPolicy.DEFAULT_MAX_RETRIES,
                DefaultRetryPolicy.DEFAULT_BACKOFF_MULT));
        queue.add(request);

MSAL für iOS und macOS

Diese Methoden zum Abrufen von Token geben ein MSALResult-Objekt zurück. MSALResult macht eine accessToken-Eigenschaft verfügbar. Sie können accessToken verwenden, um eine Web-API aufzurufen. Fügen Sie dem HTTP-Autorisierungsheader diese Eigenschaft hinzu, bevor der Aufruf zum Zugriff auf die geschützte Web-API erfolgt.

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];

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

Xamarin

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.

IAccount interface structure

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);
...
}

Erstellen mehrerer API-Anforderungen

Um die gleiche API mehrmals oder mehrere APIs aufzurufen, sollten Sie beim Erstellen Ihrer App Folgendes berücksichtigen:

  • Inkrementelle Zustimmung: Mit Microsoft Identity Platform können Apps bei Bedarf (wenn Berechtigungen erforderlich sind) Benutzerzustimmungen einholen. Daher brauchen nicht alle Zustimmungen direkt am Anfang zu erfolgen. Jedes Mal, wenn Ihre App für den Aufruf einer API bereit ist, sollte sie nur die Bereiche anfordern, die sie benötigt.

  • Bedingter Zugriff: Wenn Sie mehrere API-Anforderungen ausgeben, müssen Sie in bestimmten Szenarien zusätzlichen Anforderungen für bedingten Zugriff erfüllen. Auf diese Weise können sich die Anforderungen erhöhen, wenn für die erste Anforderung keine Richtlinien für bedingten Zugriff gelten und Ihre App automatisch versucht, auf eine neue API-zuzugreifen, die bedingten Zugriff erfordert. Stellen Sie zur Lösung dieses Problems sicher, dass Sie Fehler bei automatischen Anforderungen erkennen, und bereiten Sie sich auf eine interaktive Anforderung vor. Weitere Informationen finden Sie unter Anleitung für bedingten Zugriff.

Wenn Sie nach dem Abrufen eines Tokens für einen Benutzer für denselben Benutzer mehrere APIs aufrufen möchten, können Sie es vermeiden, den Benutzer wiederholt nach den Anmeldeinformationen zu fragen, indem Sie anschließend AcquireTokenSilent zum Abrufen eines Tokens aufrufen:

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. In diesem Fall verwenden Sie inkrementelle Zustimmung.
  • Für die erste API ist keine mehrstufige Authentifizierung erforderlich, für die nächste API 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();
}

Nächste Schritte

Fahren Sie mit dem nächsten Artikel in diesem Szenario fort: Überführen in die Produktion.