Condividi tramite

Definire un profilo tecnico dell'hint per il token ID in un criterio personalizzato di Azure Active Directory B2C

  • Articolo

Azure AD B2C consente alle applicazioni relying party di inviare un token JWT in ingresso come parte della richiesta di autorizzazione OAuth2. Il token JWT può essere emesso da un'applicazione relying party o da un provider di identità e può passare un suggerimento sull'utente o sulla richiesta di autorizzazione. Azure AD B2C convalida la firma, il nome dell'autorità emittente e il gruppo di destinatari dei token ed estrae l'attestazione dal token in ingresso.

Casi d'uso

È possibile usare questa soluzione per inviare dati ad Azure AD B2C incapsulati in un singolo token JWT. La Signup with email invitation soluzione, in cui l'amministratore di sistema può inviare un invito firmato agli utenti, si basa su id_token_hint. Solo gli utenti con accesso al messaggio di posta elettronica di invito possono creare l'account nella directory.

Approccio alla firma dei token

Con id_token_hint, l'emittente del token (un'app relying party o un provider di identità) compone il token e quindi lo firma usando una chiave di firma per dimostrare che il token proviene da un'origine attendibile. La chiave di firma può essere simmetrica o asimmetrica. La crittografia simmetrica o la crittografia a chiave privata usa un segreto condiviso per firmare e convalidare la firma. La crittografia asimmetrica o la crittografia a chiave pubblica è un sistema di crittografia che usa sia una chiave privata che una chiave pubblica. La chiave privata è nota solo all'autorità emittente del token e viene usata per firmare il token. La chiave pubblica viene condivisa con i criteri di Azure AD B2C per convalidare la firma del token.

Formato token

Il id_token_hint deve essere un token JWT valido. Nella tabella seguente sono elencate le attestazioni obbligatorie. Le attestazioni aggiuntive sono facoltative.

Nome Attestazione Valore di esempio Descrizione
Destinatari aud 00001111-aaaa-2222-bbbb-3333cccc4444 Identifica il destinatario del token. Il gruppo di destinatari è una stringa arbitraria definita dall'autorità emittente del token. Azure AD B2C convalida questo valore e rifiuta il token se non corrisponde.
Autorità di certificazione iss https://localhost Identifica il servizio token di sicurezza (autorità emittente del token). L'autorità emittente è un URI arbitrario definito dall'autorità emittente del token. Azure AD B2C convalida questo valore e rifiuta il token se non corrisponde.
Ora di scadenza exp 1600087315 Ora in cui il token non è più valido, rappresentata dal valore epoch time. Azure AD B2C convalida questo valore e rifiuta il token se il token è scaduto.
Non prima nbf 1599482515 L’ora in cui il token diventa valido, rappresentata dal valore epoch time. Equivale in genere all'ora di rilascio del token. Azure AD B2C convalida questo valore e rifiuta il token se la durata del token non è valida.

Il token seguente è un esempio di token ID valido:

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

Protocollo

L'attributo Nome dell'elemento Protocollo deve essere impostato su None. Ad esempio, il protocollo per il profilo tecnico IdTokenHint_ExtractClaims è None:

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

Il profilo tecnico viene chiamato da un passaggio di orchestrazione con tipo di GetClaims.

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

Attestazioni di output

L'elemento OutputClaims contiene un elenco di attestazioni da estrarre dal token JWT. Potrebbe essere necessario eseguire il mapping del nome dell'attestazione definita nei criteri al nome definito nel token JWT. È anche possibile includere attestazioni che non vengono restituite dal token JWT, purché si imposti l'attributo DefaultValue .

Metadati UFX

I metadati seguenti sono rilevanti quando si usa la chiave simmetrica.

Attributo Richiesto Descrizione
Autorità di certificazione Sì Identifica il servizio token di sicurezza (autorità emittente del token). Questo valore deve essere identico all'attestazione all'interno dell'attestazione iss del token JWT.
IdTokenAudience Sì Identifica il destinatario del token. Deve essere identico all'attestazione aud all'interno dell'attestazione del token JWT.

I metadati seguenti sono rilevanti quando si usa una chiave asimmetrica.

Attributo Richiesto Descrizione
METADATI Sì URL che punta a un documento di configurazione dell'autorità emittente del token, noto anche come endpoint di configurazione noto openID.
Autorità di certificazione No Identifica il servizio token di sicurezza (autorità emittente del token). Questo valore può essere usato per sovrascrivere il valore configurato nei metadati e deve essere identico all'attestazione iss all'interno dell'attestazione del token JWT.
IdTokenAudience No Identifica il destinatario del token. Deve essere identico all'attestazione aud all'interno dell'attestazione del token JWT.

Importante

Gli endpoint devono essere conformi ai requisiti di sicurezza di Azure AD B2C. Le versioni precedenti di TLS e le crittografie sono deprecate. Per altre informazioni, vedere Requisiti di Azure AD B2C TLS e della suite di crittografia.

Chiavi crittografiche

Quando si usa una chiave simmetrica, l'elemento CryptographicKeys contiene l'attributo seguente:

Attributo Richiesto Descrizione
client_secret Sì Chiave crittografica usata per convalidare la firma del token JWT.

