File konfigurasi Microsoft Authentication Library Android

Artikel
04/10/2024

Microsoft Authentication Library (MSAL) Android dikirim dengan file JSON konfigurasi default yang Anda sesuaikan untuk menentukan perilaku aplikasi klien publik Anda untuk hal-hal seperti otoritas default, otoritas mana yang akan Anda gunakan, dan sebagainya.

Artikel ini akan membantu Anda memahami berbagai pengaturan dalam file konfigurasi, dan cara menentukan file konfigurasi yang akan digunakan di aplikasi berbasis MSAL Anda.

Pengaturan konfigurasi

Pengaturan umum

Properti	Jenis Data	Wajib	Catatan
`client_id`	String	Ya	ID Klien aplikasi Anda dari halaman Pendaftaran aplikasi
`redirect_uri`	String	Ya	URI Pengalihan aplikasi Anda dari halaman Pendaftaran aplikasi
`broker_redirect_uri_registered`	Boolean	No	Nilai yang memungkinkan: `true`, `false`
`authorities`	Daftar<Otoritas>	No	Daftar otoritas yang dibutuhkan aplikasi Anda
`authorization_user_agent`	AuthorizationAgent (enum)	No	Nilai yang memungkinkan: `WEBVIEW`, `BROWSER`
`http`	HttpConfiguration	No	Mengonfigurasi `HttpUrlConnectionconnect_timeout` dan `read_timeout`
`logging`	LoggingConfiguration	No	Menentukan tingkat detail pengelogan. Konfigurasi opsional mencakup: `pii_enabled`, yang mengambil nilai boolean, dan `log_level`, yang mengambil `ERROR`, `WARNING`, `INFO`, atau `VERBOSE`.

client_id

ID klien atau ID aplikasi yang dibuat saat mendaftarkan aplikasi Anda.

redirect_uri

URI pengalihan yang Anda daftarkan ketika mendaftarkan aplikasi Anda. Jika URI pengalihan adalah ke aplikasi broker, baca URI Pengalihan untuk aplikasi klien publik untuk memastikan Anda menggunakan format URI pengalihan yang benar untuk aplikasi broker Anda.

broker_redirect_uri_registered

Jika Anda ingin memakai autentikasi menggunakan broker, properti broker_redirect_uri_registered harus diatur ke true. Dalam skenario autentikasi menggunakan broker, jika aplikasi tidak dalam format yang benar untuk berkomunikasi dengan broker, seperti yang dijelaskan dalam URI Pengalihan untuk aplikasi klien publik, aplikasi memvalidasi URI pengalihan Anda dan memberikan pengecualian ketika dimulai.

otoritas

Daftar otoritas yang dikenal dan dipercaya oleh Anda. Selain pihak berwenang yang tercantum di sini, MSAL juga meminta Microsoft untuk mendapatkan daftar cloud dan otoritas yang diketahui Microsoft. Dalam daftar otoritas ini, tentukan jenis otoritas dan parameter opsional tambahan seperti "audience", yang harus selaras dengan audiens aplikasi Anda berdasarkan pendaftaran aplikasi Anda. Berikut ini adalah contoh daftar otoritas:

// Example AzureAD and Personal Microsoft Account
{
    "type": "AAD",
    "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
    },
    "default": true // Indicates that this is the default to use if not provided as part of the acquireToken call
},
// Example AzureAD My Organization
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMyOrg",
        "tenant_id": "contoso.com" // Provide your specific tenant ID here
    }
},
// Example AzureAD Multiple Organizations
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMultipleOrgs"
    }
},
//Example PersonalMicrosoftAccount
{
    "type": "AAD",
    "audience": {
        "type": "PersonalMicrosoftAccount"
    }
}

Memetakan otoritas Microsoft Entra & audiens ke titik akhir platform identitas Microsoft

Jenis	Audiens	ID Penyewa	Authority_Url	Titik Akhir yang Dihasilkan	Catatan
Microsoft Entra ID	AzureADandPersonalMicrosoftAccount			`https://login.microsoftonline.com/common`	`common` adalah alias penyewa di mana akun tersebut berada. Seperti penyewa Microsoft Entra tertentu atau sistem akun Microsoft.
Microsoft Entra ID	AzureADMyOrg	contoso.com		`https://login.microsoftonline.com/contoso.com`	Hanya akun yang ada di contoso.com Anda yang bisa memperoleh token. Semua domain terverifikasi, atau GUID penyewa, dapat digunakan sebagai ID penyewa.
Microsoft Entra ID	AzureADMultipleOrgs			`https://login.microsoftonline.com/organizations`	Hanya akun Microsoft Entra yang dapat digunakan dengan titik akhir ini. Akun Microsoft dapat merupakan anggota organisasi. Untuk memperoleh token menggunakan akun Microsoft untuk sumber daya dalam organisasi, tentukan penyewa organisasi di mana Anda menginginkan token.
Microsoft Entra ID	PersonalMicrosoftAccount			`https://login.microsoftonline.com/consumers`	Hanya akun Microsoft yang bisa menggunakan titik akhir ini.
B2C			Lihat Titik Akhir yang Dihasilkan	`https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/B2C_1_SISOPolicy/`	Hanya akun yang ada di contoso.onmicrosoft.com penyewa yang dapat memperoleh token. Dalam contoh ini, kebijakan B2C adalah bagian dari jalur URL Otoritas.

Catatan

Validasi otoritas tidak dapat diaktifkan dan dinonaktifkan dalam MSAL. Pihak berwenang diketahui oleh Anda sebagai pengembang, seperti yang ditentukan melalui konfigurasi atau diketahui microsoft melalui metadata. Jika MSAL menerima permintaan token ke otoritas yang tidak dikenal, sebuah MsalClientException jenis UnknownAuthority. Autentikasi menggunakan broker tidak berfungsi untuk Azure AD B2C.

Properti otoritas

Properti	Jenis Data	Wajib	Catatan
`type`	String	Ya	Mencerminkan jenis audiens atau akun target aplikasi Anda. Nilai yang memungkinkan: `AAD`, `B2C`
`audience`	Objek	No	Hanya berlaku saat jenis=`AAD`. Menentukan identitas target aplikasi Anda. Menggunakan nilai dari pendaftaran aplikasi Anda
`authority_url`	String	Ya	Hanya diperlukan saat jenis=`B2C`. Opsional untuk type=`AAD`. Menentukan URL otoritas atau kebijakan yang harus digunakan aplikasi Anda
`default`	Boolean	Ya	`"default":true` tunggal diperlukan ketika salah satu atau beberapa otoritas ditentukan.

Properti Audiens

Properti	Jenis Data	Wajib	Catatan
`type`	String	Ya	Menentukan audiens yang ingin ditargetkan oleh aplikasi Anda. Nilai yang mungkin: `AzureADandPersonalMicrosoftAccount`, `PersonalMicrosoftAccount`, `AzureADMultipleOrgs`, `AzureADMyOrg`
`tenant_id`	String	Ya	Hanya diperlukan saat `"type":"AzureADMyOrg"`. Opsional untuk nilai `type` lainnya. Ini bisa menjadi domain penyewa seperti `contoso.com`, atau ID penyewa seperti `00001111-aaaa-2222-bbbb-3333cccc4444`

authorization_user_agent

Menunjukkan apakah akan menggunakan tampilan web tersemat, atau browser default pada perangkat, saat masuk ke akun atau mengotorisasi akses ke sumber daya.

Nilai yang mungkin:

WEBVIEW: Menggunakan tampilan web tersemat.
BROWSER: Menggunakan browser default pada perangkat.

multiple_clouds_supported

Untuk klien yang mendukung beberapa cloud nasional, tentukan true. Platform identitas Microsoft lalu akan secara otomatis mengalihkan ke cloud nasional yang benar selama otorisasi dan penukaran token. Anda dapat menentukan cloud nasional akun yang masuk dengan memeriksa otoritas yang terkait dengan AuthenticationResult. Perhatikan bahwa AuthenticationResult tidak menyediakan alamat titik akhir khusus cloud nasional sumber daya yang Anda mintai tokennya.

broker_redirect_uri_registered

