API-összekötők használata a regisztrációs felhasználói folyamatok és egyéni szabályzatok testreszabásához és kiterjesztéséhez külső identitás adatforrásokkal

Mielőtt hozzákezdene, válassza ki a beállított szabályzattípust a Szabályzattípus kiválasztása választóval. Az Azure Active Directory B2C két módszert kínál annak meghatározására, hogy a felhasználók hogyan használják az alkalmazásokat: előre meghatározott felhasználói folyamatokon vagy teljes mértékben konfigurálható egyéni szabályzatokon keresztül. Az ebben a cikkben előírt lépések különbözőek az egyes metódusok esetében.

Áttekintés

Fejlesztőként vagy informatikai rendszergazdaként API-összekötőkkel integrálhatja a regisztrációs felhasználói folyamatokat REST API-kkal a regisztrációs élmény testreszabásához és a külső rendszerekkel való integráláshoz. Az API-összekötőkkel például a következőket teheti:

• Felhasználói beviteli adatok ellenőrzése. Ellenőrizze a helytelen vagy érvénytelen felhasználói adatokat. Például ellenőrizheti a felhasználó által megadott adatokat egy külső adattár meglévő adataival vagy az engedélyezett értékek listájával. Ha érvénytelen, megkérheti a felhasználót, hogy adjon meg érvényes adatokat, vagy tiltsa le a felhasználót a regisztrációs folyamat folytatásában.
• Ellenőrizze a felhasználói identitást. Identitás-ellenőrzési szolgáltatás vagy külső identitás adatforrások használatával további biztonsági szintet adhat a fióklétrehozáshoz.
• Integrálás egyéni jóváhagyási munkafolyamattal. Csatlakozzon egy egyéni jóváhagyási rendszerhez a fióklétrehozás kezeléséhez és korlátozásához.
• Tokenek bővítése külső forrásokból származó attribútumokkal. Bővítse a jogkivonatokat a felhasználó attribútumaival a Azure AD B2C-től eltérő forrásokból, például felhőrendszerekből, egyéni felhasználói tárolókból, egyéni engedélyrendszerekből, örökölt identitásszolgáltatásokból és egyebekből.
• Felhasználói attribútumok felülírása. Érték újraformázása vagy hozzárendelése a felhasználótól gyűjtött attribútumhoz. Ha például egy felhasználó az utónevet az összes kisbetűben vagy az összes nagybetűben beírja, a nevet csak az első betű nagybetűvel formázhatja.
• Egyéni üzleti logika futtatása. A felhőrendszerek alsóbb rétegbeli eseményeit leküldéses értesítések küldéséhez, vállalati adatbázisok frissítéséhez, engedélyek kezeléséhez, adatbázisok naplózásához és egyéb egyéni műveletek végrehajtásához aktiválhatja.

Az API-összekötők a HTTP-végpont URL-címének és az API-hívás hitelesítésének meghatározásával biztosítják Azure AD B2C-nek az API-végpont meghívásához szükséges információkat. Miután konfigurált egy API-összekötőt, engedélyezheti azt a felhasználói folyamat egy adott lépéséhez. Amikor egy felhasználó eléri ezt a lépést a regisztrációs folyamat során, a rendszer meghívja az API-összekötőt, és HTTP POST-kérésként materializálódik az API-nak, és kulcs-érték párként küld felhasználói adatokat ("jogcímeket") egy JSON-törzsben. Az API-válasz hatással lehet a felhasználói folyamat végrehajtására. Az API-válasz például megakadályozhatja, hogy a felhasználó regisztráljon, kérje meg a felhasználót, hogy adjon meg adatokat, vagy írja felül a felhasználói attribútumokat.

Ahol engedélyezheti az API-összekötőt egy felhasználói folyamatban

A felhasználói folyamatnak három olyan helye van, ahol engedélyezheti az API-összekötőket:

• Miután összevonást végzett egy identitásszolgáltatóval a regisztráció során – csak a regisztrációs szolgáltatásokra vonatkozik
• A felhasználó létrehozása előtt – csak a regisztrációkra vonatkozik
• A jogkivonat (előzetes verzió) elküldése előtt – a regisztrációkra és a bejelentkezésekre vonatkozik

Miután összevonást végzett egy identitásszolgáltatóval 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 és Microsoft Entra azonosító). Ez a lépés megelőzi az attribútumgyűjtemény lapját, amely a felhasználó számára a felhasználói attribútumok gyűjtésére szolgáló űrlap. Ez a lépés nem lesz meghívva, ha egy felhasználó helyi fiókkal regisztrál. Az alábbi példák az API-összekötőkre vonatkozó forgatókönyvekre, amelyeket ebben a lépésben engedélyezhet:

