Hızlı Başlangıç: Android uygulamasından kullanıcıların oturumunu açma ve Microsoft Graph'ı arama

  • Makale

Bu hızlı başlangıçta, bir Android uygulamasının kullanıcılarda nasıl oturum açabileceğini ve Microsoft Graph API'sini çağırmak için erişim belirteci alabileceğini gösteren bir kod örneği indirip çalıştıracaksınız.

Bkz. Örnek bir çizim için nasıl çalışır ?

uygulamalar, Microsoft kimlik platformu uygulamanıza belirteç sağlayabilmesi için Microsoft Entra Id'deki bir uygulama nesnesiyle temsil edilmelidir.

Önkoşullar

1. Adım: Örnek uygulamayı alma

Kodu indirin.

2. Adım: Örnek uygulamayı çalıştırma

Android Studio'nun kullanılabilir cihazlar açılan listesinden öykünücünüzü veya fiziksel cihazınızı seçin ve uygulamayı çalıştırın.

Örnek uygulama Tek Hesap Modu ekranında başlar. Microsoft Graph API çağrısı sırasında kendi profil verilerinizi okurken kullanılan varsayılan user.read kapsamı varsayılan olarak sağlanır. Microsoft Graph API çağrısının URL'si varsayılan olarak sağlanır. İsterseniz bunların ikisini de değiştirebilirsiniz.

Screenshot of the MSAL sample app showing single and multiple account usage.

Tek ve birden çok hesap modu arasında değişiklik yapmak için uygulama menüsünü kullanın.

Tek hesap modunda iş veya ev hesabı kullanarak oturum açın:

  1. Kullanıcıdan kimlik bilgilerini istemesi için Graf verilerini etkileşimli olarak al'ı seçin. Ekranın alt kısmında Microsoft Graph API'sine yapılan çağrının çıkışını görürsünüz.
  2. Oturum açtıktan sonra kullanıcıdan kimlik bilgilerini yeniden istemeden Microsoft Graph API'sine çağrı yapmak için Grafik verilerini sessizce al'ı seçin. Ekranın alt kısmında Microsoft Graph API'sine yapılan çağrının çıkışını görürsünüz.

Birden çok hesap modunda aynı adımları yineleyebilirsiniz. Ayrıca, oturum açmış hesabı kaldırabilirsiniz ve bu da bu hesabın önbelleğe alınmış belirteçlerini kaldırır.

Örnek nasıl çalışır?

Diagram showing how the sample app generated by this quickstart works.

Kod, tek ve birden çok hesap MSAL uygulamasının nasıl yazıldığını gösteren parçalar halinde düzenlenmiştir. Kod dosyaları aşağıdaki gibi düzenlenir:

Dosya Gösteriler
MainActivity Kullanıcı arabirimini yönetir
MSGraphRequestWrapper MSAL tarafından sağlanan belirteci kullanarak Microsoft Graph API'sini çağırır
MultipleAccountModeFragment Çok hesaplı bir uygulama başlatır, bir kullanıcı hesabı yükler ve Microsoft Graph API'sini çağırmak için bir belirteç alır
SingleAccountModeFragment Tek hesaplı bir uygulama başlatır, bir kullanıcı hesabı yükler ve Microsoft Graph API'sini çağırmak için bir belirteç alır
res/auth_config_multiple_account.json Birden çok hesap yapılandırma dosyası
res/auth_config_single_account.json Tek hesap yapılandırma dosyası
Gradle Betikleri/build.grade (Module:app) MSAL kitaplık bağımlılıkları buraya eklenir

Şimdi bu dosyalara daha ayrıntılı bir şekilde göz atacak ve her birinde MSAL'ye özgü kodu çağıracağız.

Uygulamaya MSAL ekleme

MSAL (com.microsoft.identity.client), kullanıcılarda oturum açmak ve Microsoft kimlik platformu tarafından korunan bir API'ye erişmek için kullanılan belirteçleri istemek için kullanılan kitaplıktır. Bağımlılıklar altında build.gradle Betikleri'ne >(Modül: uygulama) aşağıdakileri eklediğinizde Gradle 3.0+ kitaplığı yükler:

dependencies {
    ...
    implementation 'com.microsoft.identity.client:msal:5.1.0'
    implementation 'com.android.volley:volley:1.2.1'
    ...
}

Bu, Gradle'a maven central'dan MSAL indirmesini ve derlemesini sağlar.

Ayrıca, dependencyResolutionManagement altında settings.gradle dosyasının allprojects>depoları bölümüne de maven başvuruları eklemeniz gerekir:

dependencyResolutionManagement {
...
maven 
{
 url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
}
... 
}

MSAL içeri aktarmaları

MSAL kitaplığıyla ilgili içeri aktarmalar şeklindedir com.microsoft.identity.client.*. Örneğin, genel istemci uygulamanızı temsil eden sınıfın PublicClientApplication ad alanının hangisi olduğunu görürsünüzimport com.microsoft.identity.client.PublicClientApplication;.

SingleAccountModeFragment.java

Bu dosyada tek bir hesap MSAL uygulamasının nasıl oluşturulacağı ve Microsoft Graph API'sinin nasıl çağrılacağı gösterilmektedir.

Tek hesap uygulamaları yalnızca tek bir kullanıcı tarafından kullanılır. Örneğin, eşleme uygulamanızda oturum açabileceğiniz tek bir hesabınız olabilir.

Tek hesap MSAL başlatma

SingleAccountModeFragment.javayönteminde onCreateView() dosyasında depolanan auth_config_single_account.json yapılandırma bilgileri kullanılarak tek bir hesap PublicClientApplication oluşturulur. Tek hesaplı bir MSAL uygulamasında kullanılmak üzere MSAL kitaplığını bu şekilde başlatırsınız:

...
// Creates a PublicClientApplication object with res/raw/auth_config_single_account.json
PublicClientApplication.createSingleAccountPublicClientApplication(getContext(),
        R.raw.auth_config_single_account,
        new IPublicClientApplication.ISingleAccountApplicationCreatedListener() {
            @Override
            public void onCreated(ISingleAccountPublicClientApplication application) {
                /**
                 * This test app assumes that the app is only going to support one account.
                 * This requires "account_mode" : "SINGLE" in the config json file.
                 **/
                mSingleAccountApp = application;
                loadAccount();
            }

            @Override
            public void onError(MsalException exception) {
                displayError(exception);
            }
        });

Bir kullanıcıda oturum açma

içindeSingleAccountModeFragment.java, bir kullanıcının oturum açma kodu, tıklama işleyicisindedirinitializeUI()signInButton.

Belirteçleri almaya çalışmadan önce öğesini çağırın signIn() . signIn() çağrılmış gibi acquireToken() davranarak kullanıcının oturum açması için etkileşimli bir istem oluşturur.

Bir kullanıcıda oturum açmak zaman uyumsuz bir işlemdir. Kullanıcı oturum açtığında Microsoft Graph API'sini çağıran ve kullanıcı arabirimini güncelleştiren bir geri arama geçirilir:

mSingleAccountApp.signIn(getActivity(), null, getScopes(), getAuthInteractiveCallback());

Kullanıcının oturumunu kapatma

içindeSingleAccountModeFragment.java, kullanıcının oturumunu kapatma kodu, tıklama işleyicisindedirinitializeUI()signOutButton. Kullanıcının oturumu kapatma işlemi zaman uyumsuz bir işlemdir. Kullanıcının oturumunu kapatması, bu hesabın belirteç önbelleğini de temizler. Kullanıcı hesabı oturumu kapatıldıktan sonra kullanıcı arabirimini güncelleştirmek için bir geri arama oluşturulur:

mSingleAccountApp.signOut(new ISingleAccountPublicClientApplication.SignOutCallback() {
    @Override
    public void onSignOut() {
        updateUI(null);
        performOperationOnSignOut();
    }

    @Override
    public void onError(@NonNull MsalException exception) {
        displayError(exception);
    }
});

Etkileşimli veya sessiz bir şekilde belirteç alma

Kullanıcıya en az sayıda istem sunmak için genellikle sessizce bir belirteç alırsınız. Ardından bir hata varsa etkileşimli olarak belirteç almayı deneyin. Uygulama ilk kez çağrısında signIn(), kullanıcıdan kimlik bilgilerini isteyen bir çağrısı acquireToken()işlevi görür.