Boolean yang menunjukkan apakah Anda menggunakan broker Identitas Microsoft yang kompatibel dengan URI pengalihan dalam broker. Atur ke false jika Anda tidak ingin menggunakan broker dalam aplikasi Anda.

Jika Anda menggunakan Microsoft Entra Authority dengan Audiens diatur ke "MicrosoftPersonalAccount", broker tidak akan digunakan.

http

Mengonfigurasi pengaturan global untuk batas waktu HTTP, seperti:

Properti	Jenis Data	Wajib	Catatan
`connect_timeout`	int	No	Waktu dalam milidetik
`read_timeout`	int	No	Waktu dalam milidetik

pencatatan

Pengaturan global berikut ini adalah untuk pengelogan:

Properti	Jenis Data	Wajib	Catatan
`pii_enabled`	Boolean	No	Apakah akan memunculkan data pribadi
`log_level`	string	No	Pesan log mana yang akan di-output. Tingkat log yang didukung mencakup `ERROR`, `WARNING`, `INFO`, dan `VERBOSE`.
`logcat_enabled`	Boolean	No	Apakah output untuk cat log selain antarmuka pengelogan

account_mode

Menentukan berapa banyak akun yang dapat digunakan dalam aplikasi Anda pada satu waktu. Nilai yang mungkin adalah:

MULTIPLE (Default)
SINGLE

Membangun mode PublicClientApplication menggunakan akun yang tidak cocok dengan pengaturan ini akan menghasilkan pengecualian.

Untuk informasi selengkapnya tentang perbedaan antara satu dan beberapa akun, lihat Aplikasi dengan satu dan beberapa akun.

browser_safelist

Daftar izin browser yang kompatibel dengan MSAL. Browser ini secara benar menangani pengalihan ke tujuan kustom. Anda bisa menambahkannya ke daftar ini. Default disediakan dalam konfigurasi default yang ditunjukkan di bawah ini. ``

File konfigurasi MSAL default

Konfigurasi MSAL default yang dikirim dengan MSAL ditunjukkan di bawah ini. Anda dapat melihat versi terbaru di GitHub.

Konfigurasi ini dilengkapi dengan nilai yang Anda berikan. Nilai yang Anda berikan akan mengambil alih default.

