Referensi API autentikasi asli

Berlaku untuk: Lingkaran hijau dengan simbol tanda centang putih yang menunjukkan konten berikut berlaku untuk penyewa eksternal. Penyewa eksternal (pelajari selengkapnya)

autentikasi natif Microsoft Entra memungkinkan Anda menghosting antarmuka pengguna aplikasi Anda di aplikasi klien alih-alih mendelegasikan autentikasi ke browser, menghasilkan pengalaman autentikasi terintegrasi secara 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. Pelajari selengkapnya tentang SDK 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 alur autentikasi:

Email dengan kata sandi, yang mendukung pendaftaran dan masuk dengan email dan kata sandi, dan pengaturan ulang kata sandi mandiri (SSPR).
- Pengguna yang login dengan alamat email dan sandi juga akan login dengan nama pengguna dan sandi.
Kode akses satu kali email, yang mendukung pendaftaran dan masuk dengan kode akses satu kali email.

Catatan

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

Prasyarat

Penyewa eksternal Microsoft Entra. Jika Anda belum memilikinya, buat penyewa eksternal.
Jika Anda belum melakukannya, Register aplikasi di pusat admin Microsoft Entra. Pastikan untuk:
- Rekam ID Aplikasi (klien) dan ID Direktori (penyewa) untuk digunakan nanti.
- Memberikan persetujuan admin untuk aplikasi.
- Aktifkan klien publik dan alur autentikasi asli.
Jika Anda belum melakukannya, Buat alur pengguna di pusat admin Microsoft Entra. Saat Anda membuat alur pengguna, perhatikan atribut pengguna yang Anda konfigurasi sesuai kebutuhan karena atribut ini adalah atribut yang Microsoft Entra mengharapkan aplikasi Anda untuk dikirimkan.
Kaitkan pendaftaran aplikasi Anda dengan alur pengguna.
Untuk alur login, daftarkan pengguna pelanggan, yang Anda gunakan untuk menguji alur. Atau, Anda bisa mendapatkan pengguna uji ini setelah menjalankan alur pendaftaran.
Untuk alur SSPR, aktifkan pengaturan ulang kata sandi layanan mandiri untuk pengguna pelanggan di penyewa eksternal. SSPR tersedia untuk pengguna pelanggan yang menggunakan email dengan metode autentikasi kata sandi.
Jika Anda ingin mengizinkan pengguna yang login dengan alamat email dan sandi untuk juga login dengan nama pengguna dan sandi, gunakan langkah-langkah dalam artikel Login dengan alias atau nama pengguna :
1. Aktifkan nama pengguna pada masuk.
2. Buat pengguna dengan nama pengguna di pusat admin atau perbarui pengguna yang sudah ada dengan menambahkan nama pengguna. Atau, Anda juga dapat aplikasi pembuatan dan pembaruan pengguna di aplikasi Anda dengan menggunakan Microsoft Graph API.
Untuk menerapkan autentikasi multifaktor (MFA) untuk pelanggan Anda, gunakan langkah-langkah dalam Menambahkan autentikasi multifaktor (MFA) ke aplikasi untuk menambahkan MFA ke alur masuk Anda. Autentikasi asli mendukung kode akses satu kali email dan SMS sebagai faktor kedua untuk MFA.

Token kelanjutan

Setiap kali Anda memanggil titik akhir masuk, pendaftaran, atau SSPR, respons menyertakan token kelanjutan. Token ini secara unik mengidentifikasi alur saat ini dan memungkinkan Microsoft Entra ID mempertahankan status di seluruh titik akhirnya. Sertakan token dalam setiap permintaan berikutnya dalam alur tersebut. Ini hanya berlaku untuk waktu yang terbatas dan hanya dapat digunakan untuk permintaan berikutnya dalam alur yang sama.

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	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 challenge 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.
`oauth/v2.0/token`	Aplikasi memanggil titik akhir ini untuk akhirnya meminta token keamanan. Aplikasi perlu menggunakan token kelanjutan yang diperolehnya dari panggilan terakhir yang berhasil ke `/signup/v1.0/continue` titik akhir.

API memungkinkan aplikasi klien untuk mengiklankan metode autentikasi yang didukungnya, ketika 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.

Diagram urutan menunjukkan alur proses pendaftaran.

Diagram autentikasi asli alur pendaftaran.

