Definování technického profilu nápovědy tokenu ID ve vlastních zásadách Azure Active Directory B2C

Článek
01/11/2024

Azure AD B2C umožňuje aplikacím předávající strany odesílat příchozí JWT jako součást žádosti o autorizaci OAuth2. Token JWT může vydat aplikace předávající strany nebo zprostředkovatele identity a může předat nápovědu k uživateli nebo autorizační žádosti. Azure AD B2C ověří podpis, název vystavitele a cílovou skupinu tokenů a extrahuje deklaraci identity z příchozího tokenu.

Případy použití

Toto řešení můžete použít k odesílání dat do Azure AD B2C zapouzdřených v jednom tokenu JWT. ŘešeníSignup with email invitation, ve kterém může správce systému poslat podepsané pozvání uživatelům, je založené na id_token_hint. Účet v adresáři můžou vytvořit jenom uživatelé s přístupem k e-mailu s pozvánkou.

Přístup k podepisování tokenů

U id_token_hint vytvoří vystavitel tokenu (aplikace předávající strany nebo zprostředkovatele identity) token a pak ho podepíše pomocí podpisového klíče, aby token prokázal, že pochází z důvěryhodného zdroje. Podpisový klíč může být symetrický nebo asymetrický. Symetrická kryptografie nebo kryptografie privátního klíče používá sdílený tajný klíč k podepsání a ověření podpisu. Asymetrická kryptografie neboli kryptografie veřejného klíče je kryptografický systém, který používá privátní i veřejný klíč. Privátní klíč je známý pouze vystavitelem tokenu a slouží k podepsání tokenu. Veřejný klíč se sdílí se zásadami Azure AD B2C, aby se ověřil podpis tokenu.

Formát tokenu

Id_token_hint musí být platný token JWT. Následující tabulka obsahuje seznam povinných deklarací identity. Další deklarace identity jsou volitelné.

Název	Deklarace identity	Příklad hodnoty	Popis
Cílová skupina	`aud`	`00001111-aaaa-2222-bbbb-3333cccc4444`	Identifikuje zamýšlený příjemce tokenu. Cílová skupina je libovolný řetězec definovaný vystavitelem tokenu. Azure AD B2C tuto hodnotu ověří a odmítne token, pokud se neshoduje.
Issuer	`iss`	`https://localhost`	Identifikuje službu tokenů zabezpečení (vystavitele tokenů). Vystavitel je libovolný identifikátor URI definovaný vystavitelem tokenu. Azure AD B2C tuto hodnotu ověří a odmítne token, pokud se neshoduje.
Čas vypršení platnosti	`exp`	`1600087315`	Čas, kdy se token stane neplatným, vyjádřený epochou. Azure AD B2C tuto hodnotu ověří a v případě vypršení platnosti tokenu odmítne.
Ne před	`nbf`	`1599482515`	Čas, kdy se token stane platným, vyjádřený epochou. Tento čas je obvykle stejný jako čas vydání tokenu. Azure AD B2C ověří tuto hodnotu a odmítne token, pokud životnost tokenu není platná.

Následující token je příkladem platného tokenu ID:

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

Protokol

Atribut Name elementu Protocol musí být nastaven na None. Například protokol pro IdTokenHint_ExtractClaims technický profil je None:

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

Technický profil je volán z kroku orchestrace s typem GetClaims.

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

Výstupní deklarace identity

OutputClaims element obsahuje seznam deklarací identity, které se mají extrahovat z tokenu JWT. Možná budete muset namapovat název deklarace identity definované ve vaší zásadě na název definovaný v tokenu JWT. Můžete také zahrnout deklarace identity, které nejsou vráceny tokenem JWT, pokud nastavíte DefaultValue atribut.

Metadata

Při použití symetrického klíče jsou relevantní následující metadata.

Atribut	Požadováno	Popis
issuer	Ano	Identifikuje službu tokenů zabezpečení (vystavitele tokenů). Tato hodnota musí být shodná s deklarací identity tokenu `iss` JWT.
IdTokenAudience	Ano	Identifikuje zamýšlený příjemce tokenu. Musí být shodná s `aud` deklarací identity v rámci deklarace tokenu JWT.

Při použití asymetrického klíče jsou relevantní následující metadata.

Atribut	Požadováno	Popis
METADATA	Ano	Adresa URL odkazující na konfigurační dokument vystavitele tokenu, který se označuje také jako známý koncový bod konfigurace OpenID.
issuer	No	Identifikuje službu tokenů zabezpečení (vystavitele tokenů). Tuto hodnotu lze použít k přepsání hodnoty nakonfigurované v metadatech a musí být stejná jako `iss` deklarace identity v rámci deklarace tokenu JWT.
IdTokenAudience	No	Identifikuje zamýšlený příjemce tokenu. Musí být shodná s `aud` deklarací identity v rámci deklarace tokenu JWT.

Důležité

Vaše koncové body musí splňovat požadavky na zabezpečení Azure AD B2C. Starší verze protokolu TLS a šifry jsou zastaralé. Další informace najdete v tématu Požadavky na protokol TLS a šifrovací sadu Azure AD B2C.

Kryptografické klíče

