API-összekötő hozzáadása felhasználói folyamathoz

A következőkre vonatkozik:Munkaerő-bérlők Külső bérlők (további információ)

API-összekötő használatához először létre kell hoznia az API-összekötőt, majd engedélyeznie kell azt egy felhasználói folyamatban.

Fontos

• 2021. július 12-től, ha a Microsoft Entra B2B ügyfelei új Google-integrációkat állítottak be az egyéni vagy üzletági alkalmazásokhoz való önkiszolgáló regisztrációhoz, a Google-identitásokkal történő hitelesítés addig nem fog működni, amíg a hitelesítések át nem kerülnek a rendszer webnézeteibe. További információ.
• 2021. szeptember 30-tól a Google elavulttá tette a beágyazott webes nézet bejelentkezési támogatását. Ha alkalmazásai beágyazott webnézettel hitelesítik a felhasználókat, és a Google összevonást használja az Azure AD B2C-vel vagy a Microsoft Entra B2B-vel külső felhasználói meghívásokhoz vagy önkiszolgáló regisztrációhoz, a Google Gmail-felhasználók nem fognak tudni hitelesíteni. További információ.

API-összekötő létrehozása

Tipp.

A cikkben szereplő lépések a portáltól függően kissé eltérhetnek.

1. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább felhasználói Rendszergazda istratorként.

2. Keresse meg az identitás>külső identitásainak áttekintését.>

3. Válassza az Összes API-összekötő, majd az Új API-összekötő lehetőséget.

   

4. Adja meg a hívás megjelenítendő nevét. Például ellenőrizze a jóváhagyási állapotot.

5. Adja meg az API-hívás végponti URL-címét .

6. Válassza ki a hitelesítés típusát , és konfigurálja a hitelesítési adatokat az API meghívásához. Megtudhatja, hogyan védheti meg az API-Csatlakozás ort.

   

7. Válassza a Mentés lehetőséget.

Az API-nak küldött kérés

Az API-összekötők HTTP POST-kérésként valósulnak meg, és a JSON-törzsben kulcs-érték párokként küldik el a felhasználói attribútumokat ('jogcímek'). Az attribútumok a Microsoft Graph felhasználói tulajdonságaihoz hasonlóan szerializálva vannak.

Példakérés

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

A kérelemben csak az Identitás>külső identitások>áttekintésében> szereplő felhasználói tulajdonságok és egyéni attribútumok érhetők el.

Az egyéni attribútumok a könyvtár extension_<extensions-app-id>_AttributeName formátumában találhatók. Az API-nak ugyanabban a szerializált formátumban kell jogcímeket fogadnia. Az egyéni attribútumokról további információt az önkiszolgáló regisztrációs folyamatok egyéni attribútumainak definiálása című témakörben talál.

Emellett a jogcímeket általában minden kérelemben elküldik:

• Felhasználói felület területi beállításai ('ui_locales') – A végfelhasználó területi beállításai az eszközükön konfigurálva. Ezt az API használhatja nemzetközi válaszok visszaadására.

• E-mail-cím (e-mail) vagy identitások (identitások) – ezeket a jogcímeket az API felhasználhatja az alkalmazáshoz hitelesítő végfelhasználó azonosítására.

Fontos

Ha egy jogcím nem rendelkezik értékkel az API-végpont meghívásakor, a jogcím nem lesz elküldve az API-nak. Az API-t úgy kell megtervezni, hogy explicit módon ellenőrizze és kezelje azt az esetet, amikor egy jogcím nem szerepel a kérelemben.

Az API-összekötő engedélyezése egy felhasználói folyamatban

Az alábbi lépéseket követve hozzáadhat egy API-összekötőt egy önkiszolgáló regisztrációs felhasználói folyamathoz.

1. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább felhasználói Rendszergazda istratorként.

2. Keresse meg az identitás>külső identitásainak áttekintését.>

3. Válassza ki a Felhasználói folyamatok lehetőséget, majd válassza ki azt a felhasználói folyamatot, amelyhez hozzá szeretné adni az API-összekötőt.

4. Válassza ki az API-összekötőket, majd válassza ki a meghívni kívánt API-végpontokat a felhasználói folyamat következő lépéseiben:

   • Identitásszolgáltatóval való összevonás után a regisztráció során
   • A felhasználó létrehozása előtt

   

5. Válassza a Mentés lehetőséget.

Identitásszolgáltatóval való összevonás után a regisztráció során

