Megosztás a következőn keresztül:

Jogkivonat lekérése webes API-kat hívó mobilalkalmazáshoz

  • Cikk

Mielőtt az alkalmazás meghívhatja a védett webes API-kat, hozzáférési jogkivonatra van szüksége. Ez a cikk végigvezeti a jogkivonatok Microsoft Authentication Library (MSAL) használatával történő lekérésének folyamatán.

Hatókör definiálása

Jogkivonat kérésekor adjon meg egy hatókört. A hatókör határozza meg, hogy az alkalmazás milyen adatokhoz férhet hozzá.

A hatókör meghatározásának legegyszerűbb módja a kívánt webes API-k App ID URI és a hatókör .defaultkombinálása. Ez a definíció azt jelzi a Microsoft Identitásplatform, hogy az alkalmazáshoz a portálon beállított összes hatókörre szükség van.

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"};

Jogkivonatok lekérése

Jogkivonatok beszerzése MSAL-en keresztül

Az MSAL lehetővé teszi az alkalmazások számára a jogkivonatok csendes és interaktív beszerzését. Híváskor AcquireTokenSilent() vagy AcquireTokenInteractive()az MSAL egy hozzáférési jogkivonatot ad vissza a kért hatókörökhöz. A helyes minta egy csendes kérés létrehozása, majd egy interaktív kérésre való visszalépés.

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

Először próbálja meg csendesen beszerezni a jogkivonatot:


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
}

Ha az MSAL visszatér MSALErrorInteractionRequired, próbálja meg interaktív módon beszerezni a jogkivonatokat:

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

Az iOS-hez és macOS-hez készült MSAL különböző módosítókat támogat a jogkivonat interaktív vagy csendes beszerzéséhez:

Xamarin

Az alábbi példa azt a minimális kódot mutatja be, amely interaktívan lekér egy jogkivonatot. A példa a Microsoft Graph használatával olvassa be a felhasználó profilját.

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

Kötelező paraméterek a MSAL.NET

AcquireTokenInteractive csak egy kötelező paramétere van: scopes. A scopes paraméter számba adja azokat a sztringeket, amelyek meghatározzák azokat a hatóköröket, amelyekhez jogkivonatra van szükség. Ha a jogkivonat a Microsoft Graphhoz tartozik, a szükséges hatóköröket az egyes Microsoft Graph API-k API-referenciajában találja. A hivatkozásban lépjen az "Engedélyek" szakaszra.

A felhasználó névjegyeinek listázásához például használja a "User.Read", "Contacts.Read" hatókört. További információ: Microsoft Graph-engedélyek referenciája.

Androidon megadhatja a szülőtevékenységet, amikor az alkalmazást a használatával PublicClientApplicationBuilderhozza létre. Ha nem adja meg a szülőtevékenységet abban az időben, később a következő szakaszban leírtak szerint .WithParentActivityOrWindow adhatja meg. Ha szülőtevékenységet ad meg, a jogkivonat az interakció után visszakerül a szülőtevékenységhez. Ha nem adja meg, a .ExecuteAsync() hívás kivételt eredményez.

Adott választható paraméterek a MSAL.NET

Az alábbi szakaszok a MSAL.NET választható paramétereit ismertetik.

WithPrompt

A WithPrompt() paraméter egy üzenet megadásával szabályozza a felhasználóval való interaktivitást.

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.

