Share via

Získání tokenu pro mobilní aplikaci, která volá webová rozhraní API

  • Článek

Než bude vaše aplikace moct volat chráněná webová rozhraní API, potřebuje přístupový token. Tento článek vás provede procesem získání tokenu pomocí knihovny MICROSOFT Authentication Library (MSAL).

Definování oboru

Když požádáte o token, definujte obor. Obor určuje, k jakým datům má vaše aplikace přístup.

Nejjednodušší způsob, jak definovat obor, je zkombinovat požadované webové rozhraní API App ID URI s oborem .default. Tato definice říká platformě Microsoft Identity Platform, že vaše aplikace vyžaduje všechny obory nastavené na portálu.

Android

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

iOS

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

Xamarin

var scopes = new [] {"https://graph.microsoft.com/.default"};

Získání tokenů

Získání tokenů prostřednictvím knihovny MSAL

MSAL umožňuje aplikacím získávat tokeny bezobslužně a interaktivně. Při volání AcquireTokenSilent() nebo AcquireTokenInteractive(), MSAL vrátí přístupový token pro požadované obory. Správným vzorem je provést bezobslužnou žádost a pak se vrátit k interaktivnímu požadavku.

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

Nejprve zkuste získat token bezobslužně:


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
}

Pokud msAL vrátí MSALErrorInteractionRequired, zkuste tokeny získat interaktivně:

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

MSAL pro iOS a macOS podporuje různé modifikátory pro interaktivní nebo tiché získání tokenu:

Xamarin

Následující příklad ukazuje minimální kód pro interaktivní získání tokenu. Příklad používá Microsoft Graph ke čtení profilu uživatele.

string[] scopes = new string[] {"user.read"};
var app = PublicClientApplicationBuilder.Create(clientId).Build();
var accounts = await app.GetAccountsAsync();
AuthenticationResult result;
try
{
 result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
             .ExecuteAsync();
}
catch(MsalUiRequiredException)
{
 result = await app.AcquireTokenInteractive(scopes)
             .ExecuteAsync();
}

Povinné parametry v MSAL.NET

AcquireTokenInteractive má pouze jeden povinný parametr: scopes. Parametr scopes vyčísluje řetězce, které definují obory, pro které je token povinný. Pokud je token pro Microsoft Graph, najdete požadované obory v referenčních informacích k rozhraní API každého rozhraní Microsoft Graph API. V odkazu přejděte do části Oprávnění.

Pokud například chcete zobrazit seznam kontaktů uživatele, použijte obor User.Read, Contacts.Read. Další informace najdete v tématu Referenční informace o oprávněních Microsoft Graphu.

V Androidu můžete při vytváření aplikace určit nadřazenou aktivitu pomocí PublicClientApplicationBuilder. Pokud v tuto chvíli nezadáte nadřazenou aktivitu, můžete ji později zadat pomocí následujícího .WithParentActivityOrWindow oddílu. Pokud zadáte nadřazenou aktivitu, token se po interakci vrátí k této nadřazené aktivitě. Pokud ho nezadáte, .ExecuteAsync() vyvolá volání výjimku.

Konkrétní volitelné parametry v MSAL.NET

Následující části popisují volitelné parametry v MSAL.NET.

WithPrompt

Parametr WithPrompt() řídí interaktivitu s uživatelem zadáním výzvy.

Image showing the fields in the Prompt structure. These constant values control interactivity with the user by defining the type of prompt displayed by the WithPrompt() parameter.

Třída definuje následující konstanty:

  • SelectAccount vynutí, aby služba tokenů zabezpečení (STS) představila dialogové okno pro výběr účtu. Dialogové okno obsahuje účty, pro které má uživatel relaci. Tuto možnost můžete použít, když chcete uživateli umožnit výběr mezi různými identitami. Tato možnost řídí knihovnu MSAL k odeslání prompt=select_account zprostředkovateli identity.

    Konstanta SelectAccount je výchozí a efektivně poskytuje nejlepší možné prostředí na základě dostupných informací. Dostupné informace můžou zahrnovat účet, přítomnost relace pro uživatele atd. Toto výchozí nastavení neměňte, pokud nemáte dobrý důvod k tomu.

  • Consent umožňuje uživateli vyzvat k vyjádření souhlasu i v případě, že byl souhlas udělen dříve. V tomto případě msAL odešle prompt=consent zprostředkovateli identity.

    Můžete chtít použít konstantu Consent v aplikacích zaměřených na zabezpečení, kde zásady správného řízení organizace vyžadují, aby uživatelé viděli dialogové okno souhlasu pokaždé, když aplikaci používají.

  • ForceLogin umožňuje službě vyzvat uživatele k zadání přihlašovacích údajů i v případě, že výzva není nutná.

    Tato možnost může být užitečná, pokud se získání tokenu nezdaří a vy chcete uživateli umožnit, aby se znovu přihlásil. V tomto případě msAL odešle prompt=login zprostředkovateli identity. Tuto možnost můžete chtít použít v aplikacích zaměřených na zabezpečení, kde zásady správného řízení organizace vyžadují, aby se uživatel při každém přístupu ke konkrétním částem aplikace přihlásil.

  • Neverje pouze pro .NET 4.5 a prostředí Windows Runtime (WinRT). Tato konstanta uživatele nezobrazí výzvu, ale pokusí se použít soubor cookie uložený ve skrytém vloženém webovém zobrazení. Další informace naleznete v tématu Použití webových prohlížečů s MSAL.NET.

    Pokud tato možnost selže, vyvolá AcquireTokenInteractive výjimku, která vás upozorní, že je potřeba interakce s uživatelským rozhraním. Pak použijte jiný Prompt parametr.

  • NoPrompt neodesílá výzvu zprostředkovateli identity.

    Tato možnost je užitečná jenom pro zásady profilu úprav v Azure Active Directory B2C. Další informace najdete v tématu Podrobnosti B2C.

WithExtraScopeToConsent

WithExtraScopeToConsent Modifikátor použijte v pokročilém scénáři, ve kterém má uživatel předem udělit souhlas s několika prostředky. Tento modifikátor můžete použít, pokud nechcete používat přírůstkový souhlas, který se obvykle používá s MSAL.NET nebo platformou Microsoft Identity Platform. Další informace najdete v tématu Předběžné vyjádření souhlasu uživatele s několika prostředky.

Tady je příklad kódu:

var result = await app.AcquireTokenInteractive(scopesForCustomerApi)
                     .WithExtraScopeToConsent(scopesForVendorApi)
                     .ExecuteAsync();
Další volitelné parametry

Další volitelné parametry AcquireTokenInteractivenajdete v referenční dokumentaci pro AcquireTokenInteractiveParameterBuilder.

Získání tokenů prostřednictvím protokolu

K získání tokenů nedoporučujeme přímo používat protokol. Pokud ano, aplikace nebude podporovat některé scénáře, které zahrnují jednotné přihlašování, správu zařízení a podmíněný přístup.

Při použití protokolu k získání tokenů pro mobilní aplikace proveďte dva požadavky:

  • Získejte autorizační kód.
  • Vyměňte kód tokenu.

Získání autorizačního kódu

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

Získání přístupu a aktualizace 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

Další kroky

Přejděte k dalšímu článku v tomto scénáři volání webového rozhraní API.