A regisztrációs folyamat ezen lépésében egy API-összekötőt azonnal meghív a rendszer, miután a felhasználó hitelesítést végzett egy identitásszolgáltatóval (például Google, Facebook vagy Microsoft Entra ID). Ez a lépés megelőzi az attribútumgyűjtemény lapját, amely a felhasználó által a felhasználói attribútumok gyűjtésére szolgáló űrlap.

Ebben a lépésben az API-nak küldött példakérés

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Az API-nak küldött pontos jogcímek attól függenek, hogy az identitásszolgáltató mely adatokat adja meg. Az "e-mail" mindig el lesz küldve.

A webes API várt választípusai ebben a lépésben

Amikor a webes API HTTP-kérést kap a Microsoft Entra-azonosítótól egy felhasználói folyamat során, a következő válaszokat tudja visszaadni:

• Folytatási válasz
• A válasz blokkolása

Folytatási válasz

A folytatási válasz azt jelzi, hogy a felhasználói folyamatnak a következő lépésre kell lépnie: az attribútumgyűjtemény oldalára.

A folytatási válaszban az API jogcímeket adhat vissza. Ha az API egy jogcímet ad vissza, a jogcím a következőt teszi:

• Előre kitölti a bemeneti mezőt az attribútumgyűjtemény oldalán.

Tekintse meg a folytatásra adott válasz példáját.

A válasz blokkolása

A blokkoló válasz kilép a felhasználói folyamatból. Az API szándékosan kibocsáthatja a felhasználói folyamat folytatásának leállításához egy blokkoldal megjelenítésével a felhasználó számára. A blokklapon az userMessage API által biztosítottak jelennek meg.

Tekintse meg a blokkoló válasz példáját.

A felhasználó létrehozása előtt

A regisztrációs folyamat ezen lépésében egy API-összekötőt hív meg az attribútumgyűjtemény lapja után, ha van ilyen. Ezt a lépést mindig meghívja a rendszer, mielőtt létrehoz egy felhasználói fiókot a Microsoft Entra-azonosítóban.

Ebben a lépésben az API-nak küldött példakérés

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Az API-nak küldött pontos jogcímek attól függenek, hogy a rendszer mely adatokat gyűjti a felhasználótól, vagy az identitásszolgáltató adja meg.

A webes API várt választípusai ebben a lépésben

Amikor a webes API HTTP-kérést kap a Microsoft Entra-azonosítótól egy felhasználói folyamat során, a következő válaszokat tudja visszaadni:

• Folytatási válasz
• A válasz blokkolása
• Érvényesítési válasz

Folytatási válasz

A folytatási válasz azt jelzi, hogy a felhasználói folyamatnak a következő lépésre kell haladnia: hozza létre a felhasználót a címtárban.

A folytatási válaszban az API jogcímeket adhat vissza. Ha az API egy jogcímet ad vissza, a jogcím a következőt teszi:

• Felülbírálja az attribútumgyűjtemény oldaláról a jogcímhez már hozzárendelt értékeket.

Tekintse meg a folytatásra adott válasz példáját.

A válasz blokkolása

A blokkoló válasz kilép a felhasználói folyamatból. Az API szándékosan kibocsáthatja a felhasználói folyamat folytatásának leállításához egy blokkoldal megjelenítésével a felhasználó számára. A blokklapon az userMessage API által biztosítottak jelennek meg.

Tekintse meg a blokkoló válasz példáját.

Érvényesítési hiba válasza

Amikor az API érvényesítési hibaválaszsal válaszol, a felhasználói folyamat az attribútumgyűjtemény oldalán marad, és megjelenik egy userMessage a felhasználó számára. A felhasználó ezután szerkesztheti és újból elküldheti az űrlapot. Ez a választípus használható a bemeneti ellenőrzéshez.

Tekintse meg az érvényesítési hiba válaszának példáját.

Példaválaszok

Példa folytatási válaszra

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

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Paraméter	Típus	Kötelező	Leírás
Verzió	Sztring	Igen	Az API verziója.
művelet	Sztring	Igen	Az értéknek meg kell lennie Continue.
<builtInUserAttribute>	<attribútumtípus>	Nem	Az értékek tárolhatók a címtárban, ha jogcímként vannak kiválasztva, hogy fogadják az API-összekötő konfigurációját és a felhasználói folyamat felhasználói attribútumait . Az értékek visszaadhatók a jogkivonatban, ha alkalmazásjogcímként van kiválasztva.
<extension_{extensions-app-id}_CustomAttribute>	<attribútumtípus>	Nem	A jogcímnek nem kell tartalmaznia _<extensions-app-id>_, nem kötelező. A visszaadott értékek felülírhatják a felhasználótól gyűjtött értékeket.

