Een technisch profiel voor id-tokenhints definiëren in een aangepast Azure Active Directory B2C-beleid

Artikel
01/11/2024

Met Azure AD B2C kunnen relying party-toepassingen een binnenkomende JWT verzenden als onderdeel van de OAuth2-autorisatieaanvraag. Het JWT-token kan worden uitgegeven door een relying party-toepassing of een id-provider en kan een hint doorgeven over de gebruiker of de autorisatieaanvraag. Azure AD B2C valideert de handtekening, de naam van de uitgever en de tokendoelgroep en extraheert de claim uit het binnenkomende token.

Gebruiksgevallen

U kunt deze oplossing gebruiken om gegevens te verzenden naar Azure AD B2C, ingekapseld in één JWT-token. De Signup with email invitation oplossing, waar uw systeembeheerder een ondertekende uitnodiging naar gebruikers kan verzenden, is gebaseerd op id_token_hint. Alleen gebruikers met toegang tot de uitnodigings-e-mail kunnen het account in de map maken.

Methode voor tokenondertekening

Met id_token_hint stelt de tokenverlener (een relying party-app of een id-provider) het token samen en ondertekent het vervolgens met behulp van een ondertekeningssleutel om te bewijzen dat het token afkomstig is van een vertrouwde bron. De ondertekeningssleutel kan symmetrisch of asymmetrisch zijn. Symmetrische cryptografie of persoonlijke sleutelcryptografie maakt gebruik van een gedeeld geheim om de handtekening te ondertekenen en te valideren. Asymmetrische cryptografie of openbare-sleutelcryptografie is een cryptografisch systeem dat zowel een persoonlijke sleutel als een openbare sleutel gebruikt. De persoonlijke sleutel is alleen bekend bij de tokenverlener en wordt gebruikt om het token te ondertekenen. De openbare sleutel wordt gedeeld met het Azure AD B2C-beleid om de handtekening van het token te valideren.

Tokenindeling

De id_token_hint moet een geldig JWT-token zijn. De volgende tabel bevat de claims die verplicht zijn. Aanvullende claims zijn optioneel.

Naam	Claimen	Voorbeeldwaarde	Omschrijving
Doelgroep	`aud`	`a489fc44-3cc0-4a78-92f6-e413cd853eae`	Identificeert de beoogde ontvanger van het token. De doelgroep is een willekeurige tekenreeks die is gedefinieerd door de tokenverlener. Azure AD B2C valideert deze waarde en weigert het token als dit niet overeenkomt.
Verlener	`iss`	`https://localhost`	Identificeert de beveiligingstokenservice (tokenverlener). De verlener is een willekeurige URI die is gedefinieerd door de tokenverlener. Azure AD B2C valideert deze waarde en weigert het token als dit niet overeenkomt.
Verlooptijd	`exp`	`1600087315`	Het tijdstip waarop het token ongeldig wordt, weergegeven in tijdsperiode. Azure AD B2C valideert deze waarde en weigert het token als het token is verlopen.
Niet eerder	`nbf`	`1599482515`	Het tijdstip waarop het token geldig wordt, weergegeven in epoch-tijd. Deze keer is meestal hetzelfde als het tijdstip waarop het token is uitgegeven. Azure AD B2C valideert deze waarde en weigert het token als de levensduur van het token niet geldig is.

Het volgende token is een voorbeeld van een geldig id-token:

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "displayName": " John Smith",
  "userId": "john.s@contoso.com",
  "nbf": 1599482515,
  "exp": 1600087315,
  "iss": "https://localhost",
  "aud": "a489fc44-3cc0-4a78-92f6-e413cd853eae"
}

Protocol

Het kenmerk Naam van het element Protocol moet worden ingesteld op None. Het protocol voor het IdTokenHint_ExtractClaims technisch profiel is Nonebijvoorbeeld:

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

Het technische profiel wordt aangeroepen vanuit een indelingsstap met het type GetClaims.

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

Uitvoerclaims

Het element OutputClaims bevat een lijst met claims die moeten worden geëxtraheerd uit het JWT-token. Mogelijk moet u de naam van de claim die in uw beleid is gedefinieerd, toewijzen aan de naam die is gedefinieerd in het JWT-token. U kunt ook claims opnemen die niet worden geretourneerd door het JWT-token, zolang u het DefaultValue kenmerk instelt.