Guida pratica

Rilasciare un token con chiavi simmetriche

Passaggio 1: Creare una chiave condivisa

Creare una chiave che può essere usata per firmare il token. Ad esempio, usare il codice di PowerShell seguente per generare una chiave.

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

Questo codice crea una stringa privata come VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=.

Passaggio 2: Aggiungere la chiave di firma ad Azure AD B2C

La stessa chiave usata dall'autorità emittente del token deve essere creata nelle chiavi dei criteri di Azure AD B2C.

  1. Accedi al portale di Azure.
  2. Se si ha accesso a più tenant, selezionare l'icona Impostazioni nel menu in alto per passare al tenant di Azure AD B2C dal menu Directory e sottoscrizioni.
  3. Nel portale di Azure cercare e selezionare Azure AD B2C.
  4. Nella pagina Panoramica, nella sezione Criteri, selezionare Framework dell'esperienza di gestione delle identità.
  5. Selezionare chiavi dei criteri
  6. Selezionare Manuale.
  7. Per Nome usare IdTokenHintKey.
    È possibile che il prefisso B2C_1A_ venga aggiunto automaticamente.
  8. Nella casella Segreto immettere la chiave di accesso generata in precedenza.
  9. Per Uso chiave usare Crittografia.
  10. Seleziona Crea.
  11. Verificare di avere creato la chiave B2C_1A_IdTokenHintKey.

Passaggio 3: Aggiungere il profilo tecnico dell'hint per il token ID

Il profilo tecnico seguente convalida il token ed estrae le attestazioni.

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

Passaggio 4: Preparare i criteri

Completare il passaggio Configurare il criterio .

Passaggio 5: Preparare il codice

L'esempio GitHub è un'applicazione Web ASP.NET e un'app console che genera un token ID firmato usando una chiave simmetrica.

Rilasciare un token con chiavi asimmetriche

Con una chiave asimmetrica, il token viene firmato usando i certificati RSA. Questa applicazione ospita un endpoint OpenID Connessione metadati e chiavi WEB JSON (JWK) usate da Azure AD B2C per convalidare la firma del token ID.

L'autorità emittente del token deve fornire gli endpoint seguenti:

  • /.well-known/openid-configuration - Endpoint di configurazione noto con informazioni pertinenti sul token, ad esempio il nome dell'autorità emittente del token e il collegamento all'endpoint JWK.
  • /.well-known/keys - Punto finale JWK (JSON Web Key) con la chiave pubblica usata per firmare la chiave (con la parte della chiave privata del certificato).

Vedere l'esempio TokenMetadataController.cs di controller MVC .NET.

Passaggio 1: Preparare un certificato autofirmato

Se non si ha già un certificato, è possibile usare un certificato autofirmato per questa guida pratica. In Windows è possibile usare il cmdlet New-SelfSignedCertificate di PowerShell per generare un certificato.

Eseguire questo comando di PowerShell per generare un certificato autofirmato. Modificare l'argomento -Subject in base al nome dell'applicazione e del tenant Azure AD B2C. Si può anche modificare la data -NotAfter per specificare una scadenza diversa per il certificato.

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"

Passaggio 2: Aggiungere il profilo tecnico dell'hint per il token ID

Il profilo tecnico seguente convalida il token ed estrae le attestazioni. Modificare l'URI dei metadati nell'endpoint di configurazione noto dell'autorità di certificazione del token.

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

Passaggio 3: Preparare i criteri

Completare il passaggio Configurare il criterio .

Passaggio 4: Preparare il codice

Questo esempio di GitHub ASP.NET'applicazione Web genera token ID e ospita gli endpoint dei metadati necessari per usare il parametro "id_token_hint" in Azure AD B2C.

Configurare i criteri

Per gli approcci simmetrici e asimmetrici, il id_token_hint profilo tecnico viene chiamato da un passaggio di orchestrazione con tipo e deve specificare le attestazioni di GetClaims input dei criteri della relying party.

  1. Aggiungere il profilo tecnico IdTokenHint_ExtractClaims ai criteri di estensione.

  2. Aggiungere il passaggio di orchestrazione seguente al percorso utente come primo elemento.

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

  3. Nei criteri della relying party ripetere le stesse attestazioni di input configurate nel profilo tecnico IdTokenHint_ExtractClaims. Ad esempio:

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

A seconda dei requisiti aziendali, potrebbe essere necessario aggiungere convalide dei token, ad esempio controllare il formato dell'indirizzo di posta elettronica. A tale scopo, aggiungere passaggi di orchestrazione che richiamano un profilo tecnico di trasformazione delle attestazioni. Aggiungere anche un profilo tecnico autocertificato per presentare un messaggio di errore.

Creare e firmare un token

Gli esempi di GitHub illustrano come creare un token di questo tipo rilasciando un token JWT che in seguito è stato inviato come parametro di stringa di id_token_hint query. Di seguito è riportato un esempio di richiesta di autorizzazione con id_token_hint parametro

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

Passaggi successivi

  • Controllare la soluzione di iscrizione con l'invito alla posta elettronica nel repository GitHub della community di Azure AD B2C.