Példa blokkoló válaszra

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

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

Paraméter	Típus	Kötelező	Leírás
Verzió	Sztring	Igen	Az API verziója.
művelet	Sztring	Igen	Az értéknek ShowBlockPage
userMessage	Sztring	Igen	A felhasználó számára megjelenítendő üzenet.

Végfelhasználói élmény blokkoló válaszokkal

Példa egy érvényesítési hiba válaszára

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

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

Paraméter	Típus	Kötelező	Leírás
Verzió	Sztring	Igen	Az API verziója.
művelet	Sztring	Igen	Az értéknek meg kell lennie ValidationError.
status	Egész szám / sztring	Igen	Értéknek 400"400" vagy ValidationError-válasznak kell lennie.
userMessage	Sztring	Igen	A felhasználó számára megjelenítendő üzenet.

Feljegyzés

A HTTP-állapotkódnak "400" értékűnek kell lennie a válasz törzsében lévő "status" érték mellett.

Végfelhasználói élmény érvényesítési hibaválaszsal

Ajánlott eljárások és hibaelhárítás

Kiszolgáló nélküli felhőfüggvények használata

A kiszolgáló nélküli függvények, például az Azure Functions HTTP-eseményindítói, lehetővé teszik API-végpontok létrehozását az API-összekötővel való használathoz. A kiszolgáló nélküli felhőfüggvény használatával például érvényesítési logikát hajthat végre, és korlátozhatja a regisztrációkat adott e-mail-tartományokra. A kiszolgáló nélküli felhőfüggvény más webes API-kat, adattárakat és más felhőszolgáltatásokat is meghívhat és meghívhat összetett forgatókönyvek esetén.

Ajánlott eljárások

Győződjön meg a következőkről:

• Az API a fent ismertetett API-kérési és válaszszerződéseket követi.
• Az API-összekötő végponti URL-címe a megfelelő API-végpontra mutat.
• Az API kifejezetten ellenőrzi a kapott jogcímek null értékeit, amelyektől függ.
• Az API implementál egy hitelesítési módszert, amely az API-Csatlakozás or biztonságossá tételében szerepel.
• Az API a lehető leggyorsabban válaszol a zökkenőmentes felhasználói élmény biztosítása érdekében.
  • A Microsoft Entra ID legfeljebb 20 másodpercig vár a válasz fogadására. Ha egyik sem érkezik meg, még egy kísérletet tesz (újrapróbálkozza) az API meghívására.
  • Ha kiszolgáló nélküli függvényt vagy méretezhető webszolgáltatást használ, használjon olyan üzemeltetési tervet, amely "ébren" vagy "melegen" tartja az API-t az éles környezetben. Az Azure Functions esetében ajánlott legalább a Prémium csomag használata.
• Gondoskodjon az API magas rendelkezésre állásáról.
• Monitorozza és optimalizálja az API alsóbb rétegbeli API-jainak, adatbázisainak vagy egyéb függőségeinek teljesítményét.
• A végpontoknak meg kell felelniük a Microsoft Entra TLS és a titkosítás biztonsági követelményeinek. További információ: TLS és titkosítási csomag követelményei.

Naplózás használata

Általában hasznos, ha a webes API-szolgáltatás által engedélyezett naplózási eszközökkel (például az Application Insightsszal) figyeli az API-t váratlan hibakódok, kivételek és gyenge teljesítmény esetén.

• Olyan HTTP-állapotkódok figyelése, amelyek nem HTTP 200 vagy 400.
• A 401 vagy 403 HTTP-állapotkód általában azt jelzi, hogy probléma van a hitelesítéssel. Ellenőrizze duplán az API hitelesítési rétegét és a megfelelő konfigurációt az API-összekötőben.
• Ha szükséges, használjon agresszívebb naplózási szinteket (például "trace" vagy "debug") a fejlesztés során.
• Monitorozza az API-t a hosszú válaszidőkért.

Következő lépések

• Megtudhatja, hogyan adhat hozzá egyéni jóváhagyási munkafolyamatot az önkiszolgáló regisztrációhoz
• Első lépések a rövid útmutatókban.