Bagikan melalui


Referensi API autentikasi asli

Berlaku untuk: Lingkaran putih dengan simbol X abu-abu. Penyewa Tenaga Kerja Penyewa Lingkaran hijau dengan simbol tanda centang putih. 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/macOS 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.

Nota

Saat ini, titik akhir API autentikasi asli tidak mendukung Berbagi Sumber Daya Lintas Asal (CORS).

Prasyarat

  1. Penyewa eksternal Microsoft Entra. Jika Anda belum memilikinya, buat penyewa eksternal.

  2. 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.

  3. Jika Anda belum melakukannya, Buat alur pengguna di pusat admin Microsoft Entra. Saat Anda membuat alur pengguna, perhatikan atribut pengguna yang Anda konfigurasi sesuai kebutuhan karena atribut ini adalah atribut yang diharapkan microsoft Entra untuk dikirimkan oleh aplikasi Anda.

  4. Kaitkan pendaftaran aplikasi Anda dengan alur pengguna.

  5. Untuk alur masuk, daftarkan pengguna pelanggan, yang Anda gunakan untuk menguji API masuk. Atau, Anda bisa mendapatkan pengguna uji ini setelah menjalankan alur pendaftaran.

  6. Untuk alur SSPR, aktifkan pengaturan ulang kata sandi layanan mandiri untuk pengguna pelanggan di penyewa eksternal. 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

Endpoint 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 alur pendaftaran autentikasi asli.

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 Diperlukan 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 Tidak 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 Tidak 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [ 
        1003037 
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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.

Nota

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 Diperlukan 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 Tidak 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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 Diperlukan 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.

Jawaban

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 String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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 Diperlukan 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 Tidak 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 Diperlukan 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]*$"
            }
        }
    ],
}

Nota

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 ketika 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 di seluruh 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": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "suberror": "password_too_weak"
}
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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 Diperlukan 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [
        552003
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd" 
}
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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 Diperlukan 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 jangka 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 ini 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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.

Endpoint 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 Tidak 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
Kotak Teks  Satu nilai seperti jabatan, Insinyur Perangkat Lunak.
SingleRadioSelect Satu nilai seperti Bahasa, Norwegia. 
Kotak CentangMultiSelect 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

Endpoint Deskripsi
/initiate Titik akhir ini memulai alur masuk. Jika aplikasi Anda memanggilnya dengan nama pengguna akun pengguna yang sudah ada, aplikasi akan mengembalikan respons sukses dengan token kelanjutan. 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 aplikasi Anda memanggil titik akhir ini dengan daftar jenis tantangan yang didukung oleh layanan identitas. Layanan identitas kami menghasilkan, lalu mengirim kode akses satu kali ke saluran tantangan yang dipilih seperti email. Jika aplikasi Anda memanggil titik akhir ini berulang kali, OTP baru dikirim setiap kali panggilan dilakukan.
/token Titik akhir ini memverifikasi kode akses satu kali yang diterimanya dari aplikasi Anda, lalu mengeluarkan token keamanan ke aplikasi Anda.

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.

Diagram masuk autentikasi asli dengan kode akses satu kali email.

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 Diperlukan 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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 Diperlukan 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 Tidak 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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 Diperlukan 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 jangka 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 ini 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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:

Endpoint 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 alur pengaturan ulang kata sandi mandiri autentikasi asli.

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 Diperlukan 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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 Diperlukan 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 Tidak 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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 Diperlukan 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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 Diperlukan 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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 Diperlukan 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        552003 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan untuk bereaksi terhadap 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 ketika 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 di seluruh 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.