Diagram ini menunjukkan bahwa aplikasi mengumpulkan nama pengguna (email), kata sandi (untuk email dengan alur 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 ke /signup/v1.0/start titik akhir. Jika aplikasi mengirimkan semua informasi yang diperlukan ke /signup/v1.0/start titik akhir, aplikasi tidak perlu melakukan panggilan dan menangani respons dalam langkah-langkah opsional.

Pada langkah 21, pengguna sudah mendaftar. Namun, jika aplikasi mengharuskan untuk secara otomatis memasukkan pengguna setelah pendaftaran, aplikasi memanggil oauth/v2.0/token titik akhir untuk meminta token keamanan.

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

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`username`	Ya	Email pengguna pelanggan yang ingin mereka daftarkan, seperti contoso-consumer@contoso.com.
`challenge_type`	Ya	Daftar string jenis tantangan otorisasi yang dipisahkan spasi yang didukung aplikasi seperti `oob password redirect`. Daftar harus selalu menyertakan `redirect` jenis tantangan. Nilai diharapkan untuk `oob redirect` atau `oob password redirect` untuk email dengan metode autentikasi kata sandi.
`password`	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.
`capabilities`	Tidak.	Bendera yang dipisahkan spasi yang menjelaskan kemampuan aplikasi klien. Meskipun `challenge_type` mendefinisikan metode apa yang dapat ditantang, `capabilities` beri tahu API autentikasi asli mana yang dapat ditangani oleh aplikasi klien alur tambahan dan UI mana yang dapat ditampilkan kepada pengguna. Misalnya, `mfa_required` berarti lain `/challenge` dan `/token` perulangan; `registration_required` berarti aplikasi klien memanggil API pendaftaran dan menampilkan UI pendaftaran. Jika kemampuan yang diperlukan tidak diiklankan oleh aplikasi klien, API akan mengembalikan pengalihan. Nilai yang didukung adalah `mfa_required` dan `registration_required`. Pelajari selengkapnya tentang kemampuan.

Respons keberhasilan

Berikut adalah contoh respons yang berhasil:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "AQABAAEAAA…",
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi yang dikembalikan Microsoft Entra.

Mengalihkan respons

Jika aplikasi klien tidak mendukung metode atau kemampuan autentikasi yang Microsoft Entra butuhkan, fallback ke alur autentikasi berbasis web diperlukan. Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan redirect dalam respons:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

Harta benda	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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.
`invalid_attributes`	Daftar (array objek) atribut yang gagal divalidasi. Respons ini dimungkinkan jika aplikasi mengirimkan atribut pengguna, dan `suberror` nilai properti 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 properti):

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 properti untuk mempelajari penyebab pasti kesalahan.
`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 properti untuk mempelajari penyebab pasti kesalahan. Parameter ini hanya berlaku untuk email dengan metode autentikasi kata sandi.

Jika parameter kesalahan memiliki nilai invalid_grant, Microsoft Entra menyertakan properti suberror dalam responsnya. Berikut adalah nilai properti 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 properti suberror dalam responsnya. Berikut adalah nilai properti yang suberror mungkin untuk kesalahan invalid_client :

Nilai suberor	Deskripsi
`nativeauthapi_disabled`	ID klien untuk aplikasi yang tidak diaktifkan untuk autentikasi asli.

Catatan

Jika Anda mengirimkan semua atribut yang diperlukan melalui /signup/v1.0/start titik akhir, tetapi tidak semua atribut opsional, Anda tidak akan dapat mengirimkan atribut opsional tambahan nanti melalui /signup/v1.0/continue titik akhir. Microsoft Entra tidak secara eksplisit meminta atribut opsional karena tidak wajib untuk menyelesaikan alur pendaftaran. Lihat tabel di bagian Mengirimkan atribut pengguna ke titik akhir untuk mempelajari atribut pengguna yang dapat Anda kirimkan ke /signup/v1.0/start titik akhir dan /signup/v1.0/continue .

Langkah 2: Pilih metode autentikasi

Aplikasi 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…

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`challenge_type`	Tidak.	Daftar string jenis tantangan otorisasi 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 Kontinuasi yang Microsoft Entra dikembalikan dalam permintaan sebelumnya.

Respons keberhasilan

Microsoft Entra mengirim kode akses satu kali ke email pengguna, lalu merespons dengan jenis tantangan dengan nilai oob dan informasi tambahan tentang kode sandi 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
}

Harta benda	Deskripsi
`interval`	Lamanya waktu dalam detik yang dibutuhkan aplikasi untuk menunggu sebelum mencoba mengirim ulang OTP.
`continuation_token`	token Kontinuasi 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 Microsoft Entra hasilkan.

Mengalihkan respons

HTTP/1.1 200 OK
Content-Type: application/json

{
   "challenge_type": "redirect"
}

Harta benda	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 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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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}

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan 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 titik akhir `/signup/v1.0/start`, dan tidak ada atribut yang dikonfigurasi di pusat admin Microsoft Entra atau semua atribut pengguna yang diperlukan dikirimkan melalui titik akhir `/signup/v1.0/start`.	Microsoft Entra mengeluarkan token kelanjutan. Aplikasi dapat menggunakan token kelanjutan untuk meminta token keamanan seperti yang ditunjukkan dalam Meminta token keamanan.
Aplikasi berhasil mengirimkan kata sandi pengguna(untuk email dengan metode autentikasi kata sandi) melalui `/signup/v1.0/start`, tetapi tidak semua atribut pengguna yang diperlukan, Microsoft Entra menunjukkan atribut yang perlu dikirimkan aplikasi seperti yang ditunjukkan dalam atribut pengguna yang diperlukan.	Aplikasi perlu mengirimkan atribut pengguna yang diperlukan melalui `/signup/v1.0/continue` titik akhir. Responsnya mirip dengan yang diperlukan dalam atribut Pengguna. Kirim atribut pengguna yang ditunjukkan dalam mengirimkan atribut pengguna.
Aplikasi tidak mengirimkan kata sandi pengguna (untuk email dengan metode autentikasi kata sandi) melalui `/signup/v1.0/start` titik akhir.	respons Microsoft Entra menunjukkan bahwa kredensial diperlukan. Lihat respons. Respons ini dimungkinkan untuk email dengan metode autentikasi kata sandi.

Respons

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "credential_required",
    "error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
    "error_codes": [
        55103
    ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABEQEAAAA..."
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.
`continuation_token`	token Kontinuasi 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 properti):

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.

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…

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`challenge_type`	Tidak.	Daftar string jenis tantangan otorisasi Daftar harus selalu menyertakan `redirect` jenis tantangan. Untuk email dengan alur pendaftaran kata sandi, nilai diharapkan berisi `password redirect`.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan 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..."
}

Harta benda	Deskripsi
`challenge_type`	kata sandi dikembalikan dalam respons untuk kredensial yang diperlukan.
`continuation_token`	token Kontinuasi yang dikembalikan Microsoft Entra.

Mengalihkan respons

HTTP/1.1 200 OK
Content-Type: application/json

{     
    "challenge_type": "redirect" 
}

Harta benda	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.

Aplikasi perlu mengirimkan kredensial pengguna, dalam hal ini kata sandi, yang Microsoft Entra diminta pada 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}

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan pada 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 titik akhir /signup/v1.0/start, aplikasi mendapatkan token kelanjutan tanpa mengirimkan atribut apa pun. Aplikasi dapat menggunakan token kelanjutan untuk meminta token keamanan seperti yang ditunjukkan dalam Meminta token keamanan. Jika tidak, respons Microsoft Entra menunjukkan bahwa aplikasi perlu mengirimkan atribut yang diperlukan. Atribut ini, bawaan atau kustom, dikonfigurasi di pusat admin Microsoft Entra oleh administrator penyewa.

Atribut pengguna diperlukan

Respons ini meminta aplikasi untuk mengirimkan nilai untuk atribut nama, usia, dan telepon .

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "attributes_required",
    "error_description": "User attributes required",
    "error_codes": [
            55106
        ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABAAEAAAAtn...",
    "required_attributes": [
        {
            "name": "displayName",
            "type": "string",
            "required": true,
            "options": {
              "regex": ".*@.**$"
            }
        },
        {
            "name": "extension_2588abcdwhtfeehjjeeqwertc_age",
            "type": "string",
            "required": true
        },
        {
            "name": "postalCode",
            "type": "string",
            "required": true,
            "options": {
              "regex":"^[1-9][0-9]*$"
            }
        }
    ],
}

Catatan

Atribut kustom (juga dikenal sebagai ekstensi direktori) dinamai dengan menggunakan konvensi extension_{appId-without-hyphens}_{attribute-name} di mana {appId-without-hyphens} adalah versi ID klien yang dilucuti untuk aplikasi ekstensi. Misalnya, jika ID klien aplikasi ekstensi adalah 2588a-bcdwh-tfeehj-jeeqw-ertc dan nama atribut adalah hobi, maka atribut kustom dinamai sebagaiextension_2588abcdwhtfeehjjeeqwertc_hobbies. Pelajari selengkapnya tentang atribut kustom dan aplikasi ekstensi.

Harta benda	Deskripsi
`error`	Atribut ini diatur jika Microsoft Entra tidak dapat membuat akun pengguna karena atribut perlu diverifikasi atau dikirimkan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.
`continuation_token`	token Kontinuasi 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 parameter `error`attributes_required.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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.

Mengalihkan respons

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

Harta benda	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 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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.
`suberror`	String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan lebih lanjut.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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 properti untuk mempelajari penyebab pasti kesalahan.
`expired_token`	Token kelanjutan kedaluwarsa.
`attributes_required`	Satu atau beberapa atribut pengguna diperlukan.

Jika parameter kesalahan memiliki nilai invalid_grant, Microsoft Entra menyertakan properti suberror dalam responsnya. Berikut adalah nilai properti 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}", "postalCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan 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 mendaftarkan pengguna, maka terapkan token kelanjutan. Aplikasi dapat menggunakan token kelanjutan untuk meminta token keamanan dari oauth/v2.0/token titik akhir.

HTTP/1.1 200 OK
Content-Type: application/json

{  
    "continuation_token": "AQABAAEAAAYn..."
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi yang dikembalikan Microsoft Entra.

Mengalihkan respons

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

Harta benda	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 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" 
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.
`continuation_token`	token Kontinuasi 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 ketika nilai parameter `error`attributes_required.
`invalid_attributes`	Daftar (array objek) atribut yang gagal divalidasi. Parameter ini disertakan dalam respons saat `suberror` nilai properti 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 properti):

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 properti untuk mempelajari penyebab pasti kesalahan.
`expired_token`	Token kelanjutan yang disertakan dalam permintaan kedaluwarsa.
`attributes_required`	Satu atau beberapa atribut pengguna diperlukan.

Nilai suberor	Deskripsi
`attribute_validation_failed`	Validasi atribut pengguna gagal. `invalid_attributes` parameter berisi daftar (array objek) atribut yang gagal divalidasi.

Jika pengguna harus masuk secara otomatis setelah pendaftaran, aplikasi membuat permintaan POST ke oauth/v2.0/token titik akhir dan menyediakan token kelanjutan yang diperoleh dari langkah sebelumnya untuk memperoleh token keamanan. Pelajari cara memanggil titik akhir token.

Mengirimkan atribut pengguna ke titik akhir

Di pusat admin Microsoft Entra, Anda dapat mengonfigurasi atribut pengguna sesuai kebutuhan atau opsional. Konfigurasi ini menentukan bagaimana Microsoft Entra merespons saat Anda melakukan panggilan ke titik akhirnya. Atribut opsional tidak wajib untuk menyelesaikan alur pendaftaran. Oleh karena itu, ketika semua atribut bersifat opsional, atribut harus dikirimkan sebelum nama pengguna diverifikasi. Jika tidak, pendaftaran selesai tanpa atribut opsional.

Tabel berikut ini meringkas kapan mungkin untuk mengirimkan atribut pengguna ke titik akhir Microsoft Entra.

Titik akhir	Atribut yang diperlukan	Atribut opsional	Atribut yang diperlukan dan opsional
`/signup/v1.0/start` Endpoint	Ya	Ya	Ya
`/signup/v1.0/continue` titik akhir sebelum verifikasi nama pengguna	Ya	Ya	Ya
`/signup/v1.0/continue` titik akhir setelah verifikasi nama pengguna	Ya	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 Centang Pilihan Ganda	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, NamaDisplay 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.

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, oauth/v2.0/initiate, , oauth/v2.0/challengeoauth/v2.0/token, dan secara oauth/v2.0/introspectopsional .

Titik akhir	Deskripsi
`oauth/v2.0/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.
`oauth/v2.0/challenge`	Aplikasi Anda memanggil titik akhir ini untuk meminta Microsoft Entra memilih salah satu jenis tantangan sign-in yang didukung agar pengguna dapat mengautentikasi. Di mana administrator penyewa memberlakukan MFA untuk pengguna pelanggan, aplikasi Anda memanggil titik akhir ini untuk menantang pengguna untuk metode autentikasi faktor kedua.
`oauth/v2.0/token`	Titik akhir ini memverifikasi kredensial pengguna yang diterimanya dari aplikasi Anda, lalu mengeluarkan token keamanan ke aplikasi Anda. Respons dari titik akhir ini juga dapat menunjukkan apakah pengguna perlu menyelesaikan tantangan MFA atau mendaftarkan metode autentikasi yang kuat.
`oauth/v2.0/introspect`	Aplikasi Anda memanggilnya untuk meminta daftar metode autentikasi kuat terdaftar untuk autentikasi multifaktor (MFA). Pelajari cara menggunakan titik akhir introspeksi

