Uzyskiwanie tokenu dla aplikacji mobilnej, która wywołuje internetowe interfejsy API

Dotyczy: Dzierżawcy Workforce Zewnętrzni dzierżawcy (dowiedzieć się więcej)

Aby aplikacja mogła wywoływać chronione internetowe interfejsy API, potrzebuje tokenu dostępu. W tym artykule przedstawiono proces uzyskiwania tokenu przy użyciu biblioteki Microsoft Authentication Library (MSAL).

Definiowanie zakresu

Podczas żądania tokenu zdefiniuj zakres. Zakres określa, do jakich danych może uzyskiwać dostęp aplikacja.

Najprostszym sposobem zdefiniowania zakresu jest połączenie żądanych internetowych interfejsów API App ID URI z zakresem .default. Ta definicja informuje platformie tożsamości Microsoft, że Twoja aplikacja wymaga wszystkich zakresów ustawionych w portalu.

Android

String[] SCOPES = {"https://graph.microsoft.com/.default"};

Ios

let scopes = ["https://graph.microsoft.com/.default"]

Uzyskiwanie tokenów

Uzyskiwanie tokenów za pośrednictwem biblioteki MSAL

Biblioteka MSAL umożliwia aplikacjom uzyskiwanie tokenów w trybie dyskretnym i interaktywnym. W przypadku wywołania AcquireTokenSilent() lub AcquireTokenInteractive(), biblioteka MSAL zwraca token dostępu dla żądanych zakresów. Prawidłowym wzorcem jest utworzenie żądania dyskretnego, a następnie powrót do żądania interakcyjnego.

Android

String[] SCOPES = {"https://graph.microsoft.com/.default"};
PublicClientApplication sampleApp = new PublicClientApplication(
                    this.getApplicationContext(),
                    R.raw.auth_config);

// Check if there are any accounts we can sign in silently.
// Result is in the silent callback (success or error).
sampleApp.getAccounts(new PublicClientApplication.AccountsLoadedCallback() {
    @Override
    public void onAccountsLoaded(final List<IAccount> accounts) {

        if (!accounts.isEmpty() && accounts.size() == 1) {
            // One account found, attempt silent sign-in.
            sampleApp.acquireTokenSilentAsync(SCOPES, accounts.get(0), getAuthSilentCallback());
        } else if (accounts.isEmpty()) {
            // No accounts found. Interactively request a token.
            sampleApp.acquireToken(getActivity(), SCOPES, getAuthInteractiveCallback());
        } else {
            // Multiple accounts found. Handle according to your app logic.
            // You may need to prompt the user to select an account.
        }
    }
});

[...]

// No accounts found. Interactively request a token.
// TODO: Create an interactive callback to catch successful or failed requests.
sampleApp.acquireToken(getActivity(), SCOPES, getAuthInteractiveCallback());

Ios

Najpierw spróbuj pozyskać token w trybie dyskretnym:

NSArray *scopes = @[@"https://graph.microsoft.com/.default"];
NSString *accountIdentifier = @"my.account.id";

MSALAccount *account = [application accountForIdentifier:accountIdentifier error:nil];

MSALSilentTokenParameters *silentParams = [[MSALSilentTokenParameters alloc] initWithScopes:scopes account:account];
[application acquireTokenSilentWithParameters:silentParams completionBlock:^(MSALResult *result, NSError *error) {

    if (!error)
    {
        // You'll want to get the account identifier to retrieve and reuse the account
        // for later acquireToken calls
        NSString *accountIdentifier = result.account.identifier;

        // Access token to call the web API
        NSString *accessToken = result.accessToken;
    }

    // Check the error
    if (error && [error.domain isEqual:MSALErrorDomain] && error.code == MSALErrorInteractionRequired)
    {
        // Interactive auth will be required, call acquireTokenWithParameters:error:
        return;
    }
}];

let scopes = ["https://graph.microsoft.com/.default"]
let accountIdentifier = "my.account.id"

