Přidání konektoru rozhraní API do toku uživatele

Platí pro: Tenanti pracovních sil – externí tenanti (další informace)

Pokud chcete použít konektor rozhraní API, nejprve vytvoříte konektor rozhraní API a pak ho povolíte v toku uživatele.

Důležité

• Od 12. července 2021, pokud zákazníci Microsoft Entra B2B nastavili nové integrace Google pro použití s samoobslužnou registraci pro své vlastní nebo obchodní aplikace, ověřování s identitami Google nebude fungovat, dokud se ověřování nepřesune do systémových webových zobrazení. Další informace.
• Od 30. září 2021 google přestane podporovat přihlášení k vloženým webovým zobrazením. Pokud vaše aplikace ověřují uživatele pomocí vloženého webového zobrazení a používáte federaci Google s Azure AD B2C nebo Microsoft Entra B2B pro pozvání externích uživatelů nebo samoobslužnou registraci, uživatelé Google Gmailu se nebudou moct ověřit. Další informace.

Vytvoření konektoru rozhraní API

Tip

Postup v tomto článku se může mírně lišit v závislosti na portálu, od který začínáte.

1. Přihlaste se k Centru pro správu Microsoft Entra alespoň jako uživatel Správa istrator.

2. Přejděte na >Přehled externích>identit identit.

3. Vyberte Všechny konektory rozhraní API a pak vyberte Nový konektor rozhraní API.

   

4. Zadejte zobrazovaný název hovoru. Můžete například zkontrolovat stav schválení.

5. Zadejte adresu URL koncového bodu pro volání rozhraní API.

6. Zvolte typ ověřování a nakonfigurujte ověřovací informace pro volání rozhraní API. Zjistěte, jak zabezpečit rozhraní API Připojení or.

   

7. Zvolte Uložit.

Požadavek odeslaný do vašeho rozhraní API

Konektor rozhraní API se materializuje jako požadavek HTTP POST a odesílá atributy uživatele ('claims') jako páry klíč-hodnota v těle JSON. Atributy jsou serializovány podobně jako vlastnosti uživatele Microsoft Graphu .

Příklad požadavku

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

V požadavku se dají odesílat pouze vlastnosti uživatele a vlastní atributy uvedené v >prostředí Přehled>externích identit>identit.

Vlastní atributy existují ve formátu extension_<extensions-app-id>_AttributeName v adresáři. Vaše rozhraní API by mělo očekávat příjem deklarací identity ve stejném serializovaném formátu. Další informace o vlastníchatributch

Deklarace identity se navíc obvykle posílají ve všech žádostech:

• Národní prostředí uživatelského rozhraní (ui_locales) – národní prostředí koncového uživatele nakonfigurované na svém zařízení. Toto rozhraní API může použít k vrácení internationalizovaných odpovědí.

• E-mailová adresa (e-mailová adresa) nebo identity (identity) – tyto deklarace identity může vaše rozhraní API použít k identifikaci koncového uživatele, který se ověřuje v aplikaci.

Důležité

Pokud deklarace identity nemá v době volání koncového bodu rozhraní API hodnotu, deklarace identity se do rozhraní API neodesílají. Vaše rozhraní API by mělo být navržené tak, aby explicitně kontrolovat a zpracovávat případ, ve kterém deklarace identity není v požadavku.

Povolení konektoru rozhraní API v toku uživatele

Podle těchto kroků přidejte konektor rozhraní API do toku uživatele samoobslužné registrace.

1. Přihlaste se k Centru pro správu Microsoft Entra alespoň jako uživatel Správa istrator.

2. Přejděte na >Přehled externích>identit identit.

3. Vyberte Toky uživatele a pak vyberte tok uživatele, do kterého chcete přidat konektor rozhraní API.

4. Vyberte konektory rozhraní API a pak vyberte koncové body rozhraní API, které chcete vyvolat v následujícím postupu v toku uživatele:

   • Po federaci s zprostředkovatelem identity během registrace
   • Před vytvořením uživatele

   

5. Zvolte Uložit.

Po federaci s zprostředkovatelem identity během registrace

Konektor rozhraní API v tomto kroku v procesu registrace se vyvolá okamžitě po ověření uživatele u zprostředkovatele identity (jako je Google, Facebook nebo Microsoft Entra ID). Tento krok předchází stránce kolekce atributů, což je formulář před uživatelem ke shromažďování atributů uživatele.

Příklad požadavku odeslaného do rozhraní API v tomto kroku

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

Přesné deklarace identity odeslané do rozhraní API závisí na tom, které informace poskytuje zprostředkovatel identity. E-mail je vždy odeslán.

Očekávané typy odpovědí z webového rozhraní API v tomto kroku

Když webové rozhraní API obdrží požadavek HTTP z ID Microsoft Entra během toku uživatele, může vrátit tyto odpovědi:

• Odpověď na pokračování
• Blokující odpověď

Odpověď na pokračování

Odpověď na pokračování znamená, že tok uživatele by měl pokračovat dalším krokem: stránka kolekce atributů.

V odpovědi na pokračování může rozhraní API vracet deklarace identity. Pokud rozhraní API vrátí deklaraci identity, provede deklarace následující:

• Předvyplní vstupní pole na stránce kolekce atributů.

Podívejte se na příklad odpovědi na pokračování.

Blokující odpověď

Blokující odpověď ukončí tok uživatele. Rozhraní API může být záměrně vydáno, aby zastavilo pokračování toku uživatele zobrazením stránky bloku pro uživatele. Na stránce bloku se userMessage zobrazí poskytnutá rozhraním API.

Podívejte se na příklad blokující odpovědi.

Před vytvořením uživatele

Konektor rozhraní API v tomto kroku v procesu registrace se vyvolá po stránce kolekce atributů, pokud je součástí. Tento krok je vždy vyvolán před vytvořením uživatelského účtu v Microsoft Entra ID.

Příklad požadavku odeslaného do rozhraní API v tomto kroku

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

Přesné deklarace identity odeslané do rozhraní API závisí na tom, které informace se shromažďují od uživatele nebo které poskytuje zprostředkovatel identity.

Očekávané typy odpovědí z webového rozhraní API v tomto kroku

Když webové rozhraní API obdrží požadavek HTTP z ID Microsoft Entra během toku uživatele, může vrátit tyto odpovědi:

• Odpověď na pokračování
• Blokující odpověď
• Odpověď na ověření

Odpověď na pokračování

Odpověď na pokračování znamená, že tok uživatele by měl pokračovat dalším krokem: vytvořte uživatele v adresáři.

V odpovědi na pokračování může rozhraní API vracet deklarace identity. Pokud rozhraní API vrátí deklaraci identity, provede deklarace následující:

• Přepíše libovolnou hodnotu, která již byla přiřazena k deklaraci identity ze stránky kolekce atributů.

Podívejte se na příklad odpovědi na pokračování.

Blokující odpověď

Blokující odpověď ukončí tok uživatele. Rozhraní API může být záměrně vydáno, aby zastavilo pokračování toku uživatele zobrazením stránky bloku pro uživatele. Na stránce bloku se userMessage zobrazí poskytnutá rozhraním API.

Podívejte se na příklad blokující odpovědi.

Odpověď na chybu ověření

Když rozhraní API odpoví odpovědí na chybu ověření, tok uživatele zůstane na stránce kolekce atributů a userMessage uživateli se zobrazí. Uživatel pak může formulář upravit a znovu odeslat. Tento typ odpovědi lze použít pro ověření vstupu.

Podívejte se na příklad odpovědi na chybu ověřování.

Ukázkové odpovědi

Příklad odpovědi na pokračování

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
}

Parametr	Type	Požadováno	Popis
version	Řetězec	Ano	Verze vašeho rozhraní API.
action	String	Ano	Hodnota musí být Continue.
<builtInUserAttribute>	<attribute-type>	No	Hodnoty mohou být uloženy v adresáři, pokud jsou vybrány jako deklarace identity pro příjem v konfiguraci konektoru rozhraní API a atributy uživatele pro tok uživatele. Hodnoty lze v tokenu vrátit, pokud jsou vybrány jako deklarace identity aplikace.
<extension_{extensions-app-id}_CustomAttribute>	<attribute-type>	No	Deklarace identity nemusí obsahovat _<extensions-app-id>_, je volitelná. Vrácené hodnoty mohou přepsat hodnoty shromážděné od uživatele.

