Definire un profilo tecnico dell'hint per il token ID in un criterio personalizzato di Azure Active Directory B2C
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 |
a489fc44-3cc0-4a78-92f6-e413cd853eae |
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": "a489fc44-3cc0-4a78-92f6-e413cd853eae"
}
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.
- Accedi al portale di Azure.
- 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.
- Nel portale di Azure cercare e selezionare Azure AD B2C.
- Nella pagina Panoramica, nella sezione Criteri, selezionare Framework dell'esperienza di gestione delle identità.
- Selezionare chiavi dei criteri
- Selezionare Manuale.
- Per Nome usare
IdTokenHintKey.
È possibile che il prefissoB2C_1A_venga aggiunto automaticamente. - Nella casella Segreto immettere la chiave di accesso generata in precedenza.
- Per Uso chiave usare Crittografia.
- Seleziona Crea.
- 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">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>
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.
Aggiungere il profilo tecnico IdTokenHint_ExtractClaims ai criteri di estensione.
Aggiungere il passaggio di orchestrazione seguente al percorso utente come primo elemento.
<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />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=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
Passaggi successivi
- Controllare la soluzione di iscrizione con l'invito alla posta elettronica nel repository GitHub della community di Azure AD B2C.
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per