Referensi API autentikasi asli
Berlaku untuk: 
Penyewa Tenaga Kerja Penyewa 
eksternal (pelajari lebih lanjut)
Autentikasi asli Microsoft Entra memungkinkan Anda menghosting antarmuka pengguna aplikasi Anda di aplikasi klien alih-alih mendelegasikan autentikasi ke browser, menghasilkan pengalaman autentikasi terintegrasi asli. Sebagai pengembang, Anda memiliki kontrol penuh atas tampilan dan nuansa antarmuka masuk.
Artikel referensi API ini menjelaskan detail yang diperlukan hanya saat Anda membuat permintaan HTTP mentah secara manual untuk menjalankan alur. Namun, kami tidak merekomendasikan pendekatan ini. Jadi, jika memungkinkan, gunakan SDK autentikasi yang dibangun dan didukung Microsoft. Untuk informasi selengkapnya tentang cara menggunakan SDK, lihat Tutorial: Menyiapkan aplikasi seluler Android Anda untuk autentikasi asli dan Tutorial: Menyiapkan aplikasi seluler iOS Anda untuk autentikasi asli.
Ketika panggilan ke titik akhir API berhasil, Anda menerima token ID untuk identifikasi pengguna dan token akses untuk memanggil API yang dilindungi. Semua respons dari API berada dalam format JSON.
API autentikasi asli Microsoft Entra mendukung pendaftaran dan masuk untuk dua metode autentikasi:
Email dengan kata sandi, yang mendukung pendaftaran dan masuk dengan email dan kata sandi, dan pengaturan ulang kata sandi mandiri (SSPR).
Kode akses satu kali email, yang mendukung pendaftaran dan masuk dengan kode akses satu kali email.
Catatan
Saat ini, titik akhir API autentikasi asli tidak mendukung Berbagi Sumber Daya Lintas Asal (CORS).
Prasyarat
MICROSOFT Entra External ID untuk penyewa pelanggan. Jika Anda belum memilikinya, daftar untuk uji coba gratis.
Jika Anda belum melakukannya, Daftarkan aplikasi di pusat admin Microsoft Entra. Pastikan Anda memberikan izin yang didelegasikan, dan mengaktifkan klien publik dan alur autentikasi asli.
Jika Anda belum melakukannya, Buat alur pengguna di pusat admin Microsoft Entra. Saat Anda membuat alur pengguna, perhatikan atribut pengguna yang Anda konfigurasi diperlukan karena atribut ini adalah atribut yang diharapkan Microsoft Entra untuk dikirimkan oleh aplikasi Anda. Di bawah Penyedia identitas, pilih Opsi kode akses satu kali email.
Untuk alur masuk, daftarkan pengguna pelanggan, yang Anda gunakan untuk menguji API masuk. Atau, Anda bisa mendapatkan pengguna uji ini setelah menjalankan alur pendaftaran.
Untuk alur SSPR, aktifkan pengaturan ulang kata sandi layanan mandiri untuk pengguna pelanggan di penyewa pelanggan. SSPR tersedia untuk pengguna pelanggan yang menggunakan email dengan metode autentikasi kata sandi.
Token kelanjutan
Setiap kali Anda memanggil titik akhir di salah satu alur, masuk, pendaftaran, atau SSPR, titik akhir menyertakan token kelanjutan dalam responsnya. Token kelanjutan adalah pengidentifikasi unik yang digunakan Microsoft Entra ID untuk mempertahankan status antara panggilan ke titik akhir yang berbeda dalam alur yang sama. Anda harus menyertakan token ini dalam permintaan berikutnya dalam alur yang sama.
Setiap token kelanjutan berlaku untuk periode tertentu dan hanya dapat digunakan untuk permintaan berikutnya dalam alur yang sama.
Referensi API pendaftaran
Untuk menyelesaikan alur pendaftaran pengguna untuk salah satu metode autentikasi, aplikasi Anda berinteraksi dengan empat titik akhir, /signup/v1.0/start, , /signup/v1.0/challenge/signup/v1.0/continue, dan /token.
Titik akhir API pendaftaran
| Titik akhir | Deskripsi |
|---|---|
/signup/v1.0/start |
Titik akhir ini memulai alur pendaftaran. Anda melewati ID aplikasi yang valid, nama pengguna baru, dan jenis tantangan, lalu Anda mendapatkan kembali token kelanjutan baru. Titik akhir dapat mengembalikan respons untuk menunjukkan kepada aplikasi untuk menggunakan alur autentikasi web jika metode autentikasi yang dipilih aplikasi tidak didukung oleh Microsoft Entra. |
/signup/v1.0/challenge |
Aplikasi Anda memanggil titik akhir ini dengan daftar jenis tantangan yang didukung oleh Microsoft Entra. Microsoft Entra kemudian memilih salah satu metode autentikasi yang didukung untuk diautentikasi pengguna. |
/signup/v1.0/continue |
Titik akhir ini membantu melanjutkan alur untuk membuat akun pengguna atau mengganggu alur karena persyaratan yang hilang seperti persyaratan kebijakan kata sandi atau format atribut yang salah. Titik akhir ini menghasilkan token kelanjutan, lalu mengembalikannya ke aplikasi. Titik akhir dapat mengembalikan respons untuk menunjukkan kepada aplikasi untuk menggunakan alur autentikasi berbasis web jika aplikasi bukan metode autentikasi yang dipilih oleh Microsoft Entra. |
/token |
Aplikasi memanggil titik akhir ini untuk akhirnya meminta token keamanan. Aplikasi ini perlu menyertakan token kelanjutan yang diperolehnya dari panggilan terakhir yang berhasil ke /signup/v1.0/continue titik akhir. |
Jenis tantangan pendaftaran
API memungkinkan aplikasi klien untuk mengiklankan metode autentikasi yang didukungnya, saat melakukan panggilan ke Microsoft Entra. Untuk melakukannya, aplikasi menggunakan challenge_type parameter dalam permintaan aplikasi. Parameter ini menyimpan nilai yang telah ditentukan sebelumnya, yang mewakili metode autentikasi yang berbeda.
Pelajari selengkapnya tentang jenis tantangan dalam jenis tantangan autentikasi asli. Artikel ini menjelaskan nilai jenis tantangan yang harus Anda gunakan untuk metode autentikasi.
Detail protokol alur pendaftaran
Diagram urutan menunjukkan alur proses pendaftaran.
Diagram ini menunjukkan bahwa aplikasi mengumpulkan nama pengguna (email), kata sandi (untuk email dengan metode autentikasi kata sandi), dan atribut dari pengguna pada waktu yang berbeda (dan mungkin di layar terpisah). Namun, Anda dapat merancang aplikasi untuk mengumpulkan nama pengguna (email), kata sandi, dan semua nilai atribut yang diperlukan, dan opsional di layar yang sama, lalu mengirimkan semuanya melalui /signup/v1.0/start titik akhir. Dalam hal ini, aplikasi tidak perlu melakukan panggilan dan menangani respons untuk langkah-langkah opsional.
Langkah 1: Minta untuk memulai alur pendaftaran
Alur pendaftaran dimulai dengan aplikasi membuat permintaan POST ke /signup/v1.0/start titik akhir untuk memulai alur pendaftaran.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
Contoh 1:
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com
Contoh 2 (sertakan atribut pengguna dan kata sandi dalam permintaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
username |
Ya | Email pengguna pelanggan yang ingin mereka daftarkan, seperti contoso-consumer@contoso.com. |
challenge_type |
Ya | Daftar string jenis tantangan otorisasi yang dipisahkan spasi yang didukung aplikasi seperti oob password redirect. Daftar harus selalu menyertakan redirect jenis tantangan. Nilai diharapkan untuk oob redirect atau oob password redirect untuk email dengan metode autentikasi kata sandi. |
password |
No | Nilai kata sandi yang dikumpulkan aplikasi dari pengguna pelanggan. Anda dapat mengirimkan kata sandi pengguna melalui /signup/v1.0/start atau yang lebih baru di /signup/v1.0/continue titik akhir. Ganti {secure_password} dengan nilai kata sandi yang dikumpulkan aplikasi dari pengguna pelanggan. Anda bertanggung jawab untuk mengonfirmasi bahwa pengguna mengetahui kata sandi yang ingin mereka gunakan dengan menyediakan bidang konfirmasi kata sandi di UI aplikasi. Anda juga harus memastikan bahwa pengguna mengetahui apa yang merupakan kata sandi yang kuat sesuai kebijakan organisasi Anda. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. Parameter ini hanya berlaku untuk email dengan metode autentikasi kata sandi. |
attributes |
No | Pengguna mengaitkan nilai yang dikumpulkan aplikasi dari pengguna pelanggan. Nilainya adalah string, tetapi diformat sebagai objek JSON yang nilai kuncinya adalah nama atribut pengguna yang dapat diprogram. Atribut ini dapat dibangun atau kustom, dan diperlukan atau opsional. Nama kunci objek bergantung pada atribut yang dikonfigurasi administrator di pusat admin Microsoft Entra. Anda dapat mengirimkan beberapa atau semua atribut pengguna melalui /signup/v1.0/start titik akhir atau yang lebih baru di /signup/v1.0/continue titik akhir. Jika Anda mengirimkan semua atribut yang diperlukan melalui /signup/v1.0/start titik akhir, Anda tidak perlu mengirimkan atribut apa pun di /signup/v1.0/continue titik akhir. Namun, jika Anda mengirimkan beberapa atribut yang diperlukan melalui /signup/v1.0/start titik akhir, Anda dapat mengirimkan atribut yang diperlukan yang tersisa nanti di /signup/v1.0/continue titik akhir. Ganti {given_name}, {user_age} dan {postal_code} dengan nilai nama, usia, dan kode pos masing-masing yang dikumpulkan aplikasi dari pengguna pelanggan. Microsoft Entra mengabaikan atribut apa pun yang Anda kirimkan, yang tidak ada. |
Respons keberhasilan
Berikut adalah contoh respons yang berhasil:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAA…",
}
| Parameter | Deskripsi |
|---|---|
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
Jika aplikasi tidak dapat mendukung metode autentikasi yang diperlukan oleh Microsoft Entra, fallback ke alur autentikasi berbasis web diperlukan. Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan pengalihan dalam responsnya:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Deskripsi |
|---|---|
challenge_type |
Microsoft Entra mengembalikan respons yang memiliki jenis tantangan. Nilai jenis tantangan ini adalah pengalihan, yang memungkinkan aplikasi untuk menggunakan alur autentikasi berbasis web. |
Respons ini dianggap berhasil, tetapi aplikasi diperlukan untuk beralih ke alur autentikasi berbasis web. Dalam hal ini, kami sarankan Anda menggunakan pustaka autentikasi yang dibuat dan didukung Microsoft.
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "user_already_exists",
"error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
1003037
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
invalid_attributes |
Daftar (array objek) atribut yang gagal divalidasi. Respons ini dimungkinkan jika aplikasi mengirimkan atribut pengguna, dan suberror nilai parameter attribute_validation_failed. |
suberror |
String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan lebih lanjut. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti ketika nilai parameter challenge_type berisi metode autentikasi yang tidak didukung atau permintaan tidak menyertakan client_id parameter nilai ID klien kosong atau tidak valid. error_description Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
invalid_client |
ID klien yang disertakan dalam aplikasi adalah untuk aplikasi yang tidak memiliki konfigurasi autentikasi asli, seperti bukan klien publik atau tidak diaktifkan untuk autentikasi asli. suberror Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
unauthorized_client |
ID klien yang digunakan dalam permintaan memiliki format ID klien yang valid, tetapi tidak ada di penyewa eksternal atau salah. |
unsupported_challenge_type |
Nilai challenge_type parameter tidak menyertakan redirect jenis tantangan. |
user_already_exists |
Pengguna sudah ada. |
invalid_grant |
Kata sandi yang dikirimkan aplikasi tidak memenuhi semua persyaratan kompleksitas, seperti kata sandi terlalu pendek. suberror Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. Parameter ini hanya berlaku untuk email dengan metode autentikasi kata sandi. |
Jika parameter kesalahan memiliki nilai invalid_grant, Microsoft Entra menyertakan suberror parameter dalam responsnya. Berikut adalah nilai parameter yang suberror mungkin untuk kesalahan invalid_grant :
| Nilai suberor | Deskripsi |
|---|---|
password_too_weak |
Kata sandi terlalu lemah karena tidak memenuhi persyaratan kompleksitas. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. Respons ini dimungkinkan jika aplikasi mengirimkan kata sandi pengguna. |
password_too_short |
Kata sandi baru kurang dari 8 karakter. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. Respons ini dimungkinkan jika aplikasi mengirimkan kata sandi pengguna. |
password_too_long |
Kata sandi baru lebih panjang dari 256 karakter. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. Respons ini dimungkinkan jika aplikasi mengirimkan kata sandi pengguna. |
password_recently_used |
Kata sandi baru tidak boleh sama dengan kata sandi yang baru-baru ini digunakan. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. Respons ini dimungkinkan jika aplikasi mengirimkan kata sandi pengguna. |
password_banned |
Kata sandi baru berisi kata, frasa, atau pola yang dilarang. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. Respons ini dimungkinkan jika aplikasi mengirimkan kata sandi pengguna. |
password_is_invalid |
Kata sandi tidak valid, misalnya karena menggunakan karakter yang tidak diizinkan. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. Respons ini dimungkinkan jika aplikasi mengirimkan kata sandi pengguna. |
Jika parameter kesalahan memiliki nilai invalid_client, Microsoft Entra menyertakan suberror parameter dalam responsnya. Berikut adalah nilai suberror parameter yang mungkin untuk kesalahan invalid_client :
| Nilai suberor | Deskripsi |
|---|---|
nativeauthapi_disabled |
ID klien untuk aplikasi yang tidak diaktifkan untuk autentikasi asli. |
Catatan
Jika Anda mengirimkan semua atribut yang diperlukan melalui /signup/v1.0/start titik akhir, tetapi tidak semua atribut opsional, Anda tidak akan dapat mengirimkan atribut opsional tambahan nanti melalui /signup/v1.0/continue titik akhir. Microsoft Entra tidak secara eksplisit meminta atribut opsional karena tidak wajib untuk menyelesaikan alur pendaftaran. Lihat tabel di bagian Mengirimkan atribut pengguna ke titik akhir untuk mempelajari atribut pengguna yang dapat Anda kirimkan ke /signup/v1.0/start titik akhir dan /signup/v1.0/continue .
Langkah 2: Pilih metode autentikasi
Aplikasi ini meminta Microsoft Entra untuk memilih salah satu jenis tantangan yang didukung bagi pengguna untuk diautentikasi. Untuk melakukannya, aplikasi melakukan panggilan ke /signup/v1.0/challenge titik akhir. Aplikasi perlu menyertakan token kelanjutan yang diperolehnya dari /signup/v1.0/start titik akhir dalam permintaan.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan).
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
challenge_type |
No | Daftar string jenis tantangan otorisasi yang dipisahkan spasi yang didukung aplikasi seperti oob password redirect. Daftar harus selalu menyertakan redirect jenis tantangan. Nilai diharapkan untuk oob redirect kode akses satu kali email dan oob password redirect untuk email dengan metode autentikasi kata sandi. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra dalam permintaan sebelumnya. |
Respons keberhasilan
Microsoft Entra mengirimkan kode akses satu kali ke email pengguna, lalu merespons dengan jenis tantangan dengan nilai oob dan informasi tambahan tentang kode akses satu kali:
HTTP/1.1 200 OK
Content-Type: application/json
{
"interval": 300,
"continuation_token": "AQABAAEAAAYn...",
"challenge_type": "oob",
"binding_method": "prompt",
"challenge_channel": "email",
"challenge_target_label": "c***r@co**o**o.com",
"code_length": 8
}
| Parameter | Deskripsi |
|---|---|
interval |
Lamanya waktu dalam detik yang dibutuhkan aplikasi untuk menunggu sebelum mencoba mengirim ulang OTP. |
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
challenge_type |
Jenis tantangan dipilih bagi pengguna untuk diautentikasi. |
binding_method |
Satu-satunya nilai yang valid adalah perintah. Parameter ini dapat digunakan di masa mendatang untuk menawarkan lebih banyak cara kepada pengguna untuk memasukkan kode sandi satu kali. Dikeluarkan jika challenge_type oob |
challenge_channel |
Jenis saluran tempat kode akses satu kali dikirim. Saat ini, hanya saluran email yang didukung. |
challenge_target_label |
Email yang dikaburkan tempat kode akses satu kali dikirim. |
code_length |
Panjang kode akses satu kali yang dihasilkan Microsoft Entra. |
Jika aplikasi tidak dapat mendukung metode autentikasi yang diperlukan oleh Microsoft Entra, fallback ke alur autentikasi berbasis web diperlukan. Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan pengalihan dalam responsnya:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Deskripsi |
|---|---|
challenge_type |
Microsoft Entra mengembalikan respons yang memiliki jenis tantangan. Nilai jenis tantangan ini adalah pengalihan, yang memungkinkan aplikasi untuk menggunakan alur autentikasi berbasis web. |
Respons ini dianggap berhasil, tetapi aplikasi diperlukan untuk beralih ke alur autentikasi berbasis web. Dalam hal ini, kami sarankan Anda menggunakan pustaka autentikasi yang dibuat dan didukung Microsoft.
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti ID klien kosong atau tidak valid. |
expired_token |
Token kelanjutan kedaluwarsa. |
unsupported_challenge_type |
Nilai challenge_type parameter tidak menyertakan redirect jenis tantangan. |
invalid_grant |
Token kelanjutan tidak valid. |
Langkah 3: Kirim kode sandi satu kali
Aplikasi mengirimkan kode akses satu kali yang dikirim ke email pengguna. Karena kami mengirimkan kode sandi satu kali, oob parameter diperlukan, dan grant_type parameter harus memiliki oob nilai.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra dalam permintaan sebelumnya. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
grant_type |
Ya | Permintaan ke /signup/v1.0/continue titik akhir dapat digunakan untuk mengirimkan kode sandi, kata sandi, atau atribut pengguna satu kali. Dalam hal ini, grant_type nilai digunakan untuk membedakan antara ketiga kasus penggunaan ini. Nilai yang mungkin untuk grant_type adalah oob, kata sandi, atribut. Dalam panggilan ini, karena kami mengirim kode akses satu kali, nilainya diharapkan menjadi oob. |
oob |
Ya | Kode akses satu kali yang diterima pengguna pelanggan dalam email mereka. Ganti {otp_code} dengan nilai kode akses satu kali yang diterima pengguna pelanggan dalam email mereka. Untuk mengirim ulang kode akses satu kali, aplikasi perlu membuat permintaan ke /signup/v1.0/challenge titik akhir lagi. |
Setelah aplikasi berhasil mengirimkan kode akses satu kali, alur pendaftaran bergantung pada skenario seperti yang ditunjukkan tabel:
| Skenario | Cara melanjutkan |
|---|---|
Aplikasi berhasil mengirimkan kata sandi pengguna (untuk email dengan metode autentikasi kata sandi) melalui /signup/v1.0/start titik akhir, dan tidak ada atribut yang dikonfigurasi di pusat admin Microsoft Entra atau semua atribut pengguna yang diperlukan dikirimkan melalui /signup/v1.0/start titik akhir. |
Microsoft Entra mengeluarkan token kelanjutan. Aplikasi ini dapat menggunakan token kelanjutan untuk meminta token keamanan seperti yang ditunjukkan pada langkah 5. |
Aplikasi berhasil mengirimkan kata sandi pengguna(untuk email dengan metode autentikasi kata sandi) melalui /signup/v1.0/start, tetapi tidak semua atribut pengguna yang diperlukan, Microsoft Entra menunjukkan atribut yang perlu dikirimkan aplikasi seperti yang ditunjukkan dalam atribut pengguna yang diperlukan. |
Aplikasi perlu mengirimkan atribut pengguna yang diperlukan melalui /signup/v1.0/continue titik akhir. Responsnya mirip dengan yang diperlukan dalam atribut Pengguna. Kirim atribut pengguna yang ditunjukkan dalam mengirimkan atribut pengguna. |
Aplikasi tidak mengirimkan kata sandi pengguna (untuk email dengan metode autentikasi kata sandi) melalui /signup/v1.0/start titik akhir. |
Respons Microsoft Entra menunjukkan bahwa kredensial diperlukan. Lihat respons. Respons ini dimungkinkan untuk email dengan metode autentikasi kata sandi. |
Respons
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "credential_required",
"error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
"error_codes": [
55103
],
"timestamp": "yy-mm-dd 02:37:33Z",
"trace_id": "d6966055-...-80500",
"correlation_id": "3944-...-60d6",
"continuation_token": "AQABEQEAAAA..."
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
suberror |
String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan lebih lanjut. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
credential_required |
Autentikasi diperlukan untuk pembuatan akun, jadi Anda harus melakukan panggilan ke /signup/v1.0/challenge titik akhir untuk menentukan kredensial yang harus diberikan pengguna. |
invalid_request |
Validasi parameter permintaan gagal seperti validasi token kelanjutan gagal atau permintaan tidak menyertakan client_id parameter nilai ID klien kosong atau tidak valid atau administrator penyewa eksternal belum mengaktifkan OTP email untuk semua pengguna penyewa. |
invalid_grant |
Jenis pemberian yang disertakan dalam permintaan tidak valid atau didukung, atau nilai OTP salah. |
expired_token |
Token kelanjutan yang disertakan dalam permintaan kedaluwarsa. |
Jika parameter kesalahan memiliki nilai invalid_grant, Microsoft Entra menyertakan suberror parameter dalam responsnya. Berikut adalah nilai parameter yang suberror mungkin untuk kesalahan invalid_grant :
| Nilai suberor | Deskripsi |
|---|---|
invalid_oob_value |
Nilai kode akses satu kali tidak valid. |
Agar kredensial kata sandi dikumpulkan dari pengguna, aplikasi perlu melakukan panggilan ke /signup/v1.0/challenge titik akhir untuk menentukan kredensial yang harus diberikan pengguna.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
challenge_type |
No | Daftar string jenis tantangan otorisasi yang dipisahkan spasi yang didukung aplikasi seperti oob password redirect. Daftar harus selalu menyertakan redirect jenis tantangan. Untuk email dengan alur pendaftaran kata sandi, nilai diharapkan berisi password redirect. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra dalam permintaan sebelumnya. |
Respons keberhasilan
Jika kata sandi adalah metode autentikasi yang dikonfigurasi untuk pengguna di pusat admin Microsoft Entra, respons keberhasilan dengan token kelanjutan dikembalikan ke aplikasi.
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "password",
"continuation_token": " AQABAAEAAAAty..."
}
| Parameter | Deskripsi |
|---|---|
challenge_type |
kata sandi dikembalikan dalam respons untuk kredensial yang diperlukan. |
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
Jika aplikasi tidak dapat mendukung metode autentikasi yang diperlukan oleh Microsoft Entra, fallback ke alur autentikasi berbasis web diperlukan. Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan pengalihan dalam responsnya:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Deskripsi |
|---|---|
challenge_type |
Microsoft Entra mengembalikan respons yang memiliki jenis tantangan. Nilai jenis tantangan ini adalah pengalihan, yang memungkinkan aplikasi untuk menggunakan alur autentikasi berbasis web. |
Respons ini dianggap berhasil, tetapi aplikasi diperlukan untuk beralih ke alur autentikasi berbasis web. Dalam hal ini, kami sarankan Anda menggunakan pustaka autentikasi yang dibuat dan didukung Microsoft.
Langkah 4: Mengautentikasi dan mendapatkan token untuk mendaftar
Aplikasi perlu mengirimkan kredensial pengguna, dalam hal ini kata sandi, yang diminta Microsoft Entra di langkah sebelumnya. Aplikasi perlu mengirimkan kredensial kata sandi jika tidak melakukannya melalui /signup/v1.0/start titik akhir. Aplikasi membuat permintaan ke /signup/v1.0/continue titik akhir untuk mengirimkan kata sandi. Karena kami mengirimkan kata sandi, password parameter diperlukan, dan grant_type parameter harus memiliki kata sandi nilai.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=password
&password={secure_password}
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra di langkah sebelumnya. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
grant_type |
Ya | Permintaan ke /signup/v1.0/continue titik akhir dapat digunakan untuk mengirimkan kode sandi, kata sandi, atau atribut pengguna satu kali. Dalam hal ini, grant_type nilai digunakan untuk membedakan antara ketiga kasus penggunaan ini. Nilai yang mungkin untuk grant_type adalah oob, kata sandi, atribut. Dalam panggilan ini, karena kami mengirim kata sandi pengguna, nilainya diharapkan menjadi kata sandi. |
password |
Ya | Nilai kata sandi yang dikumpulkan aplikasi dari pengguna pelanggan. Ganti {secure_password} dengan nilai kata sandi yang dikumpulkan aplikasi dari pengguna pelanggan. Anda bertanggung jawab untuk mengonfirmasi bahwa pengguna mengetahui kata sandi yang ingin mereka gunakan dengan menyediakan bidang konfirmasi kata sandi di UI aplikasi. Anda juga harus memastikan bahwa pengguna mengetahui apa yang merupakan kata sandi yang kuat sesuai kebijakan organisasi Anda. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
Respons keberhasilan
Jika permintaan berhasil, tetapi tidak ada atribut yang dikonfigurasi di pusat admin Microsoft Entra atau semua atribut yang diperlukan dikirimkan melalui /signup/v1.0/start titik akhir, aplikasi mendapatkan token kelanjutan tanpa mengirimkan atribut apa pun. Aplikasi ini dapat menggunakan token kelanjutan untuk meminta token keamanan seperti yang ditunjukkan pada langkah 5. Jika tidak, respons Microsoft Entra menunjukkan bahwa aplikasi perlu mengirimkan atribut yang diperlukan. Atribut ini, bawaan atau kustom, dikonfigurasi di pusat admin Microsoft Entra oleh administrator penyewa.
Atribut pengguna diperlukan
Respons ini meminta aplikasi untuk mengirimkan nilai untuk atribut nama, *usia, dan telepon .
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "attributes_required",
"error_description": "User attributes required",
"error_codes": [
55106
],
"timestamp": "yy-mm-dd 02:37:33Z",
"trace_id": "d6966055-...-80500",
"correlation_id": "3944-...-60d6",
"continuation_token": "AQABAAEAAAAtn...",
"required_attributes": [
{
"name": "displayName",
"type": "string",
"required": true,
"options": {
"regex": ".*@.**$"
}
},
{
"name": "extension_2588abcdwhtfeehjjeeqwertc_age",
"type": "string",
"required": true
},
{
"name": "postalCode",
"type": "string",
"required": true,
"options": {
"regex":"^[1-9][0-9]*$"
}
}
],
}
Catatan
Atribut kustom (juga dikenal sebagai ekstensi direktori) dinamai dengan menggunakan konvensi extension_{appId-without-hyphens}_{attribute-name} di mana {appId-without-hyphens} adalah versi ID klien yang dilucuti untuk aplikasi ekstensi. Misalnya, jika ID klien aplikasi ekstensi adalah 2588a-bcdwh-tfeehj-jeeqw-ertc dan nama atribut adalah hobi, maka atribut kustom dinamai sebagaiextension_2588abcdwhtfeehjjeeqwertc_hobbies. Pelajari selengkapnya tentang atribut kustom dan aplikasi ekstensi.
| Parameter | Deskripsi |
|---|---|
error |
Atribut ini diatur jika Microsoft Entra tidak dapat membuat akun pengguna karena atribut perlu diverifikasi atau dikirimkan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
required_attributes |
Daftar (array objek) atribut yang perlu dikirimkan aplikasi untuk melanjutkan panggilan berikutnya. Atribut ini adalah atribut tambahan yang perlu dikirimkan aplikasi selain dari nama pengguna. Microsoft Entra menyertakan parameter ini adalah respons jika nilai error parameter attributes_required. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti validasi token kelanjutan gagal atau permintaan tidak menyertakan client_id parameter nilai ID klien kosong atau tidak valid. |
invalid_grant |
Jenis pemberian yang disertakan dalam permintaan tidak valid atau didukung. Nilai yang grant_type mungkin untuk adalah oob, kata sandi, atribut |
expired_token |
Token kelanjutan yang disertakan dalam permintaan kedaluwarsa. |
attributes_required |
Satu atau beberapa atribut pengguna diperlukan. |
Jika aplikasi tidak dapat mendukung metode autentikasi yang diperlukan oleh Microsoft Entra, fallback ke alur autentikasi berbasis web diperlukan. Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan pengalihan dalam responsnya:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Deskripsi |
|---|---|
challenge_type |
Microsoft Entra mengembalikan respons yang memiliki jenis tantangan. Nilai jenis tantangan ini adalah pengalihan, yang memungkinkan aplikasi untuk menggunakan alur autentikasi berbasis web. |
Respons ini dianggap berhasil, tetapi aplikasi diperlukan untuk beralih ke alur autentikasi berbasis web. Dalam hal ini, kami sarankan Anda menggunakan pustaka autentikasi yang dibuat dan didukung Microsoft.
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_grant",
"error_description": "New password is too weak",
"error_codes": [
399246
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6",
"suberror": "password_too_weak"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
suberror |
String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan lebih lanjut. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti ketika challenge_type parameter menyertakan jenis tantangan yang tidak valid. |
invalid_grant |
Pemberian yang dikirimkan tidak valid, seperti kata sandi yang dikirimkan terlalu singkat. suberror Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
expired_token |
Token kelanjutan kedaluwarsa. |
attributes_required |
Satu atau beberapa atribut pengguna diperlukan. |
Jika parameter kesalahan memiliki nilai invalid_grant, Microsoft Entra menyertakan suberror parameter dalam responsnya. Berikut adalah nilai parameter yang suberror mungkin:
| Nilai suberor | Deskripsi |
|---|---|
password_too_weak |
Kata sandi terlalu lemah karena tidak memenuhi persyaratan kompleksitas. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
password_too_short |
Kata sandi baru kurang dari 8 karakter. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
password_too_long |
Kata sandi baru lebih panjang dari 256 karakter. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
password_recently_used |
Kata sandi baru tidak boleh sama dengan kata sandi yang baru-baru ini digunakan. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
password_banned |
Kata sandi baru berisi kata, frasa, atau pola yang dilarang. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
password_is_invalid |
Kata sandi tidak valid, misalnya karena menggunakan karakter yang tidak diizinkan. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. Respons ini dimungkinkan jika aplikasi mengirimkan kata sandi pengguna. |
Mengirimkan atribut pengguna
Untuk melanjutkan alur, aplikasi perlu melakukan panggilan ke /signup/v1.0/continue titik akhir untuk mengirimkan atribut pengguna yang diperlukan. Karena kami mengirimkan atribut, attributes parameter diperlukan, dan grant_type parameter harus memiliki nilai yang sama dengan atribut.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=attributes
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra dalam permintaan sebelumnya. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
grant_type |
Ya | Permintaan ke /signup/v1.0/continue titik akhir dapat digunakan untuk mengirimkan kode sandi, kata sandi, atau atribut pengguna satu kali. Dalam hal ini, grant_type nilai digunakan untuk membedakan antara ketiga kasus penggunaan ini. Nilai yang mungkin untuk grant_type adalah oob, kata sandi, atribut. Dalam panggilan ini, karena kami mengirim atribut pengguna, nilainya diharapkan menjadi atribut. |
attributes |
Ya | Nilai atribut pengguna yang dikumpulkan aplikasi dari pengguna pelanggan. Nilainya adalah string, tetapi diformat sebagai objek JSON yang nilai kuncinya adalah nama atribut pengguna, bawaan atau kustom. Nama kunci objek bergantung pada atribut yang dikonfigurasi administrator di pusat admin Microsoft Entra. Ganti {given_name}, {user_age} dan {postal_code} dengan nilai nama, usia, dan kode pos masing-masing yang dikumpulkan aplikasi dari pengguna pelanggan. Microsoft Entra mengabaikan atribut apa pun yang Anda kirimkan, yang tidak ada. |
Respons keberhasilan
Jika permintaan berhasil, Microsoft Entra mengeluarkan token kelanjutan, yang dapat digunakan aplikasi untuk meminta token keamanan.
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAAYn..."
}
| Parameter | Deskripsi |
|---|---|
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
Jika aplikasi tidak dapat mendukung metode autentikasi yang diperlukan oleh Microsoft Entra, fallback ke alur autentikasi berbasis web diperlukan. Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan pengalihan dalam responsnya:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Deskripsi |
|---|---|
challenge_type |
Microsoft Entra mengembalikan respons yang memiliki jenis tantangan. Nilai jenis tantangan ini adalah pengalihan, yang memungkinkan aplikasi untuk menggunakan alur autentikasi berbasis web. |
Respons ini dianggap berhasil, tetapi aplikasi diperlukan untuk beralih ke alur autentikasi berbasis web. Dalam hal ini, kami sarankan Anda menggunakan pustaka autentikasi yang dibuat dan didukung Microsoft.
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "expired_token",
"error_description": "AADSTS901007: The continuation_token is expired. .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
unverified_attributes |
Daftar (array objek) nama kunci atribut yang harus diverifikasi. Parameter ini disertakan dalam respons saat error nilai parameter verification_required. |
required_attributes |
Daftar (array objek) atribut yang perlu dikirim aplikasi. Microsoft Entra menyertakan parameter ini dalam responsnya saat error nilai parameter attributes_required. |
invalid_attributes |
Daftar (array objek) atribut yang gagal divalidasi. Parameter ini disertakan dalam respons saat suberror nilai parameter attribute_validation_failed. |
suberror |
String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan lebih lanjut. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti validasi token kelanjutan gagal atau permintaan tidak menyertakan client_id parameter nilai ID klien kosong atau tidak valid. |
invalid_grant |
Jenis pemberian yang diberikan tidak valid atau didukung atau gagal validasi, seperti validasi atribut gagal. suberror Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
expired_token |
Token kelanjutan yang disertakan dalam permintaan kedaluwarsa. |
attributes_required |
Satu atau beberapa atribut pengguna diperlukan. |
Jika parameter kesalahan memiliki nilai invalid_grant, Microsoft Entra menyertakan suberror parameter dalam responsnya. Berikut adalah nilai parameter yang suberror mungkin untuk kesalahan invalid_grant :
| Nilai suberor | Deskripsi |
|---|---|
attribute_validation_failed |
Validasi atribut pengguna gagal. invalid_attributes parameter berisi daftar (array objek) atribut yang gagal divalidasi. |
Langkah 5: Meminta token keamanan
Aplikasi ini membuat permintaan POST ke /token titik akhir dan menyediakan token kelanjutan yang diperoleh dari langkah sebelumnya untuk memperoleh token keamanan.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
continuation_token=ABAAEAAAAtyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
grant_type |
Ya | Nilai parameter harus berupa token kelanjutan. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra di langkah sebelumnya. |
scope |
Ya | Daftar cakupan yang dipisahkan spasi yang berlaku untuk token akses. Ganti {scopes} dengan cakupan valid yang dikembalikan Microsoft Entra token akses valid. |
username |
Ya | Email pengguna pelanggan yang ingin mereka daftarkan, seperti contoso-consumer@contoso.com. |
Respons berhasil
Berikut adalah contoh respons yang berhasil:
HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"scope": "openid profile",
"expires_in": 4141,
"access_token": "eyJ0eXAiOiJKV1Qi...",
"refresh_token": "AwABAAAA...",
"id_token": "eyJ0eXAiOiJKV1Q..."
}
| Parameter | Deskripsi |
|---|---|
access_token |
Token akses yang diminta aplikasi dari /token titik akhir. Aplikasi ini dapat menggunakan token akses ini untuk meminta akses ke sumber daya aman seperti API web. |
token_type |
Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung Microsoft Entra adalah Pembawa. |
expires_in |
Lamanya waktu dalam detik token akses tetap valid. |
scopes |
Daftar cakupan yang dipisahkan spasi yang berlaku untuk token akses. |
refresh_token |
Token refresh OAuth 2.0. Aplikasi dapat menggunakan token ini untuk memperoleh token akses lain setelah token akses saat ini kedaluwarsa. Token refresh berumur panjang. Mereka dapat mempertahankan akses ke sumber daya untuk waktu yang lama. Untuk detail selengkapnya tentang menyegarkan token akses, lihat artikel Refresh token akses. Catatan: Hanya dikeluarkan jika cakupan offline_access diminta. |
id_token |
JSON Web Token (Jwt) yang digunakan untuk mengidentifikasi pengguna pelanggan. Aplikasi dapat mendekode token untuk membaca informasi tentang pengguna yang masuk. Aplikasi dapat menyimpan nilai dan menampilkannya, dan klien rahasia dapat menggunakan token ini untuk otorisasi. Untuk informasi selengkapnya tentang token ID, lihat Token ID. Catatan: Hanya dikeluarkan jika cakupan openid diminta. |
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti klien/aplikasi tidak memiliki persetujuan untuk cakupan yang diminta. |
invalid_grant |
Token kelanjutan yang disertakan dalam permintaan tidak valid. |
unauthorized_client |
ID klien yang disertakan dalam permintaan tidak valid atau tidak ada. |
unsupported_grant_type |
Jenis pemberian yang disertakan dalam permintaan tidak didukung atau salah. |
Mengirimkan atribut pengguna ke titik akhir
Di pusat admin Microsoft Entra, Anda dapat mengonfigurasi atribut pengguna sebagaimana diperlukan atau opsional. Konfigurasi ini menentukan bagaimana Microsoft Entra merespons saat Anda melakukan panggilan ke titik akhirnya. Atribut opsional tidak wajib untuk menyelesaikan alur pendaftaran. Oleh karena itu, ketika semua atribut bersifat opsional, atribut harus dikirimkan sebelum nama pengguna diverifikasi. Jika tidak, pendaftaran selesai tanpa atribut opsional.
Tabel berikut ini meringkas kapan mungkin untuk mengirimkan atribut pengguna ke titik akhir Microsoft Entra.
| Titik akhir | Atribut yang diperlukan | Atribut opsional | Atribut yang diperlukan dan opsional |
|---|---|---|---|
/signup/v1.0/start Endpoint |
Ya | Ya | Ya |
/signup/v1.0/continue titik akhir sebelum verifikasi nama pengguna |
Ya | Ya | Ya |
/signup/v1.0/continue titik akhir setelah verifikasi nama pengguna |
Ya | No | Ya |
Format nilai atribut pengguna
Anda menentukan informasi yang ingin Anda kumpulkan dari pengguna dengan mengonfigurasi pengaturan alur pengguna di pusat admin Microsoft Entra. Gunakan artikel Kumpulkan atribut pengguna kustom selama pendaftaran untuk mempelajari cara mengumpulkan nilai untuk atribut bawaan dan kustom.
Anda juga dapat menentukan Jenis Input Pengguna untuk atribut yang Anda konfigurasikan. Tabel berikut ini meringkas jenis input pengguna yang didukung, dan cara mengirimkan nilai yang dikumpulkan oleh kontrol UI ke Microsoft Entra.
| Jenis Input Pengguna | Format nilai yang diajukan |
|---|---|
| TextBox | Satu nilai seperti jabatan, Insinyur Perangkat Lunak. |
| SingleRadioSelect | Satu nilai seperti Bahasa, Norwegia. |
| CheckboxMultiSelect | Satu atau beberapa nilai seperti hobi atau hobi, Menari atau Menari, Berenang, Bepergian. |
Berikut adalah contoh permintaan yang menunjukkan cara Anda mengirimkan nilai atribut:
POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
continuation_token=ABAAEAAAAtfyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=attributes
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...
Pelajari selengkapnya tentang jenis input atribut pengguna di artikel Jenis input atribut pengguna kustom.
Cara mereferensikan atribut pengguna
Saat membuat alur pengguna pendaftaran, Anda mengonfigurasi atribut pengguna yang ingin Anda kumpulkan dari pengguna selama pendaftaran. Nama atribut pengguna di pusat admin Microsoft Entra berbeda dari cara Anda mereferensikannya di API autentikasi asli.
Misalnya, Nama Tampilan di pusat admin Microsoft Entra dirujuk sebagai displayName di API.
Gunakan artikel Atribut profil pengguna untuk mempelajari cara mereferensikan atribut pengguna bawaan dan kustom di API autentikasi asli.
Referensi API masuk
Pengguna perlu masuk dengan metode autentikasi yang mereka gunakan untuk mendaftar. Misalnya, pengguna yang mendaftar menggunakan email dengan metode autentikasi kata sandi harus masuk email dan kata sandi.
Untuk meminta token keamanan, aplikasi Anda berinteraksi dengan tiga titik akhir, /initiate, /challenge dan /token.
Titik akhir API masuk
Jenis tantangan masuk
API memungkinkan aplikasi untuk mengiklankan metode autentikasi yang didukungnya, saat melakukan panggilan ke Microsoft Entra. Untuk melakukannya, aplikasi menggunakan challenge_type parameter dalam permintaannya. Parameter ini menyimpan nilai yang telah ditentukan sebelumnya, yang mewakili metode autentikasi yang berbeda.
Untuk metode autentikasi tertentu, nilai jenis tantangan yang dikirim aplikasi ke Microsoft Entra selama alur pendaftaran sama dengan saat aplikasi masuk. Misalnya, email dengan metode autentikasi kata sandi menggunakan nilai jenis tantangan oob, kata sandi, dan pengalihan untuk alur pendaftaran dan masuk.
Pelajari selengkapnya tentang jenis tantangan di artikel jenis tantangan autentikasi asli.
Detail protokol alur masuk
Diagram urutan menunjukkan alur proses masuk.
Setelah aplikasi memverifikasi email pengguna dengan OTP, aplikasi menerima token keamanan. Jika pengiriman kode sandi satu kali tertunda atau tidak pernah dikirimkan ke email pengguna, pengguna dapat meminta untuk dikirimi kode sandi satu kali lagi. Microsoft Entra mengirim ulang kode akses satu kali lagi jika yang sebelumnya belum diverifikasi. Saat Microsoft Entra mengirim ulang kode akses satu kali, microsoft Entra membatalkan kode yang dikirim sebelumnya.
Di bagian berikut, kami meringkas alur diagram urutan menjadi tiga langkah dasar.
Langkah 1: Minta untuk memulai alur masuk
Alur autentikasi dimulai dengan aplikasi yang membuat permintaan POST ke /initiate titik akhir untuk memulai alur masuk.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
username |
Ya | Email pengguna pelanggan seperti contoso-consumer@contoso.com. |
challenge_type |
Ya | Daftar string jenis tantangan otorisasi yang dipisahkan spasi yang didukung aplikasi seperti oob password redirect. Daftar harus selalu menyertakan redirect jenis tantangan. Nilai diharapkan untuk oob redirect kode akses satu kali email dan password redirect untuk email dengan kata sandi. |
Respons keberhasilan
Berikut adalah contoh respons yang berhasil:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Parameter | Deskripsi |
|---|---|
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
Jika aplikasi tidak dapat mendukung metode autentikasi yang diperlukan oleh Microsoft Entra, fallback ke alur autentikasi berbasis web diperlukan. Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan pengalihan dalam responsnya:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Deskripsi |
|---|---|
challenge_type |
Microsoft Entra mengembalikan respons yang memiliki jenis tantangan. Nilai jenis tantangan ini adalah pengalihan, yang memungkinkan aplikasi untuk menggunakan alur autentikasi berbasis web. |
Respons ini dianggap berhasil, tetapi aplikasi diperlukan untuk beralih ke alur autentikasi berbasis web. Dalam hal ini, kami sarankan Anda menggunakan pustaka autentikasi yang dibuat dan didukung Microsoft.
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti ketika challenge_type parameter menyertakan jenis tantangan yang tidak valid. atau permintaan tidak menyertakan client_id parameter nilai ID klien kosong atau tidak valid. error_description Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
unauthorized_client |
ID klien yang digunakan dalam permintaan memiliki format ID klien yang valid, tetapi tidak ada di penyewa eksternal atau salah. |
invalid_client |
ID klien yang disertakan dalam aplikasi adalah untuk aplikasi yang tidak memiliki konfigurasi autentikasi asli, seperti bukan klien publik atau tidak diaktifkan untuk autentikasi asli. suberror Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
user_not_found |
Nama pengguna tidak ada. |
unsupported_challenge_type |
Nilai challenge_type parameter tidak menyertakan redirect jenis tantangan. |
Jika parameter kesalahan memiliki nilai invalid_client, Microsoft Entra menyertakan suberror parameter dalam responsnya. Berikut adalah nilai suberror parameter yang mungkin untuk kesalahan invalid_client :
| Nilai suberor | Deskripsi |
|---|---|
nativeauthapi_disabled |
ID klien untuk aplikasi yang tidak diaktifkan untuk autentikasi asli. |
Langkah 2: Pilih metode autentikasi
Untuk melanjutkan alur, aplikasi menggunakan token kelanjutan yang diperolehnya dari langkah sebelumnya untuk meminta Microsoft Entra memilih salah satu jenis tantangan yang didukung bagi pengguna untuk diautentikasi. Aplikasi ini membuat permintaan POST ke /challenge titik akhir.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra dalam permintaan sebelumnya. |
challenge_type |
No | Daftar string jenis tantangan otorisasi yang dipisahkan spasi yang didukung aplikasi seperti oob password redirect. Daftar harus selalu menyertakan redirect jenis tantangan. Nilai diharapkan untuk oob redirect kode akses satu kali email dan password redirect untuk email dengan kata sandi. |
Respons keberhasilan
Jika administrator penyewa mengonfigurasi kode akses satu kali email di pusat admin Microsoft Entra sebagai metode autentikasi pengguna, Microsoft Entra mengirimkan kode akses satu kali ke email pengguna, lalu merespons dengan jenis tantangan oob dan memberikan informasi selengkapnya tentang kode sandi satu kali.
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"challenge_type": "oob",
"binding_method": "prompt ",
"challenge_channel": "email",
"challenge_target_label ": "c***r@co**o**o.com ",
"code_length": 8
}
| Parameter | Deskripsi |
|---|---|
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
challenge_type |
Jenis tantangan dipilih bagi pengguna untuk diautentikasi. |
binding_method |
Satu-satunya nilai yang valid adalah perintah. Parameter ini dapat digunakan di masa mendatang untuk menawarkan lebih banyak cara bagi pengguna untuk memasukkan kode sandi satu kali. Dikeluarkan jika challenge_type oob |
challenge_channel |
Jenis saluran tempat kode akses satu kali dikirim. Saat ini, kami mendukung email. |
challenge_target_label |
Email yang dikaburkan tempat kode akses satu kali dikirim. |
code_length |
Panjang kode akses satu kali yang dihasilkan Microsoft Entra. |
Jika aplikasi tidak dapat mendukung metode autentikasi yang diperlukan oleh Microsoft Entra, fallback ke alur autentikasi berbasis web diperlukan. Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan pengalihan dalam responsnya:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Deskripsi |
|---|---|
challenge_type |
Microsoft Entra mengembalikan respons yang memiliki jenis tantangan. Nilai jenis tantangan ini adalah pengalihan, yang memungkinkan aplikasi untuk menggunakan alur autentikasi berbasis web. |
Respons ini dianggap berhasil, tetapi aplikasi diperlukan untuk beralih ke alur autentikasi berbasis web. Dalam hal ini, kami sarankan Anda menggunakan pustaka autentikasi yang dibuat dan didukung Microsoft.
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti ketika challenge_type parameter menyertakan jenis tantangan yang tidak valid. |
invalid_grant |
Token kelanjutan yang disertakan dalam permintaan tidak valid. |
expired_token |
Token kelanjutan yang disertakan dalam permintaan kedaluwarsa. |
unsupported_challenge_type |
Nilai challenge_type parameter tidak menyertakan redirect jenis tantangan. |
Langkah 3: Meminta token keamanan
Aplikasi ini membuat permintaan POST ke /token titik akhir dan memberikan kredensial pengguna yang dipilih pada langkah sebelumnya, dalam hal ini kata sandi, untuk memperoleh token keamanan.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=password
&password={secure_password}
&scope=openid offline_access
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra dalam permintaan sebelumnya. |
grant_type |
Ya | Nilainya harus berupa kata sandi untuk email dengan metode autentikasi kata sandi dan oob untuk metode autentikasi kode sandi satu kali email. |
scope |
Ya | Daftar cakupan yang dipisahkan spasi. Semua cakupan harus berasal dari satu sumber daya, bersama dengan cakupan OpenID Connect (OIDC), seperti profil, *openid, dan email. Aplikasi ini perlu menyertakan cakupan openid untuk Microsoft Entra untuk mengeluarkan token ID. Aplikasi ini perlu menyertakan cakupan offline_access untuk Microsoft Entra untuk mengeluarkan token refresh. Pelajari selengkapnya tentang Izin dan persetujuan di platform identitas Microsoft. |
password |
Ya (untuk email dengan kata sandi) |
Nilai kata sandi yang dikumpulkan aplikasi dari pengguna pelanggan. Ganti {secure_password} dengan nilai kata sandi yang dikumpulkan aplikasi dari pengguna pelanggan. |
oob |
Ya (untuk kode akses satu kali email) |
Kode akses satu kali yang diterima pengguna pelanggan dalam email mereka. Ganti {otp_code} dengan kode akses satu kali yang diterima pengguna pelanggan dalam email mereka. Untuk mengirim ulang kode akses satu kali, aplikasi perlu membuat permintaan ke /challenge titik akhir lagi. |
Respons berhasil
Berikut adalah contoh respons yang berhasil:
HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"scope": "openid profile",
"expires_in": 4141,
"access_token": "eyJ0eXAiOiJKV1Qi...",
"refresh_token": "AwABAAAA...",
"id_token": "eyJ0eXAiOiJKV1Q..."
}
| Parameter | Deskripsi |
|---|---|
token_type |
Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung Microsoft Entra adalah Pembawa. |
scopes |
Daftar cakupan yang dipisahkan spasi yang berlaku untuk token akses. |
expires_in |
Lamanya waktu dalam detik token akses tetap valid. |
access_token |
Token akses yang diminta aplikasi dari /token titik akhir. Aplikasi ini dapat menggunakan token akses ini untuk meminta akses ke sumber daya aman seperti API web. |
refresh_token |
Token refresh OAuth 2.0. Aplikasi dapat menggunakan token ini untuk memperoleh token akses lain setelah token akses saat ini kedaluwarsa. Token refresh berumur panjang. Mereka dapat mempertahankan akses ke sumber daya untuk waktu yang lama. Untuk detail selengkapnya tentang menyegarkan token akses, lihat artikel Refresh token akses. Catatan: Hanya dikeluarkan jika Anda meminta cakupan offline_access . |
id_token |
JSON Web Token (Jwt) yang digunakan untuk mengidentifikasi pengguna pelanggan. Aplikasi dapat mendekode token untuk meminta informasi tentang pengguna yang masuk. Aplikasi dapat menyimpan nilai dan menampilkannya, dan klien rahasia dapat menggunakan token ini untuk otorisasi. Untuk informasi selengkapnya tentang token ID, lihat Token ID. Catatan: Hanya dikeluarkan jika Anda meminta cakupan openid . |
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_grant",
"error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal. Untuk memahami apa yang terjadi, gunakan pesan dalam deskripsi kesalahan. |
invalid_grant |
Token kelanjutan yang disertakan dalam permintaan tidak valid atau kredensial masuk pengguna pelanggan yang disertakan dalam permintaan tidak valid atau jenis pemberian yang disertakan dalam permintaan tidak diketahui. |
invalid_client |
ID klien yang disertakan dalam permintaan bukan untuk klien publik. |
expired_token |
Token kelanjutan yang disertakan dalam permintaan kedaluwarsa. |
invalid_scope |
Satu atau beberapa cakupan yang disertakan dalam permintaan tidak valid. |
Jika parameter kesalahan memiliki nilai invalid_grant, Microsoft Entra menyertakan suberror parameter dalam responsnya. Berikut adalah nilai parameter yang suberror mungkin untuk kesalahan invalid_grant :
| Nilai suberor | Deskripsi |
|---|---|
invalid_oob_value |
Nilai kode akses satu kali tidak valid. Sub-kesalahan ini hanya menerapkan kode akses satu kali email |
Pengaturan ulang kata sandi mandiri (SSPR)
Jika Anda menggunakan email dan kata sandi sebagai metode autentikasi di aplikasi Anda, gunakan API pengaturan ulang kata sandi mandiri (SSPR) untuk memungkinkan pengguna pelanggan mengatur ulang kata sandi mereka. Gunakan API ini untuk lupa kata sandi atau ubah skenario kata sandi.
Titik akhir API reset kata sandi mandiri
Untuk menggunakan API ini, aplikasi berinteraksi dengan titik akhir yang diperlihatkan dalam tabel berikut:
| Titik akhir | Deskripsi |
|---|---|
/start |
Aplikasi Anda memanggil titik akhir ini saat pengguna pelanggan memilih Lupa kata sandi atau Ubah tautan kata sandi atau tombol di aplikasi. Titik akhir ini memvalidasi nama pengguna (email), lalu mengembalikan token kelanjutan untuk digunakan dalam alur reset kata sandi. Jika aplikasi Anda meminta untuk menggunakan metode autentikasi yang tidak didukung oleh Microsoft Entra, respons titik akhir ini dapat menunjukkan kepada aplikasi Anda bahwa aplikasi perlu menggunakan alur autentikasi berbasis browser. |
/challenge |
Menerima daftar jenis tantangan yang didukung oleh klien dan token kelanjutan. Tantangan dikeluarkan untuk salah satu kredensial pemulihan pilihan. Misalnya, tantangan oob mengeluarkan kode akses sekali pakai out-of-band ke email yang terkait dengan akun pengguna pelanggan. Jika aplikasi Anda meminta untuk menggunakan metode autentikasi yang tidak didukung oleh Microsoft Entra, respons titik akhir ini dapat menunjukkan kepada aplikasi Anda bahwa aplikasi perlu menggunakan alur autentikasi berbasis browser. |
/continue |
Memvalidasi tantangan yang dikeluarkan oleh /challenge titik akhir, lalu mengembalikan token kelanjutan untuk /submit titik akhir, atau mengeluarkan tantangan lain kepada pengguna. |
/submit |
Menerima input kata sandi baru oleh pengguna bersama dengan token kelanjutan untuk menyelesaikan alur reset kata sandi. Titik akhir ini mengeluarkan token kelanjutan lainnya. |
/poll_completion |
Terakhir, aplikasi dapat menggunakan token kelanjutan yang dikeluarkan oleh /submit titik akhir untuk memeriksa status permintaan reset kata sandi. |
Jenis tantangan pengaturan ulang kata sandi mandiri
API memungkinkan aplikasi untuk mengiklankan metode autentikasi yang didukungnya, saat melakukan panggilan ke Microsoft Entra. Untuk melakukannya, aplikasi menggunakan challenge_type parameter dalam permintaannya. Parameter ini menyimpan nilai yang telah ditentukan sebelumnya, yang mewakili metode autentikasi yang berbeda.
Untuk alur SSPR, nilai jenis tantangan adalah oob, dan pengalihan.
Pelajari selengkapnya tentang jenis tantangan dalam jenis tantangan autentikasi asli.
Detail protokol alur pengaturan ulang kata sandi mandiri
Diagram urutan menunjukkan alur untuk proses reset kata sandi.
Diagram ini menunjukkan bahwa aplikasi mengumpulkan nama pengguna (email) dan kata sandi dari pengguna pada waktu yang berbeda (dan mungkin di layar terpisah). Namun, Anda dapat merancang aplikasi untuk mengumpulkan nama pengguna (email) dan kata sandi baru di layar yang sama. Dalam hal ini, aplikasi menyimpan kata sandi, lalu mengirimkannya melalui /submit titik akhir di mana diperlukan.
Langkah 1: Minta untuk memulai alur pengaturan ulang kata sandi mandiri
Alur reset kata sandi dimulai dengan aplikasi membuat permintaan POST ke /start titik akhir untuk memulai alur pengaturan ulang kata sandi mandiri.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&username=contoso-consumer@contoso.com
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
username |
Ya | Email pengguna pelanggan seperti contoso-consumer@contoso.com. |
challenge_type |
Ya | Daftar string jenis tantangan otorisasi yang dipisahkan spasi yang didukung aplikasi seperti oob password redirect. Daftar harus selalu menyertakan redirect jenis tantangan. Untuk permintaan ini, nilai diharapkan berisi oob redirect. |
Respons keberhasilan
Contoh:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Parameter | Deskripsi |
|---|---|
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
Jika aplikasi tidak dapat mendukung metode autentikasi yang diperlukan oleh Microsoft Entra, fallback ke alur autentikasi berbasis web diperlukan. Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan pengalihan dalam responsnya:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Deskripsi |
|---|---|
challenge_type |
Microsoft Entra mengembalikan respons yang memiliki jenis tantangan. Nilai jenis tantangan ini adalah pengalihan, yang memungkinkan aplikasi untuk menggunakan alur autentikasi berbasis web. |
Respons ini dianggap berhasil, tetapi aplikasi diperlukan untuk beralih ke alur autentikasi berbasis web. Dalam hal ini, kami sarankan Anda menggunakan pustaka autentikasi yang dibuat dan didukung Microsoft.
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti ketika challenge_type parameter menyertakan jenis tantangan yang tidak valid atau permintaan tidak menyertakan client_id parameter nilai ID klien kosong atau tidak valid. error_description Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
user_not_found |
Nama pengguna tidak ada. |
unsupported_challenge_type |
Nilai challenge_type parameter tidak menyertakan redirect jenis tantangan. |
invalid_client |
ID klien yang disertakan dalam aplikasi adalah untuk aplikasi yang tidak memiliki konfigurasi autentikasi asli, seperti bukan klien publik atau tidak diaktifkan untuk autentikasi asli. suberror Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
unauthorized_client |
ID klien yang digunakan dalam permintaan memiliki format ID klien yang valid, tetapi tidak ada di penyewa eksternal atau salah. |
Jika parameter kesalahan memiliki nilai invalid_client, Microsoft Entra menyertakan suberror parameter dalam responsnya. Berikut adalah nilai suberror parameter yang mungkin untuk kesalahan invalid_client :
| Nilai suberor | Deskripsi |
|---|---|
nativeauthapi_disabled |
ID klien untuk aplikasi yang tidak diaktifkan untuk autentikasi asli. |
Langkah 2: Pilih metode autentikasi
Untuk melanjutkan alur, aplikasi menggunakan token kelanjutan yang diperoleh dari langkah sebelumnya untuk meminta Microsoft Entra memilih salah satu jenis tantangan yang didukung bagi pengguna untuk diautentikasi. Aplikasi ini membuat permintaan POST ke /challenge titik akhir. Jika permintaan ini berhasil, Microsoft Entra mengirimkan kode akses satu kali ke email akun pengguna. Saat ini, kami hanya mendukung email OTP.
Berikut adalah contoh (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra dalam permintaan sebelumnya. |
challenge_type |
No | Daftar string jenis tantangan otorisasi yang dipisahkan spasi yang didukung aplikasi seperti oob redirect. Daftar harus selalu menyertakan redirect jenis tantangan. Untuk permintaan ini, nilai diharapkan berisi oob redirect. |
Respons keberhasilan
Contoh:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"challenge_type": "oob",
"binding_method": "prompt ",
"challenge_channel": "email",
"challenge_target_label ": "c***r@co**o**o.com ",
"code_length": 8
}
| Parameter | Deskripsi |
|---|---|
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
challenge_type |
Jenis tantangan dipilih bagi pengguna untuk diautentikasi. |
binding_method |
Satu-satunya nilai yang valid adalah perintah. Parameter ini dapat digunakan di masa mendatang untuk menawarkan lebih banyak cara kepada pengguna untuk memasukkan kode sandi satu kali. Dikeluarkan jika challenge_type oob |
challenge_channel |
Jenis saluran tempat kode akses satu kali dikirim. Saat ini, kami mendukung email. |
challenge_target_label |
Email yang dikaburkan tempat kode akses satu kali dikirim. |
code_length |
Panjang kode akses satu kali yang dihasilkan Microsoft Entra. |
Jika aplikasi tidak dapat mendukung metode autentikasi yang diperlukan oleh Microsoft Entra, fallback ke alur autentikasi berbasis web diperlukan. Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan pengalihan dalam responsnya:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Deskripsi |
|---|---|
challenge_type |
Microsoft Entra mengembalikan respons yang memiliki jenis tantangan. Nilai jenis tantangan ini adalah pengalihan, yang memungkinkan aplikasi untuk menggunakan alur autentikasi berbasis web. |
Respons ini dianggap berhasil, tetapi aplikasi diperlukan untuk beralih ke alur autentikasi berbasis web. Dalam hal ini, kami sarankan Anda menggunakan pustaka autentikasi yang dibuat dan didukung Microsoft.
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti ketika challenge_type parameter menyertakan jenis tantangan yang tidak valid atau validasi token kelanjutan gagal. |
expired_token |
Token kelanjutan kedaluwarsa. |
unsupported_challenge_type |
Nilai challenge_type parameter tidak menyertakan redirect jenis tantangan. |
Langkah 3: Kirim kode sandi satu kali
Aplikasi kemudian membuat permintaan POST ke /continue titik akhir. Dalam permintaan, aplikasi perlu menyertakan kredensial pengguna yang dipilih pada langkah sebelumnya dan token kelanjutan yang dikeluarkan dari /challenge titik akhir.
Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra dalam permintaan sebelumnya. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
grant_type |
Ya | Satu-satunya nilai yang valid adalah oob. |
oob |
Ya | Kode akses satu kali yang diterima pengguna pelanggan dalam email mereka. Ganti {otp_code} dengan kode akses satu kali yang diterima pengguna pelanggan dalam email mereka. Untuk mengirim ulang kode akses satu kali, aplikasi perlu membuat permintaan ke /challenge titik akhir lagi. |
Respons keberhasilan
Contoh:
HTTP/1.1 200 OK
Content-Type: application/json
{
"expires_in": 600,
"continuation_token": "czZCaGRSa3F0MzpnW...",
}
| Parameter | Deskripsi |
|---|---|
expires_in |
Waktu dalam detik sebelum continuation_token kedaluwarsa. Nilai expires_in maksimum adalah 600 detik. |
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
55200
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
suberror |
String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan lebih lanjut. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti validasi token kelanjutan gagal atau permintaan tidak menyertakan client_id parameter nilai ID klien kosong atau tidak valid atau administrator penyewa eksternal belum mengaktifkan SSPR dan email OTP untuk semua pengguna penyewa. error_description Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
invalid_grant |
Jenis pemberian tidak diketahui atau tidak cocok dengan nilai jenis hibah yang diharapkan. suberror Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
expired_token |
Token kelanjutan kedaluwarsa. |
Jika parameter kesalahan memiliki nilai invalid_grant, Microsoft Entra menyertakan suberror parameter dalam responsnya. Berikut adalah nilai parameter yang suberror mungkin untuk kesalahan invalid_grant :
| Nilai suberor | Deskripsi |
|---|---|
invalid_oob_value |
Kode akses satu kali yang disediakan oleh pengguna tidak valid. |
Langkah 4: Kirim kata sandi baru
Aplikasi ini mengumpulkan kata sandi baru dari pengguna, lalu menggunakan token kelanjutan yang dikeluarkan oleh /continue titik akhir untuk mengirimkan kata sandi dengan membuat permintaan POST ke /submit titik akhir.
Berikut adalah contoh (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra dalam permintaan sebelumnya. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
new_password |
Ya | Kata sandi baru pengguna. Ganti {new_password} dengan kata sandi baru pengguna. Anda bertanggung jawab untuk mengonfirmasi bahwa pengguna mengetahui kata sandi yang ingin mereka gunakan dengan menyediakan bidang konfirmasi kata sandi di UI aplikasi. Anda juga harus memastikan bahwa pengguna mengetahui apa yang merupakan kata sandi yang kuat sesuai kebijakan organisasi Anda. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
Respons keberhasilan
Contoh:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"poll_interval": 2
}
| Parameter | Deskripsi |
|---|---|
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. |
poll_interval |
Jumlah waktu minimum dalam detik yang harus ditunggu aplikasi di antara permintaan polling untuk memeriksa status permintaan reset kata sandi melalui /poll_completion titik akhir, lihat langkah 5 |
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
suberror |
String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan lebih lanjut. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti validasi token kelanjutan gagal. |
expired_token |
Token kelanjutan kedaluwarsa. |
invalid_grant |
Pemberian yang dikirimkan tidak valid, seperti kata sandi yang dikirimkan terlalu singkat. suberror Gunakan parameter untuk mempelajari penyebab kesalahan yang tepat. |
Jika parameter kesalahan memiliki nilai invalid_grant, Microsoft Entra menyertakan suberror parameter dalam responsnya. Berikut adalah nilai parameter yang suberror mungkin:
| Nilai suberor | Deskripsi |
|---|---|
password_too_weak |
Kata sandi terlalu lemah karena tidak memenuhi persyaratan kompleksitas. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
password_too_short |
Kata sandi baru kurang dari 8 karakter. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
password_too_long |
Kata sandi baru lebih panjang dari 256 karakter. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
password_recently_used |
Kata sandi baru tidak boleh sama dengan kata sandi yang baru-baru ini digunakan. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
password_banned |
Kata sandi baru berisi kata, frasa, atau pola yang dilarang. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. |
password_is_invalid |
Kata sandi tidak valid, misalnya karena menggunakan karakter yang tidak diizinkan. Pelajari selengkapnya tentang kebijakan kata sandi Microsoft Entra. Respons ini dimungkinkan jika aplikasi mengirimkan kata sandi pengguna. |
Langkah 5: Polling untuk status reset kata sandi
Terakhir, karena memperbarui konfigurasi pengguna dengan kata sandi baru menimbulkan beberapa penundaan, aplikasi dapat menggunakan /poll_completion titik akhir untuk polling Microsoft Entra untuk status pengaturan ulang kata sandi. Jumlah waktu minimum dalam detik yang harus ditunggu aplikasi di antara permintaan polling dikembalikan dari /submit titik akhir dalam poll_interval parameter.
Berikut adalah contoh (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0...
| Parameter | Wajib | Deskripsi |
|---|---|---|
tenant_subdomain |
Ya | Subdomain penyewa eksternal yang Anda buat. Di URL, ganti {tenant_subdomain} dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda. |
continuation_token |
Ya | Token kelanjutan yang dikembalikan Microsoft Entra dalam permintaan sebelumnya. |
client_id |
Ya | ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra. |
Respons keberhasilan
Contoh:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "succeeded",
"continuation_token":"czZCaGRSa3F0..."
}
| Parameter | Deskripsi |
|---|---|
status |
Status permintaan reset kata sandi. Jika Microsoft Entra mengembalikan status gagal, aplikasi dapat mengirim ulang kata sandi baru dengan membuat permintaan lain ke /submit titik akhir dan menyertakan token kelanjutan baru. |
continuation_token |
Token kelanjutan yang dikembalikan Microsoft Entra. Jika status berhasil, aplikasi dapat menggunakan token kelanjutan yang dikembalikan Microsoft Entra untuk meminta token keamanan melalui /token titik akhir seperti yang dijelaskan di langkah 5 alur pendaftaran. Ini berarti bahwa setelah pengguna berhasil mereset kata sandi mereka, Anda dapat langsung memasukkannya ke aplikasi Anda tanpa memulai alur masuk baru. |
Berikut adalah kemungkinan status yang dikembalikan Microsoft Entra (kemungkinan nilai status parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
succeeded |
Reset kata sandi berhasil diselesaikan. |
failed |
Reset kata sandi gagal. Aplikasi dapat mengirim ulang kata sandi baru dengan membuat permintaan lain ke /submit titik akhir. |
not_started |
Reset kata sandi belum dimulai. Aplikasi dapat memeriksa status lagi nanti. |
in_progress |
Reset kata sandi sedang berlangsung. Aplikasi dapat memeriksa status lagi nanti. |
Respons kesalahan
Contoh:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "expired_token",
"error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan. |
timestamp |
Waktu kesalahan terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error parameter):
| Nilai kesalahan | Deskripsi |
|---|---|
invalid_request |
Validasi parameter permintaan gagal seperti validasi token kelanjutan gagal. |
expired_token |
Token kelanjutan kedaluwarsa. |
Langkah berikutnya
- Referensi OTP API email autentikasi asli.
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk