Credenziali del certificato per l'autenticazione di un'applicazione con Microsoft Identity Platform

  • Articolo

Microsoft Identity Platform consente a un'applicazione di usare le proprie credenziali per l'autenticazione ovunque sia possibile usare un segreto client, ad esempio nel flusso di concessione delle credenziali client OAuth 2.0 e nel flusso OBO (On-behalf-of).

Una forma di credenziale che un'applicazione può usare per l'autenticazione è un'asserzione JWT (JSON Web Token ) firmata con un certificato di proprietà dell'applicazione. Questo argomento è descritto nella specifica di Connessione OpenID per l'opzione private_key_jwt di autenticazione client.

Se si è interessati a usare un token JWT rilasciato da un altro provider di identità come credenziale per l'applicazione, vedere Federazione delle identità del carico di lavoro per informazioni su come configurare un criterio federativo.

Formato di asserzione

Per calcolare l'asserzione, è possibile usare una delle numerose librerie JWT nel linguaggio preferito. MSAL supporta questa operazione usando .WithCertificate(). Le informazioni vengono trasportate dal token nella relativa intestazione, attestazioni e firma.

Parametro Commento
alg Deve essere RS256
typ Deve essere JWT
x5t Identificazione personale SHA-1 con codifica Base64url della codifica DER del certificato X.509. Ad esempio, dato un hash del certificato X.509 di 84E05C1D98BCE3A5421D225B140B36E86A3D5534 (Hex), l'attestazione x5t sarà hOBcHZi846VCHSJbFAs26Go9VTQ (Base64url).

Attestazioni (payload)

Tipo di attestazione Valore Descrizione
aud https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token L'attestazione "aud" (audience) identifica i destinatari per cui il token JWT è destinato (qui Microsoft Entra ID) Vedere RFC 7519, sezione 4.1.3. In questo caso, il destinatario è il server di accesso (login.microsoftonline.com).
exp 1601519414 L'attestazione "exp" (scadenza) identifica l'ora di scadenza in o dopo la quale il token JWT non deve essere accettato per l'elaborazione. Vedere RFC 7519, sezione 4.1.4. In questo modo l'asserzione può essere usata fino a quel momento, quindi mantenerla breve- 5-10 minuti dopo nbf al massimo. Microsoft Entra ID non pone restrizioni al exp momento.
iss {ClientID} L'attestazione "iss" (autorità di certificazione) identifica l'entità che ha emesso il token JWT, in questo caso l'applicazione client. Usare l'ID applicazione GUID.
jti (guid) l'attestazione "jti" (JWT ID) fornisce un identificatore univoco per il token JWT. Il valore dell'identificatore deve essere assegnato in modo da garantire che vi sia una probabilità trascurabile che lo stesso valore venga assegnato accidentalmente a un oggetto dati diverso. Se l'applicazione usa più emittenti, è necessario impedire conflitti tra i valori prodotti anche da autorità emittenti diverse. Il valore "jti" è una stringa con distinzione tra maiuscole e minuscole. RFC 7519, Sezione 4.1.7
nbf 1601519114 L'attestazione "nbf" (not before) identifica l'ora prima della quale il token JWT non deve essere accettato per l'elaborazione. RFC 7519, sezione 4.1.5. L'uso dell'ora corrente è appropriato.
sub {ClientID} L'attestazione "sub" (oggetto) identifica l'oggetto del token JWT, in questo caso anche l'applicazione. Usare lo stesso valore di iss.
iat 1601519114 l'attestazione "iat" (issued at) identifica l'ora in cui è stato emesso il token JWT. Questa attestazione può essere usata per determinare l'età del token JWT. RFC 7519, sezione 4.1.5.

Firma

La firma viene calcolata applicando il certificato come descritto nella specifica json Web Token RFC7519.

Esempio di asserzione del token JWT decodificata

