Alur kode otorisasi OAuth 2.0 di Azure Active Directory B2C

Artikel
11/06/2023

Anda dapat menggunakan pemberian kode otorisasi OAuth 2.0 di aplikasi yang dipasang pada perangkat untuk mendapatkan akses ke sumber daya yang dilindungi, seperti API web. Dengan menggunakan implementasi Azure Active Directory B2C (AAD B2C) OAuth 2.0, Anda dapat menambahkan tugas pendaftaran, rincian masuk, dan manajemen identitas lainnya ke aplikasi satu halaman, ponsel, dan desktop Anda. Artikel ini tidak bergantung pada bahasa komputer. Artikel ini menjelaskan cara mengirim dan menerima pesan HTTP tanpa menggunakan pustaka sumber terbuka apa pun. Jika memungkinkan, kami sarankan Anda menggunakan Pustaka Autentikasi Microsoft (MSAL) yang didukung. Lihat sampel aplikasi yang menggunakan MSAL.

Alur kode otorisasi OAuth 2.0 dijelaskan dalam bagian 4.1 dari spesifikasi OAuth 2.0. Anda dapat menggunakannya untuk autentikasi dan otorisasi di sebagian besar jenis aplikasi, termasuk aplikasi web, aplikasi satu halaman, dan aplikasi yang dipasang secara asli. Anda dapat menggunakan alur kode otorisasi OAuth 2.0 untuk memperoleh token akses dan token refresh dengan aman untuk aplikasi Anda, yang dapat digunakan untuk mengakses sumber daya yang diamankan oleh server otorisasi. Token refresh memungkinkan klien untuk memperoleh token akses (dan refresh) baru setelah token akses berakhir, biasanya setelah satu jam.

Artikel ini berfokus pada alur kode otorisasi OAuth 2.0 klien publik. Klien publik adalah aplikasi klien apa pun yang tidak dapat dipercaya untuk mempertahankan integritas kata sandi rahasia dengan aman. Ini termasuk aplikasi satu halaman, aplikasi ponsel, aplikasi desktop, dan pada dasarnya aplikasi apa pun yang tidak berjalan di server.

Catatan

Untuk menambahkan manajemen identitas ke aplikasi web dengan menggunakan AAD B2C, gunakan OpenID Connect sebagai ganti dari OAuth 2.0.

AAD B2C memperluas alur OAuth 2.0 standar untuk melakukan lebih dari sekadar autentikasi dan otorisasi sederhana. Ini memperkenalkan alur pengguna. Dengan alur pengguna, Anda dapat menggunakan OAuth 2.0 untuk menambahkan pengalaman pengguna ke aplikasi Anda, seperti pendaftaran, rincian masuk, dan manajemen profil. Penyedia identitas yang menggunakan protokol OAuth 2.0 termasuk Amazon, ID Microsoft Entra, Facebook, GitHub, Google, dan LinkedIn.

Untuk mencoba permintaan HTTP di artikel ini:

Ganti {tenant} dengan nama penyewa AAD B2C Anda.
Ganti 90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 dengan ID aplikasi yang sebelumnya telah Anda daftarkan di penyewa AAD B2C Anda.
Ganti {policy} dengan nama kebijakan yang telah Anda buat di penyewa Anda, misalnya b2c_1_sign_in.

Penyiapan URI pengalihan diperlukan untuk aplikasi satu halaman

Alur kode otorisasi untuk aplikasi satu halaman memerlukan beberapa penyiapan tambahan. Ikuti instruksi untuk membuat aplikasi satu halaman untuk menandai dengan benar URI pengalihan Anda sebagai diaktifkan untuk CORS. Untuk memperbarui URI pengalihan yang ada untuk mengaktifkan CORS, Anda dapat mengeklik permintaan migrasi di bagian "Web" pada tab Autentikasi pada Pendaftaran aplikasi. Atau, Anda dapat membuka Editor manifes pendaftaran aplikasi dan mengatur bidang type untuk URI pengalihan Anda ke spa di bagian replyUrlsWithType.

