Share via

Een token ophalen voor een mobiele app die web-API's aanroept

  • Artikel

Voordat uw app beveiligde web-API's kan aanroepen, heeft deze een toegangstoken nodig. In dit artikel wordt u begeleid bij het ophalen van een token met behulp van de Microsoft Authentication Library (MSAL).

Een bereik definiëren

Wanneer u een token aanvraagt, definieert u een bereik. Het bereik bepaalt tot welke gegevens uw app toegang heeft.

De eenvoudigste manier om een bereik te definiëren, is door de gewenste web-API's App ID URI te combineren met het bereik .default. Met deze definitie wordt aan het Microsoft Identity Platform doorgegeven dat uw app alle bereiken vereist die zijn ingesteld in de portal.

Android

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

iOS

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

Tokens ophalen

Tokens ophalen via MSAL

Met MSAL kunnen apps op de achtergrond en interactief tokens ophalen. Wanneer u AcquireTokenSilent() of AcquireTokenInteractive() aanroept, retourneert MSAL een toegangstoken voor de aangevraagde bereiken. Het juiste patroon is om een aanvraag op de achtergrond te doen en vervolgens terug te vallen op een interactieve aanvraag.

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

Probeer eerst een token op de achtergrond op te halen:


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
}

Als MSAL MSALErrorInteractionRequired retourneert, probeert u interactief tokens op te halen:

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 voor iOS en macOS ondersteunt verschillende modifiers om een token interactief of op de achtergrond op te halen:

Verplichte parameters in MSAL.NET

AcquireTokenInteractive heeft slechts één verplichte parameter: scopes. Met de parameter scopes worden tekenreeksen opgesomd die de bereiken definiëren waarvoor een token is vereist. Als het token voor Microsoft Graph is, kunt u de vereiste bereiken vinden in de API-verwijzing van elke Microsoft Graph API. Ga in de verwijzing naar de sectie Machtigingen.

Als u bijvoorbeeld de contactpersonen van de gebruiker wilt weergeven, gebruikt u het bereik 'User.Read', 'Contacts.Read'. Raadpleeg Microsoft Graph-machtigingen voor meer informatie.

Op Android kunt u bovenliggende activiteit opgeven wanneer u de app maakt met behulp van PublicClientApplicationBuilder. Als u de bovenliggende activiteit niet op dat moment opgeeft, kunt u deze later opgeven met behulp van .WithParentActivityOrWindow, zoals in de volgende sectie. Als u bovenliggende activiteit opgeeft, wordt het token na de interactie teruggezet naar die bovenliggende activiteit. Als u deze niet opgeeft, genereert de aanroep .ExecuteAsync() een uitzondering.

Specifieke optionele parameters in MSAL.NET

In de volgende secties worden de optionele parameters in MSAL.NET uitgelegd.

WithPrompt

De parameter WithPrompt() bepaalt de interactiviteit met de gebruiker door een prompt op te geven.

Afbeelding van de velden in de structuur van de prompt. Deze constante waarden beheren de interactiviteit met de gebruiker door het type prompt dat wordt weergegeven door de parameter WithPrompt() te definiëren.

De klasse definieert de volgende constanten:

  • SelectAccount dwingt de beveiligingstokenservice (STS) om het dialoogvenster voor accountselectie weer te geven. Het dialoogvenster bevat de accounts waarvoor de gebruiker een sessie heeft. U kunt deze optie gebruiken als u de gebruiker wilt laten kiezen uit verschillende identiteiten. Met deze optie stuurt MSAL prompt=select_account naar de id-provider.

    De constante SelectAccount is de standaardwaarde en biedt de best mogelijke ervaring op basis van de beschikbare informatie. De beschikbare informatie kan account, aanwezigheid van een sessie voor de gebruiker, enzovoort omvatten. Wijzig deze standaardinstelling alleen als u een goede reden hebt om dit te doen.

  • Met Consent kunt u de gebruiker om toestemming vragen, zelfs als er eerder toestemming is verleend. In dit geval verzendt MSAL prompt=consent naar de id-provider.

    Mogelijk wilt u de constante Consent gebruiken in beveiligingstoepassingen waarbij aan gebruikers het toestemmingsdialoogvenster bij elk gebruik moet worden weergegeven om aan de governance van de organisatie te voldoen.

  • Met ForceLogin kan de service de gebruiker om aanmeldingsgegevens vragen, zelfs als de prompt niet nodig is.

    Deze optie kan handig zijn als het ophalen van het token mislukt en u de gebruiker zich opnieuw wilt laten aanmelden. In dit geval verzendt MSAL prompt=login naar de id-provider. U kunt deze optie gebruiken in beveiligingstoepassingen, waarbij de gebruiker zich elke keer moet aanmelden voor toegang tot specifieke onderdelen van de toepassing om aan de governance van de organisatie te voldoen.

  • Never is alleen voor .NET 4.5 en Windows Runtime (WinRT). Met deze constante krijgt de gebruiker geen prompt, maar wordt geprobeerd de cookie te gebruiken die is opgeslagen in de verborgen, ingesloten webweergave. Zie Webbrowsers gebruiken met MSAL.NET voor meer informatie.

    Als deze optie mislukt, genereert AcquireTokenInteractive een uitzondering om u te laten weten dat er een gebruikersinterface-interactie nodig is. Gebruik vervolgens een andere Prompt-parameter.

  • NoPrompt stuurt geen prompt naar de id-provider.

    Deze optie is alleen handig voor beleid voor het bewerken van profielen in Azure Active Directory B2C. Zie B2C-details voor meer informatie.

WithExtraScopeToConsent

Gebruik de modifier WithExtraScopeToConsent in een geavanceerd scenario waarin u wilt dat de gebruiker vooraf toestemming geeft voor verschillende resources. U kunt deze modifier gebruiken wanneer u geen incrementele toestemming wilt gebruiken, die normaal gesproken wordt gebruikt met MSAL.NET of het Microsoft Identity Platform. Zie Gebruikers vooraf toestemming laten geven voor verschillende resources voor meer informatie.

Hier volgt een codevoorbeeld:

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

Zie de referentiedocumentatie voor AcquireTokenInteractiveParameterBuilder voor meer informatie over de andere optionele parameters voor AcquireTokenInteractive.

Tokens ophalen via het protocol

We raden u af om rechtstreeks via het protocol tokens op te halen. Als u dit doet, biedt de app geen ondersteuning voor sommige scenario's waarbij eenmalige aanmelding (SSO), apparaatbeheer en voorwaardelijke toegang zijn betrokken.

Wanneer u het protocol gebruikt om tokens voor mobiele apps op te halen, moet u twee aanvragen indienen:

  • Autorisatiecode ophalen.
  • Wissel de code voor een token.

Autorisatiecode ophalen

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

Toegang krijgen en het token vernieuwen

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

Volgende stappen

  • Meer informatie vindt u door een React-toepassing met één pagina (SPA) te bouwen waarmee gebruikers worden aangemeld in de volgende reeks meerdelige zelfstudies.

  • Voorbeelden van mobiele code van Microsoft Identity Platform verkennen