• Használja azt az e-mailt vagy összevont identitást, amelyet a felhasználó megadott a meglévő rendszerben lévő jogcímek kereséséhez. Adja vissza ezeket a jogcímeket a meglévő rendszerből, töltse ki előre az attribútumgyűjtemény oldalát, és tegye őket elérhetővé a jogkivonatban való visszatéréshez.
• Közösségi identitáson alapuló engedélyezési vagy tiltólista implementálása.

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 a program az attribútumgyűjtési oldal után, ha van ilyen. Ezt a lépést a rendszer mindig meghívja a felhasználói fiók létrehozása előtt. Az alábbi példák olyan forgatókönyveket mutatnak be, amelyeket a regisztráció során ezen a ponton engedélyezhet:

• Ellenőrizze a felhasználói bemeneti adatokat, és kérje meg a felhasználót, hogy küldje újra az adatokat.
• Felhasználó regisztrációjának letiltása a felhasználó által megadott adatok alapján.
• Ellenőrizze a felhasználói identitást.
• Lekérdezheti a külső rendszereket, hogy a felhasználó meglévő adatai visszajuttathatók-e az alkalmazás jogkivonatában, vagy Microsoft Entra azonosítóban tárolják.

A jogkivonat elküldése előtt (előzetes verzió)

Megjegyzés

Ez a funkció nyilvános előzetes verzióban érhető el.

A regisztrációs vagy bejelentkezési folyamat ezen lépésében egy API-összekötőt hív meg a jogkivonat kiadása előtt. Az alábbi példák azokra a forgatókönyvekre mutatnak be, amelyeket ebben a lépésben engedélyezhet:

• A jogkivonat bővítése a felhasználó attribútumaival a címtártól eltérő forrásokból, beleértve az örökölt identitásrendszereket, a HR-rendszereket, a külső felhasználói tárolókat és egyebeket.
• A jogkivonat bővítése a saját engedélyrendszerében tárolt és kezelt csoport- vagy szerepkörattribútumokkal.
• Jogcímátalakítások vagy -manipulációk alkalmazása a címtárban lévő jogcímek értékeire.

Az Azure Active Directory B2C (Azure AD B2C) alapjául szolgáló Identity Experience Framework integrálható a RESTful API-kkal egy felhasználói folyamaton belül. Ez a cikk bemutatja, hogyan hozhat létre olyan felhasználói folyamatot, amely RESTful technikai profillal kommunikál egy RESTful szolgáltatással.

A Azure AD B2C használatával saját üzleti logikát adhat hozzá egy felhasználói folyamathoz a saját RESTful szolgáltatás meghívásával. Az Identity Experience Framework adatokat küldhet és fogadhat a RESTful szolgáltatásból a jogcímek cseréjéhez. Megteheti például a következőt:

• Használjon külső identitás adatforrást a felhasználói bemeneti adatok ellenőrzéséhez. Ellenőrizheti például, hogy a felhasználó által megadott e-mail-cím megtalálható-e az ügyfél adatbázisában, és ha nem, hibát jelez. Az API-összekötőket a kimenő webhookok támogatásának is tekintheti, mivel a hívás esemény bekövetkezésekor történik, például regisztrációkor.
• Jogcímek feldolgozása. Ha egy felhasználó az utónevét minden kisbetűben vagy az összes nagybetűben megadja, a REST API csak az első nagybetűvel formázhatja a nevet, és visszaadhatja Azure AD B2C-nek. Egyéni szabályzat használata esetén azonban a ClaimsTransformations használata előnyben részesítve a RESTful API meghívását.
• Dinamikusan bővítheti a felhasználói adatokat a vállalati üzletági alkalmazásokkal való további integrációval. A RESTful szolgáltatás megkaphatja a felhasználó e-mail-címét, lekérdezheti az ügyfél adatbázisát, és visszaadhatja a felhasználó hűségszámát Azure AD B2C-nek. Ezután a visszaadott jogcímek tárolhatók a felhasználó Microsoft Entra fiókjában, kiértékelhetők a következő vezénylési lépésekben, vagy belefoglalhatók a hozzáférési jogkivonatba.
• Egyéni üzleti logika futtatása. Leküldéses értesítéseket küldhet, frissítheti a vállalati adatbázisokat, futtathat egy felhasználói migrálási folyamatot, kezelheti az engedélyeket, naplózhatja az adatbázisokat, és bármilyen más munkafolyamatot végrehajthat.