Jenis pengalihan spa kompatibel mundur dengan alur implisit. Aplikasi yang saat ini menggunakan alur implisit untuk mendapatkan token dapat berpindah ke jenis URI pengalihan spa tanpa masalah dan terus menggunakan alur implisit.

1. Mendapatkan kode otorisasi

Alur kode otorisasi dimulai dengan klien mengarahkan pengguna ke titik akhir /authorize. Ini adalah bagian interaktif dari alur, yang penggunanya mengambil tindakan. Dalam permintaan ini, klien menunjukkan dalam parameter scope izin yang dibutuhkannya dari pengguna. Contoh berikut (dengan jeda baris untuk keterbacaan) menunjukkan cara memperoleh kode otorisasi. Jika Anda menguji permintaan GET HTTP ini, gunakan browser Anda.

GET https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/authorize?
client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&response_type=code
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&response_mode=query
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6%20offline_access%20https://{tenant-name}/{app-id-uri}/{scope}
&state=arbitrary_data_you_can_receive_in_the_response
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Parameter	Diperlukan?	Deskripsi
{penyewa}	Diperlukan	Nama penyewa Azure AD B2C Anda
{kebijakan}	Diperlukan	Alur pengguna yang akan dijalankan. Tentukan nama alur pengguna yang telah Anda buat di penyewa Azure AD B2C Anda. Misalnya: `b2c_1_sign_in`, `b2c_1_sign_up`, atau `b2c_1_edit_profile`.
client_id	Diperlukan	ID aplikasi yang ditetapkan ke aplikasi Anda di portal Microsoft Azure.
response_type	Diperlukan	Jenis respons, yang harus menyertakan `code` untuk alur kode otorisasi. Anda dapat menerima token ID jika menyertakannya dalam jenis respons, seperti `code+id_token`, dan dalam hal ini, cakupannya harus menyertakan `openid`.
redirect_uri	Diperlukan	URI pengalihan aplikasi Anda, yang respons autentikasinya dapat dikirim dan diterima oleh aplikasi Anda. Ini harus sama persis dengan salah satu URI pengalihan yang Anda daftarkan di portal, kecuali hal itu memang harus dikodekan dengan URL.
cakupan	Diperlukan	Daftar cakupan yang dipisahkan spasi. cakupan `openid` menunjukkan izin untuk masuk ke pengguna dan mendapatkan data tentang pengguna dalam bentuk token ID. Cakupan `offline_access` bersifat opsional untuk aplikasi web. Ini menunjukkan bahwa aplikasi Anda akan memerlukan token refresh untuk akses yang diperluas ke sumber daya. ID klien menunjukkan bahwa token yang dikeluarkan dimaksudkan untuk digunakan oleh klien terdaftar Azure AD B2C. `https://{tenant-name}/{app-id-uri}/{scope}` menunjukkan izin untuk sumber daya yang dilindungi, seperti API web. Untuk informasi selengkapnya, lihat Meminta token akses.
mode_response	Disarankan	Metode yang digunakan untuk mengirim kode otorisasi yang dihasilkan kembali ke aplikasi Anda. Bisa berupa `query`, `form_post`, atau `fragment`.
status	Disarankan	Nilai yang disertakan dalam permintaan yang dapat menjadi string konten apa pun yang ingin Anda gunakan. Biasanya, nilai unik yang dihasilkan secara acak digunakan, untuk mencegah serangan pemalsuan permintaan antar situs. Status ini juga digunakan untuk mengodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi terjadi. Misalnya, halaman tempat pengguna berada, atau alur pengguna yang sedang dijalankan.
permintaan	Opsional	Jenis interaksi pengguna yang diperlukan. Saat ini, satu-satunya nilai yang valid adalah `login`, yang memaksa pengguna untuk memasukkan informasi masuk mereka pada permintaan tersebut. Akses menyeluruh tidak akan berpengaruh.
code_challenge	disarankan/diperlukan	Digunakan untuk mengamankan pemberian kode otorisasi melalui Proof Key for Code Exchange (PKCE). Diperlukan jika `code_challenge_method` disertakan. Anda perlu menambahkan logika dalam aplikasi Anda untuk menghasilkan `code_verifier` dan `code_challenge`. `code_challenge` adalah hash SHA256 yang dikodekan URL Base64 dari `code_verifier`. Anda menyimpannya `code_verifier` di aplikasi Anda untuk digunakan nanti, dan kirim `code_challenge` bersama dengan permintaan otorisasi. Untuk informasi selengkapnya, lihat PKCE RFC. Ini sekarang disarankan untuk semua jenis aplikasi - aplikasi asli, SPA, dan klien rahasia seperti aplikasi web.
`code_challenge_method`	disarankan/diperlukan	Metode yang digunakan untuk mengodekan `code_verifier` untuk parameter `code_challenge`. Ini HARUS menjadi `S256`, tetapi spesifikasi mengizinkan penggunaan `plain` jika karena alasan tertentu klien tidak dapat mendukung SHA256. Jika Anda mengecualikan `code_challenge_method`, tetapi masih menyertakan `code_challenge`, `code_challenge` diasumsikan sebagai teks biasa. Platform identitas Microsoft mendukung `plain` dan `S256`. Untuk informasi selengkapnya, lihat PKCE RFC. Diperlukan untuk aplikasi satu halaman yang menggunakan alur kode otorisasi.
login_hint	Tidak	Dapat digunakan untuk mengisi lebih dulu bidang nama masuk di halaman masuk. Untuk informasi selengkapnya, lihat Pra-populasi nama masuk.
domain_hint	Tidak	Memberikan petunjuk kepada Azure AD B2C tentang penyedia identitas sosial yang harus digunakan untuk masuk. Jika nilai yang valid disertakan, pengguna langsung masuk ke halaman masuk penyedia identitas. Untuk informasi selengkapnya, lihat Mengalihkan rincian masuk ke penyedia sosial.
Custom parameters	Tidak	Parameter kustom yang dapat digunakan dengan kebijakan kustom. Misalnya, URI konten halaman kustom dinamis, atau penyelesai klaim nilai kunci.

