Hızlı Başlangıç: Android uygulamasından kullanıcıların oturumunu açma ve Microsoft Graph'ı arama
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.
uygulamalar, Microsoft kimlik platformu uygulamanıza belirteç sağlayabilmesi için Microsoft Entra Id'deki bir uygulama nesnesiyle temsil edilmelidir.
Önkoşullar
- Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
- Android Studio
- Android 16+
Örnek nasıl çalışır?
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.
Örnek uygulamayı alma
Örnek uygulamayı kaydetme
İpucu
Bu makaledeki adımlar, başladığınız portala göre biraz değişiklik gösterebilir.
Microsoft Entra yönetim merkezinde en azından Uygulama Geliştiricisi olarak oturum açın.
Birden çok kiracıya erişiminiz varsa, Dizinler + abonelikler menüsünden uygulamayı kaydetmek istediğiniz kiracıya geçmek için üst menüdeki Ayarlar simgesinikullanın.
Kimlik>Uygulamaları'na> göz atın Uygulama kayıtları.
Yeni kayıt öğesini seçin.
Uygulamanız için bir Ad girin. Uygulamanızın kullanıcıları bu adı görebilir ve daha sonra değiştirebilirsiniz.
Desteklenen hesap türleri için herhangi bir kuruluş dizinindeki Hesaplar (Herhangi bir Microsoft Entra dizini - Çok Kiracılı) ve kişisel Microsoft hesapları (skype, Xbox gibi) seçeneğini belirleyin. Farklı hesap türleri hakkında bilgi için Bana yardım et seçeneğini belirleyin.
Kaydet'i seçin.
Yönet'in altında Kimlik Doğrulaması>Platform>ekle Android'i seçin.
Yukarıda indirdiğiniz örnek türüne göre projenizin Paket Adını girin.
- Java örneği -
com.azuresamples.msalandroidapp
- Kotlin örneği -
com.azuresamples.msalandroidkotlinapp
- Java örneği -
Android uygulamanızı yapılandırın bölmesinin İmza karması bölümünde Geliştirme İmza Karması Oluşturma'yı seçin ve KeyTool komutunu komut satırınıza kopyalayın.
- KeyTool.exe, Java Geliştirme Seti'nin (JDK) bir parçası olarak yüklenir. KeyTool komutunu yürütmek için OpenSSL aracını da yüklemeniz gerekir. Daha fazla bilgi için bkz . Anahtar oluşturmayla ilgili Android belgeleri.
KeyTool tarafından oluşturulan İmza karması girin.
Yapılandır'ıseçin ve Daha sonra uygulamanızı yapılandırırken girebilmeniz için Android yapılandırma bölmesinde görüntülenen MSAL Yapılandırmasını kaydedin.
Bitti'yi seçin.
Örnek uygulamayı yapılandırma
Android Studio'nun proje bölmesinde app\src\main\res adresine gidin.
Res'e sağ tıklayın ve Yeni Dizin'i> seçin. Yeni dizin adı olarak girin
raw
ve Tamam'ı seçin.App>src>main>res>raw'da adlı
auth_config_single_account.json
JSON dosyasına gidin ve daha önce kaydettiğiniz MSAL Yapılandırmasını yapıştırın.Yeniden yönlendirme URI'sinin altına yapıştırın:
"account_mode" : "SINGLE",
Yapılandırma dosyanız şu örneğe benzemelidir:
{ "client_id": "00001111-aaaa-bbbb-3333-cccc4444", "authorization_user_agent": "WEBVIEW", "redirect_uri": "msauth://com.azuresamples.msalandroidapp/00001111%cccc4444%3D", "broker_redirect_uri_registered": true, "account_mode": "SINGLE", "authorities": [ { "type": "AAD", "audience": { "type": "AzureADandPersonalMicrosoftAccount", "tenant_id": "common" } } ] }
Bu öğreticide yalnızca Tek Hesap modunda bir uygulamanın nasıl yapılandırılması gösterilmektedir; daha fazla bilgi için bkz . tek ve birden çok hesap modu ve uygulamanızı yapılandırma
Ö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.
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:
- 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.
- 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.
Daha Fazla Bilgi
Bu hızlı başlangıç hakkında daha fazla bilgi almak için şu bölümleri okuyun.
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.java
yö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.java
initializeUI()
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.java
loadAccount()
. 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.java
tanı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 file
yapı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.java
loadAccounts()
. 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.java
callGraphApiInteractiveButton
/**
* 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.