Megjegyzés

Ha a RESTful szolgáltatás lassan vagy egyáltalán nem válaszol Azure AD B2C-re, az időtúllépés 30 másodperc, az újrapróbálkozások száma pedig kétszer (tehát összesen 3 próbálkozás van). Jelenleg nem konfigurálhatja az időtúllépési és újrapróbálkozás-számlálási beállításokat.

RESTful szolgáltatás meghívása

Az interakció magában foglalja a REST API-jogcímek és a B2C Azure AD közötti adatcserét. A RESTful-szolgáltatásokkal való integrációt a következő módokon tervezheti meg:

• Érvényesítési műszaki profil. A RESTful szolgáltatás hívása a megadott önérvényesített műszaki profilérvényesítési műszaki profilján vagy egy megjelenítési vezérlőellenőrző megjelenítési vezérlőjén belül történik. Az érvényesítési műszaki profil ellenőrzi a felhasználó által megadott adatokat, mielőtt a felhasználói folyamat továbbhalad. Az érvényesítési műszaki profillal a következő műveletekre van lehetőség:

  • Jogcímek küldése a REST API-nak.
  • Ellenőrizze a jogcímeket, és egyéni hibaüzeneteket jelenítsen meg a felhasználó számára.
  • Jogcímeket küldhet vissza a REST API-ból a következő vezénylési lépésekre.

• Jogcímcsere. A közvetlen jogcímcsere konfigurálható úgy, hogy egy REST API-technikai profilt közvetlenül egy felhasználói folyamat vezénylési lépéséből hív meg. Ez a definíció a következőkre korlátozódik:

  • Jogcímek küldése a REST API-nak.
  • Ellenőrizze a jogcímeket, és egyéni hibaüzeneteket küld az alkalmazásnak.
  • Jogcímeket küldhet vissza a REST API-ból a következő vezénylési lépésekre.

A REST API-hívásokat az egyéni szabályzat által meghatározott felhasználói folyamat bármely lépésében hozzáadhatja. Meghívhat például EGY REST API-t:

• Bejelentkezéskor közvetlenül a Azure AD előtt a B2C ellenőrzi a hitelesítő adatokat.
• Közvetlenül a bejelentkezés után.
• Mielőtt Azure AD B2C létrehoz egy új fiókot a címtárban.
• Miután Azure AD A B2C létrehoz egy új fiókot a címtárban.
• Mielőtt Azure AD B2C kiad egy hozzáférési jogkivonatot.

Adatok küldése

A RESTful műszaki profilban az elem tartalmazza a InputClaims RESTful szolgáltatásnak küldendő jogcímek listáját. A jogcím nevét leképezheti a RESTful szolgáltatásban meghatározott névre, beállíthat egy alapértelmezett értéket, és jogcímfeloldókat használhat.

A bemeneti jogcímek küldési módját a RESTful jogcímszolgáltatónak a SendClaimsIn attribútum használatával konfigurálhatja. Lehetséges értékek:

• Törzs, elküldve a HTTP POST kérelemtörzsében JSON formátumban.
• Űrlap, amelyet a HTTP POST kérelemtörzsében és "&" elválasztott kulcsérték formátumban küld el.
• Fejléc, elküldve a HTTP GET kérelem fejlécében.
• QueryString, elküldve a HTTP GET kérelem lekérdezési sztringjében.

A Törzs beállítás konfigurálásakor a REST API műszaki profilja lehetővé teszi, hogy összetett JSON-hasznos adatokat küldjön egy végpontnak. További információ: JSON-hasznos adat küldése.

Adatok fogadása

A OutputClaimsRESTful technikai profil eleme tartalmazza a REST API által visszaadott jogcímek listáját. Előfordulhat, hogy le kell képeznie a szabályzatban meghatározott jogcím nevét a REST API-ban meghatározott névre. Olyan jogcímeket is megadhat, amelyeket a REST API-identitásszolgáltató nem ad vissza, feltéve, hogy beállítja a DefaultValue attribútumot.

A RESTful jogcímszolgáltató által elemezett kimeneti jogcímek mindig arra számítanak, hogy egy sima JSON-törzsválaszt elemeznek, például:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

A kimeneti jogcímek a következő xml-kódrészlethez hasonlóan néznek ki:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Null értékek kezelése