API memungkinkan aplikasi untuk mengiklankan metode autentikasi yang didukungnya, ketika 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.

Diagram urutan menunjukkan alur proses masuk. Alur masuk tergantung pada metode autentikasi pengguna.

Kode sekali pakai email
Email dengan kata sandi

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, kode sandi tersebut membatalkan kode yang dikirim sebelumnya.

Diagram masuk autentikasi asli dengan opsi email dan kata sandi.

Diagram ini menunjukkan bahwa aplikasi mengumpulkan nama pengguna (email) dan kata sandi dari pengguna pada waktu yang berbeda (dan mungkin di layar terpisah). Namun, Anda dapat merancang aplikasi untuk mengumpulkan dua nilai di layar yang sama.
Jika Anda mengumpulkan nama pengguna (email) dan kata sandi di layar yang sama, langkah dua dan tiga akan digabungkan dengan langkah delapan dan sembilan. Dalam hal ini, aplikasi menyimpan kata sandi, lalu mengirimkannya di langkah sepuluh jika diperlukan.

Jika administrator penyewa mengaktifkan MFA untuk pengguna penyewa, respons dari /oauth2/v2.0/token titik akhir bergantung pada apakah pengguna sudah memiliki metode autentikasi kuat yang terdaftar:

Jika pengguna memiliki metode autentikasi yang kuat terdaftar, maka mereka menyelesaikan alur tantangan MFA.
Jika pengguna tidak memiliki metode autentikasi yang kuat terdaftar, maka mereka menyelesaikan register untuk alur metode autentikasi yang kuat .