Pada titik ini, pengguna diminta untuk menyelesaikan alur kerja alur pengguna. Pengguna mungkin harus memasukkan nama pengguna dan kata sandi mereka, masuk dengan identitas sosial, mendaftar ke direktori, atau beberapa langkah lainnya. Tindakan pengguna bergantung pada bagaimana alur pengguna ditentukan.

Setelah pengguna menyelesaikan alur pengguna, ID Microsoft Entra mengembalikan respons ke aplikasi Anda pada nilai yang Anda gunakan untuk redirect_uri. Ini menggunakan metode yang ditentukan dalam parameter response_mode. Responsnya persis sama untuk setiap skenario tindakan pengguna, tidak dipengaruhi oleh alur pengguna yang dijalankan.

Respons sukses yang menggunakan response_mode=query terlihat seperti ini:

GET urn:ietf:wg:oauth:2.0:oob?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...        // the authorization_code, truncated
&state=arbitrary_data_you_can_receive_in_the_response                // the value provided in the request

Parameter	Deskripsi
kode	Kode otorisasi yang diminta aplikasi. Aplikasi dapat menggunakan kode otorisasi untuk meminta token akses untuk sumber daya target. Kode otorisasi berumur sangat pendek. Biasanya, kode otorisasi kedaluwarsa setelah sekitar 10 menit.
status	Lihat deskripsi lengkap dalam tabel di bagian sebelumnya. Jika parameter `state` disertakan dalam permintaan, nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai `state` dalam permintaan dan respons adalah identik.

