Definiowanie profilu technicznego wskazówki dotyczącej tokenu identyfikatora w zasadach niestandardowych usługi Azure Active Directory B2C

Artykuł
01/11/2024

Usługa Azure AD B2C umożliwia aplikacjom jednostki uzależnionej wysyłanie przychodzącego protokołu JWT w ramach żądania autoryzacji OAuth2. Token JWT może być wystawiony przez aplikację jednostki uzależnionej lub dostawcę tożsamości i może przekazać wskazówkę dotyczącą użytkownika lub żądania autoryzacji. Usługa Azure AD B2C weryfikuje podpis, nazwę wystawcy i odbiorców tokenu oraz wyodrębnia oświadczenie z tokenu przychodzącego.

Przypadki użycia

To rozwiązanie umożliwia wysyłanie danych do usługi Azure AD B2C hermetyzowanej w jednym tokenie JWT. RozwiązanieSignup with email invitation, w którym administrator systemu może wysłać podpisane zaproszenie do użytkowników, jest oparte na id_token_hint. Tylko użytkownicy z dostępem do wiadomości e-mail z zaproszeniem mogą utworzyć konto w katalogu.

Podejście do podpisywania tokenów

W przypadku id_token_hint wystawca tokenu (aplikacja jednostki uzależnionej lub dostawca tożsamości) komponuje token, a następnie podpisuje go przy użyciu klucza podpisywania, aby udowodnić, że token pochodzi z zaufanego źródła. Klucz podpisywania może być symetryczny lub asymetryczny. Kryptografia symetryczna lub kryptografia klucza prywatnego używa wspólnego wpisu tajnego do podpisywania i weryfikowania podpisu. Kryptografia asymetryczna lub kryptografia klucza publicznego to system kryptograficzny, który używa zarówno klucza prywatnego, jak i klucza publicznego. Klucz prywatny jest znany tylko wystawcy tokenu i służy do podpisywania tokenu. Klucz publiczny jest udostępniany zasadom usługi Azure AD B2C w celu zweryfikowania podpisu tokenu.

Format tokenu

Id_token_hint musi być prawidłowym tokenem JWT. W poniższej tabeli wymieniono oświadczenia, które są obowiązkowe. Dodatkowe oświadczenia są opcjonalne.

Nazwisko	Oświadczenie	Przykładowa wartość	opis
Odbiorcy	`aud`	`a489fc44-3cc0-4a78-92f6-e413cd853eae`	Identyfikuje zamierzonego adresata tokenu. Odbiorcy są dowolnym ciągiem zdefiniowanym przez wystawcę tokenu. Usługa Azure AD B2C weryfikuje tę wartość i odrzuca token, jeśli nie jest zgodny.
Wystawca	`iss`	`https://localhost`	Identyfikuje usługę tokenu zabezpieczającego (wystawcę tokenu). Wystawca jest dowolnym identyfikatorem URI zdefiniowanym przez wystawcę tokenu. Usługa Azure AD B2C weryfikuje tę wartość i odrzuca token, jeśli nie jest zgodny.
Czas wygaśnięcia	`exp`	`1600087315`	Czas, w którym token staje się nieprawidłowy, reprezentowany w czasie epoki. Usługa Azure AD B2C weryfikuje tę wartość i odrzuca token, jeśli token wygasł.
Nie wcześniej	`nbf`	`1599482515`	Czas, w którym token staje się prawidłowy, reprezentowany w czasie epoki. Ten czas jest zwykle taki sam jak czas wystawienia tokenu. Usługa Azure AD B2C weryfikuje tę wartość i odrzuca token, jeśli okres istnienia tokenu jest nieprawidłowy.

Poniższy token jest przykładem prawidłowego tokenu identyfikatora:

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

Protokół

Atrybut Name elementu Protocol musi być ustawiony na None. Na przykład protokół profilu technicznego IdTokenHint_ExtractClaims to None:

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

Profil techniczny jest wywoływany z kroku aranżacji o typie GetClaims.

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

Oświadczenia wyjściowe