Příklad blokující odpovědi

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

Parametr	Type	Požadováno	Popis
version	Řetězec	Ano	Verze vašeho rozhraní API.
action	String	Ano	Hodnota musí být ShowBlockPage
userMessage	String	Ano	Zpráva, která se zobrazí uživateli.

Prostředí koncového uživatele s blokující odpovědí

Příklad odpovědi na chybu ověřování

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

Parametr	Type	Požadováno	Popis
version	Řetězec	Ano	Verze vašeho rozhraní API.
action	String	Ano	Hodnota musí být ValidationError.
stav	Celé číslo / řetězec	Ano	Musí být hodnota 400nebo "400" pro odpověď ValidationError.
userMessage	String	Ano	Zpráva, která se zobrazí uživateli.

Poznámka:

Stavový kód HTTP musí být kromě hodnoty status v textu odpovědi 400.

Prostředí koncového uživatele s odpovědí na chybu ověřování

Osvědčené postupy a postupy při řešení potíží

Použití bezserverových cloudových funkcí

Bezserverové funkce, jako jsou triggery HTTP ve službě Azure Functions, poskytují způsob, jak vytvářet koncové body rozhraní API pro použití s konektorem rozhraní API. Pomocí funkce bezserverového cloudu můžete například provést logiku ověřování a omezit registrace na konkrétní e-mailové domény. Funkce bezserverového cloudu může také volat a volat další webová rozhraní API, úložiště dat a další cloudové služby pro složité scénáře.

Osvědčené postupy

Zajistěte následující:

• Vaše rozhraní API sleduje kontrakty požadavků rozhraní API a odpovědí, jak je uvedeno výše.
• Adresa URL koncového bodu konektoru rozhraní API odkazuje na správný koncový bod rozhraní API.
• Vaše rozhraní API explicitně kontroluje hodnoty null přijatých deklarací identity, na které závisí.
• Vaše rozhraní API implementuje metodu ověřování popsanou v zabezpečení vašeho rozhraní API Připojení or.
• Vaše rozhraní API reaguje co nejrychleji, aby se zajistilo prostředí pro uživatele s proměnlivým prostředím.
  • Microsoft Entra ID čeká na přijetí odpovědi maximálně 20 sekund . Pokud se žádná nepřijala, provede další pokus (zkuste to znovu) při volání rozhraní API.
  • Pokud používáte bezserverovou funkci nebo škálovatelnou webovou službu, použijte plán hostování, který udržuje rozhraní API vzhůru nebo "teplé" v produkčním prostředí. Pro Azure Functions doporučujeme použít minimálně plán Premium.
• Zajistěte vysokou dostupnost vašeho rozhraní API.
• Monitorujte a optimalizujte výkon podřízených rozhraní API, databází nebo jiných závislostí vašeho rozhraní API.
• Vaše koncové body musí splňovat požadavky microsoft Entra TLS a zabezpečení šifrování. Další informace najdete v tématu Požadavky na protokol TLS a šifrovací sadu.

Použití protokolování

Obecně je užitečné použít nástroje protokolování povolené službou webového rozhraní API, jako je Application Insights, k monitorování neočekávaných kódů chyb, výjimek a nízkého výkonu.

• Monitorujte stavové kódy HTTP, které nejsou HTTP 200 nebo 400.
• Stavový kód HTTP 401 nebo 403 obvykle značí problém s ověřováním. Pečlivě zkontrolujte ověřovací vrstvu vašeho rozhraní API a odpovídající konfiguraci v konektoru rozhraní API.
• V případě potřeby používejte agresivnější úrovně protokolování (například "trace" nebo "debug").
• Monitorujte rozhraní API po dlouhou dobu odezvy.

Další kroky

• Zjistěte, jak přidat vlastní pracovní postup schvalování do samoobslužné registrace.
• Začínáme s našimi ukázkami rychlého startu