Definieren eines technischen ID-Tokenhinweisprofils in einer benutzerdefinierten Azure Active Directory B2C-Richtlinie

Artikel
01/11/2024

Azure AD B2C ermöglicht es Anwendungen der vertrauenden Seite, ein eingehendes JSON Web Token als Teil der OAuth2-Autorisierungsanforderung zu senden. Das JWT-Token kann von einer Anwendung der vertrauenden Seite oder einem Identitätsanbieter ausgegeben werden, und es kann einen Hinweis zum Benutzer oder zur Autorisierungsanforderung übergeben. Azure AD B2C überprüft die Signatur, den Ausstellernamen und die Tokenzielgruppe und extrahiert den Anspruch aus dem eingehenden Token.

Anwendungsfälle

Mit dieser Lösung können Sie Daten an Azure AD B2C senden, die in einem einzelnen JWT-Token gekapselt sind. Die Signup with email invitation-Lösung, bei der Ihr Systemadministrator eine signierte Einladung an Benutzer senden kann, basiert auf „id_token_hint“. Nur Benutzer mit Zugriff auf die Einladungs-E-Mail können das Konto im Verzeichnis erstellen.

Tokensignaturansatz

Bei „id_token_hint“ verfasst der Tokenaussteller (eine App der vertrauenden Seite oder ein Identitätsanbieter) das Token und signiert es dann mithilfe eines Signaturschlüssels, um nachzuweisen, dass es von einer vertrauenswürdigen Quelle stammt. Der Signaturschlüssel kann symmetrisch oder asymmetrisch sein. Bei der symmetrischen Kryptografie oder Kryptografie mit privatem Schlüssel wird ein gemeinsames Geheimnis verwendet, um die Signatur zu signieren und zu überprüfen. Die asymmetrische Kryptografie oder Kryptografie mit öffentlichem Schlüssel ist ein Kryptografiesystem, das sowohl einen privaten Schlüssel als auch einen öffentlichen Schlüssel verwendet. Der private Schlüssel ist nur dem Tokenaussteller bekannt und wird verwendet, um das Token zu signieren. Der öffentliche Schlüssel wird für die Azure AD B2C-Richtlinie freigegeben, um die Signatur des Tokens zu überprüfen.

Tokenformat

„id_token_hint“ muss ein gültiges JWT-Token sein. In den folgenden Tabelle werden die erforderlichen Ansprüche aufgeführt. Zusätzliche Ansprüche sind optional.

Name	Anspruch	Beispielwert	BESCHREIBUNG
Zielgruppe	`aud`	`a489fc44-3cc0-4a78-92f6-e413cd853eae`	Identifiziert den vorgesehenen Empfänger des Tokens. Die Zielgruppe ist eine beliebige Zeichenfolge, die vom Tokenaussteller definiert wird. Azure AD B2C überprüft diesen Wert und lehnt das Token ab, wenn es nicht mit der Vorgabe übereinstimmt.
Issuer (Aussteller)	`iss`	`https://localhost`	Hiermit wird der Sicherheitstokendienst (Tokenaussteller) identifiziert. Der Aussteller ist ein beliebiger URI, der vom Tokenaussteller definiert wird. Azure AD B2C überprüft diesen Wert und lehnt das Token ab, wenn es nicht mit der Vorgabe übereinstimmt.
Ablaufzeit	`exp`	`1600087315`	Die Zeit, zu der das Token ungültig wird (dargestellt als Epochenzeit). Azure AD B2C überprüft diesen Wert und lehnt das Token ab, wenn es abgelaufen ist.
Nicht vor	`nbf`	`1599482515`	Die Zeit, zu der das Token gültig wird (dargestellt als Epochenzeit). Diese Zeit entspricht in der Regel dem Ausstellungszeitpunkt des Tokens. Azure AD B2C überprüft diesen Wert und lehnt das Token ab, wenn seine Lebensdauer ungültig ist.

Das folgende Token ist ein Beispiel für ein gültiges 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

Das Name-Attribut des Protocol-Elements muss auf None festgelegt werden. Das Protokoll für das technische Profil IdTokenHint_ExtractClaims ist beispielsweise None:

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

Das technische Profil wird von einem Orchestrierungsschritt mit dem Typ von GetClaims aufgerufen.

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

Ausgabeansprüche

Das Element OutputClaims enthält eine Liste mit Ansprüchen, die aus dem JWT-Token extrahiert werden sollen. Sie müssen den Namen des in Ihrer Richtlinie definierten Anspruchs möglicherweise dem im JWT-Token definierten Namen zuordnen. Sie können auch Ansprüche einfügen, die nicht vom JWT-Token zurückgegeben werden, sofern Sie das DefaultValue-Attribut festlegen.