Element OutputClaims zawiera listę oświadczeń do wyodrębnienia z tokenu JWT. Może być konieczne zamapowania nazwy oświadczenia zdefiniowanego w zasadach na nazwę zdefiniowaną w tokenie JWT. Można również uwzględnić oświadczenia, które nie są zwracane przez token JWT, o ile ustawisz DefaultValue atrybut.

Metadane

Następujące metadane są istotne w przypadku korzystania z klucza symetrycznego.

Atrybut	Wymagania	opis
issuer	Tak	Identyfikuje usługę tokenu zabezpieczającego (wystawcę tokenu). Ta wartość musi być identyczna z oświadczeniem `iss` w ramach oświadczenia tokenu JWT.
IdTokenAudience	Tak	Identyfikuje zamierzonego adresata tokenu. Musi być identyczna z oświadczeniem `aud` w ramach oświadczenia tokenu JWT.

Następujące metadane są istotne w przypadku używania klucza asymetrycznego.

Atrybut	Wymagania	opis
METADANYCH	Tak	Adres URL wskazujący dokument konfiguracji wystawcy tokenu, który jest również znany jako dobrze znany punkt końcowy konfiguracji OpenID.
issuer	Nie.	Identyfikuje usługę tokenu zabezpieczającego (wystawcę tokenu). Ta wartość może służyć do zastępowania wartości skonfigurowanej w metadanych i musi być identyczna z oświadczeniem `iss` w ramach oświadczenia tokenu JWT.
IdTokenAudience	Nie.	Identyfikuje zamierzonego adresata tokenu. Musi być identyczna z oświadczeniem `aud` w ramach oświadczenia tokenu JWT.

Ważne

Punkty końcowe muszą być zgodne z wymaganiami dotyczącymi zabezpieczeń usługi Azure AD B2C. Starsze wersje protokołu TLS i szyfry są przestarzałe. Aby uzyskać więcej informacji, zobacz Wymagania dotyczące protokołu TLS i pakietu szyfrowania usługi Azure AD B2C.

Klucze kryptograficzne

W przypadku używania klucza symetrycznego element CryptographicKeys zawiera następujący atrybut:

Atrybut	Wymagania	opis
client_secret	Tak	Klucz kryptograficzny używany do weryfikowania podpisu tokenu JWT.

Przewodnik z instrukcjami

Wystawianie tokenu z kluczami symetrycznymi

Krok 1. Tworzenie klucza współużytkowanego

Utwórz klucz, który może służyć do podpisywania tokenu. Na przykład użyj następującego kodu programu PowerShell, aby wygenerować klucz.

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

Ten kod tworzy ciąg tajny, taki jak VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=.

Krok 2. Dodawanie klucza podpisywania do usługi Azure AD B2C

Ten sam klucz, który jest używany przez wystawcę tokenu, należy utworzyć w kluczach zasad usługi Azure AD B2C.

Zaloguj się w witrynie Azure Portal.
Jeśli masz dostęp do wielu dzierżaw, wybierz ikonę Ustawienia w górnym menu, aby przełączyć się do dzierżawy usługi Azure AD B2C z menu Katalogi i subskrypcje.
W witrynie Azure Portal wyszukaj i wybierz pozycję Azure AD B2C.
Na stronie przeglądu w obszarze Zasady wybierz pozycję Identity Experience Framework.
Wybieranie kluczy zasad
Wybierz pozycję Ręczne.
W polu Nazwa użyj polecenia IdTokenHintKey.
Prefiks B2C_1A_ może zostać dodany automatycznie.
W polu Wpis tajny wprowadź wygenerowany wcześniej klucz logowania.
W przypadku użycia klucza użyj szyfrowania.
Wybierz pozycję Utwórz.
Upewnij się, że klucz został utworzony B2C_1A_IdTokenHintKey.

Krok 3. Dodawanie profilu technicznego wskazówki tokenu identyfikatora

Poniższy profil techniczny weryfikuje token i wyodrębnia oświadczenia.

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

Krok 4. Przygotowanie zasad