Az osztály a következő állandókat határozza meg:

  • SelectAccount kényszeríti a biztonsági jogkivonat-szolgáltatást (STS) a fiókválasztási párbeszédpanel megjelenítésére. A párbeszédpanel tartalmazza azokat a fiókokat, amelyeknek a felhasználó munkamenete van. Ezt a lehetőséget akkor használhatja, ha engedélyezni szeretné, hogy a felhasználó válasszon a különböző identitások közül. Ez a beállítás az MSAL-t az identitásszolgáltatónak küldi prompt=select_account el.

    Az SelectAccount állandó az alapértelmezett érték, és hatékonyan biztosítja a lehető legjobb élményt a rendelkezésre álló információk alapján. A rendelkezésre álló információk közé tartozhat például a fiók, a felhasználó munkamenetének jelenléte stb. Ne módosítsa ezt az alapértelmezett beállítást, hacsak nincs rá jó oka.

  • Consent lehetővé teszi, hogy kérje a felhasználót a hozzájárulás megadására még akkor is, ha korábban már megadták a hozzájárulást. Ebben az esetben az MSAL elküldi prompt=consent az identitásszolgáltatónak.

    Érdemes lehet az állandót használni a Consent biztonságra összpontosító alkalmazásokban, ahol a szervezetirányítás megköveteli, hogy a felhasználók minden egyes alkalommal lássák a hozzájárulás párbeszédpanelt, amikor az alkalmazást használják.

  • ForceLogin lehetővé teszi a szolgáltatás számára, hogy kérje a felhasználótól a hitelesítő adatokat, még akkor is, ha nincs szükség a kérésre.

    Ez a beállítás akkor lehet hasznos, ha a jogkivonat beszerzése meghiúsul, és engedélyezni szeretné a felhasználónak, hogy újra bejelentkezjen. Ebben az esetben az MSAL elküldi prompt=login az identitásszolgáltatónak. Érdemes lehet ezt a beállítást olyan, biztonságra összpontosító alkalmazásokban használni, ahol a szervezetirányítás megköveteli a felhasználótól, hogy minden alkalommal jelentkezzen be, amikor az alkalmazás adott részeihez fér hozzá.

  • Nevercsak .NET 4.5 és Windows-futtatókörnyezet (WinRT) esetén használható. Ez az állandó nem kéri a felhasználót, de megpróbálja használni a rejtett beágyazott webes nézetben tárolt cookie-t. További információ: Webböngészők használata MSAL.NET.

    Ha ez a beállítás nem sikerül, akkor AcquireTokenInteractive kivételt küld, amely értesíti Önt arról, hogy felhasználói felületi beavatkozásra van szükség. Ezután használjon egy másik Prompt paramétert.

  • NoPrompt nem küld üzenetet az identitásszolgáltatónak.

    Ez a beállítás csak az Azure Active Directory B2C szerkesztési profilszabályzataiban hasznos. További információ: B2C specifics.

WithExtraScopeToConsent

WithExtraScopeToConsent A módosító olyan speciális forgatókönyvben használható, amelyben azt szeretné, hogy a felhasználó előzetes hozzájárulást adjon több erőforráshoz. Ezt a módosítót akkor használhatja, ha nem szeretne növekményes hozzájárulást használni, amelyet általában a MSAL.NET vagy a Microsoft Identitásplatform használ. További információ: A felhasználó beleegyezése több erőforrásra vonatkozóan.

Íme egy példa kódra:

var result = await app.AcquireTokenInteractive(scopesForCustomerApi)
                     .WithExtraScopeToConsent(scopesForVendorApi)
                     .ExecuteAsync();
Egyéb választható paraméterek

A további választható paraméterekről AcquireTokenInteractivea AcquireTokenInteractiveParameterBuilder referenciadokumentációjában olvashat.

Jogkivonatok beszerzése a protokollon keresztül

Nem javasoljuk, hogy közvetlenül használja a protokollt a jogkivonatok lekéréséhez. Ha igen, akkor az alkalmazás nem támogatja az egyszeri bejelentkezést (SSO), az eszközkezelést és a feltételes hozzáférést magában foglaló forgatókönyveket.

Amikor a protokollt használja a mobilalkalmazások jogkivonatainak lekéréséhez, két kérést kell intéznie:

  • Szerezze be az engedélyezési kódot.
  • Cserélje le a kódot egy jogkivonatra.

Engedélyezési kód lekérése

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

Hozzáférés kérése és a jogkivonat frissítése

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

Következő lépések

Lépjen tovább a következő cikkre ebben a forgatókönyvben: Webes API meghívása.