Diagram urutan ini menunjukkan jalur MFA. Ini mencakup kedua kasus: (1) pengguna sudah memiliki metode autentikasi yang kuat terdaftar, atau (2) pengguna tidak memiliki dan harus mendaftarkan satu just-in-time. Alur dimulai setelah aplikasi mengumpulkan kata sandi yang benar dari pengguna dan memanggil /oauth2/v2.0/token, yang kemudian merespons yang menunjukkan apakah pengguna perlu menyelesaikan MFA atau mendaftarkan metode autentikasi yang kuat.

Diagram metode autentikasi pendaftaran titik akhir token panggilan autentikasi asli atau MFA lengkap.

Di bagian berikut, kami meringkas alur masuk menjadi tiga langkah dasar.

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
&capabilities=registration_required mfa_required

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`username`	Ya	Email pengguna pelanggan seperti contoso-consumer@contoso.com.
`challenge_type`	Ya	Daftar string jenis tantangan otorisasi 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.
`capabilities`	Tidak.	Bendera yang dipisahkan spasi yang menjelaskan kesiapan "bagaimana" aplikasi klien. Meskipun `challenge_type` mendefinisikan metode apa yang dapat ditantang, `capabilities` beri tahu API autentikasi asli mana yang dapat ditangani oleh aplikasi klien alur tambahan dan UI mana yang dapat ditampilkan. Misalnya, `mfa_required` berarti `/introspect`, `/challenge`, dan `/token` perulangan; `registration_required` berarti aplikasi klien memanggil API pendaftaran dan menampilkan UI pendaftaran. Jika kemampuan yang diperlukan tidak disertakan oleh aplikasi klien, API akan mengembalikan pengalihan. Nilai yang didukung adalah `mfa_required` dan `registration_required`. Pelajari selengkapnya tentang kemampuan.

Respons keberhasilan

Berikut adalah contoh respons yang berhasil:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi yang dikembalikan Microsoft Entra.

Mengalihkan respons

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

Harta benda	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 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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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 properti untuk mempelajari penyebab pasti kesalahan.
`user_not_found`	Nama pengguna tidak ada.
`unsupported_challenge_type`	Nilai `challenge_type` parameter tidak menyertakan `redirect` jenis tantangan.

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 mengautentikasi atau menyelesaikan tantangan MFA. Aplikasi ini membuat permintaan POST ke /oauth2/v2.0/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...

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan dalam permintaan sebelumnya. Permintaan sebelumnya memanggil `/oauth2/v2.0/initiate` titik akhir, atau `/oauth2/v2.0/introspect` titik akhir jika pengguna menyelesaikan tantangan MFA.
`challenge_type`	Tidak.	Daftar string jenis tantangan otorisasi 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.
`id`	Tidak.	Pengidentifikasi string dari metode autentikasi kuat yang dikembalikan dari `/oauth2/v2.0/introspect` titik akhir. Parameter ini diperlukan ketika aplikasi klien menantang pengguna untuk autentikasi faktor kedua. Pelajari cara menggunakan titik akhir introspeksi.

Respons keberhasilan

Respons keberhasilan tergantung pada metode autentikasi pengguna.

Kode sekali pakai email
Email dengan kata sandi

Jika administrator penyewa mengonfigurasi kode akses satu kali email di pusat admin Microsoft Entra sebagai metode autentikasi pengguna, Microsoft Entra mengirim 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
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi 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 Microsoft Entra hasilkan.

Jika administrator penyewa mengonfigurasi email dengan kata sandi di pusat admin Microsoft Entra sebagai metode autentikasi pengguna, respons bergantung pada apakah permintaan ke titik akhir /oauth2/v2.0/challenge adalah memilih metode bagi pengguna untuk mengautentikasi dengan atau menyelesaikan tantangan MFA.

Respons jika permintaan adalah memilih metode autentikasi

Jika permintaan ke titik akhir /oauth2/v2.0/challenge adalah memilih metode bagi pengguna untuk mengautentikasi dengan (autentikasi faktor pertama), Microsoft Entra mengembalikan respons keberhasilan, yang mencakup jenis tantangan password.

Contoh:

HTTP/1.1 200 OK
Content-Type: application/json

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi yang dikembalikan Microsoft Entra.
`challenge_type`	Microsoft Entra mengembalikan jenis tantangan yang didukung yang dikonfigurasi untuk pengguna di pusat admin Microsoft Entra. Dalam hal ini, nilai diharapkan menjadi kata sandi.

Respons jika permintaan adalah menyelesaikan tantangan MFA

Jika permintaan ke titik akhir /oauth2/v2.0/challenge adalah menyelesaikan tantangan MFA (autentikasi faktor kedua), Microsoft Entra mengirim kode akses satu kali ke saluran tantangan MFA yang dipilih pengguna dan memberikan informasi lebih lanjut 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
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi yang dikembalikan Microsoft Entra.
`challenge_type`	Jenis tantangan dipilih bagi pengguna untuk menyelesaikan MFA.
`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 tantangan MFA tempat kode sandi satu kali dikirim. Nilai yang didukung: email, sms.
`challenge_target_label`	Email yang dikaburkan tempat kode akses satu kali dikirim.
`code_length`	Panjang kode akses satu kali yang Microsoft Entra hasilkan.

Mengalihkan respons

Fallback ke alur autentikasi berbasis web mungkin diperlukan dalam skenario berikut:

Aplikasi klien tidak mendukung metode atau kemampuan autentikasi yang Microsoft Entra butuhkan.
Pengguna mencoba menggunakan SMS sebagai metode autentikasi yang kuat, tetapi perlindungan penipuan memblokir permintaan jika dianggap berisiko tinggi (hanya dalam email dengan autentikasi kata sandi).

Dalam skenario ini, Microsoft Entra menginformasikan aplikasi dengan mengembalikan jenis tantangan redirect dalam respons:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

Harta benda	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 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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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 oauth2/v2.0/token titik akhir dan memberikan kredensial pengguna yang dipilih pada 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=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
&scope=openid offline_access

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan dalam permintaan sebelumnya.
`grant_type`	Ya	Jenis pemberian. Saat Anda memanggil titik akhir token, nilai ini harus: - kata sandi untuk email dengan metode autentikasi kata sandi dalam alur masuk untuk memverifikasi autentikasi faktor pertama pengguna. - oob untuk metode autentikasi kode akses satu kali email dalam alur masuk. - continuation_token untuk masuk otomatis setelah alur pendaftaran. - continuation_token untuk masuk otomatis setelah alur pengaturan ulang kata sandi mandiri. - continuation_token setelah alur pendaftaran metode autentikasi yang kuat. - mfa_oob saat memverifikasi autentikasi faktor kedua pengguna.
`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 agar Microsoft Entra mengeluarkan token ID. Aplikasi ini perlu menyertakan cakupan offline_access agar Microsoft Entra mengeluarkan token refresh. Pelajari selengkapnya tentang Izin dan persetujuan di platform identitas Microsoft.
`password`	Tidak.	Nilai kata sandi yang dikumpulkan aplikasi dari pengguna. Ganti `{secure_password}` dengan nilai kata sandi yang dikumpulkan aplikasi dari pengguna. Parameter ini diperlukan jika metode autentikasi adalah email dengan kata sandi.
`oob`	Tidak.	Kode akses satu kali yang diterima pengguna melalui email. Diperlukan jika: - Metode autentikasi utama adalah kode akses satu kali email. - Aplikasi mengirimkan kode akses satu kali email untuk memenuhi tantangan MFA ketika metode autentikasi utama adalah email dengan kata sandi. Untuk mengirim ulang kode akses satu kali, panggil `/challenge` titik akhir lagi.
`username`	Tidak.	Email pengguna yang ingin mereka daftarkan, seperti contoso-consumer@contoso.com. Parameter ini diperlukan dalam alur pendaftaran.

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..."
}