Metagegevens

De volgende metagegevens zijn relevant bij het gebruik van een symmetrische sleutel.

Kenmerk	Vereist	Beschrijving
Uitgevende instelling	Ja	Identificeert de beveiligingstokenservice (tokenverlener). Deze waarde moet identiek zijn aan de `iss` claim binnen de JWT-tokenclaim.
IdTokenAudience	Ja	Identificeert de beoogde ontvanger van het token. Moet identiek zijn aan de `aud` claim binnen de JWT-tokenclaim.

De volgende metagegevens zijn relevant wanneer u een asymmetrische sleutel gebruikt.

Kenmerk	Vereist	Beschrijving
METAGEGEVENS	Ja	Een URL die verwijst naar een configuratiedocument voor tokenverleners, dat ook wel een bekend OpenID-configuratie-eindpunt wordt genoemd.
Uitgevende instelling	Nee	Identificeert de beveiligingstokenservice (tokenverlener). Deze waarde kan worden gebruikt om de waarde die is geconfigureerd in de metagegevens te overschrijven en moet identiek zijn aan de claim binnen de `iss` JWT-tokenclaim.
IdTokenAudience	Nee	Identificeert de beoogde ontvanger van het token. Moet identiek zijn aan de `aud` claim binnen de JWT-tokenclaim.

Belangrijk

Uw eindpunten moeten voldoen aan de Azure AD B2C-beveiligingsvereisten. Oudere TLS-versies en -coderingen zijn afgeschaft. Zie Vereisten voor Azure AD B2C TLS en suites met coderingsmethoden voor meer informatie.

Cryptografische sleutels

Wanneer u een symmetrische sleutel gebruikt, bevat het element CryptographicKeys het volgende kenmerk:

Kenmerk	Vereist	Beschrijving
client_secret	Ja	De cryptografische sleutel die wordt gebruikt om de JWT-tokenhandtekening te valideren.

Instructiegids

Een token met symmetrische sleutels uitgeven

Stap 1: Een gedeelde sleutel maken

Maak een sleutel die kan worden gebruikt om het token te ondertekenen. Gebruik bijvoorbeeld de volgende PowerShell-code om een sleutel te genereren.

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

Met deze code maakt u een geheime tekenreeks zoals VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=.

Stap 2: De ondertekeningssleutel toevoegen aan Azure AD B2C

Dezelfde sleutel die door de tokenverlener wordt gebruikt, moet worden gemaakt in uw Azure AD B2C-beleidssleutels.

Meld u aan bij de Azure-portal.
Als u toegang hebt tot meerdere tenants, selecteert u het pictogram Instellingen in het bovenste menu om over te schakelen naar uw Azure AD B2C-tenant in het menu Mappen en abonnementen.
Zoek en selecteer Azure AD B2C in de Azure-portal.
Selecteer op de overzichtspagina onder Beleid de optie Identity Experience Framework.
Beleidssleutels selecteren
Selecteer Handmatig.
Voor Naam gebruikt u IdTokenHintKey.
Het voorvoegsel B2C_1A_ wordt mogelijk automatisch toegevoegd.
Voer in het vak Geheim de aanmeldingssleutel in die u eerder hebt gegenereerd.
Gebruik Versleuteling voor sleutelgebruik.
Selecteer Maken.
Bevestig dat u de sleutel B2C_1A_IdTokenHintKeyhebt gemaakt.

Stap 3: Het technische profiel van de id-tokenhint toevoegen

Met het volgende technische profiel wordt het token gevalideerd en worden de claims geëxtraheerd.

<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">a489fc44-3cc0-4a78-92f6-e413cd853eae</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>

Stap 4: Uw beleid voorbereiden

Voltooi de stap Uw beleid configureren.

Stap 5: De code voorbereiden

Het GitHub-voorbeeld is een ASP.NET-webtoepassing en console-app waarmee een id-token wordt gegenereerd dat is ondertekend met behulp van een symmetrische sleutel.

Een token met asymmetrische sleutels uitgeven

