Definiera en teknisk profil för ID-tokentips i en anpassad Azure Active Directory B2C-princip

Artikel
01/11/2024

Med Azure AD B2C kan förlitande partprogram skicka en inkommande JWT som en del av OAuth2-auktoriseringsbegäran. JWT-token kan utfärdas av ett förlitande partprogram eller en identitetsprovider, och den kan ge en ledtråd om användaren eller auktoriseringsbegäran. Azure AD B2C verifierar signaturen, utfärdarens namn och tokenpubliken och extraherar anspråket från den inkommande token.

Praktiska ärenden

Du kan använda den här lösningen för att skicka data till Azure AD B2C inkapslade i en enda JWT-token. LösningenSignup with email invitation, där systemadministratören kan skicka en signerad inbjudan till användare, baseras på id_token_hint. Endast användare med åtkomst till e-postmeddelandet för inbjudan kan skapa kontot i katalogen.

Metod för tokensignering

Med id_token_hint skriver tokenutfärdaren (en förlitande partapp eller en identitetsprovider) token och signerar den sedan med hjälp av en signeringsnyckel för att bevisa att token kommer från en betrodd källa. Signeringsnyckeln kan vara symmetrisk eller asymmetrisk. Symmetrisk kryptografi, eller kryptografi med privat nyckel, använder en delad hemlighet för att både signera och validera signaturen. Asymmetrisk kryptografi, eller kryptering med offentliga nycklar, är ett kryptografiskt system som använder både en privat nyckel och en offentlig nyckel. Den privata nyckeln är endast känd för token utfärdaren och används för att signera token. Den offentliga nyckeln delas med Azure AD B2C-principen för att verifiera tokens signatur.

Tokenformat

Id_token_hint måste vara en giltig JWT-token. I följande tabell visas de anspråk som är obligatoriska. Ytterligare anspråk är valfria.

Name	Anspråk	Exempelvärde	Description
Målgrupp	`aud`	`00001111-aaaa-2222-bbbb-3333cccc4444`	Identifierar den avsedda mottagaren av token. Målgruppen är en godtycklig sträng som definieras av token utfärdaren. Azure AD B2C verifierar det här värdet och avvisar token om den inte matchar.
Utfärdare	`iss`	`https://localhost`	Identifierar tjänsten för säkerhetstoken (token utfärdare). Utfärdaren är en godtycklig URI som definieras av token utfärdaren. Azure AD B2C verifierar det här värdet och avvisar token om den inte matchar.
Förfallotid	`exp`	`1600087315`	Den tid då token blir ogiltig, representerad i epoktid. Azure AD B2C verifierar det här värdet och avvisar token om token har upphört att gälla.
Inte tidigare	`nbf`	`1599482515`	Den tid då token blir giltig, representerad i epoktid. Den här gången är vanligtvis samma som när token utfärdades. Azure AD B2C verifierar det här värdet och avvisar token om tokens livslängd inte är giltig.

Följande token är ett exempel på en giltig ID-token:

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "displayName": " John Smith",
  "userId": "john.s@contoso.com",
  "nbf": 1599482515,
  "exp": 1600087315,
  "iss": "https://localhost",
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

Protokoll

Attributet Namn för protokollelementet måste anges till None. Protokollet för den IdTokenHint_ExtractClaims tekniska profilen är Nonetill exempel :

<TechnicalProfile Id="IdTokenHint_ExtractClaims">
  <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
  <Protocol Name="None" />
  ...

Den tekniska profilen anropas från ett orkestreringssteg med typen GetClaims.

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

Utdataanspråk

OutputClaims-elementet innehåller en lista över anspråk som ska extraheras från JWT-token. Du kan behöva mappa namnet på anspråket som definierats i principen till det namn som definierats i JWT-token. Du kan också inkludera anspråk som inte returneras av JWT-token, så länge du anger DefaultValue attributet.

Metadata

Följande metadata är relevanta när du använder symmetrisk nyckel.