guard let account = try? application.account(forIdentifier: accountIdentifier) else { return }
let silentParameters = MSALSilentTokenParameters(scopes: scopes, account: account)
application.acquireTokenSilent(with: silentParameters) { (result, error) in

    guard let authResult = result, error == nil else {

    let nsError = error! as NSError

    if (nsError.domain == MSALErrorDomain &&
        nsError.code == MSALError.interactionRequired.rawValue) {

            // Interactive auth will be required, call acquireToken()
            return
         }
         return
     }

    // You'll want to get the account identifier to retrieve and reuse the account
    // for later acquireToken calls
    let accountIdentifier = authResult.account.identifier

    // Access token to call the web API
    let accessToken = authResult.accessToken
}

Jeśli biblioteka MSAL zwróci wartość MSALErrorInteractionRequired, spróbuj interaktywnie pozyskać tokeny:

UIViewController *viewController = ...; // Pass a reference to the view controller that should be used when getting a token interactively
MSALWebviewParameters *webParameters = [[MSALWebviewParameters alloc] initWithAuthPresentationViewController:viewController];
MSALInteractiveTokenParameters *interactiveParams = [[MSALInteractiveTokenParameters alloc] initWithScopes:scopes webviewParameters:webParameters];
[application acquireTokenWithParameters:interactiveParams completionBlock:^(MSALResult *result, NSError *error) {
    if (!error)
    {
        // You'll want to get the account identifier to retrieve and reuse the account
        // for later acquireToken calls
        NSString *accountIdentifier = result.account.identifier;

        NSString *accessToken = result.accessToken;
    }
}];

let viewController = ... // Pass a reference to the view controller that should be used when getting a token interactively
let webviewParameters = MSALWebviewParameters(authPresentationViewController: viewController)
let interactiveParameters = MSALInteractiveTokenParameters(scopes: scopes, webviewParameters: webviewParameters)
application.acquireToken(with: interactiveParameters, completionBlock: { (result, error) in

    guard let authResult = result, error == nil else {
        print(error!.localizedDescription)
        return
    }

    // Get access token from result
    let accessToken = authResult.accessToken
})

Biblioteka MSAL dla systemów iOS i macOS obsługuje różne modyfikatory w celu interaktywnego lub dyskretnego pobierania tokenu:

• Typowe parametry pobierania tokenu
• Parametry pobierania tokenu interakcyjnego
• Parametry pobierania tokenu dyskretnego

Obowiązkowe parametry w MSAL.NET

AcquireTokenInteractive ma tylko jeden obowiązkowy parametr: scopes. Parametr scopes wylicza ciągi definiujące zakresy, dla których jest wymagany token. Jeśli token jest przeznaczony dla Microsoft Graph, możesz znaleźć wymagane uprawnienia w dokumentacji każdego interfejsu API Microsoft Graph. W referencji przejdź do sekcji "Uprawnienia".

Aby na przykład wyświetlić listę kontaktów użytkownika, użyj zakresu "User.Read", "Contacts.Read". Aby uzyskać więcej informacji, zobacz Informacje o uprawnieniach usługi Microsoft Graph.

W systemie Android można określić działanie nadrzędne podczas tworzenia aplikacji przy użyciu polecenia PublicClientApplicationBuilder. Jeśli nie określisz w danym momencie działania nadrzędnego, później możesz je określić, korzystając z funkcji .WithParentActivityOrWindow, jak to pokazano w sekcji poniżej. Jeśli określisz działanie nadrzędne, token wróci do tego działania nadrzędnego po interakcji. Jeśli nie określisz tego, wywołanie .ExecuteAsync() zgłasza wyjątek.

Określone parametry opcjonalne w MSAL.NET

W poniższych sekcjach opisano parametry opcjonalne w MSAL.NET.

Z podpowiedzią

Parametr WithPrompt() steruje interakcyjnością z użytkownikiem, określając monit.

Klasa definiuje następujące stałe:

• SelectAccount wymusza, aby usługa tokenu zabezpieczającego (STS) wyświetlała okno dialogowe wyboru konta. Okno dialogowe zawiera konta, dla których użytkownik ma sesję. Możesz użyć tej opcji, jeśli chcesz zezwolić użytkownikowi na wybór między różnymi tożsamościami. Ta opcja powoduje, że MSAL wysyła prompt=select_account do dostawcy tożsamości.

  Stała SelectAccount jest wartością domyślną i efektywnie umożliwia najlepsze możliwe doświadczenie na podstawie dostępnych informacji. Dostępne informacje mogą obejmować konto, obecność sesji dla użytkownika itd. Nie zmieniaj tego ustawienia domyślnego, chyba że masz dobry powód, aby to zrobić.