Harta benda	Deskripsi
`token_type`	Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung Microsoft Entra adalah Bearer.
`scopes`	Daftar cakupan yang dipisahkan spasi yang token aksesnya valid.
`expires_in`	Lamanya waktu dalam detik token akses tetap valid.
`access_token`	Token akses yang diminta aplikasi dari `/token` titik akhir. Aplikasi ini dapat menggunakan token akses ini untuk meminta akses ke sumber daya aman seperti API web.
`refresh_token`	Token refresh OAuth 2.0. Aplikasi dapat menggunakan token ini untuk memperoleh token akses lain setelah token akses saat ini kedaluwarsa. Token refresh berumur panjang. Mereka dapat mempertahankan akses ke sumber daya untuk waktu yang lama. Untuk detail selengkapnya tentang merefresh token akses, lihat Merefresh token akses. Catatan: Hanya dikeluarkan jika Anda meminta cakupan offline_access .
`id_token`	JSON Web Token (Jwt) yang digunakan untuk mengidentifikasi pengguna. Aplikasi dapat mendekode token untuk meminta informasi tentang pengguna yang masuk. Aplikasi dapat menyimpan nilai dan menampilkannya, dan klien rahasia dapat menggunakan token ini untuk otorisasi. Untuk informasi selengkapnya tentang token ID, lihat token ID di platform identitas Microsoft. 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"
}

Harta benda	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 kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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, kredensial masuk pengguna yang disertakan dalam permintaan tidak valid, interaksi lebih lanjut yang diperlukan dari pengguna, 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.
`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.

Nilai suberor	Deskripsi
`invalid_oob_value`	Nilai kode akses satu kali yang dikirimkan aplikasi tidak valid.
`mfa_required`	MFA diperlukan. Respons mencakup token kelanjutan. `oauth2/v2.0/introspect` Panggil titik akhir untuk mendapatkan metode autentikasi kuat yang terdaftar dari pengguna. Suberror ini hanya terjadi ketika metode autentikasi utama pengguna adalah email dengan kata sandi. Lihat cara mendapatkan metode autentikasi kuat pengguna yang terdaftar. Catatan: Dalam beberapa kasus MFA diperlukan tetapi autentikasi asli tidak mengembalikan `mfa_required`. atau misalnya, jika alur pendaftaran metode autentikasi yang kuat mendahului panggilan ke `/oauth2/v2.0/token` dan satu-satunya metode (email) yang tersedia sudah diverifikasi selama alur tersebut.
`registration_required`	Pengguna harus menyelesaikan tantangan MFA tetapi tidak memiliki metode autentikasi yang kuat yang terdaftar. Minta pengguna untuk mendaftarkan pengguna. Kesalahan ini terjadi ketika metode autentikasi utama pengguna adalah email dengan kata sandi. Pelajari cara mendaftarkan metode autentikasi yang kuat.

Mengalihkan respons

HTTP/1.1 200 OK
Content-Type: application/json

{     
    "challenge_type": "redirect",
    "redirect_reason": "Client is missing registration_required capability"
}

Harta benda	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.
`redirect_reason`	Alasan pengalihan diperlukan. Misalnya, Microsoft Entra mendeteksi bahwa MFA atau pendaftaran untuk metode autentikasi yang kuat diperlukan, tetapi aplikasi tidak menyertakan kemampuan ini dalam permintaannya.

Mendapatkan metode autentikasi kuat yang terdaftar pengguna

oauth2/v2.0/introspect Gunakan titik akhir untuk meminta daftar metode autentikasi kuat terdaftar pengguna.

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/introspect
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan dalam permintaan sebelumnya.

Respons keberhasilan

Contoh:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"c***r@co**o**o.com"
        },
        {   
          "id": "1b1b1b1b-2222-cccc-3333-4d4d4d4d4d4d",   
          "challenge_type": "oob",   
          "challenge_channel": "sms",   
          "login_hint": "+1********6"
        }
    ]
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi yang dikembalikan Microsoft Entra.
`methods`	Daftar (objek) metode autentikasi kuat yang terdaftar pengguna.

Objek metode MFA memiliki properti berikut:

Harta benda	Deskripsi
`id`	Pengidentifikasi string unik yang dibuat secara otomatis untuk metode MFA. Aplikasi ini menggunakan string ini seperti `id` saat memanggil `/oauth2/v2.0/challenge` titik akhir.
`challenge_type`	Jenis tantangan dipilih bagi pengguna untuk digunakan sebagai metode MFA. Jenis tantangan yang didukung saat ini adalah oob.
`challenge_channel`	Jenis saluran tempat metode MFA dikirim. Saluran tantangan yang didukung saat ini adalah email.
`login_hint`	Petunjuk untuk metode autentikasi yang kuat seperti email yang dikaburkan.

Mengalihkan respons

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

Respons kesalahan

Contoh:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

Nilai kesalahan	Deskripsi
`invalid_request`	Validasi parameter permintaan gagal. Untuk memahami apa yang terjadi, gunakan pesan dalam deskripsi kesalahan.
`invalid_client`	ID klien yang disertakan dalam permintaan bukan untuk klien publik.
`expired_token`	Token kelanjutan yang disertakan dalam permintaan kedaluwarsa.
`server_error`	Terjadi kesalahan dengan permintaan tersebut.

Setelah aplikasi klien berhasil mengambil daftar metode autentikasi kuat yang terdaftar untuk pengguna, pengguna memilih metode yang ingin mereka gunakan untuk menyelesaikan tantangan MFA. Alur kemudian dilanjutkan sebagai berikut:

Aplikasi klien memanggil /oauth2/v2.0/challenge dan menyertakan token kelanjutan yang diperoleh dari /oauth2/v2.0/introspect dan id metode pilihan MFA:

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
&id=0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c 
&continuation_token=uY29tL2F1dGhlbnRpY...

Microsoft Entra mengirim kode tantangan ke saluran tantangan pengguna, seperti email, lalu merespons kembali ke aplikasi klien dengan token kelanjutan dan detail tantangan MFA:

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
}

Aplikasi sekarang dapat membuat permintaan POST ke /oauth2/v2.0/token titik akhir dan menyertakan token kelanjutan, jenis pemberian yang benar, dan nilai jenis pemberian yang sesuai untuk mendapatkan token keamanan. Lihat respons yang diharapkan dalam Meminta token keamanan:

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded    
client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&continuation_token=uY29tL2F1dGhlbnRpY...   
&grant_type=mfa_oob  
&oob={otp_code}
&scope=openid offline_access

Mendaftarkan referensi API metode autentikasi yang kuat

Autentikasi asli mendukung pendaftaran metode autentikasi yang kuat. Ketika aplikasi memanggil titik akhir /oauth2/v2.0/token dan MFA diperlukan tetapi pengguna tidak memiliki metode kuat terdaftar, respons, registeration_required, memberi tahu aplikasi agar pengguna mendaftarkannya sebelum token dapat dikeluarkan.

Setelah aplikasi klien menyelesaikan alur untuk mendaftarkan metode autentikasi yang kuat, aplikasi ini memanggil /oauth2/v2.0/token titik akhir untuk meminta token keamanan.

Titik akhir pendaftaran metode autentikasi yang kuat

Untuk menggunakan API pendaftaran metode autentikasi yang kuat, aplikasi menggunakan titik akhir yang ditunjukkan dalam tabel berikut:

Titik akhir	Deskripsi
`/register/v1.0/introspect`	Panggil titik akhir ini untuk mengambil daftar metode autentikasi kuat yang dapat didaftarkan pengguna.
`/register/v1.0/challenge`	Panggil titik akhir ini untuk mengirim tantangan kepada pengguna, seperti kode akses satu kali email.
`/register/v1.0/continue`	Panggil titik akhir ini untuk mengirimkan tantangan yang dikumpulkan aplikasi dari pengguna, seperti kode sandi satu kali, untuk menyelesaikan alur untuk mendaftarkan metode autentikasi yang kuat. Setelah panggilan berhasil dan Anda mendapatkan token kelanjutan, panggil `/oauth2/v2.0/token` titik akhir titik akhir untuk meminta token keamanan. Pelajari cara memanggil titik akhir token.

Langkah 1: Dapatkan daftar metode autentikasi yang kuat

Alur pendaftaran dimulai ketika aplikasi meminta daftar metode autentikasi yang kuat yang diizinkan pengguna untuk mendaftar.

Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/introspect
Content-Type: application/x-www-form-urlencoded
?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.

Respons keberhasilan

Berikut adalah contoh respons yang berhasil:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"email",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"caseyjensen@contoso.com"
        },
        {   
          "id": "sms",   
          "challenge_type": "oob",   
          "challenge_channel": "sms"
        }
    ]
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi yang dikembalikan Microsoft Entra.
`methods`	Daftar (objek) metode autentikasi kuat yang tersedia untuk pengguna untuk mendaftar.

Objek metode autentikasi yang kuat memiliki properti berikut:

Harta benda	Deskripsi
`id`	Kunci string metode. Email nilai yang didukung, sms.
`challenge_type`	Jenis tantangan dipilih bagi pengguna untuk digunakan sebagai metode MFA. Jenis tantangan yang didukung saat ini adalah oob.
`challenge_channel`	Jenis saluran tempat metode MFA dikirim. Email nilai yang didukung, sms.
`login_hint`	Petunjuk untuk metode autentikasi yang kuat seperti email. Nilai ini digunakan oleh aplikasi klien untuk mengisi kotak teks email terlebih dahulu.

Respons kesalahan

Contoh:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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 OTP email untuk semua pengguna penyewa.
`expired_token`	Token kelanjutan yang disertakan dalam permintaan kedaluwarsa.

Langkah 2: Pilih metode autentikasi yang kuat

Dalam langkah ini, kirimkan metode autentikasi kuat yang ingin didaftarkan pengguna. Microsoft Entra kemudian mengirimkan tantangan, seperti kode akses satu kali email, kepada pengguna.

Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/challenge 

?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  
&challenge_type=oob  
&challenge_channel=email 
&challenge_target=contoso-consumer@contoso.com

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`continuation_token`	Ya	Token Kontinuasi yang Microsoft Entra kembali dari titik akhir `/register/v1.0/introspect`
`challenge_type`	Ya	Jenis tantangan metode autentikasi. Jenis saat ini adalah oob.
`challenge_target`	Ya	Email atau nomor telepon yang ingin didaftarkan pengguna.
`challenge_channel`	Tidak.	Saluran untuk mengirimkan tantangan. Nilai saluran tantangan yang didukung: email, sms.

Respons keberhasilan

Berikut adalah contoh respons yang berhasil.

Contoh 1:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...", 
  "challenge_type": "oob", 
  "binding_method": "prompt", 
  "challenge_target": "contoso-consumer@contoso.com", 
  "challenge_channel": "email", 
  "code_length": 8 
}

Contoh 2:

Jika alur pendaftaran mendahului alur pendaftaran metode autentikasi yang kuat dan email yang dikirimkan ke /register/v1.0/challenge titik akhir cocok dengan yang diverifikasi dalam alur pendaftaran, API autentikasi asli mendaftarkan metode tanpa mengirim tantangan kepada pengguna. Dalam hal ini, respons akan terlihat mirip dengan cuplikan berikut:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "preverified" 
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi yang dikembalikan Microsoft Entra.
`challenge_type`	Jenis tantangan yang dipilih agar pengguna dapat mengautentikasi dengan, seperti oob, atau diverifikasi sebelumnya jika metode autentikasi yang kuat diverifikasi sebelumnya.
`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 dan metode autentikasi yang kuat tidak diverifikasi sebelumnya.
`challenge_channel`	Jenis saluran tempat kode akses satu kali dikirim. Email nilai yang didukung, sms. Dikembalikan jika metode autentikasi yang kuat tidak diverifikasi sebelumnya.
`code_length`	Panjang kode akses satu kali jika `binding_method` diminta. Dikembalikan jika metode autentikasi yang kuat tidak diverifikasi sebelumnya.
`challenge_target`	Target tantangan dikirim. Ini sama dengan input yang disediakan dalam permintaan. Dikembalikan jika metode autentikasi yang kuat tidak diverifikasi sebelumnya.
`interval`	Interval (dalam detik) klien harus menunggu antara polling /register/continue. Hanya Dikembalikan jika `prompt=none` dan metode autentikasi yang kuat tidak diverifikasi sebelumnya. Klien harus menggandakan interval setiap kali mereka menerima `HTTP 429` dari API autentikasi asli.

Respons kesalahan

Kesalahan di sini mirip dengan yang dapat Anda alami saat memanggil /register/v1.0/introspect titik akhir. Namun, saat mendaftarkan nomor telepon, jika nomor telepon dianggap berisiko tinggi, permintaan dapat diblokir.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui jika permintaan diblokir:

Nilai kesalahan	Deskripsi
`access_denied`	SMS telah diblokir.

Jika parameter kesalahan memiliki nilai access_denied, Microsoft Entra menyertakan properti suberror dalam responsnya. Berikut adalah nilai yang mungkin dari properti suberror untuk kesalahan invalid_grant:

Nilai suberor	Deskripsi
`provider_blocked_by_admin`	Administrator penyewa telah memblokir wilayah telepon.
`provider_blocked_by_rep`	Metode autentikasi multifaktor diblokir (nomor telepon diblokir oleh RepMap).

Langkah 3: Kirim tantangan

Dalam langkah ini, lakukan panggilan ke /register/v1.0/continue titik akhir untuk menyelesaikan pendaftaran metode autentikasi yang kuat.

Berikut adalah contoh permintaan (kami menyajikan contoh permintaan dalam beberapa baris untuk keterbacaan):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/continue 

?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  
&grant_type=oob  
&oob={otp_code}

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan dalam permintaan sebelumnya.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`grant_type`	Ya	Jenis pemberian. Nilai yang didukung saat ini adalah oob, atau continuation_token jika metode autentikasi yang kuat diverifikasi sebelumnya di `/register/v1.0/challenge` titik akhir.
`oob`	Tidak.	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 `/register/v1.0/challenge` titik akhir lagi. Diperlukan jika metode autentikasi yang kuat tidak diverifikasi sebelumnya di `/register/v1.0/challenge` titik akhir.

Respons keberhasilan

Berikut adalah contoh respons yang berhasil:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Harta benda	Deskripsi
`continuation_token`	Token kontinuasi yang Microsoft Entra kembalikan. Gunakan token kelanjutan ini untuk memanggil `/oauth2/v2.0/token` titik akhir untuk meminta token keamanan. Pelajari cara memanggil titik akhir token.

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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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

Nilai suberor	Deskripsi
`invalid_oob_value`	Nilai kode akses satu kali tidak valid.

Pengaturan ulang kata sandi mandiri (SSPR)

Untuk pengguna yang metode autentikasi utamanya adalah email dengan kata sandi, gunakan API pengaturan ulang kata sandi mandiri (SSPR) untuk memungkinkan pengguna pelanggan mengatur ulang kata sandi mereka. Anda dapat menggunakan API ini untuk lupa kata sandi atau mengubah skenario kata sandi.

Titik akhir API untuk pengaturan ulang sandi layanan mandiri

Untuk menggunakan API ini, aplikasi menggunakan titik akhir yang diperlihatkan dalam tabel berikut:

Titik akhir	Deskripsi
`/resetpassword/v1.0/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.
`/resetpassword/v1.0/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.
`/resetpassword/v1.0/continue`	Memvalidasi tantangan yang dikeluarkan oleh `/resetpassword/v1.0/challenge` titik akhir, lalu mengembalikan token kelanjutan untuk `/resetpassword/v1.0/submit` titik akhir, atau mengeluarkan tantangan lain kepada pengguna.
`/resetpassword/v1.0/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.
`/resetpassword/v1.0/poll_completion`	Aplikasi dapat menggunakan token kelanjutan yang dikeluarkan oleh `/resetpassword/v1.0/submit` titik akhir untuk memeriksa status permintaan reset kata sandi.
`oauth2/v2.0/token`	Jika reset kata sandi berhasil, aplikasi dapat menggunakan token kelanjutan yang diperolehnya dari `/resetpassword/v1.0/poll_completion` titik akhir untuk mendapatkan token keamanan dari `oauth2/v2.0/token` titik akhir.

Jenis tantangan pengaturan ulang kata sandi mandiri

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 /resetpassword/v1.0/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 /resetpassword/v1.0/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

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`username`	Ya	Email pengguna pelanggan seperti contoso-consumer@contoso.com.
`challenge_type`	Ya	Daftar string jenis tantangan otorisasi Daftar harus selalu menyertakan `redirect` jenis tantangan. Untuk permintaan ini, nilai diharapkan berisi `oob redirect`.
`capabilities`	Tidak.	Bendera yang dipisahkan spasi yang menjelaskan kesiapan "bagaimana" aplikasi klien. Meskipun `challenge_type` mendefinisikan metode apa yang dapat ditantang, `capabilities` beri tahu API autentikasi asli mana yang dapat ditangani oleh aplikasi klien alur tambahan dan UI mana yang dapat ditampilkan. Misalnya, `mfa_required` berarti lain `/challenge` dan `/token` perulangan; `registration_required` berarti aplikasi klien memanggil API pendaftaran dan menampilkan UI pendaftaran. Jika kemampuan yang diperlukan tidak diiklankan oleh aplikasi klien, API akan mengembalikan pengalihan. Nilai yang didukung adalah `mfa_required` dan `registration_required`. Pelajari selengkapnya tentang kemampuan.

Respons keberhasilan

Contoh:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi yang dikembalikan Microsoft Entra.

Mengalihkan respons

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

Harta benda	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 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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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 properti untuk mempelajari penyebab pasti kesalahan.
`unauthorized_client`	ID klien yang digunakan dalam permintaan memiliki format ID klien yang valid, tetapi tidak ada di penyewa eksternal atau salah.

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 /resetpassword/v1.0/challenge titik akhir. Jika permintaan ini berhasil, Microsoft Entra mengirim 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=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`client_id`	Ya	ID Aplikasi (klien) aplikasi yang Anda daftarkan di pusat admin Microsoft Entra.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan dalam permintaan sebelumnya.
`challenge_type`	Tidak.	Daftar string jenis tantangan otorisasi 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
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi 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. Jika MFA diaktifkan untuk pengguna, email yang berisi kode sandi satu kali dikirim ke: - alamat email yang digunakan sebagai metode autentikasi yang kuat ketika alamat email berbeda dari alamat email akun. - alamat email akun ketika metode autentikasi yang kuat adalah SMS.
`code_length`	Panjang kode akses satu kali yang Microsoft Entra hasilkan.

Mengalihkan respons

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}

Harta benda	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 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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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 /resetpassword/v1.0/continue titik akhir. Dalam permintaan, aplikasi perlu menyertakan kredensial pengguna yang dipilih pada langkah sebelumnya dan token kelanjutan yang dikeluarkan dari /resetpassword/v1.0/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}

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan 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 `/resetpassword/v1.0/challenge` titik akhir lagi.

Respons keberhasilan

Contoh:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
}

Harta benda	Deskripsi
`expires_in`	Waktu dalam detik sebelum continuation_token kedaluwarsa. Nilai `expires_in` maksimum adalah 600 detik.
`continuation_token`	token Kontinuasi 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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.
`suberror`	String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan lebih lanjut.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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 properti untuk mempelajari penyebab pasti kesalahan.
`expired_token`	Token kelanjutan kedaluwarsa.

Nilai suberor	Deskripsi
`invalid_oob_value`	Nilai kode akses satu kali tidak valid.

Langkah 4: Kirim kata sandi baru

Aplikasi ini mengumpulkan kata sandi baru dari pengguna, lalu menggunakan token kelanjutan yang dikeluarkan oleh /resetpassword/v1.0/continue titik akhir untuk mengirimkan kata sandi dengan membuat permintaan POST ke /resetpassword/v1.0/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}

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan 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
}

Harta benda	Deskripsi
`continuation_token`	token Kontinuasi 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 `/resetpassword/v1.0/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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.
`suberror`	String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan lebih lanjut.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

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 properti untuk mempelajari penyebab pasti kesalahan.

Jika parameter kesalahan memiliki nilai invalid_grant, Microsoft Entra menyertakan properti suberror dalam responsnya. Berikut adalah nilai properti 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 titik akhir /resetpassword/v1.0/poll_completion 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 /resetpassword/v1.0/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...

Pengaturan	Wajib	Deskripsi
`tenant_subdomain`	Ya	Subdomain penyewa eksternal yang Anda buat. Di URL, ganti `{tenant_subdomain}` dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki subdomain penyewa, pelajari cara membaca detail penyewa Anda.
`continuation_token`	Ya	token Kontinuasi yang Microsoft Entra dikembalikan 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..."
}

Harta benda Deskripsi

status Status permintaan reset kata sandi. Jika Microsoft Entra mengembalikan status failed, aplikasi dapat mengirim ulang kata sandi baru dengan membuat permintaan lain ke titik akhir />

continuation_token token Kontinuasi yang dikembalikan Microsoft Entra. Jika statusnya succeeded, aplikasi dapat menggunakan token kelanjutan yang Microsoft Entra kembali untuk meminta token keamanan melalui titik akhir oauth2/v2.0/token seperti yang dijelaskan dalam Request untuk token keamanan. 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 Microsoft Entra kembalikan (kemungkinan nilai parameter status):

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 `/resetpassword/v1.0/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"
}

Harta benda	Deskripsi
`error`	Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan.
`error_description`	Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
`error_codes`	Daftar kode kesalahan khusus Microsoft Entra yang dapat membantu Anda mendiagnosis kesalahan.
`timestamp`	Waktu kesalahan terjadi.
`trace_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu Anda mendiagnosis kesalahan.
`correlation_id`	Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen.

Berikut adalah kemungkinan kesalahan yang dapat Anda temui (kemungkinan nilai error properti):

Nilai kesalahan	Deskripsi
`invalid_request`	Validasi parameter permintaan gagal seperti validasi token kelanjutan gagal.
`expired_token`	Token kelanjutan kedaluwarsa.

Jika pengguna perlu masuk setelah reset kata sandi berhasil. Aplikasi perlu memanggil /oauth2/v2.0/token titik akhir. Pelajari cara memanggil titik akhir token.

Mengonfigurasi penyedia klaim kustom.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-11

Bagikan melalui

Referensi API autentikasi asli

Prasyarat

Token kelanjutan

Referensi API untuk pendaftaran

Titik akhir API untuk pendaftaran

Jenis tantangan pendaftaran

Detail protokol alur pendaftaran

Langkah 1: Minta untuk memulai alur pendaftaran

Respons keberhasilan

Mengalihkan respons

Respons kesalahan

Langkah 2: Pilih metode autentikasi

Respons keberhasilan

Mengalihkan respons

Respons kesalahan

Langkah 3: Kirim kode sandi satu kali

Respons

Respons keberhasilan

Mengalihkan respons

Langkah 4: Mengautentikasi dan mendapatkan token untuk mendaftar

Respons keberhasilan

Atribut pengguna diperlukan

Mengalihkan respons

Respons kesalahan

Mengirimkan atribut pengguna

Respons keberhasilan

Mengalihkan respons

Respons kesalahan

Langkah 5: Masuk secara otomatis setelah pendaftaran

Mengirimkan atribut pengguna ke titik akhir

Format nilai atribut pengguna

Cara mereferensikan atribut pengguna

Referensi API untuk alur masuk

Titik akhir API untuk masuk

Jenis tantangan masuk

Detail protokol alur masuk

Langkah 1: Minta untuk memulai alur masuk

Respons keberhasilan

Mengalihkan respons

Respons kesalahan

Langkah 2: Pilih metode autentikasi

Respons keberhasilan

Mengalihkan respons

Respons kesalahan

Langkah 3: Meminta token keamanan

Respons berhasil

Respons kesalahan

Mengalihkan respons

Mendapatkan metode autentikasi kuat yang terdaftar pengguna

Respons keberhasilan

Mengalihkan respons

Respons kesalahan

Mendaftarkan referensi API metode autentikasi yang kuat

Titik akhir pendaftaran metode autentikasi yang kuat

Langkah 1: Dapatkan daftar metode autentikasi yang kuat

Respons keberhasilan

Respons kesalahan

Langkah 2: Pilih metode autentikasi yang kuat

Respons keberhasilan

Respons kesalahan

Langkah 3: Kirim tantangan

Respons keberhasilan

Respons kesalahan

Pengaturan ulang kata sandi mandiri (SSPR)

Titik akhir API untuk pengaturan ulang sandi layanan mandiri

Jenis tantangan pengaturan ulang kata sandi mandiri

Detail protokol alur pengaturan ulang kata sandi mandiri

Langkah 1: Minta untuk memulai alur pengaturan ulang kata sandi mandiri

Respons keberhasilan

Mengalihkan respons

Respons kesalahan

Langkah 2: Pilih metode autentikasi

Respons keberhasilan

Mengalihkan respons

Respons kesalahan

Langkah 3: Kirim kode sandi satu kali

Respons keberhasilan

Respons kesalahan

Langkah 4: Kirim kata sandi baru