{
  "alg": "RS256",
  "typ": "JWT",
  "x5t": "gx8tGysyjcRqKjFPnd7RFwvwZI0"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "jti": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "nbf": 1484592741,
  "sub": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
.
"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u..."

Esempio di asserzione del token JWT codificata

La stringa seguente è un esempio di asserzione codificata. Se si osserva attentamente, si notano tre sezioni separate da punti (.):

  • La prima sezione codifica l'intestazione
  • La seconda sezione codifica le attestazioni (payload)
  • L'ultima sezione è la firma calcolata con i certificati del contenuto delle prime due sezioni
"eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbVwvam1wcmlldXJob3RtYWlsLm9ubWljcm9zb2Z0LmNvbVwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQ4NDU5MzM0MSwiaXNzIjoiOTdlMGE1YjctZDc0NS00MGI2LTk0ZmUtNWY3N2QzNWM2ZTA1IiwianRpIjoiMjJiM2JiMjYtZTA0Ni00MmRmLTljOTYtNjVkYmQ3MmMxYzgxIiwibmJmIjoxNDg0NTkyNzQxLCJzdWIiOiI5N2UwYTViNy1kNzQ1LTQwYjYtOTRmZS01Zjc3ZDM1YzZlMDUifQ.
Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

Registrare un certificato con Microsoft Identity Platform

È possibile associare le credenziali del certificato all'applicazione client in Microsoft Identity Platform tramite l'interfaccia di amministrazione di Microsoft Entra usando uno dei metodi seguenti:

Caricamento del file del certificato

Nella scheda Registrazioni app per l'applicazione client:

  1. Selezionare Certificati e certificati segreti>.
  2. Selezionare Carica certificato e selezionare il file del certificato da caricare.
  3. Selezionare Aggiungi. Dopo aver caricato il certificato, vengono visualizzati i valori di identificazione personale, data di inizio e scadenza.

Aggiornamento del manifesto dell'applicazione

Dopo aver acquisito un certificato, calcolare questi valori:

  • $base64Thumbprint - Valore con codifica Base64 dell'hash del certificato
  • $base64Value - Valore con codifica Base64 dei dati non elaborati del certificato

Specificare un GUID per identificare la chiave nel manifesto dell'applicazione ($keyId).

Nella registrazione dell'app di Azure per l'applicazione client:

  1. Selezionare Manifesto per aprire il manifesto dell'applicazione.

  2. Sostituire la proprietà keyCredentials con le nuove informazioni del certificato usando lo schema seguente.

    "keyCredentials": [
    {
        "customKeyIdentifier": "$base64Thumbprint",
        "keyId": "$keyid",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value":  "$base64Value"
    }
]

  3. Salvare le modifiche apportate al manifesto dell'applicazione e caricare il manifesto in Microsoft Identity Platform.

    La proprietà keyCredentials è multivalore, quindi è possibile caricare più certificati per una gestione delle chiavi più avanzata.

Uso di un'asserzione client

Le asserzioni client possono essere usate ovunque venga usato un segreto client. Ad esempio, nel flusso del codice di autorizzazione è possibile passare un oggetto client_secret per dimostrare che la richiesta proviene dall'app. È possibile sostituirlo con client_assertion i parametri e client_assertion_type .

Parametro valore Descrizione
client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer Si tratta di un valore fisso che indica che si usa una credenziale del certificato.
client_assertion JWT Questo è il token JWT creato in precedenza.

Passaggi successivi

La libreria MSAL.NET gestisce questo scenario in una singola riga di codice.

L'applicazione console daemon .NET che usa l'esempio di codice di Microsoft Identity Platform in GitHub illustra come un'applicazione usa le proprie credenziali per l'autenticazione. Illustra anche come creare un certificato autofirmato usando il New-SelfSignedCertificate cmdlet di PowerShell. È anche possibile usare gli script di creazione dell'app nel repository di esempio per creare certificati, calcolare l'identificazione personale e così via.