• Consent umożliwia wystosowanie monitu do użytkownika o zgodę, nawet jeśli wcześniej udzielono zgody. W takim przypadku MSAL wysyła prompt=consent do dostawcy tożsamości.

  Możesz chcieć używać stałej Consent w aplikacjach skoncentrowanych na zabezpieczeniach, w których ład organizacji wymaga od użytkowników wyświetlenia okna dialogowego zgody za każdym razem, gdy używają aplikacji.

• ForceLogin umożliwia usłudze monitowanie użytkownika o poświadczenia, nawet jeśli monit nie jest potrzebny.

  Ta opcja może być przydatna, jeśli pozyskiwanie tokenu zakończy się niepowodzeniem i chcesz zezwolić użytkownikowi na ponowne zalogowanie. W takim przypadku MSAL wysyła prompt=login do dostawcy tożsamości. Możesz użyć tej opcji w aplikacjach skoncentrowanych na zabezpieczeniach, w których ład organizacji wymaga od użytkownika zalogowania się za każdym razem, gdy uzyskują dostęp do określonych części aplikacji.

• Neverjest przeznaczony tylko dla platformy .NET 4.5 oraz środowiska wykonawczego Windows Runtime (WinRT). Ta stała nie wyświetli komunikatu użytkownika, ale spróbuje użyć pliku cookie przechowywanego w ukrytym w osadzonym widoku internetowym. Aby uzyskać więcej informacji, zobacz Używanie przeglądarek internetowych z MSAL.NET.

  Jeśli ta opcja nie powiedzie się, AcquireTokenInteractive zgłasza wyjątek informujący o konieczności interakcji interfejsu użytkownika. Następnie użyj innego Prompt parametru.

• NoPrompt nie wysyła monitu do dostawcy tożsamości.

  Ta opcja jest przydatna tylko w przypadku zasad edytowania profilu w usłudze Azure Active Directory B2C. Aby uzyskać więcej informacji, zobacz Szczegóły dotyczące B2C.

Z dodatkowym zakresem zgody

Użyj modyfikatora WithExtraScopeToConsent w zaawansowanym scenariuszu, w którym chcesz, aby użytkownik udzielił z góry zgody na kilka zasobów. Tego modyfikatora można używać, gdy nie chcesz używać zgody przyrostowej, która jest zwykle używana z MSAL.NET lub platformą tożsamości Microsoft. Aby uzyskać więcej informacji, zobacz Uzyskiwanie zgody użytkownika z góry dla kilku zasobów.

Oto przykład kodu:

var result = await app.AcquireTokenInteractive(scopesForCustomerApi)
                     .WithExtraScopeToConsent(scopesForVendorApi)
                     .ExecuteAsync();

Inne parametry opcjonalne

Aby dowiedzieć się więcej o innych opcjonalnych parametrach dla AcquireTokenInteractive, zobacz dokumentację referencyjną AcquireTokenInteractiveParameterBuilder.

Uzyskiwanie tokenów za pośrednictwem protokołu

Nie zalecamy bezpośredniego używania protokołu do pobierania tokenów. Jeśli to zrobisz, aplikacja nie będzie obsługiwać niektórych scenariuszy obejmujących logowanie jednokrotne, zarządzanie urządzeniami i dostęp warunkowy.

Gdy używasz protokołu do pobierania tokenów dla aplikacji mobilnych, wykonaj dwa żądania:

• Pobierz kod autoryzacji.
• Wymiana kodu dla tokenu.

Pobieranie kodu autoryzacji

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=<CLIENT_ID>
&response_type=code
&redirect_uri=<ENCODED_REDIRECT_URI>
&response_mode=query
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2F.default
&state=12345

Uzyskiwanie dostępu i odświeżanie tokenu

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=<CLIENT_ID>
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=<ENCODED_REDIRECT_URI>
&grant_type=authorization_code

Następne kroki

• Dowiedz się więcej, tworząc jednostronicową aplikację React (SPA), która pozwala użytkownikom się zalogować, w następnej serii wieloczęściowych samouczków.

• Eksploruj przykłady kodów mobilnych platformy tożsamości Microsoft