Met een asymmetrische sleutel wordt het token ondertekend met RSA-certificaten. Deze toepassing fungeert als host voor een OpenID Verbinding maken eindpunt voor metagegevens en JSON Web Keys (JWK's) dat wordt gebruikt door Azure AD B2C om de handtekening van het id-token te valideren.

De tokenverlener moet de volgende eindpunten opgeven:

/.well-known/openid-configuration - Een bekend configuratie-eindpunt met relevante informatie over het token, zoals de naam van de tokenverlener en de koppeling naar het JWK-eindpunt.
/.well-known/keys - het JSON-eindpunt (JWK) met de openbare sleutel die wordt gebruikt om de sleutel te ondertekenen (met het persoonlijke sleutelgedeelte van het certificaat).

Zie het voorbeeld van de TokenMetadataController.cs .NET MVC-controller.

Stap 1: Een zelfondertekend certificaat voorbereiden

Als u nog geen certificaat hebt, kunt u een zelfondertekend certificaat gebruiken voor deze handleiding. In Windows kunt u de cmdlet New-SelfSignedCertificate van PowerShell gebruiken om een certificaat te genereren.

Voer deze PowerShell-opdracht uit om een zelfondertekend certificaat te genereren. Wijzig het -Subject argument zo nodig voor de naam van uw toepassing en azure AD B2C-tenant. U kunt ook de -NotAfter-datum aanpassen om een andere vervaldatum voor het certificaat op te geven.

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"

Stap 2: het technische profiel voor de id-tokenhint toevoegen

Met het volgende technische profiel wordt het token gevalideerd en worden de claims geëxtraheerd. Wijzig de metagegevens-URI in het bekende configuratie-eindpunt van de tokenverlener.

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

Stap 3: Uw beleid voorbereiden

Voltooi de stap Uw beleid configureren.

Stap 4: De code voorbereiden

Met deze GitHub-voorbeeld-ASP.NET webtoepassing worden id-tokens gegenereerd en worden de metagegevenseindpunten gehost die nodig zijn voor het gebruik van de parameter id_token_hint in Azure AD B2C.

Uw beleid configureren

Voor zowel symmetrische als asymmetrische benaderingen wordt het id_token_hint technische profiel aangeroepen vanuit een indelingsstap met het type GetClaims en moet de invoerclaims van het relying party-beleid worden opgegeven.

Voeg het IdTokenHint_ExtractClaims technisch profiel toe aan uw extensiebeleid.

Voeg de volgende indelingsstap toe aan uw gebruikerstraject als het eerste item.

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

Herhaal in uw relying party-beleid dezelfde invoerclaims die u hebt geconfigureerd in het IdTokenHint_ExtractClaims technisch profiel. Bijvoorbeeld:

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

Afhankelijk van uw zakelijke vereisten moet u mogelijk tokenvalidaties toevoegen, bijvoorbeeld de indeling van het e-mailadres controleren. Voeg hiervoor indelingsstappen toe die een technisch profiel voor claimtransformatie aanroepen. Voeg ook een zelfbeweert technisch profiel toe om een foutbericht weer te geven.

Een token maken en ondertekenen

In de GitHub-voorbeelden ziet u hoe u een dergelijk token maakt met een JWT die later wordt verzonden als een id_token_hint querytekenreeksparameter. Hieronder volgt een voorbeeld van een autorisatieaanvraag met id_token_hint parameter

https://tenant-name.b2clogin.com/tenant-name.onmicrosoft.com/B2C_1A_signup_signin/oauth2/v2.0/authorize?client_id=63ba0d17-c4ba-47fd-89e9-31b3c2734339&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaXNwbGF5TmFtZSI6IiBKb2huIFNtaXRoIiwidXNlcklkIjoiam9obi5zQGNvbnRvc28uY29tIiwibmJmIjoxNTk5NDgyNTE1LCJleHAiOjE2MDAwODczMTUsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0IiwiYXVkIjoiYTQ4OWZjNDQtM2NjMC00YTc4LTkyZjYtZTQxM2NkODUzZWFlIn0.nPmLXydI83PQCk5lRBYUZRu_aX58pL1khahHyQuupig

Volgende stappen

Controleer de aanmelding met de e-mailoplossing voor uitnodigingen in de GitHub-opslagplaats van de Azure AD B2C-community.