Metadaten

Die folgenden Metadaten sind relevant, wenn der symmetrische Schlüssel verwendet wird.

attribute	Erforderlich	Beschreibung
Issuer (Aussteller)	Ja	Hiermit wird der Sicherheitstokendienst (Tokenaussteller) identifiziert. Dieser Wert muss mit dem `iss`-Anspruch innerhalb des JWT-Tokenanspruchs identisch sein.
IdTokenAudience	Ja	Identifiziert den vorgesehenen Empfänger des Tokens. Dieser Wert muss mit dem `aud`-Anspruch innerhalb des JWT-Tokenanspruchs identisch sein.

Die folgenden Metadaten sind relevant, wenn ein asymmetrischer Schlüssel verwendet wird.

attribute	Erforderlich	Beschreibung
METADATA	Ja	Dies ist eine URL, die auf ein Konfigurationsdokument eines Tokenausstellers verweist, das auch als bekannter OpenID-Konfigurationsendpunkt bekannt ist.
Issuer (Aussteller)	Nein	Hiermit wird der Sicherheitstokendienst (Tokenaussteller) identifiziert. Dieser Wert kann verwendet werden, um den in den Metadaten konfigurierten Wert zu überschreiben. Er muss mit dem `iss`-Anspruch innerhalb des JWT-Tokenanspruchs identisch sein.
IdTokenAudience	Nein	Identifiziert den vorgesehenen Empfänger des Tokens. Dieser Wert muss mit dem `aud`-Anspruch innerhalb des JWT-Tokenanspruchs identisch sein.

Wichtig

Ihre Endpunkte müssen die Azure AD B2C-Sicherheitsanforderungen erfüllen. Ältere TLS-Versionen und Verschlüsselungsverfahren sind veraltet. Weitere Informationen finden Sie unter Azure Active Directory B2C TLS- und Cipher Suite-Anforderungen.

Kryptografische Schlüssel

Bei Verwendung eines symmetrischen Schlüssels enthält das Element CryptographicKeys die folgenden Attribute:

attribute	Erforderlich	BESCHREIBUNG
client_secret	Ja	Dies ist der Kryptografieschlüssel, der zum Überprüfen der JWT-Tokensignatur verwendet wird.

Schrittanleitung

Ausstellen eines Tokens mit symmetrischen Schlüsseln

Schritt 1: Erstellen eines gemeinsam verwendeten Schlüssels

Erstellen Sie einen Schlüssel, der zum Signieren des Tokens verwendet werden kann. Verwenden Sie beispielsweise den folgenden PowerShell-Code, um einen Schlüssel zu generieren.

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

Mit diesem Code wird ein Geheimnis wie VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI= erstellt.

Schritt 2: Hinzufügen des Signaturschlüssels zu Azure AD B2C

Der Schlüssel, der vom Tokenaussteller verwendet wird, muss in Ihren Azure AD B2C-Richtlinienschlüsseln erstellt werden.

Melden Sie sich beim Azure-Portal an.
Wenn Sie Zugriff auf mehrere Mandanten haben, wählen Sie das Symbol Einstellungen im Menü oben aus, um über das Menü Verzeichnisse + Abonnements zu Ihrem Azure AD B2C-Mandanten zu wechseln.
Suchen Sie im Azure-Portal nach Azure AD B2C, und wählen Sie diese Option dann aus.
Wählen Sie auf der Übersichtsseite unter Richtlinien die Option Identity Experience Framework aus.
Klicken Sie auf Richtlinienschlüssel.
Wählen Sie Manuell aus.
Verwenden Sie für Name den Wert IdTokenHintKey.
Das Präfix B2C_1A_ wird möglicherweise automatisch hinzugefügt.
Geben Sie im Feld Geheimnis den zuvor generierten Anmeldeschlüssel ein.
Verwenden Sie für Schlüsselverwendung die Option Verschlüsselung.
Klicken Sie auf Erstellen.
Vergewissern Sie sich, dass Sie den Schlüssel B2C_1A_IdTokenHintKey erstellt haben.

Schritt 3: Hinzufügen des technischen ID-Tokenhinweisprofils

Das folgende technische Profil überprüft das Token und extrahiert die Ansprüche.

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

Schritt 4: Vorbereiten Ihrer Richtlinie

Schließen Sie den Schritt Konfigurieren Sie Ihre Richtlinie ab.