Kullanıcıdan hesabını seçmesi, kimlik bilgilerini girmesi veya uygulamanızın istediği izinlere onay vermesinin istenebileceği bazı durumlar şunlardır:

  • Kullanıcı uygulamada ilk kez oturum açtığında
  • Bir kullanıcı parolasını sıfırlarsa, kimlik bilgilerini girmesi gerekir
  • Onay iptal edilirse
  • Uygulamanız açıkça onay gerektiriyorsa
  • Uygulamanız bir kaynağa ilk kez erişim istediğinde
  • MFA veya diğer Koşullu Erişim ilkeleri gerektiğinde

Etkileşimli olarak bir belirteç almaya ilişkin kod( kullanıcıyı kapsayan kullanıcı arabirimiyle birlikte) içinde, içinde, tıklama işleyicisindedirSingleAccountModeFragment.javainitializeUI()callGraphApiInteractiveButton:

/**
 * If acquireTokenSilent() returns an error that requires an interaction (MsalUiRequiredException),
 * invoke acquireToken() to have the user resolve the interrupt interactively.
 *
 * Some example scenarios are
 *  - password change
 *  - the resource you're acquiring a token for has a stricter set of requirement than your Single Sign-On refresh token.
 *  - you're introducing a new scope which the user has never consented for.
 **/
mSingleAccountApp.acquireToken(getActivity(), getScopes(), getAuthInteractiveCallback());

Kullanıcı zaten oturum açtıysa, acquireTokenSilentAsync() uygulamaların tıklama işleyicisinde initializeUI()gösterildiği gibi sessizce belirteç istemesine callGraphApiSilentButton izin verir:

/**
 * Once you've signed the user in,
 * you can perform acquireTokenSilent to obtain resources without interrupting the user.
 **/
  mSingleAccountApp.acquireTokenSilentAsync(getScopes(), AUTHORITY, getAuthSilentCallback());

Hesap yükleme

Hesap yükleme kodu içindedir SingleAccountModeFragment.javaloadAccount(). Kullanıcının hesabını yüklemek zaman uyumsuz bir işlemdir, bu nedenle hesap yüklendiğinde, değiştiğinde veya bir hata oluştuğunda işlemeye yönelik geri çağırmalar MSAL'ye geçirilir. Aşağıdaki kod, bir hesap kaldırıldığında, kullanıcı başka bir hesaba değiştiğinde vb. oluşan öğesini de işler onAccountChanged().

private void loadAccount() {
    ...

    mSingleAccountApp.getCurrentAccountAsync(new ISingleAccountPublicClientApplication.CurrentAccountCallback() {
        @Override
        public void onAccountLoaded(@Nullable IAccount activeAccount) {
            // You can use the account data to update your UI or your app database.
            updateUI(activeAccount);
        }

        @Override
        public void onAccountChanged(@Nullable IAccount priorAccount, @Nullable IAccount currentAccount) {
            if (currentAccount == null) {
                // Perform a cleanup task as the signed-in account changed.
                performOperationOnSignOut();
            }
        }

        @Override
        public void onError(@NonNull MsalException exception) {
            displayError(exception);
        }
    });

Microsoft Graph'ı arayın

Bir kullanıcı oturum açtığında, Microsoft Graph çağrısı içinde SingleAccountModeFragment.javatanımlanan bir HTTP isteği callGraphAPI() aracılığıyla yapılır. Bu işlev, içinden erişim belirtecini authenticationResult alma ve MSGraphRequestWrapper çağrısının paketlenmesi ve çağrının sonuçlarının görüntülenmesi gibi bazı görevleri gerçekleştirerek örneği basitleştiren bir sarmalayıcıdır.

private void callGraphAPI(final IAuthenticationResult authenticationResult) {
    MSGraphRequestWrapper.callGraphAPIUsingVolley(
            getContext(),
            graphResourceTextView.getText().toString(),
            authenticationResult.getAccessToken(),
            new Response.Listener<JSONObject>() {
                @Override
                public void onResponse(JSONObject response) {
                    /* Successfully called graph, process data and send to UI */
                    ...
                }
            },
            new Response.ErrorListener() {
                @Override
                public void onErrorResponse(VolleyError error) {
                    ...
                }
            });
}

auth_config_single_account.json

Bu, tek bir hesap kullanan bir MSAL uygulamasının yapılandırma dosyasıdır.

Bu alanların açıklaması için bkz . Android MSAL yapılandırma dosyasını anlama.

Bu uygulamayı tek bir hesap kullanacak şekilde yapılandıran öğesinin "account_mode" : "SINGLE"varlığına dikkat edin.

"client_id" , Microsoft'un koruduğu bir uygulama nesnesi kaydını kullanacak şekilde önceden yapılandırılmıştır. "redirect_uri", kod örneğiyle birlikte sağlanan imzalama anahtarını kullanacak şekilde önceden yapılandırılmıştır.

{
  "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "redirect_uri": "msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "account_mode": "SINGLE",
  "broker_redirect_uri_registered": true,
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

MultipleAccountModeFragment.java

Bu dosya, birden çok hesap MSAL uygulaması oluşturmayı ve Microsoft Graph API'sini çağırmayı gösterir.

Birden çok hesap uygulamasına örnek olarak, iş hesabı ve kişisel hesap gibi birden çok kullanıcı hesabıyla çalışmanızı sağlayan bir posta uygulaması örnektir.

Birden çok hesap MSAL başlatması

MultipleAccountModeFragment.java dosyasında, içinde onCreateView()içinde depolanan auth_config_multiple_account.json fileyapılandırma bilgileri kullanılarak bir birden çok hesap uygulaması nesnesi (IMultipleAccountPublicClientApplication) oluşturulur:

// Creates a PublicClientApplication object with res/raw/auth_config_multiple_account.json
PublicClientApplication.createMultipleAccountPublicClientApplication(getContext(),
        R.raw.auth_config_multiple_account,
        new IPublicClientApplication.IMultipleAccountApplicationCreatedListener() {
            @Override
            public void onCreated(IMultipleAccountPublicClientApplication application) {
                mMultipleAccountApp = application;
                loadAccounts();
            }

            @Override
            public void onError(MsalException exception) {
                ...
            }
        });

Oluşturulan MultipleAccountPublicClientApplication nesne bir sınıf üyesi değişkeninde depolanır, böylece belirteçleri almak ve kullanıcı hesabını yükleyip kaldırmak için MSAL kitaplığıyla etkileşim kurmak için kullanılabilir.

Hesap yükleme

Birden çok hesap uygulaması genellikle MSAL işlemleri için kullanılacak hesabı seçmek için arar getAccounts() . Hesap yükleme kodu dosyasındadır MultipleAccountModeFragment.javaloadAccounts(). Kullanıcının hesabını yüklemek zaman uyumsuz bir işlemdir. Bu nedenle, geri arama hesabın yüklendiği, değiştiği veya bir hata oluştuğu durumları işler.

/**
 * Load currently signed-in accounts, if there's any.
 **/
private void loadAccounts() {
    if (mMultipleAccountApp == null) {
        return;
    }

    mMultipleAccountApp.getAccounts(new IPublicClientApplication.LoadAccountsCallback() {
        @Override
        public void onTaskCompleted(final List<IAccount> result) {
            // You can use the account data to update your UI or your app database.
            accountList = result;
            updateUI(accountList);
        }

        @Override
        public void onError(MsalException exception) {
            displayError(exception);
        }
    });
}

Etkileşimli veya sessiz bir şekilde belirteç alma

Kullanıcıdan hesabını seçmesi, kimlik bilgilerini girmesi veya uygulamanızın istediği izinlere onay vermesinin istenebileceği bazı durumlar şunlardır:

  • Kullanıcılar uygulamada ilk kez oturum açtığında
  • Bir kullanıcı parolasını sıfırlarsa, kimlik bilgilerini girmesi gerekir
  • Onay iptal edilirse
  • Uygulamanız açıkça onay gerektiriyorsa
  • Uygulamanız bir kaynağa ilk kez erişim istediğinde
  • MFA veya diğer Koşullu Erişim ilkeleri gerektiğinde

Birden çok hesap uygulaması genellikle kullanıcının bulunduğu kullanıcı arabiriminde ve çağrısıyla acquireToken()etkileşimli olarak belirteçler almalıdır. Etkileşimli olarak belirteç almaya ilişkin kod, içindeki dosyasındainitializeUI(), tıklama işleyicisindedir:MultipleAccountModeFragment.javacallGraphApiInteractiveButton

/**
 * Acquire token interactively. It will also create an account object for the silent call as a result (to be obtained by getAccount()).
 *
 * If acquireTokenSilent() returns an error that requires an interaction,
 * invoke acquireToken() to have the user resolve the interrupt interactively.
 *
 * Some example scenarios are
 *  - password change
 *  - the resource you're acquiring a token for has a stricter set of requirement than your SSO refresh token.
 *  - you're introducing a new scope which the user has never consented for.
 **/
mMultipleAccountApp.acquireToken(getActivity(), getScopes(), getAuthInteractiveCallback());

Uygulamalar, kullanıcının her belirteç istediğinde oturum açmasını gerektirmemelidir. Kullanıcı zaten oturum açmışsa, acquireTokenSilentAsync() tıklama işleyicisinde gösterildiği MultipleAccountModeFragment.java gibi, kullanıcıdaninitializeUI() istemeden uygulamaların belirteç istemesine callGraphApiSilentButton izin verir:

/**
 * Performs acquireToken without interrupting the user.
 *
 * This requires an account object of the account you're obtaining a token for.
 * (can be obtained via getAccount()).
 */
mMultipleAccountApp.acquireTokenSilentAsync(getScopes(),
    accountList.get(accountListSpinner.getSelectedItemPosition()),
    AUTHORITY,
    getAuthSilentCallback());

Hesabı kaldırma

Hesabı kaldırma kodu ve hesap için önbelleğe alınmış belirteçler, hesabı kaldır düğmesinin işleyicisindeki dosyasında initializeUI() yer MultipleAccountModeFragment.java alır. Bir hesabı kaldırabilmeniz için önce ve acquireToken()gibi getAccounts() MSAL yöntemlerinden aldığınız bir hesap nesnesine ihtiyacınız vardır. Hesabı kaldırmak zaman uyumsuz bir işlem olduğundan, onRemoved kullanıcı arabirimini güncelleştirmek için geri çağırma sağlanır.

/**
 * Removes the selected account and cached tokens from this app (or device, if the device is in shared mode).
 **/
mMultipleAccountApp.removeAccount(accountList.get(accountListSpinner.getSelectedItemPosition()),
        new IMultipleAccountPublicClientApplication.RemoveAccountCallback() {
            @Override
            public void onRemoved() {
                ...
                /* Reload account asynchronously to get the up-to-date list. */
                loadAccounts();
            }

            @Override
            public void onError(@NonNull MsalException exception) {
                displayError(exception);
            }
        });

auth_config_multiple_account.json

Bu, birden çok hesap kullanan bir MSAL uygulamasının yapılandırma dosyasıdır.

Çeşitli alanların açıklaması için bkz . Android MSAL yapılandırma dosyasını anlama.

auth_config_single_account.json yapılandırma dosyasından farklı olarak, bunun yerine bu yapılandırma dosyasının "account_mode" : "MULTIPLE""account_mode" : "SINGLE" birden çok hesap uygulaması olması gerekir.

"client_id" , Microsoft'un koruduğu bir uygulama nesnesi kaydını kullanacak şekilde önceden yapılandırılmıştır. "redirect_uri", kod örneğiyle birlikte sağlanan imzalama anahtarını kullanacak şekilde önceden yapılandırılmıştır.

{
  "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "redirect_uri": "msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "account_mode": "MULTIPLE",
  "broker_redirect_uri_registered": true,
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

Yardım ve destek 

Yardıma ihtiyacınız varsa, bir sorunu bildirmek veya destek seçenekleriniz hakkında bilgi edinmek istiyorsanız bkz . Geliştiriciler için yardım ve destek.

Sonraki adımlar

Microsoft kimlik platformu erişim belirtecini alan ve Microsoft Graph API'sini çağırmak için kullanan bir Android uygulaması oluşturduğunuz Android öğreticisine geçin.

Öğretici: Android uygulamasından kullanıcıları oturum açma ve Microsoft Graph'ı çağırma