Ha egy oszlop értéke ismeretlen vagy hiányzik, az adatbázis nullértéket használ. Ne tartalmazzon értékekkel rendelkező null JSON-kulcsokat. A következő példában az e-mail értéket ad null vissza:

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Ha egy elem null értékű, a következők valamelyike:

• A kulcs-érték pár kihagyása a JSON-ból.
• Olyan értéket ad vissza, amely megfelel a B2C-jogcím adattípusának Azure AD. Adattípus esetén például üres sztringet string""ad vissza. integer Adattípus esetén nulla értéket 0ad vissza. dateTime Adattípus esetén adjon meg egy minimális értéket1970-00-00T00:00:00.0000000Z.

Az alábbi példa bemutatja, hogyan kezelhető a null érték. Az e-mail hiányzik a JSON-ból:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Beágyazott JSON-törzs elemzése

Beágyazott JSON-törzsválasz elemzéséhez állítsa a ResolveJsonPathsInJsonTokens metaadatokat true (igaz) értékre. A kimeneti jogcímben állítsa a PartnerClaimType értéket a kimenetként megjeleníteni kívánt JSON-elérési útelemre.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

A kimeneti jogcímek a következő xml-kódrészlethez hasonlóan néznek ki:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

A REST API honosítása

A RESTful technikai profilban érdemes lehet elküldeni az aktuális munkamenet nyelvét/területi beállítását, és szükség esetén honosított hibaüzenetet küldeni. A jogcímfeloldóval környezeti jogcímeket küldhet, például a felhasználói nyelvet. Az alábbi példa egy RESTful technikai profilt mutat be, amely ezt a forgatókönyvet mutatja be.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Hibaüzenetek kezelése

Előfordulhat, hogy a REST API-nak vissza kell küldenie egy hibaüzenetet, például: "A felhasználó nem található a CRM-rendszerben". Hiba esetén a REST API-nak HTTP 409-hibaüzenetet kell visszaadnia (Ütközési válasz állapotkódja). További információt a RESTful műszaki profilban talál.

Ez a viselkedés csak akkor érhető el, ha egy REST API műszaki profilt hív meg egy érvényesítési műszaki profilból. Lehetővé teszi a felhasználónak, hogy javítsa ki az oldalon lévő adatokat, és futtassa újra az ellenőrzést az oldal elküldésekor.

Ha közvetlenül egy felhasználói folyamatból hivatkozik egy REST API-technikai profilra, a rendszer visszairányítja a felhasználót a függő entitásalkalmazásba a megfelelő hibaüzenettel.

A REST API fejlesztése

A REST API bármilyen platformon fejleszthető, és bármilyen programnyelven írható, feltéve, hogy biztonságos, és JSON formátumban küldhet és fogadhat jogcímeket.

A REST API-szolgáltatásra irányuló kérés Azure AD B2C-kiszolgálókról származik. A REST API-szolgáltatást közzé kell tenni egy nyilvánosan elérhető HTTPS-végponton. A REST API-hívások egy Azure-adatközpont IP-címéről érkeznek.

A könnyebb fejlesztés érdekében használhat kiszolgáló nélküli felhőfüggvényeket, például HTTP-eseményindítókat a Azure Functions.

A REST API-szolgáltatást és annak mögöttes összetevőit (például az adatbázist és a fájlrendszert) magas rendelkezésre állásúnak kell megterveznie.

Fontos

A végpontoknak meg kell felelniük a B2C Azure AD biztonsági követelményeinek. A régebbi TLS-verziók és titkosítások elavultak. További információ: Azure AD B2C TLS és titkosítási csomag követelményei.

Következő lépések

• Megtudhatja, hogyan adhat hozzá API-összekötőt a regisztrációs élmény módosításához
• Megtudhatja, hogyan adhat hozzá API-összekötőt a jogkivonatok külső jogcímekkel való bővítéséhez
• Ismerje meg, hogyan védheti meg az API-összekötőt
• Ismerkedés a mintákkal

A RESTful műszaki profil használatára az alábbi cikkekben talál példákat:

• Útmutató: API-összekötő hozzáadása egy regisztrációs felhasználói folyamathoz
• Útmutató: REST API-jogcímcserék hozzáadása egyéni szabályzatokhoz az Azure Active Directory B2C-ben
• A REST API-szolgáltatások védelme
• Referencia: RESTful műszaki profil

• Ismerje meg, hogyan építhet rugalmasságot a külső folyamatokkal való együttműködés során
• Ismerje meg, hogyan építheti ki a rugalmasságot a fejlesztői ajánlott eljárások segítségével.