Při použití symetrického klíče obsahuje element CryptographicKeys následující atribut:

Atribut	Požadováno	Popis
tajný klíč klienta	Ano	Kryptografický klíč, který slouží k ověření podpisu tokenu JWT.

Praktičtí průvodci

Vystavení tokenu se symetrickými klíči

Krok 1: Vytvoření sdíleného klíče

Vytvořte klíč, který lze použít k podepsání tokenu. K vygenerování klíče použijte například následující kód PowerShellu.

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

Tento kód vytvoří tajný řetězec, jako je VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=.

Krok 2: Přidání podpisového klíče do Azure AD B2C

Stejný klíč, který používá vystavitel tokenu, je potřeba vytvořit v klíčích zásad Azure AD B2C.

Přihlaste se k portálu Azure.
Pokud máte přístup k více tenantům, v horní nabídce vyberte ikonu Nastavení a v nabídce Adresáře a předplatná přepněte do svého tenanta Azure AD B2C.
Na webu Azure Portal vyhledejte a vyberte Azure AD B2C.
Na stránce přehledu v části Zásady vyberte Architekturu prostředí identit.
Výběr klíčů zásad
Vyberte Ručně.
Jako název použijte IdTokenHintKey.
Předpona B2C_1A_ může být přidána automaticky.
Do pole Tajný kód zadejte přihlašovací klíč, který jste vygenerovali dříve.
Pro použití klíče použijte šifrování.
Vyberte Vytvořit.
Potvrďte, že jste klíč B2C_1A_IdTokenHintKeyvytvořili.

Krok 3: Přidání technického profilu nápovědy tokenu ID

Následující technický profil ověří token a extrahuje deklarace identity.

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

Krok 4: Příprava zásad

Dokončete krok Konfigurace zásad.

Krok 5: Příprava kódu

Ukázka GitHubu je webová aplikace ASP.NET a konzolová aplikace, která generuje token ID podepsaný pomocí symetrického klíče.

Vystavení tokenu s asymetrickými klíči

S asymetrickým klíčem je token podepsaný pomocí certifikátů RSA. Tato aplikace hostuje koncový bod metadat OpenID Připojení a koncový bod JSON Web Keys (JWKs), který používá Azure AD B2C k ověření podpisu tokenu ID.

Vystavitel tokenu musí poskytovat následující koncové body:

/.well-known/openid-configuration – Známý koncový bod konfigurace s relevantními informacemi o tokenu, jako je název vystavitele tokenu a odkaz na koncový bod JWK.
/.well-known/keys – koncový bod webového klíče JSON (JWK) s veřejným klíčem, který se používá k podepsání klíče (s privátní částí certifikátu).

TokenMetadataController.cs Viz ukázka kontroleru .NET MVC.

Krok 1: Příprava certifikátu podepsaného svým držitelem

Pokud ještě certifikát nemáte, můžete k tomuto průvodci použít certifikát podepsaný svým držitelem. Ve Windows můžete k vygenerování certifikátu použít rutinu New-SelfSignedCertificate PowerShellu.

Spuštěním tohoto příkazu PowerShellu vygenerujte certifikát podepsaný svým držitelem. -Subject Upravte argument podle potřeby pro vaši aplikaci a název tenanta Azure AD B2C. Můžete také upravit -NotAfter datum a určit jiné vypršení platnosti certifikátu.

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: Přidání technického profilu nápovědy tokenu ID

Následující technický profil ověří token a extrahuje deklarace identity. Změňte identifikátor URI metadat na známý koncový bod konfigurace vystavitele 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: Příprava zásad

Dokončete krok Konfigurace zásad.

Krok 4: Příprava kódu

Tato ukázková ASP.NET webové aplikace GitHubu generuje tokeny ID a hostuje koncové body metadat vyžadované k použití parametru id_token_hint v Azure AD B2C.

Konfigurace zásad

U symetrických i asymetrických přístupů id_token_hint se technický profil volá z kroku orchestrace s typem GetClaims a potřebuje zadat vstupní deklarace zásad předávající strany.

Přidejte do zásad rozšíření IdTokenHint_ExtractClaims technický profil.

Jako první položku přidejte do cesty uživatele následující krok orchestrace.

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

V zásadách předávající strany opakujte stejné vstupní deklarace identity, které jste nakonfigurovali v IdTokenHint_ExtractClaims technickém profilu. Příklad:

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

V závislosti na vašich obchodních požadavcích možná budete muset přidat ověření tokenů, například zkontrolovat formát e-mailové adresy. Uděláte to tak, že přidáte kroky orchestrace, které vyvolají technický profil transformace deklarací identity. Přidejte také technický profil s vlastním kontrolním výrazem , který zobrazí chybovou zprávu.

Vytvoření a podepsání tokenu

Ukázky GitHubu ukazují, jak vytvořit takový token, který později odeslal jako id_token_hint parametr řetězce dotazu. Následuje příklad žádosti o autorizaci s parametrem id_token_hint.

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

Další kroky

Zkontrolujte registraci pomocí e-mailového řešení pro pozvání v úložišti GitHub komunity Azure AD B2C.

Sdílet prostřednictvím