Ukończ krok Konfigurowanie zasad .

Krok 5. Przygotowanie kodu

Przykład usługi GitHub to aplikacja internetowa ASP.NET i aplikacja konsolowa, która generuje token identyfikatora podpisany przy użyciu klucza symetrycznego.

Wystawianie tokenu z kluczami asymetrycznymi

W przypadku klucza asymetrycznego token jest podpisany przy użyciu certyfikatów RSA. Ta aplikacja hostuje punkt końcowy metadanych openID Połączenie i punkt końcowy kluczy sieci Web JSON (JWKs), który jest używany przez usługę Azure AD B2C do sprawdzania poprawności podpisu tokenu identyfikatora.

Wystawca tokenu musi podać następujące punkty końcowe:

/.well-known/openid-configuration — Dobrze znany punkt końcowy konfiguracji z odpowiednimi informacjami o tokenie, takimi jak nazwa wystawcy tokenu i link do punktu końcowego zestawu JWK.
/.well-known/keys — punkt końcowy klucza internetowego JSON (JWK) z kluczem publicznym używanym do podpisywania klucza (z częścią klucza prywatnego certyfikatu).

Zobacz przykład kontrolera MVC platformy TokenMetadataController.cs .NET.

Krok 1. Przygotowanie certyfikatu z podpisem własnym

Jeśli nie masz jeszcze certyfikatu, możesz użyć certyfikatu z podpisem własnym w tym przewodniku z instrukcjami. W systemie Windows możesz użyć polecenia cmdlet New-SelfSignedCertificate programu PowerShell do wygenerowania certyfikatu.

Uruchom to polecenie programu PowerShell, aby wygenerować certyfikat z podpisem własnym. Zmodyfikuj -Subject argument odpowiednio dla aplikacji i nazwy dzierżawy usługi Azure AD B2C. Możesz również dostosować -NotAfter datę, aby określić inne wygaśnięcie certyfikatu.

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"

Krok 2. Dodawanie profilu technicznego wskazówki tokenu identyfikatora

Poniższy profil techniczny weryfikuje token i wyodrębnia oświadczenia. Zmień identyfikator URI metadanych na dobrze znany punkt końcowy konfiguracji wystawcy tokenu.

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

Krok 3. Przygotowanie zasad

Ukończ krok Konfigurowanie zasad .

Krok 4. Przygotowanie kodu

Ten przykładowy ASP.NET aplikacji internetowej usługi GitHub generuje tokeny identyfikatorów i hostuje punkty końcowe metadanych wymagane do użycia parametru "id_token_hint" w usłudze Azure AD B2C.

Konfigurowanie zasad

W przypadku metod id_token_hint symetrycznych i asymetrycznych profil techniczny jest wywoływany z kroku aranżacji z typem GetClaims i musi określać oświadczenia wejściowe zasad jednostki uzależnionej.

Dodaj profil techniczny IdTokenHint_ExtractClaims do zasad rozszerzenia.

Dodaj następujący krok aranżacji do podróży użytkownika jako pierwszy element.

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

W zasadach jednostki uzależnionej powtórz te same oświadczenia wejściowe skonfigurowane w profilu technicznym IdTokenHint_ExtractClaims. Przykład:

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

W zależności od wymagań biznesowych może być konieczne dodanie weryfikacji tokenu, na przykład sprawdzenie formatu adresu e-mail. W tym celu dodaj kroki aranżacji, które wywołują profil techniczny przekształcania oświadczeń. Dodaj również własny profil techniczny, aby wyświetlić komunikat o błędzie.

Tworzenie i podpisywanie tokenu

Przykłady usługi GitHub ilustrują sposób tworzenia takiego tokenu, który później został wysłany jako id_token_hint parametr ciągu zapytania. Poniżej przedstawiono przykład żądania autoryzacji z parametrem 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

Następne kroki

Sprawdź rozwiązanie do tworzenia konta zaproszeń pocztą e-mail w repozytorium GitHub społeczności usługi Azure AD B2C.

Udostępnij za pośrednictwem