Udostępnij za pośrednictwem

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

  • Artykuł

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 Platforma tożsamości Microsoft, że 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() metody 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) {
            // TODO: Create a silent callback to catch successful or failed request.
            sampleApp.acquireTokenSilentAsync(SCOPES, accounts.get(0), getAuthSilentCallback());
        } else {
            /* No accounts or > 1 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:

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 programu Microsoft Graph, możesz znaleźć wymagane zakresy w dokumentacji interfejsu API każdego interfejsu API programu Microsoft Graph. W dokumentacji 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 tym czasie działania nadrzędnego, później możesz określić je przy użyciu funkcji .WithParentActivityOrWindow , jak w poniższej sekcji. Jeśli określisz działanie nadrzędne, token wróci do tego działania nadrzędnego po interakcji. Jeśli go nie określisz, .ExecuteAsync() wywołanie zgłasza wyjątek.

Określone parametry opcjonalne w MSAL.NET

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

WithPrompt

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

Obraz przedstawiający pola w strukturze Monit. Te stałe wartości kontrolują interakcyjność z użytkownikiem, definiując typ monitu wyświetlanego przez parametr WithPrompt().

Klasa definiuje następujące stałe:

  • SelectAccount wymusza wyświetlenie okna dialogowego wyboru konta przez usługę tokenu zabezpieczającego (STS). 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 wysłanie biblioteki prompt=select_account MSAL do dostawcy tożsamości.

    Stała SelectAccount jest wartością domyślną i efektywnie zapewnia najlepsze możliwe środowisko 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 wyświetlenie monitu użytkownika o zgodę, nawet jeśli wcześniej udzielono zgody. W takim przypadku biblioteka MSAL wysyła do dostawcy prompt=consent 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 biblioteka MSAL wysyła do dostawcy prompt=login 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 i środowisko wykonawcze systemu Windows (WinRT). Ta stała nie wyświetli monitu użytkownika, ale spróbuje użyć pliku cookie przechowywanego w ukrytym 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 B2C.

WithExtraScopeToConsent

Modyfikator jest WithExtraScopeToConsent używany w zaawansowanym scenariuszu, w którym użytkownik chce, aby udzielał 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 Platforma tożsamości Microsoft. Aby uzyskać więcej informacji, zobacz Wyświetlanie 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 parametrach opcjonalnych dla AcquireTokenInteractiveprogramu , zobacz dokumentację referencyjną metody 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 aplikację jednostronicową React (SPA), która loguje użytkowników w poniższej serii samouczków wieloczęściowych.

  • Eksplorowanie przykładów kodu mobilnego Platforma tożsamości Microsoft