Attribut	Obligatoriskt	Beskrivning
Emittenten	Ja	Identifierar tjänsten för säkerhetstoken (token utfärdare). Det här värdet måste vara identiskt med anspråket `iss` i JWT-tokenanspråket.
IdTokenAudience	Ja	Identifierar den avsedda mottagaren av token. Måste vara identisk med anspråket `aud` i JWT-tokenanspråket.

Följande metadata är relevanta när du använder en asymmetrisk nyckel.

Attribut	Obligatoriskt	Beskrivning
METADATA	Ja	En URL som pekar på ett konfigurationsdokument för token utfärdare, som även kallas en välkänd OpenID-konfigurationsslutpunkt.
Emittenten	Inga	Identifierar tjänsten för säkerhetstoken (token utfärdare). Det här värdet kan användas för att skriva över värdet som konfigurerats i metadata och måste vara identiskt med anspråket `iss` i JWT-tokenanspråket.
IdTokenAudience	Inga	Identifierar den avsedda mottagaren av token. Måste vara identisk med anspråket `aud` i JWT-tokenanspråket.

Viktigt!

Dina slutpunkter måste uppfylla säkerhetskraven för Azure AD B2C. Äldre TLS-versioner och chiffer är inaktuella. Mer information finns i Azure AD B2C TLS- och chiffersvitkrav.

Krypteringsnycklar

När du använder en symmetrisk nyckel innehåller cryptographicKeys-elementet följande attribut:

Attribut	Obligatoriskt	Beskrivning
client_secret	Ja	Den kryptografiska nyckel som används för att verifiera JWT-tokensignaturen.

Instruktionsguide

Utfärda en token med symmetriska nycklar

Steg 1: Skapa en delad nyckel

Skapa en nyckel som kan användas för att signera token. Använd till exempel följande PowerShell-kod för att generera en nyckel.

$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$newClientSecret

Den här koden skapar en hemlig sträng som VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=.

Steg 2: Lägg till signeringsnyckeln i Azure AD B2C

Samma nyckel som används av token utfärdaren måste skapas i dina Azure AD B2C-principnycklar.

Logga in på Azure-portalen.
Om du har åtkomst till flera klienter väljer du ikonen Inställningar på den översta menyn för att växla till din Azure AD B2C-klient från menyn Kataloger + prenumerationer.
I Azure-portalen söker du efter och väljer Azure AD B2C.
På översiktssidan går du till Principer och väljer Identity Experience Framework.
Välj principnycklar
Välj Manuell.
Som Namn använder du IdTokenHintKey.
Prefixet B2C_1A_ kan läggas till automatiskt.
I rutan Hemlighet anger du inloggningsnyckeln som du genererade tidigare.
För Nyckelanvändning använder du Kryptering.
Välj Skapa.
Bekräfta att du har skapat nyckeln B2C_1A_IdTokenHintKey.

Steg 3: Lägg till teknisk profil för ID-tokentips

Följande tekniska profil verifierar token och extraherar anspråken.

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <Item Key="IdTokenAudience">00001111-aaaa-2222-bbbb-3333cccc4444</Item>
        <Item Key="issuer">https://localhost</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="client_secret" StorageReferenceId="B2C_1A_IdTokenHintKey" />
      </CryptographicKeys>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Steg 4: Förbered din princip

Slutför steget Konfigurera din princip.

Steg 5: Förbered koden

GitHub-exemplet är en ASP.NET webbapp och konsolapp som genererar en ID-token som är signerad med en symmetrisk nyckel.

Utfärda en token med asymmetriska nycklar

Med en asymmetrisk nyckel signeras token med RSA-certifikat. Det här programmet är värd för en OpenID-Anslut slutpunkt för metadata och JSON-slutpunkter (JWK:er) som används av Azure AD B2C för att verifiera signaturen för ID-token.

Token-utfärdaren måste ange följande slutpunkter:

/.well-known/openid-configuration – En välkänd konfigurationsslutpunkt med relevant information om token, till exempel namnet på token utfärdaren och länken till JWK-slutpunkten.
/.well-known/keys – JSON-slutpunkten (JWK) med den offentliga nyckel som används för att signera nyckeln (med den privata nyckeldelen av certifikatet).

TokenMetadataController.cs Se .NET MVC-kontrollantexemplet.

Steg 1: Förbereda ett självsignerat certifikat

Om du inte redan har ett certifikat kan du använda ett självsignerat certifikat för den här instruktionsguiden. I Windows kan du använda PowerShells cmdlet New-SelfSignedCertificate för att generera ett certifikat.

Kör det här PowerShell-kommandot för att generera ett självsignerat certifikat. -Subject Ändra argumentet efter behov för ditt program och Azure AD B2C-klientnamn. Du kan också justera -NotAfter datumet för att ange ett annat förfallodatum för certifikatet.

New-SelfSignedCertificate `
    -KeyExportPolicy Exportable `
    -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -KeyUsage DigitalSignature `
    -NotAfter (Get-Date).AddMonths(12) `
    -CertStoreLocation "Cert:\CurrentUser\My"

Steg 2: Lägg till teknisk profil för ID-tokentips

Följande tekniska profil verifierar token och extraherar anspråken. Ändra metadata-URI:n till din token utfärdare välkänd konfigurationsslutpunkt.

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <!-- Replace with your endpoint location -->
        <Item Key="METADATA">https://your-app.azurewebsites.net/.well-known/openid-configuration</Item>
        <Item Key="IdTokenAudience">your_optional_audience</Item>
        <!-- <Item Key="issuer">your_optional_token_issuer_override</Item> -->
      </Metadata>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Steg 3: Förbered din princip

Slutför steget Konfigurera din princip.

Steg 4: Förbered koden

Det här GitHub-exemplet ASP.NET webbprogrammet genererar ID-token och är värd för de metadataslutpunkter som krävs för att använda parametern "id_token_hint" i Azure AD B2C.

Konfigurera din princip

För både symmetriska och asymmetriska metoder anropas den id_token_hint tekniska profilen från ett orkestreringssteg med typen av GetClaims och måste ange indataanspråken för den förlitande partens princip.

Lägg till den IdTokenHint_ExtractClaims tekniska profilen i tilläggsprincipen.

Lägg till följande orkestreringssteg i användarresan som det första objektet.

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

I principen för förlitande part upprepar du samma indataanspråk som du konfigurerade i den IdTokenHint_ExtractClaims tekniska profilen. Till exempel:

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUp" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <InputClaims>
      <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
    </InputClaims>
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Beroende på dina affärskrav kan du behöva lägga till tokenvalidering, till exempel kontrollera formatet på e-postadressen. Det gör du genom att lägga till orkestreringssteg som anropar en teknisk profil för anspråkstransformering. Lägg också till en självsäkrad teknisk profil för att visa ett felmeddelande.

Skapa och signera en token

GitHub-exemplen visar hur du skapar ett sådant tokenproblem med en JWT som senare skickades som en id_token_hint frågesträngsparameter. Följande är ett exempel på en auktoriseringsbegäran med id_token_hint parameter

https://tenant-name.b2clogin.com/tenant-name.onmicrosoft.com/B2C_1A_signup_signin/oauth2/v2.0/authorize?client_id=11112222-bbbb-3333-cccc-4444dddd5555&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaXNwbGF5TmFtZSI6IiBKb2huIFNtaXRoIiwidXNlcklkIjoiam9obi5zQGNvbnRvc28uY29tIiwibmJmIjoxNTk5NDgyNTE1LCJleHAiOjE2MDAwODczMTUsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0IiwiYXVkIjoiYTQ4OWZjNDQtM2NjMC00YTc4LTkyZjYtZTQxM2NkODUzZWFlIn0.nPmLXydI83PQCk5lRBYUZRu_aX58pL1khahHyQuupig

Nästa steg

Kontrollera registreringen med e-postlösningen för inbjudan på GitHub-lagringsplatsen för Azure AD B2C-communityn.

Dela via