Schritt 5: Vorbereiten des Codes

Das GitHub-Beispiel ist eine ASP.NET-Webanwendung und Konsolen-App, die ein ID-Token generiert, das mithilfe eines symmetrischen Schlüssels signiert wird.

Ausstellen eines Tokens mit asymmetrischen Schlüsseln

Mit einem asymmetrischen Schlüssel wird das Token mithilfe von RSA-Zertifikaten signiert. Diese Anwendung hostet einen OpenID Connect-Metadatenendpunkt und einen JWK-Endpunkt (JSON Web Key), die von Azure AD B2C zum Überprüfen der Signatur des ID-Tokens verwendet werden.

Der Tokenaussteller muss folgende Endpunkte bereitstellen:

/.well-known/openid-configuration: Dies ist ein bekannter Konfigurationsendpunkt mit relevanten Informationen über das Token (z. B. Name des Tokenausstellers und Link zum JWK-Endpunkt).
/.well-known/keys: Dies ist der JWK-Endpunkt (JSON Web Key) mit dem öffentlichen Schlüssel, der zum Signieren des Schlüssels (mit dem privaten Schlüsselteil des Zertifikats) verwendet wird.

Weitere Informationen finden Sie im .NET MVC-Controllerbeispiel TokenMetadataController.cs.

Schritt 1: Vorbereiten eines selbstsignierten Zertifikats

Wenn Sie noch nicht über ein Zertifikat verfügen, können Sie für diese Schrittanleitung ein selbstsigniertes Zertifikat verwenden. Unter Windows können Sie das PowerShell-Cmdlet New-SelfSignedCertificate verwenden, um ein Zertifikat zu generieren.

Führen Sie diesen PowerShell-Befehl aus, um ein selbstsigniertes Zertifikat zu generieren. Ändern Sie das Argument -Subject entsprechend Ihrer Anwendung und des Azure AD B2C-Mandantennamens. Sie können auch das -NotAfter-Datum anpassen, um einen anderen Ablaufzeitpunkt für das Zertifikat anzugeben.

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"

Schritt 2: Hinzufügen des technischen ID-Tokenhinweisprofils

Das folgende technische Profil überprüft das Token und extrahiert die Ansprüche. Ändern Sie den Metadaten-URI in den bekannten Konfigurationsendpunkt des Tokenausstellers.

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

Schritt 3: Vorbereiten Ihrer Richtlinie

Schließen Sie den Schritt Konfigurieren Sie Ihre Richtlinie ab.

Schritt 4: Vorbereiten des Codes

Diese ASP.NET-Webanwendung im GitHub-Beispiel generiert ID-Token und hostet die Metadatenendpunkte, die für die Verwendung des Parameters „id_token_hint“ in Azure AD B2C erforderlich sind.

Konfigurieren der Richtlinie

Sowohl beim symmetrischen als auch beim asymmetrischen Ansatz wird das technische Profil id_token_hint über einen Orchestrierungsschritt des Typs GetClaims aufgerufen und muss die Eingabeansprüche der Richtlinie für die vertrauende Seite angeben.

Fügen Sie Ihrer Erweiterungsrichtlinie das technische Profil „IdTokenHint_ExtractClaims“ hinzu.

Fügen Sie Ihrer User Journey den folgenden Orchestrierungsschritt als erstes Element hinzu.

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

Wiederholen Sie in der Richtlinie für die vertrauende Seite dieselben Eingabeansprüche, die Sie im technischen Profil „IdTokenHint_ExtractClaims “ konfiguriert haben. Beispiel:

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

Abhängig von Ihren geschäftlichen Anforderungen müssen Sie möglicherweise Tokenüberprüfungen hinzufügen, um beispielsweise das Format der E-Mail-Adresse zu überprüfen. Fügen Sie hierzu Orchestrierungsschritte hinzu, die ein technisches Profil zur Anspruchstransformation aufrufen. Fügen Sie auch ein selbstbestätigtes technisches Profil hinzu, um eine Fehlermeldung anzuzeigen.

Erstellen und Signieren eines Tokens

In den GitHub-Beispielen wird veranschaulicht, wie ein solches Token in einem JWT-Token erstellt wird, das später als id_token_hint-Abfragezeichenfolgenparameter gesendet wird. Im Folgenden finden Sie ein Beispiel für eine Autorisierungsanforderung mit dem Parameter „id_token_hint“.

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

Nächste Schritte

Sehen Sie sich die Lösung zum Registrieren mit einer Einladungs-E-Mail im Azure AD B2C-Repository der GitHub-Community an.