Respons kesalahan juga dapat dikirim ke URI pengalihan sehingga aplikasi dapat menanganinya dengan tepat:

GET urn:ietf:wg:oauth:2.0:oob?
error=access_denied
&error_description=The+user+has+cancelled+entering+self-asserted+information
&state=arbitrary_data_you_can_receive_in_the_response

Parameter	Deskripsi
kesalahan	String kode galat yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi. Anda juga dapat menggunakan string untuk merespons kesalahan.
Deskripsi kesalahan/error	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi.
status	Lihat deskripsi lengkap dalam tabel sebelumnya. Jika parameter `state` disertakan dalam permintaan, nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai `state` dalam permintaan dan respons adalah identik.

2. Mendapatkan token akses

Setelah mendapatkan kode otorisasi, Anda dapat menukarkan code untuk token ke sumber daya yang dimaksud dengan mengirim permintaan KIRIM ke titik akhir /token. Di AAD B2C, Anda dapat meminta token akses untuk API lain seperti biasa dengan menentukan cakupannya dalam permintaan.

Anda juga dapat meminta token akses untuk API Web ujung-belakang aplikasi Anda sendiri dengan konvensi menggunakan ID klien aplikasi sebagai cakupan yang diminta (yang akan menghasilkan token akses dengan ID klien tersebut sebagai "audiens"):

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong

Parameter	Diperlukan?	Deskripsi
{penyewa}	Diperlukan	Nama penyewa Azure AD B2C Anda
{kebijakan}	Diperlukan	Alur pengguna yang digunakan untuk memperoleh kode otorisasi. Anda tidak dapat menggunakan alur pengguna yang berbeda dalam permintaan ini.
client_id	Diperlukan	ID aplikasi yang ditetapkan ke aplikasi Anda di portal Microsoft Azure.
client_secret	Ya, di Aplikasi Web	Rahasia aplikasi yang dihasilkan di portal Microsoft Azure. Rahasia klien digunakan dalam alur ini untuk skenario Aplikasi Web, yang kliennya dapat menyimpan rahasia klien dengan aman. Untuk skenario Aplikasi Asli (klien umum), rahasia klien tidak dapat disimpan dengan aman, oleh karena itu tidak digunakan pada panggilan ini. Jika menggunakan rahasia klien, harap ubah secara berkala.
grant_type	Diperlukan	Jenis pemberian. Untuk alur kode otorisasi, jenis pemberian harus `authorization_code`.
cakupan	Disarankan	Daftar cakupan yang dipisahkan spasi. Nilai cakupan tunggal menunjukkan untuk Microsoft Entra ID kedua izin yang diminta. Menggunakan ID klien sebagai cakupan menunjukkan bahwa aplikasi Anda membutuhkan token akses yang dapat digunakan terhadap layanan atau API web Anda sendiri, yang diwakili oleh ID klien yang sama. Cakupan `offline_access` menunjukkan bahwa aplikasi Anda memerlukan token refresh untuk akses jangka panjang ke sumber daya. Anda juga dapat menggunakan cakupan `openid` untuk meminta token ID dari AAD B2C.
kode	Diperlukan	Kode otorisasi yang Anda peroleh dari titik akhir `/authorize`.
redirect_uri	Diperlukan	URI pengalihan aplikasi tempat Anda menerima kode otorisasi.
code_verifier	Disarankan	`code_verifier` yang sama yang digunakan untuk mendapatkan authorization_code. Diperlukan jika PKCE digunakan dalam permintaan pemberian kode otorisasi. Untuk informasi selengkapnya, lihat PKCE RFC.

Jika Anda menguji permintaan HTTP POST ini, Anda dapat menggunakan klien HTTP apa pun seperti Microsoft PowerShell atau Postman.

Respons token yang sukses terlihat seperti ini:

{
    "not_before": "1442340812",
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
    "expires_in": "3600",
    "refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}

Parameter	Deskripsi
not_before	Waktu di mana token dianggap valid, dalam masa waktu.
token_type	Nilai jenis token. Satu-satunya jenis yang didukung ID Microsoft Entra adalah Pembawa.
access_token	JSON Web Token (JWT) yang ditandatangani yang Anda minta.
cakupan	Cakupan yang berlaku untuk token. Anda juga dapat menggunakan cakupan untuk cache token untuk digunakan nanti.
expires_in	Masa berlaku token valid (dalam detik).
refresh_token	Token refresh OAuth 2.0. Aplikasi dapat menggunakan token ini untuk memperoleh token tambahan setelah token saat ini kedaluwarsa. Token refresh berumur panjang. Anda dapat menggunakannya untuk mempertahankan akses ke sumber daya untuk jangka waktu yang lama. Untuk informasi selengkapnya, lihat referensi token AAD B2C.

Respons kesalahan terlihat seperti ini:

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}

Parameter	Deskripsi
kesalahan	String kode galat yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi. Anda juga dapat menggunakan string untuk merespons kesalahan.
Deskripsi kesalahan/error	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi.

3. Menggunakan token

Setelah berhasil memperoleh token akses, Anda dapat menggunakan token dalam permintaan ke API web ujung-belakang Anda dengan menyertakannya di header Authorization:

GET /tasks
Host: mytaskwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

4. Me-refresh token

Token akses dan token ID berumur pendek. Setelah kedaluwarsa, Anda harus me-refresh token untuk terus mengakses sumber daya. Saat Anda merefresh token akses, Azure AD B2C mengembalikan token baru. Token akses yang di-refresh akan diperbarui nbf (tidak sebelumnya), iat (dikeluarkan pada), dan exp (kedaluwarsa) nilai klaim. Semua nilai klaim lainnya akan sama dengan token akses yang dikeluarkan awalnya.

Untuk me-refresh token, kirimkan permintaan POST lainnya ke titik akhir /token. Kali ini, berikan refresh_tokensebagai ganti dari code:

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob

Parameter	Diperlukan?	Deskripsi
{penyewa}	Diperlukan	Nama penyewa Azure AD B2C Anda
{kebijakan}	Diperlukan	Alur pengguna yang digunakan untuk memperoleh token refresh asli. Anda tidak dapat menggunakan alur pengguna yang berbeda dalam permintaan ini.
client_id	Diperlukan	ID aplikasi yang ditetapkan ke aplikasi Anda di portal Microsoft Azure.
client_secret	Ya, di Aplikasi Web	Rahasia aplikasi yang dihasilkan di portal Microsoft Azure. Rahasia klien digunakan dalam alur ini untuk skenario Aplikasi Web, yang kliennya dapat menyimpan rahasia klien dengan aman. Untuk skenario Aplikasi Asli (klien umum), rahasia klien tidak dapat disimpan dengan aman, oleh karena itu tidak digunakan pada panggilan ini. Jika menggunakan rahasia klien, harap ubah secara berkala.
grant_type	Diperlukan	Jenis pemberian. Untuk alur kode otorisasi, jenis pemberian harus `refresh_token`.
cakupan	Disarankan	Daftar cakupan yang dipisahkan spasi. Satu nilai cakupan menunjukkan untuk Microsoft Entra ID kedua izin yang diminta. Menggunakan ID klien sebagai cakupan menunjukkan bahwa aplikasi Anda membutuhkan token akses yang dapat digunakan terhadap layanan atau API web Anda sendiri, yang diwakili oleh ID klien yang sama. Cakupan `offline_access` menunjukkan bahwa aplikasi Anda memerlukan token refresh untuk akses jangka panjang ke sumber daya. Anda juga dapat menggunakan cakupan `openid` untuk meminta token ID dari AAD B2C.
redirect_uri	Opsional	URI pengalihan aplikasi tempat Anda menerima kode otorisasi.
refresh_token	Diperlukan	Token refresh asli yang anda peroleh di bagian kedua alur.