{
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      },
      "default": true
    }
  ],
  "authorization_user_agent": "DEFAULT",
  "multiple_clouds_supported": false,
  "broker_redirect_uri_registered": false,
  "http": {
    "connect_timeout": 10000,
    "read_timeout": 30000
  },
  "logging": {
    "pii_enabled": false,
    "log_level": "WARNING",
    "logcat_enabled": false
  },
  "shared_device_mode_supported": false,
  "account_mode": "MULTIPLE",
  "browser_safelist": [
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "7fmduHKTdHHrlMvldlEqAIlSfii1tl35bxj1OXN5Ve8c4lU6URVu4xtSHc3BVZxS6WWJnxMDhIfQN0N0K2NDJg=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "45"
    },
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "7fmduHKTdHHrlMvldlEqAIlSfii1tl35bxj1OXN5Ve8c4lU6URVu4xtSHc3BVZxS6WWJnxMDhIfQN0N0K2NDJg=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "2gCe6pR_AO_Q2Vu8Iep-4AsiKNnUHQxu0FaDHO_qa178GByKybdT_BuE8_dYk99G5Uvx_gdONXAOO2EaXidpVQ=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "2gCe6pR_AO_Q2Vu8Iep-4AsiKNnUHQxu0FaDHO_qa178GByKybdT_BuE8_dYk99G5Uvx_gdONXAOO2EaXidpVQ=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "57"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "ABi2fbt8vkzj7SJ8aD5jc4xJFTDFntdkMrYXL3itsvqY1QIw-dZozdop5rgKNxjbrQAd5nntAGpgh9w84O1Xgg=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "4.0"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "ABi2fbt8vkzj7SJ8aD5jc4xJFTDFntdkMrYXL3itsvqY1QIw-dZozdop5rgKNxjbrQAd5nntAGpgh9w84O1Xgg=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.cloudmosa.puffinFree",
      "browser_signature_hashes": [
        "1WqG8SoK2WvE4NTYgr2550TRhjhxT-7DWxu6C_o6GrOLK6xzG67Hq7GCGDjkAFRCOChlo2XUUglLRAYu3Mn8Ag=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.duckduckgo.mobile.android",
      "browser_signature_hashes": [
        "S5Av4cfEycCvIvKPpKGjyCuAE5gZ8y60-knFfGkAEIZWPr9lU5kA7iOAlSZxaJei08s0ruDvuEzFYlmH-jAi4Q=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.explore.web.browser",
      "browser_signature_hashes": [
        "BzDzBVSAwah8f_A0MYJCPOkt0eb7WcIEw6Udn7VLcizjoU3wxAzVisCm6bW7uTs4WpMfBEJYf0nDgzTYvYHCag=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.ksmobile.cb",
      "browser_signature_hashes": [
        "lFDYx1Rwc7_XUn4KlfQk2klXLufRyuGHLa3a7rNjqQMkMaxZueQfxukVTvA7yKKp3Md3XUeeDSWGIZcRy7nouw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.microsoft.emmx",
      "browser_signature_hashes": [
        "Ivy-Rk6ztai_IudfbyUrSHugzRqAtHWslFvHT0PTvLMsEKLUIgv7ZZbVxygWy_M5mOPpfjZrd3vOx3t-cA6fVQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.browser",
      "browser_signature_hashes": [
        "FIJ3IIeqB7V0qHpRNEpYNkhEGA_eJaf7ntca-Oa_6Feev3UkgnpguTNV31JdAmpEFPGNPo0RHqdlU0k-3jWJWw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.mini.native",
      "browser_signature_hashes": [
        "TOTyHs086iGIEdxrX_24aAewTZxV7Wbi6niS2ZrpPhLkjuZPAh1c3NQ_U4Lx1KdgyhQE4BiS36MIfP6LbmmUYQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "mobi.mgeek.TunnyBrowser",
      "browser_signature_hashes": [
        "RMVoXuK1sfJZuGZ8onG1yhMc-sKiAV2NiB_GZfdNlN8XJ78XEE2wPM6LnQiyltF25GkHiPN2iKQiGwaO2bkyyQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "org.mozilla.focus",
      "browser_signature_hashes": [
        "L72dT-stFqomSY7sYySrgBJ3VYKbipMZapmUXfTZNqOzN_dekT5wdBACJkpz0C6P0yx5EmZ5IciI93Q0hq0oYA=="
      ],
      "browser_use_customTab" : false
    }
  ]
}

Contoh konfigurasi dasar

Contoh berikut mengilustrasikan konfigurasi dasar yang menentukan ID klien, URI pengalihan, apakah pengalihan broker terdaftar, serta daftar otoritas.

{
  "client_id" : "00001111-aaaa-2222-bbbb-3333cccc4444",
  "redirect_uri" : "msauth://com.microsoft.identity.client.sample.local/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "broker_redirect_uri_registered": true,
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      }
      "default": true
    }
  ]
}

Cara menggunakan file konfigurasi

Membuat file konfigurasi. Kami menyarankan agar Anda membuat file konfigurasi kustom di res/raw/auth_config.json. Tetapi Anda bisa menempatkannya di mana saja yang Anda inginkan.

Memberitahu MSAL tempat untuk mencari konfigurasi Anda saat Anda membangun PublicClientApplication. Contohnya:

//On Worker Thread
IMultipleAccountPublicClientApplication sampleApp = null; 
sampleApp = new PublicClientApplication.createMultipleAccountPublicClientApplication(getApplicationContext(), R.raw.auth_config);

File konfigurasi Microsoft Authentication Library Android

Pengaturan konfigurasi

Pengaturan umum

client_id

redirect_uri

broker_redirect_uri_registered

otoritas

Memetakan otoritas Microsoft Entra & audiens ke titik akhir platform identitas Microsoft

Properti otoritas

Properti Audiens

authorization_user_agent

multiple_clouds_supported

broker_redirect_uri_registered

http

pencatatan

account_mode

browser_safelist

File konfigurasi MSAL default

Contoh konfigurasi dasar

Cara menggunakan file konfigurasi

Sumber Daya Tambahan: