Natív hitelesítési API-referencia
A következőkre vonatkozik:
Munkaerő-bérlők 
Külső bérlők (további információ)
A Microsoft Entra natív hitelesítése lehetővé teszi, hogy az alkalmazás felhasználói felületét az ügyfélalkalmazásban tárolja ahelyett, hogy a hitelesítést a böngészőkre delegálja, ami natívan integrált hitelesítési élményt eredményez. Fejlesztőként teljes mértékben szabályozhatja a bejelentkezési felület megjelenését és megjelenését.
Ez az API-referenciacikk csak akkor szükséges részleteket ismertet, ha manuálisan hajt végre nyers HTTP-kéréseket a folyamat végrehajtásához. Ezt a megközelítést azonban nem javasoljuk. Ezért ha lehetséges, használjon microsoftos és támogatott hitelesítési SDK-t. További információ az SDK használatáról: Oktatóanyag: Android-mobilalkalmazás előkészítése natív hitelesítésre és oktatóanyag: Az iOS-mobilalkalmazás előkészítése natív hitelesítésre.
Ha az API-végpontokra irányuló hívás sikeres, egy azonosító jogkivonatot is kap a felhasználóazonosításhoz, valamint egy hozzáférési jogkivonatot a védett API-k meghívásához. Az API-ból érkező összes válasz JSON formátumban van.
A Microsoft Entra natív hitelesítési API-ja két hitelesítési módszerhez támogatja a regisztrációt és a bejelentkezést:
E-mail jelszóval, amely támogatja a regisztrációt és a bejelentkezést e-mailben és jelszóval, valamint az önkiszolgáló jelszó-visszaállítást (SSPR).
Egyszeri pin-kód küldése e-mailben, amely támogatja a regisztrációt és a bejelentkezést egyszeri pin-kóddal.
Feljegyzés
A natív hitelesítési API-végpontok jelenleg nem támogatják a forrásközi erőforrás-megosztást (CORS).
Előfeltételek
Microsoft Entra Külső ID ügyfelek bérlője számára. Ha még nincs ilyenje, regisztráljon egy ingyenes próbaverzióra.
Ha még nem tette meg, regisztráljon egy alkalmazást a Microsoft Entra felügyeleti központban. Győződjön meg arról, hogy delegált engedélyeket ad meg, és engedélyezi a nyilvános ügyfél- és natív hitelesítési folyamatokat.
Ha még nem tette meg, hozzon létre egy felhasználói folyamatot a Microsoft Entra Felügyeleti központban. A felhasználói folyamat létrehozásakor jegyezze fel a szükséges felhasználói attribútumokat, mivel ezek az attribútumok azok, amelyeket a Microsoft Entra elvár az alkalmazástól. Az Identitásszolgáltatók területen válassza az Egyszeri jelszó megadása e-mail lehetőséget.
Az alkalmazásregisztráció társítása a felhasználói folyamattal.
A bejelentkezési folyamathoz regisztráljon egy ügyfélfelhasználót, amelyet a bejelentkezési API-k teszteléséhez használ. Másik lehetőségként a regisztrációs folyamat futtatása után is lekérheti ezt a tesztfelhasználót.
Az SSPR-folyamat esetében engedélyezze az önkiszolgáló jelszó-visszaállítást az ügyfelek bérlőjében lévő ügyfélfelhasználók számára. Az SSPR az e-maileket jelszó-hitelesítési módszerrel használó ügyfelek számára érhető el.
Folytatási jogkivonat
Minden alkalommal, amikor meghív egy végpontot bármelyik folyamatban, bejelentkezésben, regisztrációban vagy SSPR-ben, a végpont tartalmaz egy folytatási jogkivonatot a válaszában. A folytatási jogkivonat egy egyedi azonosító, amelyet a Microsoft Entra ID használ az állapot fenntartására a különböző végpontokra irányuló hívások között ugyanabban a folyamatban. Ezt a jogkivonatot bele kell foglalnia a későbbi kérésekbe ugyanabban a folyamatban.
Minden folytatási jogkivonat egy adott időszakra érvényes, és csak az ugyanazon a folyamaton belüli későbbi kérésekhez használható.
Regisztrációs API-referencia
Ha egy felhasználói regisztrációs folyamatot szeretne végrehajtani bármelyik hitelesítési módszerhez, az alkalmazás négy végponttal /signup/v1.0/start, , /signup/v1.0/challengeés /signup/v1.0/continue/token.
Regisztrációs API-végpontok
| Végpont | Leírás |
|---|---|
/signup/v1.0/start |
Ez a végpont elindítja a regisztrációs folyamatot. Érvényes alkalmazásazonosítót, új felhasználónevet és feladattípust ad át, majd egy új folytatási jogkivonatot kap vissza. A végpont olyan választ adhat vissza, amely jelzi az alkalmazásnak, hogy webes hitelesítési folyamatot használjon, ha az alkalmazás választott hitelesítési módszereit a Microsoft Entra nem támogatja. |
/signup/v1.0/challenge |
Az alkalmazás meghívja ezt a végpontot a Microsoft Entra által támogatott kihívástípusok listájával. A Microsoft Entra ezután kiválasztja az egyik támogatott hitelesítési módszert, amellyel a felhasználó hitelesítheti magát. |
/signup/v1.0/continue |
Ez a végpont segít folytatni a folyamatot a felhasználói fiók létrehozásához, vagy megszakítani a folyamatot hiányzó követelmények, például jelszóházirend-követelmények vagy helytelen attribútumformátumok miatt. Ez a végpont létrehoz egy folytatási jogkivonatot, majd visszaadja az alkalmazásnak. A végpont olyan választ adhat vissza, amely jelzi az alkalmazásnak, hogy webes hitelesítési folyamatot használjon, ha az alkalmazás nem a Microsoft Entra által választott hitelesítési módszert használja. |
/token |
Az alkalmazás meghívja ezt a végpontot, hogy végül biztonsági jogkivonatokat kérjen. Az alkalmazásnak tartalmaznia kell a végpont utolsó sikeres hívásából beszerzett folytatási jogkivonatot /signup/v1.0/continue . |
Regisztrációs kihívások típusai
Az API lehetővé teszi, hogy az ügyfélalkalmazás meghirdetje az általa támogatott hitelesítési módszereket, amikor hívást kezdeményez a Microsoft Entra felé. Ehhez az alkalmazás az challenge_type alkalmazás kérésében szereplő paramétert használja. Ez a paraméter előre definiált értékeket tartalmaz, amelyek különböző hitelesítési módszereket jelölnek.
További információ a natív hitelesítési feladattípusok feladattípusairól. Ez a cikk a hitelesítési módszerhez szükséges feladattípus-értékeket ismerteti.
Regisztrációs folyamat protokoll részletei
A folyamatábra bemutatja a regisztrációs folyamat folyamatát.
Ez az ábra azt jelzi, hogy az alkalmazás a felhasználónevet (e-mailt), a jelszót (a jelszóhitelesítési módszerekkel ellátott e-mailekhez) és attribútumokat gyűjti a felhasználótól különböző időpontokban (és esetleg külön képernyőkön). Az alkalmazást azonban úgy is megtervezheti, hogy ugyanazon a képernyőn összegyűjtse a felhasználónevet (e-mailt), a jelszót és az összes szükséges és opcionális attribútumértéket, majd küldje el az összeset a /signup/v1.0/start végponton keresztül. Ebben az esetben az alkalmazásnak nem kell hívásokat kezdeményeznie és kezelnie az opcionális lépésekre adott válaszokat.
1. lépés: A regisztrációs folyamat elindításának kérése
A regisztrációs folyamat azzal kezdődik, hogy az alkalmazás POST-kérelmet küld a végpontnak a /signup/v1.0/start regisztrációs folyamat elindításához.
Íme néhány példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
1. példa:
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
2. példa (felhasználói attribútumok és jelszó belefoglalása a kérelembe):
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
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
username |
Igen | Az ügyfél felhasználójának e-mail-címe, amellyel regisztrálni szeretne, például contoso-consumer@contoso.com. |
challenge_type |
Igen | Az alkalmazás által támogatott oob password redirectengedélyezési feladattípus-sztringek szóközzel elválasztott listája. A listának mindig tartalmaznia kell a redirect feladat típusát. Az érték várhatóan a jelszó-hitelesítési módszerrel rendelkező e-mailekhez vagy e-mailekhez lesz megadva oob redirectoob password redirect . |
password |
Nem | Az alkalmazás által az ügyfél felhasználójától gyűjtött jelszóérték. A felhasználó jelszavát a /signup/v1.0/start végponton vagy az azt követőn /signup/v1.0/continue keresztül küldheti el. Cserélje le {secure_password} az alkalmazás által az ügyfélfelhasználótól gyűjtött jelszóértékre. Az Ön felelőssége annak ellenőrzése, hogy a felhasználó tisztában van-e a használni kívánt jelszóval az alkalmazás felhasználói felületén található jelszó-megerősítési mező megadásával. Arról is gondoskodnia kell, hogy a felhasználó tisztában legyen azzal, hogy mi számít erős jelszónak a szervezet szabályzata szerint. További információ a Microsoft Entra jelszószabályzatairól. Ez a paraméter csak jelszó-hitelesítési módszerrel rendelkező e-mailekre alkalmazható. |
attributes |
Nem | A felhasználó attribútumai olyan értékeket tartalmaznak, amelyeket az alkalmazás gyűjt az ügyfélfelhasználótól. Az érték egy sztring, de JSON-objektumként van formázva, amelynek kulcsértékei a felhasználói attribútumok programozható neve . Ezek az attribútumok lehetnek beépítettek vagy egyéniek, és kötelezőek vagy nem kötelezőek. Az objektum kulcsneve a Microsoft Entra Felügyeleti központban konfigurált attribútumoktól függ. A végponton vagy a végponton /signup/v1.0/continue keresztül /signup/v1.0/start beküldhet néhány vagy az összes felhasználói attribútumot. Ha a végponton keresztül /signup/v1.0/start küldi el az összes szükséges attribútumot, nem kell attribútumokat küldenie a /signup/v1.0/continue végponton. Ha azonban a végponton keresztül /signup/v1.0/start küld el néhány szükséges attribútumot, a fennmaradó szükséges attribútumokat később is elküldheti a /signup/v1.0/continue végponton. {user_age}{postal_code} Cserélje le {given_name}az alkalmazás által az ügyfélfelhasználótól gyűjtött nevet, kort és irányítószámot, valamint a nevet, az életkort és az irányítószámot. A Microsoft Entra figyelmen kívül hagyja a beküldött attribútumokat, amelyek nem léteznek. |
Sikeres válasz
Íme egy példa a sikeres válaszra:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAA…",
}
| Paraméter | Leírás |
|---|---|
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
Ha egy alkalmazás nem tudja támogatni a Microsoft Entra által megkövetelt hitelesítési módszert, vissza kell állítani a webes hitelesítési folyamatot. Ebben a forgatókönyvben a Microsoft Entra egy átirányítási feladattípus válaszában tájékoztatja az alkalmazást:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Paraméter | Leírás |
|---|---|
challenge_type |
A Microsoft Entra egy kihívástípusú választ ad vissza. Ennek a feladattípusnak az értéke átirányítás, amely lehetővé teszi az alkalmazás számára a webes hitelesítési folyamat használatát. |
Ez a válasz sikeresnek minősül, de az alkalmazásnak webalapú hitelesítési folyamatra kell váltania. Ebben az esetben javasoljuk, hogy a Microsoft által létrehozott és támogatott hitelesítési kódtárat használja.
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "user_already_exists",
"error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
1003037
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
invalid_attributes |
A sikertelen érvényesítést okozó attribútumok listája (objektumtömbje). Ez a válasz akkor lehetséges, ha az alkalmazás felhasználói attribútumokat küld, és a suberror paraméter értéke attribute_validation_failed. |
suberror |
Hibakódsztring, amely a hibatípusok további besorolására használható. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése sikertelen volt, például ha a challenge_type paraméter értéke nem támogatott hitelesítési módszert tartalmaz, vagy a kérés nem tartalmaz client_id olyan paramétert, amely az ügyfélazonosító értéke üres vagy érvénytelen. A paraméter használatával error_description megismerheti a hiba pontos okát. |
invalid_client |
Az alkalmazás által a kérelemben szereplő ügyfél-azonosító egy olyan alkalmazáshoz tartozik, amely nem rendelkezik natív hitelesítési konfigurációval, például nem nyilvános ügyfél, vagy nincs engedélyezve natív hitelesítésre. A paraméter használatával suberror megismerheti a hiba pontos okát. |
unauthorized_client |
A kérelemben használt ügyfél-azonosító érvényes ügyfélazonosító-formátummal rendelkezik, de nem létezik a külső bérlőben, vagy helytelen. |
unsupported_challenge_type |
A challenge_type paraméter értéke nem tartalmazza a redirect feladat típusát. |
user_already_exists |
A felhasználó már létezik. |
invalid_grant |
Az alkalmazás által beküldött jelszó nem felel meg az összes összetettségi követelménynek, például a jelszó túl rövid. A paraméter használatával suberror megismerheti a hiba pontos okát. Ez a paraméter csak jelszó-hitelesítési módszerrel rendelkező e-mailekre alkalmazható. |
Ha a hibaparaméter értéke invalid_grant, a Microsoft Entra tartalmaz egy paramétert suberror a válaszában. Egy invalid_grant hiba paraméterének suberrorlehetséges értékei a következők:
| Alhálózati érték | Leírás |
|---|---|
password_too_weak |
A jelszó túl gyenge, mivel nem felel meg az összetettségi követelményeknek. További információ a Microsoft Entra jelszószabályzatairól. Ez a válasz akkor lehetséges, ha az alkalmazás felhasználói jelszót küld. |
password_too_short |
Az új jelszó 8 karakternél kevesebb karakterből áll. További információ a Microsoft Entra jelszószabályzatairól. Ez a válasz akkor lehetséges, ha az alkalmazás felhasználói jelszót küld. |
password_too_long |
Az új jelszó 256 karakternél hosszabb. További információ a Microsoft Entra jelszószabályzatairól. Ez a válasz akkor lehetséges, ha az alkalmazás felhasználói jelszót küld. |
password_recently_used |
Az új jelszó nem lehet ugyanaz, mint a közelmúltban használt jelszó. További információ a Microsoft Entra jelszószabályzatairól. Ez a válasz akkor lehetséges, ha az alkalmazás felhasználói jelszót küld. |
password_banned |
Az új jelszó tiltott szót, kifejezést vagy mintát tartalmaz. További információ a Microsoft Entra jelszószabályzatairól. Ez a válasz akkor lehetséges, ha az alkalmazás felhasználói jelszót küld. |
password_is_invalid |
A jelszó érvénytelen, például azért, mert nem engedélyezett karaktereket használ. További információ a Microsoft Entra jelszószabályzatairól. Ez a válasz akkor lehetséges, ha az alkalmazás felhasználói jelszót küld. |
Ha a hibaparaméter értéke invalid_client, a Microsoft Entra tartalmaz egy paramétert suberror a válaszában. Egy invalid_client hiba paraméterének suberrorlehetséges értékei a következők:
| Alhálózati érték | Leírás |
|---|---|
nativeauthapi_disabled |
Egy olyan alkalmazás ügyfélazonosítója, amely nem engedélyezi a natív hitelesítést. |
Feljegyzés
Ha az összes szükséges attribútumot végponton keresztül /signup/v1.0/start küldi el, de nem minden választható attribútumot, később nem tud további opcionális attribútumokat küldeni a /signup/v1.0/continue végponton keresztül. A Microsoft Entra nem kér explicit módon választható attribútumokat, mivel nem kötelezőek a regisztrációs folyamat befejezéséhez. A felhasználói attribútumok végpontokra való elküldésének szakaszában található táblázatból megtudhatja, hogy azokat a felhasználói attribútumokat hogyan küldheti el a végpontoknak és /signup/v1.0/continue a /signup/v1.0/start végpontoknak.
2. lépés: Hitelesítési módszer kiválasztása
Az alkalmazás kéri a Microsoft Entrát, hogy válasszon ki egy támogatott feladattípust, amellyel a felhasználó hitelesítheti magát. Ehhez az alkalmazás meghívja a /signup/v1.0/challenge végpontot. Az alkalmazásnak tartalmaznia kell a végponttól /signup/v1.0/start beszerzett folytatási jogkivonatot a kérelemben.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében).
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…
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
challenge_type |
Nem | Az alkalmazás által támogatott oob password redirectengedélyezési feladattípus-sztringek szóközzel elválasztott listája. A listának mindig tartalmaznia kell a redirect feladat típusát. Az érték várhatóan az egyszeri pin-kód oob password redirect és a jelszóhitelesítési módszerrel rendelkező e-mailek esetében várhatóoob redirect. |
continuation_token |
Igen | A Microsoft Entra által az előző kérelemben visszaadott folytatási jogkivonat . |
Sikeres válasz
A Microsoft Entra egyszeri pin-kódot küld a felhasználó e-mail-címére, majd az oob értékével és az egyszeri pin-kód további információival válaszol a feladat típusára:
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
}
| Paraméter | Leírás |
|---|---|
interval |
Az alkalmazásnak másodpercek alatt meg kell várnia az OTP újbóli elküldésének kísérletét. |
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
challenge_type |
A felhasználó által a hitelesítéshez kiválasztott feladattípus. |
binding_method |
Az egyetlen érvényes érték a parancssor. Ez a paraméter a jövőben további lehetőségeket kínálhat a felhasználó számára az egyszeri pin-kód megadására. Kiállítva, ha challenge_type oob |
challenge_channel |
Annak a csatornának a típusa, amelyen keresztül az egyszeri pin-kód el lett küldve. Jelenleg csak az e-mail csatorna támogatott. |
challenge_target_label |
Egy elhomályosított e-mail, amelyben az egyszeri pin-kód lett elküldve. |
code_length |
A Microsoft Entra által létrehozott egyszeri pin-kód hossza. |
Ha egy alkalmazás nem tudja támogatni a Microsoft Entra által megkövetelt hitelesítési módszert, vissza kell állítani a webes hitelesítési folyamatot. Ebben a forgatókönyvben a Microsoft Entra egy átirányítási feladattípus válaszában tájékoztatja az alkalmazást:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Paraméter | Leírás |
|---|---|
challenge_type |
A Microsoft Entra egy kihívástípusú választ ad vissza. Ennek a feladattípusnak az értéke átirányítás, amely lehetővé teszi az alkalmazás számára a webes hitelesítési folyamat használatát. |
Ez a válasz sikeresnek minősül, de az alkalmazásnak webalapú hitelesítési folyamatra kell váltania. Ebben az esetben javasoljuk, hogy a Microsoft által létrehozott és támogatott hitelesítési kódtárat használja.
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése nem sikerült, például az ügyfélazonosító üres vagy érvénytelen. |
expired_token |
A folytatási jogkivonat lejárt. |
unsupported_challenge_type |
A challenge_type paraméter értéke nem tartalmazza a redirect feladat típusát. |
invalid_grant |
A folytatási jogkivonat érvénytelen. |
3. lépés: Egyszeri pin-kód elküldése
Az alkalmazás elküldi a felhasználó e-mail-címére küldött egyszeri pin-kódot. Mivel egyszeri pin-kódot küldünk el, egy oob paraméterre van szükség, és a grant_type paraméternek érték oob értékkel kell rendelkeznie.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
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}
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
continuation_token |
Igen | A Microsoft Entra által az előző kérelemben visszaadott folytatási jogkivonat . |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
grant_type |
Igen | A végpontra /signup/v1.0/continue irányuló kérések felhasználhatók egyszeri pin-kód, jelszó vagy felhasználói attribútumok elküldésére. Ebben az esetben az grant_type érték a három használati eset megkülönböztetésére szolgál. A grant_type lehetséges értékei az oob, a jelszó, az attribútumok. Ebben a hívásban, mivel egyszeri pin-kódot küldünk, az érték várhatóan nem lesz egyszerű. |
oob |
Igen | Az az egyszeri pin-kód, amelyet az ügyfélfelhasználó kapott az e-mailben. Cserélje le {otp_code} azokat az egyszeri pin-kódértékeket, amelyeket az ügyfélfelhasználó kapott az e-mailben. Az egyszeri pin-kód újbóli megadásához az alkalmazásnak újra kell kérnie a /signup/v1.0/challenge végpontot. |
Miután az alkalmazás sikeresen elküldte az egyszeri pin-kódot, a regisztrációs folyamat a táblázatban látható forgatókönyvtől függ:
| Eset | A folytatás menete |
|---|---|
Az alkalmazás sikeresen elküldi a felhasználó jelszavát (jelszó-hitelesítési módszerrel ellátott e-mailekhez) a /signup/v1.0/start végponton keresztül, és a Microsoft Entra Felügyeleti központban nincs konfigurálva attribútum, vagy az összes szükséges felhasználói attribútum a /signup/v1.0/start végponton keresztül lesz elküldve. |
A Microsoft Entra kiad egy folytatási jogkivonatot. Az alkalmazás a folytatási jogkivonat használatával kérhet biztonsági jogkivonatokat az 5. lépésben látható módon. |
Az alkalmazás sikeresen elküldi a felhasználó jelszavát (a jelszó-hitelesítési módszerrel ellátott e-mailekhez) az /signup/v1.0/startösszes szükséges felhasználói attribútumon keresztül, a Microsoft Entra jelzi azokat az attribútumokat, amelyeket az alkalmazásnak be kell küldenie a szükséges felhasználói attribútumokban látható módon. |
Az alkalmazásnak a végponton keresztül kell elküldenie a /signup/v1.0/continue szükséges felhasználói attribútumokat. A válasz hasonló a Felhasználói attribútumok kötelező eleméhez. Küldje el a felhasználói attribútumokat a Felhasználói attribútumok elküldése mezőben látható módon. |
Az alkalmazás nem küldi el a felhasználó jelszavát (jelszó-hitelesítési módszerrel ellátott e-mailekhez) a végponton keresztül /signup/v1.0/start . |
A Microsoft Entra válasza azt jelzi, hogy hitelesítő adatokra van szükség. Lásd a választ. Ez a válasz jelszó-hitelesítési módszerrel rendelkező e-mailek esetén lehetséges. |
Válasz
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..."
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
suberror |
Hibakódsztring, amely a hibatípusok további besorolására használható. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
credential_required |
A fióklétrehozáshoz hitelesítés szükséges, ezért fel kell hívnia a /signup/v1.0/challenge végpontot annak megállapításához, hogy a felhasználónak milyen hitelesítő adatokat kell megadnia. |
invalid_request |
A kérelemparaméter érvényesítése sikertelen volt, például a folytatási jogkivonat ellenőrzése meghiúsult, vagy a kérés nem tartalmazta client_id az ügyfélazonosító üres vagy érvénytelen paraméterét, vagy a külső bérlői rendszergazda nem engedélyezte az e-mailes OTP-t az összes bérlőfelhasználó számára. |
invalid_grant |
A kérelemben szereplő támogatási típus érvénytelen vagy támogatott, vagy az OTP értéke helytelen. |
expired_token |
A kérelemben szereplő folytatási jogkivonat lejárt. |
Ha a hibaparaméter értéke invalid_grant, a Microsoft Entra tartalmaz egy paramétert suberror a válaszában. Egy invalid_grant hiba paraméterének suberrorlehetséges értékei a következők:
| Alhálózati érték | Leírás |
|---|---|
invalid_oob_value |
Az egyszeri pin-kód értéke érvénytelen. |
Ahhoz, hogy a jelszó hitelesítő adatait a felhasználótól lehessen gyűjteni, az alkalmazásnak fel kell hívnia a /signup/v1.0/challenge végpontot annak megállapításához, hogy a felhasználónak milyen hitelesítő adatot kell megadnia.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
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…
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
challenge_type |
Nem | Az alkalmazás által támogatott oob password redirectengedélyezési feladattípus-sztringek szóközzel elválasztott listája. A listának mindig tartalmaznia kell a redirect feladat típusát. A jelszó-regisztrációs folyamatot tartalmazó e-mail esetében az érték várhatóan tartalmazni password redirectfog. |
continuation_token |
Igen | A Microsoft Entra által az előző kérelemben visszaadott folytatási jogkivonat . |
Sikeres válasz
Ha a jelszó a Microsoft Entra felügyeleti központban a felhasználóhoz konfigurált hitelesítési módszer, a rendszer sikeres választ ad vissza a folytatási jogkivonattal az alkalmazásnak.
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "password",
"continuation_token": " AQABAAEAAAAty..."
}
| Paraméter | Leírás |
|---|---|
challenge_type |
a rendszer a szükséges hitelesítő adatok válaszában adja vissza a jelszót . |
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
Ha egy alkalmazás nem tudja támogatni a Microsoft Entra által megkövetelt hitelesítési módszert, vissza kell állítani a webes hitelesítési folyamatot. Ebben a forgatókönyvben a Microsoft Entra egy átirányítási feladattípus válaszában tájékoztatja az alkalmazást:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Paraméter | Leírás |
|---|---|
challenge_type |
A Microsoft Entra egy kihívástípusú választ ad vissza. Ennek a feladattípusnak az értéke átirányítás, amely lehetővé teszi az alkalmazás számára a webes hitelesítési folyamat használatát. |
Ez a válasz sikeresnek minősül, de az alkalmazásnak webalapú hitelesítési folyamatra kell váltania. Ebben az esetben javasoljuk, hogy a Microsoft által létrehozott és támogatott hitelesítési kódtárat használja.
4. lépés: Hitelesítés és jogkivonat lekérése a regisztrációhoz
Az alkalmazásnak el kell küldenie a felhasználó hitelesítő adatait, ebben az esetben a Microsoft Entra által az előző lépésben kért jelszót. Az alkalmazásnak jelszót kell küldenie, ha nem a végponton keresztül /signup/v1.0/start tette meg. Az alkalmazás kérést küld a végpontnak a /signup/v1.0/continue jelszó elküldésére. Mivel jelszót küldünk, paraméterre password van szükség, és a grant_type paraméternek értékjelszóval kell rendelkeznie.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
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}
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
continuation_token |
Igen | A Microsoft Entra által az előző lépésben visszaadott folytatási jogkivonat . |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
grant_type |
Igen | A végpontra /signup/v1.0/continue irányuló kérések felhasználhatók egyszeri pin-kód, jelszó vagy felhasználói attribútumok elküldésére. Ebben az esetben az grant_type érték a három használati eset megkülönböztetésére szolgál. A grant_type lehetséges értékei az oob, a jelszó, az attribútumok. Ebben a hívásban, mivel a felhasználó jelszavát küldjük el, az érték várhatóan jelszó lesz. |
password |
Igen | Az alkalmazás által az ügyfél felhasználójától gyűjtött jelszóérték. Cserélje le {secure_password} az alkalmazás által az ügyfélfelhasználótól gyűjtött jelszóértékre. Az Ön felelőssége annak ellenőrzése, hogy a felhasználó tisztában van-e a használni kívánt jelszóval az alkalmazás felhasználói felületén található jelszó-megerősítési mező megadásával. Arról is gondoskodnia kell, hogy a felhasználó tisztában legyen azzal, hogy mi számít erős jelszónak a szervezet szabályzata szerint. További információ a Microsoft Entra jelszószabályzatairól. |
Sikeres válasz
Ha a kérés sikeres, de nem konfiguráltak attribútumokat a Microsoft Entra felügyeleti központban, vagy az összes szükséges attribútumot a /signup/v1.0/start végponton keresztül adták le, az alkalmazás egy folytatási jogkivonatot kap attribútumok elküldése nélkül. Az alkalmazás a folytatási jogkivonat használatával kérhet biztonsági jogkivonatokat az 5. lépésben látható módon. Ellenkező esetben a Microsoft Entra válasza azt jelzi, hogy az alkalmazásnak el kell küldenie a szükséges attribútumokat. Ezeket az egyéni vagy beépített attribútumokat a bérlői rendszergazda konfigurálta a Microsoft Entra felügyeleti központban.
Felhasználói attribútumok szükségesek
Ez a válasz arra kéri az alkalmazást, hogy küldjön be értékeket a név, a *kor és a telefon attribútumai számára.
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]*$"
}
}
],
}
Feljegyzés
Az egyéni attribútumok (más néven címtárbővítmények) elnevezése azzal a konvencióval extension_{appId-without-hyphens}_{attribute-name} történik, ahol {appId-without-hyphens} a bővítmények alkalmazás ügyfélazonosítójának le van vetve. Ha például a bővítményalkalmazás ügyfél-azonosítója, 2588a-bcdwh-tfeehj-jeeqw-ertc és az attribútum neve hobbi, akkor az egyéni attribútum neve a következőextension_2588abcdwhtfeehjjeeqwertc_hobbies. További információ az egyéni attribútumokról és a bővítményalkalmazásról.
| Paraméter | Leírás |
|---|---|
error |
Ez az attribútum akkor van beállítva, ha a Microsoft Entra nem tudja létrehozni a felhasználói fiókot, mert egy attribútumot ellenőrizni vagy elküldeni kell. |
error_description |
Egy adott hibaüzenet, amely segíthet a hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
required_attributes |
Az attribútumok listája (objektumtömb), amelyet az alkalmazásnak be kell küldenie a következő híváshoz a folytatáshoz. Ezek az attribútumok azok az extra attribútumok, amelyeket az alkalmazásnak a felhasználónévn kívül kell elküldenie. A Microsoft Entra ezt a paramétert tartalmazza, ha a paraméter értéke error attributes_required. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése sikertelen volt, például a folytatási jogkivonat ellenőrzése meghiúsult, vagy a kérés nem tartalmazta client_id az ügyfélazonosító üres vagy érvénytelen paraméterét. |
invalid_grant |
A kérelemben szereplő támogatási típus érvénytelen vagy támogatott. A lehetséges értékek az oob, a grant_typejelszó, az attribútumok |
expired_token |
A kérelemben szereplő folytatási jogkivonat lejárt. |
attributes_required |
Egy vagy több felhasználói attribútumra van szükség. |
Ha egy alkalmazás nem tudja támogatni a Microsoft Entra által megkövetelt hitelesítési módszert, vissza kell állítani a webes hitelesítési folyamatot. Ebben a forgatókönyvben a Microsoft Entra egy átirányítási feladattípus válaszában tájékoztatja az alkalmazást:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Paraméter | Leírás |
|---|---|
challenge_type |
A Microsoft Entra egy kihívástípusú választ ad vissza. Ennek a feladattípusnak az értéke átirányítás, amely lehetővé teszi az alkalmazás számára a webes hitelesítési folyamat használatát. |
Ez a válasz sikeresnek minősül, de az alkalmazásnak webalapú hitelesítési folyamatra kell váltania. Ebben az esetben javasoljuk, hogy a Microsoft által létrehozott és támogatott hitelesítési kódtárat használja.
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_grant",
"error_description": "New password is too weak",
"error_codes": [
399246
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6",
"suberror": "password_too_weak"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
suberror |
Hibakódsztring, amely a hibatípusok további besorolására használható. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése nem sikerült, például ha a challenge_type paraméter érvénytelen feladattípust tartalmaz. |
invalid_grant |
A benyújtott támogatás érvénytelen, például a beküldött jelszó túl rövid. A paraméter használatával suberror megismerheti a hiba pontos okát. |
expired_token |
A folytatási jogkivonat lejárt. |
attributes_required |
Egy vagy több felhasználói attribútumra van szükség. |
Ha a hibaparaméter értéke invalid_grant, a Microsoft Entra tartalmaz egy paramétert suberror a válaszában. A paraméter lehetséges értékei a suberror következők:
| Alhálózati érték | Leírás |
|---|---|
password_too_weak |
A jelszó túl gyenge, mivel nem felel meg az összetettségi követelményeknek. További információ a Microsoft Entra jelszószabályzatairól. |
password_too_short |
Az új jelszó 8 karakternél kevesebb karakterből áll. További információ a Microsoft Entra jelszószabályzatairól. |
password_too_long |
Az új jelszó 256 karakternél hosszabb. További információ a Microsoft Entra jelszószabályzatairól. |
password_recently_used |
Az új jelszó nem lehet ugyanaz, mint a közelmúltban használt jelszó. További információ a Microsoft Entra jelszószabályzatairól. |
password_banned |
Az új jelszó tiltott szót, kifejezést vagy mintát tartalmaz. További információ a Microsoft Entra jelszószabályzatairól. |
password_is_invalid |
A jelszó érvénytelen, például azért, mert nem engedélyezett karaktereket használ. További információ a Microsoft Entra jelszószabályzatairól. Ez a válasz akkor lehetséges, ha az alkalmazás felhasználói jelszót küld. |
Felhasználói attribútumok küldése
A folyamat folytatásához az alkalmazásnak fel kell hívnia a végpontot a /signup/v1.0/continue szükséges felhasználói attribútumok elküldéséhez. Mivel attribútumokat küldünk el, egy attributes paraméterre van szükség, és a grant_type paraméternek attribútumokkal egyenlő értékkel kell rendelkeznie.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=attributes
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
continuation_token |
Igen | A Microsoft Entra által az előző kérelemben visszaadott folytatási jogkivonat . |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
grant_type |
Igen | A végpontra /signup/v1.0/continue irányuló kérések felhasználhatók egyszeri pin-kód, jelszó vagy felhasználói attribútumok elküldésére. Ebben az esetben az grant_type érték a három használati eset megkülönböztetésére szolgál. A grant_type lehetséges értékei az oob, a jelszó, az attribútumok. Ebben a hívásban, mivel felhasználói attribútumokat küldünk, az érték várhatóan attribútumok lesznek. |
attributes |
Igen | Az alkalmazás által az ügyfél felhasználójától gyűjtött felhasználói attribútumértékek. Az érték egy sztring, de JSON-objektumként van formázva, amelynek kulcsértékei a beépített vagy egyéni felhasználói attribútumok nevei. Az objektum kulcsneve a Microsoft Entra Felügyeleti központban konfigurált attribútumoktól függ. {user_age}{postal_code} Cserélje le {given_name}az alkalmazás által az ügyfélfelhasználótól gyűjtött nevet, kort és irányítószámot, valamint a nevet, az életkort és az irányítószámot. A Microsoft Entra figyelmen kívül hagyja a beküldött attribútumokat, amelyek nem léteznek. |
Sikeres válasz
Ha a kérés sikeres, a Microsoft Entra kiad egy folytatási jogkivonatot, amelyet az alkalmazás a biztonsági jogkivonatok igénylésére használhat.
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAAYn..."
}
| Paraméter | Leírás |
|---|---|
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
Ha egy alkalmazás nem tudja támogatni a Microsoft Entra által megkövetelt hitelesítési módszert, vissza kell állítani a webes hitelesítési folyamatot. Ebben a forgatókönyvben a Microsoft Entra egy átirányítási feladattípus válaszában tájékoztatja az alkalmazást:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Paraméter | Leírás |
|---|---|
challenge_type |
A Microsoft Entra egy kihívástípusú választ ad vissza. Ennek a feladattípusnak az értéke átirányítás, amely lehetővé teszi az alkalmazás számára a webes hitelesítési folyamat használatát. |
Ez a válasz sikeresnek minősül, de az alkalmazásnak webalapú hitelesítési folyamatra kell váltania. Ebben az esetben javasoljuk, hogy a Microsoft által létrehozott és támogatott hitelesítési kódtárat használja.
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "expired_token",
"error_description": "AADSTS901007: The continuation_token is expired. .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
unverified_attributes |
Az attribútumkulcsok neveinek (objektumtömbjeinek) listája, amelyeket ellenőrizni kell. Ez a paraméter akkor jelenik meg a válaszban, ha a error paraméter értéke verification_required. |
required_attributes |
Az alkalmazás által elküldendő attribútumok listája (objektumtömbje). A Microsoft Entra akkor tartalmazza ezt a paramétert a válaszában, ha a error paraméter értéke attributes_required. |
invalid_attributes |
A sikertelen érvényesítést okozó attribútumok listája (objektumtömbje). Ez a paraméter akkor jelenik meg a válaszban, ha a suberror paraméter értéke attribute_validation_failed. |
suberror |
Hibakódsztring, amely a hibatípusok további besorolására használható. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése sikertelen volt, például a folytatási jogkivonat ellenőrzése meghiúsult, vagy a kérés nem tartalmazta client_id az ügyfélazonosító üres vagy érvénytelen paraméterét. |
invalid_grant |
A megadott támogatási típus érvénytelen, nem támogatott vagy sikertelen érvényesítés, például az attribútumok érvényesítése sikertelen. A paraméter használatával suberror megismerheti a hiba pontos okát. |
expired_token |
A kérelemben szereplő folytatási jogkivonat lejárt. |
attributes_required |
Egy vagy több felhasználói attribútumra van szükség. |
Ha a hibaparaméter értéke invalid_grant, a Microsoft Entra tartalmaz egy paramétert suberror a válaszában. Egy invalid_grant hiba paraméterének suberrorlehetséges értékei a következők:
| Alhálózati érték | Leírás |
|---|---|
attribute_validation_failed |
A felhasználói attribútum érvényesítése nem sikerült. invalid_attributes A paraméter tartalmazza a sikertelen érvényesítést okozó attribútumok listáját (objektumtömbje). |
5. lépés: Biztonsági jogkivonatok kérése
Az alkalmazás POST kérést küld a /token végpontnak, és biztosítja az előző lépésből beszerzett folytatási jogkivonatot a biztonsági jogkivonatok beszerzéséhez.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
continuation_token=ABAAEAAAAtyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
grant_type |
Igen | A paraméter értékének folytatási jogkivonatnak kell lennie. |
continuation_token |
Igen | A Microsoft Entra által az előző lépésben visszaadott folytatási jogkivonat . |
scope |
Igen | A hozzáférési jogkivonat által érvényes hatókörök szóközzel elválasztott listája. Cserélje le {scopes} a Microsoft Entra hozzáférési jogkivonat által visszaadott érvényes hatókörökre. |
username |
Igen | Az ügyfél felhasználójának e-mail-címe, amellyel regisztrálni szeretne, például contoso-consumer@contoso.com. |
Sikeres válasz
Íme egy példa a sikeres válaszra:
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..."
}
| Paraméter | Leírás |
|---|---|
access_token |
Az alkalmazás által a /token végponttól kért hozzáférési jogkivonat. Az alkalmazás ezzel a hozzáférési jogkivonattal hozzáférést kérhet biztonságos erőforrásokhoz, például webes API-khoz. |
token_type |
A jogkivonat típusértékét jelzi. A Microsoft Entra csak a Bearer típust támogatja. |
expires_in |
A hozzáférési jogkivonat érvényességi időtartama másodpercben. |
scopes |
A hozzáférési jogkivonat által érvényes hatókörök szóközzel elválasztott listája. |
refresh_token |
OAuth 2.0 frissítési jogkivonat. Az alkalmazás ezt a jogkivonatot használhatja más hozzáférési jogkivonatok beszerzésére az aktuális hozzáférési jogkivonat lejárta után. A frissítési jogkivonatok hosszú élettartamúak. Hosszabb ideig fenntarthatják az erőforrásokhoz való hozzáférést. A hozzáférési jogkivonat frissítéséről további információt a hozzáférési jogkivonat frissítéséről szóló cikkben talál. Megjegyzés: Csak akkor lett kiadva, ha offline_access hatókört kértek. |
id_token |
Az ügyfélfelhasználó azonosítására szolgáló JSON-webjogkivonat (Jwt). Az alkalmazás dekódolhatja a jogkivonatot, hogy információkat olvasson a bejelentkezett felhasználóról. Az alkalmazás gyorsítótárazza és megjeleníti az értékeket, a bizalmas ügyfelek pedig ezt a jogkivonatot használhatják az engedélyezéshez. Az azonosító jogkivonatokkal kapcsolatos további információkért lásd az azonosító jogkivonatokat. Megjegyzés: Csak openid hatókör kérése esetén adható ki. |
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése meghiúsult, például az ügyfél/alkalmazás nem rendelkezik hozzájárulással a kért hatókörökhöz. |
invalid_grant |
A kérelemben szereplő folytatási jogkivonat érvénytelen. |
unauthorized_client |
A kérelemben szereplő ügyfélazonosító érvénytelen vagy nem létezik. |
unsupported_grant_type |
A kérelemben szereplő támogatási típus nem támogatott vagy helytelen. |
Felhasználói attribútumok elküldése végpontokra
A Microsoft Entra Felügyeleti központban igény szerint vagy opcionálisan konfigurálhatja a felhasználói attribútumokat. Ez a konfiguráció határozza meg, hogyan válaszol a Microsoft Entra a végpontokra irányuló híváskor. Az opcionális attribútumok nem kötelezőek a regisztrációs folyamat befejezéséhez. Ezért ha az összes attribútum nem kötelező, a felhasználónév ellenőrzése előtt el kell küldeni őket. Ellenkező esetben a regisztráció az opcionális attribútumok nélkül fejeződik be.
Az alábbi táblázat összefoglalja, hogy mikor lehet felhasználói attribútumokat küldeni a Microsoft Entra-végpontokra.
| Végpont | Szükséges attribútumok | Választható attribútumok | Kötelező és nem kötelező attribútumok is |
|---|---|---|---|
/signup/v1.0/start végpont |
Igen | Igen | Igen |
/signup/v1.0/continue végpont a felhasználónév ellenőrzése előtt |
Igen | Igen | Igen |
/signup/v1.0/continue végpont a felhasználónév ellenőrzése után |
Igen | Nem | Igen |
A felhasználói attribútumok értékeinek formátuma
A felhasználói folyamat beállításainak konfigurálásával megadhatja a felhasználótól begyűjtendő adatokat a Microsoft Entra felügyeleti központban. Az egyéni felhasználói attribútumok összegyűjtése a regisztráció során című cikkből megtudhatja, hogyan gyűjthet értékeket a beépített és az egyéni attribútumokhoz is.
Megadhatja a konfigurált attribútumok felhasználói beviteli típusát is. Az alábbi táblázat összefoglalja a támogatott felhasználói beviteli típusokat, valamint azt, hogyan küldheti el a felhasználói felület vezérlői által gyűjtött értékeket a Microsoft Entra-nak.
| Felhasználói beviteli típus | A beküldött értékek formátuma |
|---|---|
| TextBox | Egyetlen érték, például a beosztás, a szoftvermérnök. |
| SingleRadioSelect | Egyetlen érték, például nyelv, norvég. |
| CheckboxMultiSelect | Egy vagy több érték, például hobbi vagy hobbi, Tánc vagy Tánc, Úszás, Utazás. |
Íme egy példakérés, amely bemutatja, hogyan küldi el az attribútumok értékeit:
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...
További információ a felhasználói attribútumok beviteli típusairól az Egyéni felhasználói attribútumok beviteli típusok című cikkben.
Felhasználói attribútumok hivatkozása
Amikor létrehoz egy regisztrációs felhasználói folyamatot, konfigurálja azokat a felhasználói attribútumokat, amelyeket a regisztráció során a felhasználótól szeretne gyűjteni. A Microsoft Entra felügyeleti központban található felhasználói attribútumok neve eltér attól, ahogyan a natív hitelesítési API-ban hivatkozik rájuk.
A Microsoft Entra felügyeleti központban például a megjelenítendő névre hivatkozik a rendszer displayName néven az API-ban.
A Felhasználói profil attribútumok című cikkből megtudhatja, hogyan hivatkozhat mind a beépített, mind az egyéni felhasználói attribútumokra a natív hitelesítési API-ban.
Bejelentkezési API-referencia
A felhasználóknak a regisztrációhoz használt hitelesítési módszerrel kell bejelentkezniük. A jelszó-hitelesítési módszerrel e-mailben regisztráló felhasználóknak például e-mailben és jelszóval kell bejelentkezniük.
Biztonsági jogkivonatok kéréséhez az alkalmazás három végponttal /initiate/challenge és /token.
Bejelentkezési API-végpontok
| Végpont | Leírás |
|---|---|
/initiate |
Ez a végpont elindítja a bejelentkezési folyamatot. Ha az alkalmazás egy már létező felhasználói fiók felhasználónevével hívja meg, egy folytatási jogkivonattal ad vissza egy sikeres választ. Ha az alkalmazás a Microsoft Entra által nem támogatott hitelesítési módszerek használatát kéri, ez a végpont-válasz jelezheti az alkalmazásnak, hogy böngészőalapú hitelesítési folyamatot kell használnia. |
/challenge |
az alkalmazás meghívja ezt a végpontot az identitásszolgáltatás által támogatott kihívástípusok listájával. Az identitásszolgáltatás létrehoz, majd egy egyszeri pin-kódot küld a kiválasztott kihívás csatornának, például az e-mailnek. Ha az alkalmazás többször is meghívja ezt a végpontot, a rendszer minden híváskor új OTP-t küld. |
/token |
Ez a végpont ellenőrzi az alkalmazástól kapott egyszeri pin-kódot, majd biztonsági jogkivonatokat ad ki az alkalmazásnak. |
Bejelentkezési kihívások típusai
Az API lehetővé teszi, hogy az alkalmazás meghirdetje az általa támogatott hitelesítési módszereket, amikor hívást kezdeményez a Microsoft Entra felé. Ehhez az alkalmazás a paramétert használja a challenge_type kéréseiben. Ez a paraméter előre definiált értékeket tartalmaz, amelyek különböző hitelesítési módszereket jelölnek.
Egy adott hitelesítési módszer esetében az alkalmazás által a Microsoft Entra számára a regisztrációs folyamat során küldött kihívástípus-értékek megegyeznek az alkalmazás bejelentkezéskor megadott értékeivel. A jelszó-hitelesítési módszerrel ellátott e-mail például oob, jelszó és átirányítási feladattípus-értékeket használ mind a regisztrációs, mind a bejelentkezési folyamatokhoz.
További információ a feladattípusokról a natív hitelesítési feladattípusokról szóló cikkben.
Bejelentkezési folyamat protokoll részletei
A folyamatábra bemutatja a bejelentkezési folyamat folyamatát.
Miután az alkalmazás ellenőrizte a felhasználó e-mail-címét az OTP-vel, biztonsági jogkivonatokat kap. Ha az egyszeri pin-kód kézbesítése késik vagy soha nem érkezik meg a felhasználó e-mailjéhez, a felhasználó kérheti egy másik egyszeri pin-kód küldését. A Microsoft Entra újrakend egy másik egyszeri pin-kódot, ha az előző nem lett ellenőrizve. Amikor a Microsoft Entra újra elküld egy egyszeri pin-kódot, az érvényteleníti a korábban elküldött kódot.
Az alábbi szakaszokban három alapvető lépésben foglaljuk össze a szekvenciadiagram folyamatát.
1. lépés: A bejelentkezési folyamat elindításának kérése
A hitelesítési folyamat azzal kezdődik, hogy az alkalmazás POST-kérelmet küld a /initiate végpontnak a bejelentkezési folyamat elindításához.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
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
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
username |
Igen | Az ügyfél felhasználójának e-mail címe, például contoso-consumer@contoso.com. |
challenge_type |
Igen | Az alkalmazás által támogatott oob password redirectengedélyezési feladattípus-sztringek szóközzel elválasztott listája. A listának mindig tartalmaznia kell a redirect feladat típusát. Az érték várhatóan az egyszeri pin-kód és password redirect a jelszóval rendelkező e-mailek esetében leszoob redirect. |
Sikeres válasz
Íme egy példa a sikeres válaszra:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Paraméter | Leírás |
|---|---|
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
Ha egy alkalmazás nem tudja támogatni a Microsoft Entra által megkövetelt hitelesítési módszert, vissza kell állítani a webes hitelesítési folyamatot. Ebben a forgatókönyvben a Microsoft Entra egy átirányítási feladattípus válaszában tájékoztatja az alkalmazást:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Paraméter | Leírás |
|---|---|
challenge_type |
A Microsoft Entra egy kihívástípusú választ ad vissza. Ennek a feladattípusnak az értéke átirányítás, amely lehetővé teszi az alkalmazás számára a webes hitelesítési folyamat használatát. |
Ez a válasz sikeresnek minősül, de az alkalmazásnak webalapú hitelesítési folyamatra kell váltania. Ebben az esetben javasoljuk, hogy a Microsoft által létrehozott és támogatott hitelesítési kódtárat használja.
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése nem sikerült, például ha a challenge_type paraméter érvénytelen feladattípust tartalmaz. vagy a kérés nem tartalmazta client_id az ügyfél-azonosító értéke üres vagy érvénytelen paramétert. A paraméter használatával error_description megismerheti a hiba pontos okát. |
unauthorized_client |
A kérelemben használt ügyfél-azonosító érvényes ügyfélazonosító-formátummal rendelkezik, de nem létezik a külső bérlőben, vagy helytelen. |
invalid_client |
Az alkalmazás által a kérelemben szereplő ügyfél-azonosító egy olyan alkalmazáshoz tartozik, amely nem rendelkezik natív hitelesítési konfigurációval, például nem nyilvános ügyfél, vagy nincs engedélyezve natív hitelesítésre. A paraméter használatával suberror megismerheti a hiba pontos okát. |
user_not_found |
A felhasználónév nem létezik. |
unsupported_challenge_type |
A challenge_type paraméter értéke nem tartalmazza a redirect feladat típusát. |
Ha a hibaparaméter értéke invalid_client, a Microsoft Entra tartalmaz egy paramétert suberror a válaszában. Egy invalid_client hiba paraméterének suberrorlehetséges értékei a következők:
| Alhálózati érték | Leírás |
|---|---|
nativeauthapi_disabled |
Egy olyan alkalmazás ügyfélazonosítója, amely nem engedélyezi a natív hitelesítést. |
2. lépés: Hitelesítési módszer kiválasztása
A folyamat folytatásához az alkalmazás az előző lépésből beszerzett folytatási jogkivonattal kéri a Microsoft Entrát, hogy válasszon ki egy támogatott feladattípust, amellyel a felhasználó hitelesítheti magát. Az alkalmazás POST kérést küld a /challenge végpontnak.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
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...
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
continuation_token |
Igen | A Microsoft Entra által az előző kérelemben visszaadott folytatási jogkivonat . |
challenge_type |
Nem | Az alkalmazás által támogatott oob password redirectengedélyezési feladattípus-sztringek szóközzel elválasztott listája. A listának mindig tartalmaznia kell a redirect feladat típusát. Az érték várhatóan az egyszeri pin-kód és password redirect a jelszóval rendelkező e-mailek esetében leszoob redirect. |
Sikeres válasz
Ha a bérlői rendszergazda a Felhasználó hitelesítési módszereként a Microsoft Entra felügyeleti központban konfigurálta az egyszeri pin-kód megadását, a Microsoft Entra egyszeri pin-kódot küld a felhasználó e-mail-címére, majd egy feladattípussal válaszol, és további információt nyújt az egyszeri pin-kódról.
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
}
| Paraméter | Leírás |
|---|---|
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
challenge_type |
A felhasználó által a hitelesítéshez kiválasztott feladattípus. |
binding_method |
Az egyetlen érvényes érték a parancssor. Ez a paraméter a jövőben további lehetőségeket kínál a felhasználó számára az egyszeri pin-kód megadására. Kiállítva, ha challenge_type oob |
challenge_channel |
Annak a csatornának a típusa, amelyen keresztül az egyszeri pin-kód el lett küldve. Jelenleg támogatjuk az e-maileket. |
challenge_target_label |
Egy elhomályosított e-mail, amelyben az egyszeri pin-kód lett elküldve. |
code_length |
A Microsoft Entra által létrehozott egyszeri pin-kód hossza. |
Ha egy alkalmazás nem tudja támogatni a Microsoft Entra által megkövetelt hitelesítési módszert, vissza kell állítani a webes hitelesítési folyamatot. Ebben a forgatókönyvben a Microsoft Entra egy átirányítási feladattípus válaszában tájékoztatja az alkalmazást:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Paraméter | Leírás |
|---|---|
challenge_type |
A Microsoft Entra egy kihívástípusú választ ad vissza. Ennek a feladattípusnak az értéke átirányítás, amely lehetővé teszi az alkalmazás számára a webes hitelesítési folyamat használatát. |
Ez a válasz sikeresnek minősül, de az alkalmazásnak webalapú hitelesítési folyamatra kell váltania. Ebben az esetben javasoljuk, hogy a Microsoft által létrehozott és támogatott hitelesítési kódtárat használja.
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése nem sikerült, például ha a challenge_type paraméter érvénytelen feladattípust tartalmaz. |
invalid_grant |
A kérelemben szereplő folytatási jogkivonat érvénytelen. |
expired_token |
A kérelemben szereplő folytatási jogkivonat lejárt. |
unsupported_challenge_type |
A challenge_type paraméter értéke nem tartalmazza a redirect feladat típusát. |
3. lépés: Biztonsági jogkivonatok kérése
Az alkalmazás POST kérést küld a /token végpontnak, és megadja a felhasználó előző lépésben kiválasztott hitelesítő adatait, ebben az esetben a jelszót a biztonsági jogkivonatok beszerzéséhez.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
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
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
continuation_token |
Igen | A Microsoft Entra által az előző kérelemben visszaadott folytatási jogkivonat . |
grant_type |
Igen | Az értéknek jelszónak kell lennie a jelszóhitelesítési módszerrel rendelkező e-mailekhez, az egyszeri pin-kód-hitelesítési módszernél pedig az oob értéknek. |
scope |
Igen | A hatókörök szóközzel elválasztott listája. Az összes hatókörnek egyetlen erőforrásból kell származnia, az OpenID Connect (OIDC) hatókörökkel együtt, például profilból, *openid-ből és e-mailből. Az alkalmazásnak openid hatókört kell tartalmaznia ahhoz, hogy a Microsoft Entra kibocsátson egy azonosító jogkivonatot. Az alkalmazásnak tartalmaznia kell offline_access hatókört ahhoz, hogy a Microsoft Entra kibocsátsa a frissítési jogkivonatot. További információ az engedélyekről és a hozzájárulásokról a Microsoft Identitásplatform. |
password |
Igen (jelszóval ellátott e-mailekhez) |
Az alkalmazás által az ügyfél felhasználójától gyűjtött jelszóérték. Cserélje le {secure_password} az alkalmazás által az ügyfélfelhasználótól gyűjtött jelszóértékre. |
oob |
Igen (egyszeri e-mail-jelszó esetén) |
Az az egyszeri pin-kód, amelyet az ügyfélfelhasználó kapott az e-mailben. Cserélje le {otp_code} az ügyfélfelhasználó által az e-mailben kapott egyszeri pin-kódra. Az egyszeri pin-kód újbóli megadásához az alkalmazásnak újra kell kérnie a /challenge végpontot. |
Sikeres válasz
Íme egy példa a sikeres válaszra:
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..."
}
| Paraméter | Leírás |
|---|---|
token_type |
A jogkivonat típusértékét jelzi. A Microsoft Entra csak a Bearer típust támogatja. |
scopes |
A hozzáférési jogkivonat által érvényes hatókörök szóközzel elválasztott listája. |
expires_in |
A hozzáférési jogkivonat érvényességi időtartama másodpercben. |
access_token |
Az alkalmazás által a /token végponttól kért hozzáférési jogkivonat. Az alkalmazás ezzel a hozzáférési jogkivonattal hozzáférést kérhet biztonságos erőforrásokhoz, például webes API-khoz. |
refresh_token |
OAuth 2.0 frissítési jogkivonat. Az alkalmazás ezt a jogkivonatot használhatja más hozzáférési jogkivonatok beszerzésére az aktuális hozzáférési jogkivonat lejárta után. A frissítési jogkivonatok hosszú élettartamúak. Hosszabb ideig fenntarthatják az erőforrásokhoz való hozzáférést. A hozzáférési jogkivonat frissítéséről további információt a hozzáférési jogkivonat frissítéséről szóló cikkben talál. Megjegyzés: Csak akkor adható ki, ha offline_access hatókört kér. |
id_token |
Az ügyfélfelhasználó azonosítására szolgáló JSON-webjogkivonat (Jwt). Az alkalmazás dekódolhatja a jogkivonatot, hogy információt kérjen a bejelentkezett felhasználóról. Az alkalmazás gyorsítótárazza és megjeleníti az értékeket, a bizalmas ügyfelek pedig ezt a jogkivonatot használhatják az engedélyezéshez. Az azonosító jogkivonatokkal kapcsolatos további információkért lásd az azonosító jogkivonatokat. Megjegyzés: Csak akkor adható ki, ha openid hatókört kér. |
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_grant",
"error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése nem sikerült. A történtek megértéséhez használja az üzenetet a hiba leírásában. |
invalid_grant |
A kérelemben szereplő folytatási jogkivonat érvénytelen, vagy a kérelemben szereplő ügyfélfelhasználói bejelentkezési hitelesítő adatok érvénytelenek, vagy a kérelemben szereplő támogatási típus ismeretlen. |
invalid_client |
A kérelemben szereplő ügyfélazonosító nem nyilvános ügyfélhez tartozik. |
expired_token |
A kérelemben szereplő folytatási jogkivonat lejárt. |
invalid_scope |
A kérelemben szereplő hatókör egy vagy több része érvénytelen. |
Ha a hibaparaméter értéke invalid_grant, a Microsoft Entra tartalmaz egy paramétert suberror a válaszában. Egy invalid_grant hiba paraméterének suberrorlehetséges értékei a következők:
| Alhálózati érték | Leírás |
|---|---|
invalid_oob_value |
Az egyszeri pin-kód értéke érvénytelen. Ez az alhiba csak egyszeri e-mail-jelszót alkalmaz |
Új jelszó önkiszolgáló kérése (self-service password reset, SSPR)
Ha az alkalmazás hitelesítési módszereként e-mailt és jelszót használ, az önkiszolgáló jelszó-visszaállítási (SSPR) API-val engedélyezheti az ügyfélfelhasználók számára, hogy visszaállítsák a jelszavukat. Használja ezt az API-t az elfelejtett jelszóhoz vagy a jelszómódosítási forgatókönyvekhez.
Önkiszolgáló jelszó-visszaállítási API-végpontok
Az API használatához az alkalmazás az alábbi táblázatban látható végponttal kommunikál:
| Végpont | Leírás |
|---|---|
/start |
Az alkalmazás meghívja ezt a végpontot, amikor az ügyfél felhasználója az Elfelejtett jelszó vagy a Jelszó módosítása hivatkozás vagy gombot választja az alkalmazásban. Ez a végpont ellenőrzi a felhasználó felhasználónevét (e-mail-címét), majd visszaad egy folytatási jogkivonatot a jelszó-visszaállítási folyamatban való használathoz. Ha az alkalmazás a Microsoft Entra által nem támogatott hitelesítési módszerek használatát kéri, ez a végpont-válasz jelezheti az alkalmazásnak, hogy böngészőalapú hitelesítési folyamatot kell használnia. |
/challenge |
Elfogadja az ügyfél és a folytatási jogkivonat által támogatott feladattípusok listáját. A feladat az egyik előnyben részesített helyreállítási hitelesítő adatra kerül ki. Az oob-kihívás például egy sávon kívüli egyszeri pin-kódot ad ki az ügyfél felhasználói fiókjához társított e-mailhez. Ha az alkalmazás a Microsoft Entra által nem támogatott hitelesítési módszerek használatát kéri, ez a végpont-válasz jelezheti az alkalmazásnak, hogy böngészőalapú hitelesítési folyamatot kell használnia. |
/continue |
Ellenőrzi a végpont által /challenge kiadott kihívást, majd visszaad egy folytatási jogkivonatot a /submit végponthoz, vagy egy másik kihívást ad ki a felhasználónak. |
/submit |
Elfogadja a felhasználó új jelszóbemenetét a folytatási jogkivonattal együtt a jelszó-visszaállítási folyamat befejezéséhez. Ez a végpont újabb folytatási jogkivonatot ad ki. |
/poll_completion |
Végül az alkalmazás használhatja a végpont által /submit kiadott folytatási jogkivonatot a jelszó-visszaállítási kérés állapotának ellenőrzéséhez. |
Új jelszó önkiszolgáló alaphelyzetbe állításával kapcsolatos kihívások típusai
Az API lehetővé teszi, hogy az alkalmazás meghirdetje az általa támogatott hitelesítési módszereket, amikor hívást kezdeményez a Microsoft Entra felé. Ehhez az alkalmazás a paramétert használja a challenge_type kéréseiben. Ez a paraméter előre definiált értékeket tartalmaz, amelyek különböző hitelesítési módszereket jelölnek.
Az SSPR-folyamat esetében a feladattípus értéke oob, és átirányítás.
További információ a natív hitelesítési feladattípusok feladattípusairól.
Az önkiszolgáló jelszó-visszaállítás folyamatprotokoll-részletei
A folyamatábra bemutatja a jelszó-visszaállítási folyamat folyamatát.
Ez a diagram azt jelzi, hogy az alkalmazás különböző időpontokban (és esetleg külön képernyőkön) gyűjti a felhasználó felhasználónevét (e-mail-címét) és jelszavát. Az alkalmazást azonban úgy is megtervezheti, hogy ugyanazon a képernyőn összegyűjtse a felhasználónevet (e-mailt) és az új jelszót. Ebben az esetben az alkalmazás tárolja a jelszót, majd elküldi a /submit végponton keresztül, ahol szükség van rá.
1. lépés: Az önkiszolgáló jelszó-visszaállítási folyamat elindításának kérése
A jelszó-visszaállítási folyamat azzal kezdődik, hogy az alkalmazás POST-kérést küld a /start végpontnak az önkiszolgáló jelszó-visszaállítási folyamat elindításához.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
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
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
username |
Igen | Az ügyfél felhasználójának e-mail címe, például contoso-consumer@contoso.com. |
challenge_type |
Igen | Az alkalmazás által támogatott oob password redirectengedélyezési feladattípus-sztringek szóközzel elválasztott listája. A listának mindig tartalmaznia kell a redirect feladat típusát. Ebben a kérésben az érték várhatóan tartalmazni fog.oob redirect |
Sikeres válasz
Példa:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Paraméter | Leírás |
|---|---|
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
Ha egy alkalmazás nem tudja támogatni a Microsoft Entra által megkövetelt hitelesítési módszert, vissza kell állítani a webes hitelesítési folyamatot. Ebben a forgatókönyvben a Microsoft Entra egy átirányítási feladattípus válaszában tájékoztatja az alkalmazást:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Paraméter | Leírás |
|---|---|
challenge_type |
A Microsoft Entra egy kihívástípusú választ ad vissza. Ennek a feladattípusnak az értéke átirányítás, amely lehetővé teszi az alkalmazás számára a webes hitelesítési folyamat használatát. |
Ez a válasz sikeresnek minősül, de az alkalmazásnak webalapú hitelesítési folyamatra kell váltania. Ebben az esetben javasoljuk, hogy a Microsoft által létrehozott és támogatott hitelesítési kódtárat használja.
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése sikertelen volt, például ha a challenge_type paraméter érvénytelen kihívástípust tartalmaz, vagy a kérés nem tartalmazta client_id az ügyfélazonosító üres vagy érvénytelen paraméterét. A paraméter használatával error_description megismerheti a hiba pontos okát. |
user_not_found |
A felhasználónév nem létezik. |
unsupported_challenge_type |
A challenge_type paraméter értéke nem tartalmazza a redirect feladat típusát. |
invalid_client |
Az alkalmazás által a kérelemben szereplő ügyfél-azonosító egy olyan alkalmazáshoz tartozik, amely nem rendelkezik natív hitelesítési konfigurációval, például nem nyilvános ügyfél, vagy nincs engedélyezve natív hitelesítésre. A paraméter használatával suberror megismerheti a hiba pontos okát. |
unauthorized_client |
A kérelemben használt ügyfél-azonosító érvényes ügyfélazonosító-formátummal rendelkezik, de nem létezik a külső bérlőben, vagy helytelen. |
Ha a hibaparaméter értéke invalid_client, a Microsoft Entra tartalmaz egy paramétert suberror a válaszában. Egy invalid_client hiba paraméterének suberrorlehetséges értékei a következők:
| Alhálózati érték | Leírás |
|---|---|
nativeauthapi_disabled |
Egy olyan alkalmazás ügyfélazonosítója, amely nem engedélyezi a natív hitelesítést. |
2. lépés: Hitelesítési módszer kiválasztása
A folyamat folytatásához az alkalmazás az előző lépésben beszerzett folytatási jogkivonattal kéri a Microsoft Entrát, hogy válasszon ki egy támogatott feladattípust, amellyel a felhasználó hitelesítheti magát. Az alkalmazás POST kérést küld a /challenge végpontnak. Ha a kérés sikeres, a Microsoft Entra egyszeri pin-kódot küld a felhasználó fiókjának e-mail-címére. Jelenleg csak az e-mailes OTP-t támogatjuk.
Íme egy példa (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
continuation_token |
Igen | A Microsoft Entra által az előző kérelemben visszaadott folytatási jogkivonat . |
challenge_type |
Nem | Az alkalmazás által támogatott oob redirectengedélyezési feladattípus-sztringek szóközzel elválasztott listája. A listának mindig tartalmaznia kell a redirect feladat típusát. Ebben a kérésben az érték várhatóan tartalmazni fog.oob redirect |
Sikeres válasz
Példa:
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
}
| Paraméter | Leírás |
|---|---|
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
challenge_type |
A felhasználó által a hitelesítéshez kiválasztott feladattípus. |
binding_method |
Az egyetlen érvényes érték a parancssor. Ez a paraméter a jövőben további lehetőségeket kínálhat a felhasználó számára az egyszeri pin-kód megadására. Kiállítva, ha challenge_type oob |
challenge_channel |
Annak a csatornának a típusa, amelyen keresztül az egyszeri pin-kód el lett küldve. Jelenleg támogatjuk az e-maileket. |
challenge_target_label |
Egy elhomályosított e-mail, amelyben az egyszeri pin-kód lett elküldve. |
code_length |
A Microsoft Entra által létrehozott egyszeri pin-kód hossza. |
Ha egy alkalmazás nem tudja támogatni a Microsoft Entra által megkövetelt hitelesítési módszert, vissza kell állítani a webes hitelesítési folyamatot. Ebben a forgatókönyvben a Microsoft Entra egy átirányítási feladattípus válaszában tájékoztatja az alkalmazást:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Paraméter | Leírás |
|---|---|
challenge_type |
A Microsoft Entra egy kihívástípusú választ ad vissza. Ennek a feladattípusnak az értéke átirányítás, amely lehetővé teszi az alkalmazás számára a webes hitelesítési folyamat használatát. |
Ez a válasz sikeresnek minősül, de az alkalmazásnak webalapú hitelesítési folyamatra kell váltania. Ebben az esetben javasoljuk, hogy a Microsoft által létrehozott és támogatott hitelesítési kódtárat használja.
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése sikertelen volt, például ha a challenge_type paraméter érvénytelen feladattípust tartalmaz, vagy a folytatási jogkivonat érvényesítése sikertelen volt. |
expired_token |
A folytatási jogkivonat lejárt. |
unsupported_challenge_type |
A challenge_type paraméter értéke nem tartalmazza a redirect feladat típusát. |
3. lépés: Egyszeri pin-kód elküldése
Az alkalmazás ezután POST kérést küld a /continue végpontnak. A kérésben az alkalmazásnak tartalmaznia kell az előző lépésben kiválasztott felhasználó hitelesítő adatait, valamint a végpontról kiadott folytatási /challenge jogkivonatot.
Íme egy példa a kérésre (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
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}
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
continuation_token |
Igen | A Microsoft Entra által az előző kérelemben visszaadott folytatási jogkivonat . |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
grant_type |
Igen | Az egyetlen érvényes érték az oob. |
oob |
Igen | Az az egyszeri pin-kód, amelyet az ügyfélfelhasználó kapott az e-mailben. Cserélje le {otp_code} az ügyfélfelhasználó által az e-mailben kapott egyszeri pin-kódra. Az egyszeri pin-kód újbóli megadásához az alkalmazásnak újra kell kérnie a /challenge végpontot. |
Sikeres válasz
Példa:
HTTP/1.1 200 OK
Content-Type: application/json
{
"expires_in": 600,
"continuation_token": "czZCaGRSa3F0MzpnW...",
}
| Paraméter | Leírás |
|---|---|
expires_in |
A continuation_token lejárata előtti idő másodpercben. A maximális érték expires_in600 másodperc. |
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
55200
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
suberror |
Hibakódsztring, amely a hibatípusok további besorolására használható. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése sikertelen volt, például a folytatási jogkivonat érvényesítése meghiúsult, vagy a kérés nem tartalmazta client_id az ügyfélazonosító üres vagy érvénytelen paraméterét, vagy a külső bérlői rendszergazda nem engedélyezte az SSPR-t, és nem küldött e-mailt az összes bérlői felhasználónak. A paraméter használatával error_description megismerheti a hiba pontos okát. |
invalid_grant |
A támogatás típusa ismeretlen, vagy nem felel meg a várt támogatástípus-értéknek. A paraméter használatával suberror megismerheti a hiba pontos okát. |
expired_token |
A folytatási jogkivonat lejárt. |
Ha a hibaparaméter értéke invalid_grant, a Microsoft Entra tartalmaz egy paramétert suberror a válaszában. Egy invalid_grant hiba paraméterének suberrorlehetséges értékei a következők:
| Alhálózati érték | Leírás |
|---|---|
invalid_oob_value |
A felhasználó által megadott egyszeri pin-kód érvénytelen. |
4. lépés: Új jelszó elküldése
Az alkalmazás új jelszót gyűjt a felhasználótól, majd a /continue végpont által kiadott folytatási jogkivonat használatával küldi el a jelszót post kéréssel a /submit végpontnak.
Íme egy példa (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
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}
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
continuation_token |
Igen | A Microsoft Entra által az előző kérelemben visszaadott folytatási jogkivonat . |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
new_password |
Igen | A felhasználó új jelszava. Cserélje le {new_password} a felhasználó új jelszavát. Az Ön felelőssége annak ellenőrzése, hogy a felhasználó tisztában van-e a használni kívánt jelszóval az alkalmazás felhasználói felületén található jelszó-megerősítési mező megadásával. Arról is gondoskodnia kell, hogy a felhasználó tisztában legyen azzal, hogy mi számít erős jelszónak a szervezet szabályzata szerint. További információ a Microsoft Entra jelszószabályzatairól. |
Sikeres válasz
Példa:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"poll_interval": 2
}
| Paraméter | Leírás |
|---|---|
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . |
poll_interval |
Az a minimális idő másodpercben, amíg az alkalmazásnak várnia kell a lekérdezési kérések között, hogy ellenőrizze a jelszó-visszaállítási kérés állapotát a /poll_completion végponton keresztül, lásd : 5. lépés |
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
suberror |
Hibakódsztring, amely a hibatípusok további besorolására használható. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése meghiúsult, például a folytatási jogkivonat ellenőrzése meghiúsult. |
expired_token |
A folytatási jogkivonat lejárt. |
invalid_grant |
A benyújtott támogatás érvénytelen, például a beküldött jelszó túl rövid. A paraméter használatával suberror megismerheti a hiba pontos okát. |
Ha a hibaparaméter értéke invalid_grant, a Microsoft Entra tartalmaz egy paramétert suberror a válaszában. A paraméter lehetséges értékei a suberror következők:
| Alhálózati érték | Leírás |
|---|---|
password_too_weak |
A jelszó túl gyenge, mivel nem felel meg az összetettségi követelményeknek. További információ a Microsoft Entra jelszószabályzatairól. |
password_too_short |
Az új jelszó 8 karakternél kevesebb karakterből áll. További információ a Microsoft Entra jelszószabályzatairól. |
password_too_long |
Az új jelszó 256 karakternél hosszabb. További információ a Microsoft Entra jelszószabályzatairól. |
password_recently_used |
Az új jelszó nem lehet ugyanaz, mint a közelmúltban használt jelszó. További információ a Microsoft Entra jelszószabályzatairól. |
password_banned |
Az új jelszó tiltott szót, kifejezést vagy mintát tartalmaz. További információ a Microsoft Entra jelszószabályzatairól. |
password_is_invalid |
A jelszó érvénytelen, például azért, mert nem engedélyezett karaktereket használ. További információ a Microsoft Entra jelszószabályzatairól. Ez a válasz akkor lehetséges, ha az alkalmazás felhasználói jelszót küld. |
5. lépés: A jelszó-visszaállítás állapotának lekérdezése
Végül, mivel a felhasználó konfigurációjának az új jelszóval való frissítése némi késéssel jár, az alkalmazás a végpont használatával lekérdezheti a /poll_completion Microsoft Entrát a jelszó-visszaállítás állapotáról. A paraméter végpontja adja /submit vissza az alkalmazás által a lekérdezési kérések közötti várakozás minimális időtartamát poll_interval másodpercben.
Íme egy példa (a példakérést több sorban mutatjuk be az olvashatóság érdekében):
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...
| Paraméter | Kötelező | Leírás |
|---|---|---|
tenant_subdomain |
Igen | A létrehozott külső bérlő altartománya. Az URL-címben cserélje le {tenant_subdomain} a Címtár (bérlő) altartományt. Ha például a bérlő elsődleges tartománya contoso.onmicrosoft.com, használja a contoso-t. Ha nincs bérlői altartománya, olvassa el a bérlő adatait. |
continuation_token |
Igen | A Microsoft Entra által az előző kérelemben visszaadott folytatási jogkivonat . |
client_id |
Igen | A Microsoft Entra felügyeleti központban regisztrált alkalmazás (ügyfél) azonosítója. |
Sikeres válasz
Példa:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "succeeded",
"continuation_token":"czZCaGRSa3F0..."
}
| Paraméter | Leírás |
|---|---|
status |
Az alaphelyzetbe állítási jelszó kérésének állapota. Ha a Microsoft Entra sikertelen állapotot ad vissza, az alkalmazás újraküldheti az új jelszót úgy, hogy egy másik kérést küld a /submit végpontnak, és belefoglalja az új folytatási jogkivonatot. |
continuation_token |
A Microsoft Entra által visszaadott folytatási jogkivonat . Ha az állapot sikeres, az alkalmazás használhatja a Microsoft Entra által visszaadott folytatási jogkivonatot a végponton keresztüli biztonsági jogkivonatok igényléséhez a /token regisztrációs folyamat 5. lépésében leírtak szerint. Ez azt jelenti, hogy miután egy felhasználó sikeresen visszaállította a jelszavát, közvetlenül bejelentkezhet az alkalmazásba anélkül, hogy új bejelentkezési folyamatot kezdeményez. |
A Microsoft Entra által visszaadott lehetséges állapotok (a status paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
succeeded |
A jelszó-visszaállítás sikeresen befejeződött. |
failed |
A jelszó alaphelyzetbe állítása nem sikerült. Az alkalmazás újraküldheti az új jelszót úgy, hogy egy másik kérést küld a /submit végpontnak. |
not_started |
A jelszó-visszaállítás nem indult el. Az alkalmazás később újra ellenőrizheti az állapotot. |
in_progress |
A jelszó alaphelyzetbe állítása folyamatban van. Az alkalmazás később újra ellenőrizheti az állapotot. |
Hibaválasz
Példa:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "expired_token",
"error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a hitelesítési hiba okának azonosításában. |
error_codes |
A Microsoft Entra-specifikus hibakódok listája, amelyek segíthetnek a hibák diagnosztizálásában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a hibák diagnosztizálásában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
Íme a lehetséges hibák (a error paraméter lehetséges értékei):
| Hibaérték | Leírás |
|---|---|
invalid_request |
A kérelemparaméter érvényesítése sikertelen volt, például a folytatási jogkivonat ellenőrzése meghiúsult. |
expired_token |
A folytatási jogkivonat lejárt. |
Következő lépések
Visszajelzés
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ: https://aka.ms/ContentUserFeedback.
Visszajelzés küldése és megtekintése a következőhöz: