Personalizzare le attestazioni rilasciate nel token Web JSON (JWT) per le applicazioni aziendali
Microsoft Identity Platform supporta l'accesso Single Sign-On (SSO) con la maggior parte delle applicazioni prei integrate nella raccolta di applicazioni Di Microsoft Entra e nelle applicazioni personalizzate. Quando un utente esegue l'autenticazione a un'applicazione tramite Microsoft Identity Platform usando il protocollo OIDC, invia un token all'applicazione. L'applicazione quindi convalida e usa il token per concedere l'accesso all'utente anziché richiedere l'immissione di nome utente e password.
Questi token JSON Web (JWT) usati dalle applicazioni OIDC e OAuth contengono informazioni sull'utente noto come attestazioni. Un'attestazione è un insieme di informazioni relative ad un utente dichiarate da un provider di identità all'interno del token rilasciato per tale utente. In una risposta OIDC i dati delle attestazioni sono in genere contenuti nel token ID rilasciato dal provider di identità sotto forma di token JWT.
Visualizzare o modificare le attestazioni
Suggerimento
La procedura descritta in questo articolo può variare leggermente in base al portale di partenza.
Le attestazioni JWT facoltative possono essere configurate nella registrazione dell'applicazione originale, ma possono anche essere configurate nell'applicazione aziendale. Per visualizzare o modificare le attestazioni rilasciate nel token JWT nell'applicazione:
- Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come Amministratore applicazione cloud.
- Passare a Identità>Applicazioni>Applicazioni aziendali>Tutte le applicazioni.
- Selezionare l'applicazione, scegliere Single Sign-On nel menu a sinistra e quindi selezionare Modifica nella sezione Attributi e attestazioni.
Un'applicazione potrebbe richiedere la personalizzazione delle attestazioni per vari motivi. Ad esempio, quando un'applicazione richiede un set diverso di URI attestazioni o valori attestazioni. Usando la sezione Attributi e attestazioni , è possibile aggiungere o rimuovere un'attestazione per l'applicazione. È anche possibile creare un'attestazione personalizzata specifica per un'applicazione in base al caso d'uso.
I passaggi seguenti descrivono come assegnare un valore costante:
- Selezionare l'attestazione da modificare.
- Immettere il valore costante senza virgolette nell'attributo Source in base all'organizzazione e quindi selezionare Salva.
La panoramica attributi visualizza il valore costante.
Funzioni speciali di trasformazione delle attestazioni
È possibile usare le seguenti funzioni speciali di trasformazione delle attestazioni.
| Funzione | Descrizione |
|---|---|
| ExtractMailPrefix() | Rimuove il suffisso del dominio dall'indirizzo di posta elettronica o dal nome dell'entità utente. Questa funzione estrae solo la prima parte del nome utente. Ad esempio, joe_smith anziché joe_smith@contoso.com. |
| ToLower() | Converte i caratteri dell'attributo selezionato in minuscole. |
| ToUpper() | Converte i caratteri dell'attributo selezionato in maiuscole. |
Aggiungere attestazioni specifiche dell'applicazione
Per aggiungere attestazioni specifiche dell'applicazione:
- In Attributi utente e intestazioni selezionare Aggiungi nuova attestazione per aprire la pagina Gestisci attestazioni utente.
- Immettere il nome delle attestazioni. Il valore non deve necessariamente seguire un modello URI. Se è necessario un modello di URI, è possibile inserirlo nel campo Spazio dei nomi.
- Selezionare l'opzione di Origine da cui l'attestazione recupererà il valore. È possibile selezionare un attributo utente nell'elenco a discesa degli attributi di origine oppure applicare una trasformazione all'attributo utente prima di crearlo come attestazione.
Trasformazioni delle attestazioni
Per applicare una trasformazione a un attributo utente:
- In Gestisci l'attestazioneselezionare Trasformazione come origine dell'attestazione per aprire la pagina Gestisci la trasformazione.
- Selezionare la funzione nell'elenco a discesa Trasformazione. A seconda della funzione selezionata, specificare i parametri e un valore costante da valutare nella trasformazione.
- Considerare l'origine come multivalore indica se la trasformazione viene applicata a tutti i valori o solo alla prima. Per impostazione predefinita, il primo elemento di un'attestazione multivalore viene applicato alle trasformazioni. Quando si seleziona questa casella, garantisce che venga applicata a tutti. Questa casella di controllo è abilitata solo per gli attributi multivalore. Ad esempio:
user.proxyaddresses. - Per applicare più trasformazioni, selezionare Aggiungi trasformazione. È possibile applicare un massimo di due trasformazioni a un'attestazione. È ad esempio possibile estrarre prima il prefisso dell'indirizzo di posta elettronica da
user.mail. Quindi, impostare la stringa in maiuscolo.
Per trasformare le attestazioni, è possibile usare le funzioni seguenti.
| Funzione | Descrizione |
|---|---|
| ExtractMailPrefix() | Rimuove il suffisso del dominio dall'indirizzo di posta elettronica o dal nome dell'entità utente. Questa funzione estrae solo la prima parte del nome utente. Ad esempio, joe_smith anziché joe_smith@contoso.com. |
| Join() | Crea un nuovo valore creando un join tra due attributi. Facoltativamente, è possibile usare un separatore tra i due attributi. Per la trasformazione dell'attestazione NameID, la funzione Join() ha un comportamento specifico quando l'input della trasformazione ha una parte di dominio. Rimuove la parte del dominio dall'input prima di unirla al separatore e al parametro selezionato. Ad esempio, se l'input della trasformazione è joe_smith@contoso.com, il separatore è @ e il parametro è fabrikam.com, questa combinazione di input restituisce joe_smith@fabrikam.com. |
| ToLowercase() | Converte i caratteri dell'attributo selezionato in minuscole. |
| ToUppercase() | Converte i caratteri dell'attributo selezionato in maiuscole. |
| Contains() | Restituisce un attributo o una costante se l'input corrisponde al valore specificato. In caso contrario, se non esistono corrispondenze, è possibile specificare un altro output. Ad esempio, è possibile scegliere che venga creata un'attestazione in cui il valore corrisponde all'indirizzo di posta elettronica dell'utente se contiene il dominio @contoso.com e in caso contrario che venga restituito il nome dell'entità utente. Per eseguire questa funzione, configurare i valori seguenti:Parametro 1 (input): user.email Valore: "@contoso.com" Parametro 2 (output): user.email Parametro 3 (output se non esistono corrispondenze): user.userprincipalname |
| EndWith() | Restituisce un attributo o una costante se l'input termina con il valore specificato. In caso contrario, se non esistono corrispondenze, è possibile specificare un altro output. Ad esempio, è possibile scegliere che venga creata un'attestazione in cui il valore corrisponde all'ID dipendente dell'utente se termina con 000 e in caso contrario che venga restituito un attributo di estensione. Per eseguire questa funzione, configurare i valori seguenti:Parametro 1 (input): user.employeeid Valore: "000" Parametro 2 (output): user.employeeid Parametro 3 (output se non esistono corrispondenze): user.extensionattribute1 |
| StartWith() | Restituisce un attributo o una costante se l'input inizia con il valore specificato. In caso contrario, se non esistono corrispondenze, è possibile specificare un altro output. Ad esempio, è possibile scegliere che venga creata un'attestazione in cui il valore corrisponde all'ID dipendente dell'utente se il paese/area geografica inizia con US e in caso contrario che venga restituito un attributo di estensione. Per eseguire questa funzione, configurare i valori seguenti:Parametro 1 (input): user.country Valore: "US" Parametro 2 (output): user.employeeid Parametro 3 (output se non esistono corrispondenze): user.extensionattribute1 |
| Extract() - Dopo la corrispondenza | Restituisce la sottostringa dopo aver trovato una corrispondenza con il valore specificato. Ad esempio, se il valore di input è Finance_BSimon e il valore corrispondente è Finance_, allora l'output dell'attestazione è BSimon. |
| Extract() - Prima della corrispondenza | Restituisce la sottostringa finché non trova una corrispondenza con il valore specificato. Ad esempio, se il valore di input è BSimon_USe il valore corrispondente è _US, allora l'output dell'attestazione è BSimon. |
| Extract() - Tra corrispondenze | Restituisce la sottostringa finché non trova una corrispondenza con il valore specificato. Ad esempio, se il valore dell'input è Finance_BSimon_US, il primo valore corrispondente è Finance_ e il secondo valore corrispondente è _US, allora l'output dell'attestazione è BSimon. |
| ExtractAlpha() - Prefisso | Restituisce la parte alfabetica del prefisso della stringa. Ad esempio, se il valore dell'input è BSimon_123, restituisce BSimon. |
| ExtractAlpha() - Suffisso | Restituisce la parte alfabetica del suffisso della stringa. Ad esempio, se il valore dell'input è 123_Simon, restituisce Simon. |
| ExtractNumeric() - Prefisso | Restituisce la parte numerica del prefisso della stringa. Ad esempio, se il valore dell'input è 123_BSimon, restituisce 123. |
| ExtractNumeric() - Suffisso | Restituisce la parte numerica del suffisso della stringa. Ad esempio, se il valore dell'input è BSimon_123, restituisce 123. |
| IfEmpty() | Restituisce un attributo o una costante se l'input è Null o vuoto. Ad esempio, se si vuole restituire un attributo archiviato in un attributo di estensione se l'ID dipendente per un determinato utente è vuoto. Per eseguire questa funzione, configurare i valori seguenti: Parametro 1 (input): user.employeeid Parametro 2 (output): user.extensionattribute1 Parametro 3 (output se non esistono corrispondenze): user.employeeid |
| IfNotEmpty() | Restituisce un attributo o una costante se l'input è Null o vuoto. Ad esempio, se si vuole restituire un attributo archiviato in un attributo di estensione se l'ID dipendente per un determinato utente non è vuoto. Per eseguire questa funzione, configurare i valori seguenti: Parametro 1 (input): user.employeeid Parametro 2 (output): user.extensionattribute1 |
| Substring() - Lunghezza fissa | Estrae parti di un tipo di attestazione di stringa, a partire dal carattere in corrispondenza della posizione specificata, e restituisce il numero di caratteri specificato. SourceClaim: origine attestazione della trasformazione che deve essere eseguita. StartIndex: posizione del carattere iniziale in base zero di una sottostringa in questa istanza. Length : lunghezza in caratteri della sottostringa. Ad esempio: sourceClaim - PleaseExtractThisNow StartIndex - 6 Lunghezza - 11 Output: ExtractThis |
| Substring() - EndOfString | Estrae parti di un tipo di attestazione di stringa, a partire dal carattere in corrispondenza della posizione specificata, e restituisce la parte restante dell’attestazione dall’indice di inizio. SourceClaim: origine attestazione della trasformazione. StartIndex: posizione del carattere iniziale in base zero di una sottostringa in questa istanza. Ad esempio: sourceClaim - PleaseExtractThisNow StartIndex - 6 Output: ExtractThisNow |
| RegexReplace() | La trasformazione RegexReplace() accetta come parametri di input: - Parametro 1: un attributo utente come input regex - Opzione per considerare attendibile l'origine come multivalore - Criterio regex - Modello di sostituzione. Il modello di sostituzione può contenere un formato di testo statico insieme a un riferimento che punta ai gruppi di output regex e a più parametri di input. |
Se sono necessarie altre trasformazioni, inviare l'idea nel forum di commenti e suggerimenti in Microsoft Entra ID nella categoria di applicazioni SaaS.
Trasformazione delle attestazioni basate su regex
L'immagine seguente mostra un esempio del primo livello della trasformazione:
Nella tabella seguente vengono fornite informazioni sul primo livello di trasformazioni. Le azioni elencate nella tabella corrispondono alle etichette dell'immagine precedente. Selezionare Modifica per aprire il pannello di trasformazione delle attestazioni.
| Azione | Campo | Descrizione |
|---|---|---|
| 1 | Transformation |
Selezionare l'opzione RegexReplace() nelle opzioni Trasformazione per usare il metodo di trasformazione delle attestazioni basate su regex per la trasformazione delle attestazioni. |
| 2 | Parameter 1 |
Input per la trasformazione di un’espressione regolare. Ad esempio, user.mail che include l’indirizzo di posta elettronica dell’utente come admin@fabrikam.com. |
| 3 | Treat source as multivalued |
Alcuni attributi utente di input possono essere attributi utente multivalore. Se l'attributo utente selezionato supporta più valori e l'utente vuole usare più valori per la trasformazione, è necessario selezionare Considera origine come multivalore. Se questa opzione è selezionata, tutti i valori vengono usati per la corrispondenza regex. In caso contrario, viene usato solo il primo valore. |
| 4 | Regex pattern |
Espressione regolare valutata rispetto al valore dell'attributo utente selezionato come Parametro 1. Ad esempio, un'espressione regolare per estrarre l'alias utente dall'indirizzo di posta elettronica dell'utente viene rappresentata come (?'domain'^.*?)(?i)(\@fabrikam\.com)$. |
| 5 | Add additional parameter |
Per la trasformazione è possibile usare più attributi utente. I valori degli attributi verranno quindi uniti con l'output della trasformazione regex. Sono supportati fino a cinque parametri. |
| 6 | Replacement pattern |
Il modello di sostituzione è il modello di testo, che contiene segnaposto per il risultato regex. Tutti i nomi dei gruppi devono essere racchiusi tra parentesi graffe, ad esempio {group-name}. Si supponga che l'amministrazione voglia usare l'alias utente con un altro nome di dominio, ad esempio xyz.com, e unire il nome del paese con esso. In questo caso, il modello di sostituzione sarà {country}.{domain}@xyz.com, dove {country} è il valore del parametro di input e {domain} è l'output del gruppo risultante dalla valutazione dell'espressione regolare. In questo caso, il risultato previsto è US.swmal@xyz.com. |
L'immagine seguente mostra un esempio del secondo livello della trasformazione:
Nella tabella seguente vengono fornite informazioni sul secondo livello della trasformazione. Le azioni elencate nella tabella corrispondono alle etichette dell'immagine precedente.
| Azione | Campo | Descrizione |
|---|---|---|
| 1 | Transformation |
Le trasformazioni delle attestazioni basate su regex non sono limitate alla prima trasformazione e possono essere usate anche come trasformazione di secondo livello. È possibile usare qualsiasi altro metodo di trasformazione come prima trasformazione. |
| 2 | Parameter 1 |
Se RegexReplace() è selezionato come trasformazione di secondo livello, l'output della trasformazione di primo livello viene usato come input per la trasformazione di secondo livello. Per applicare la trasformazione,è necessario che l'espressione regex di secondo livello corrisponda all'output della prima trasformazione. |
| 3 | Regex pattern |
Il criterio regex rappresenta l'espressione regolare per la trasformazione di secondo livello. |
| 4 | Parameter input |
Input degli attributi utente per le trasformazioni di secondo livello. |
| 5 | Parameter input |
Gli amministratori possono eliminare il parametro di input selezionato se non è più necessario. |
| 6 | Replacement pattern |
Il modello di sostituzione è il modello di testo, che contiene segnaposto per il nome del gruppo di risultati regex, il nome del gruppo di parametri di input e il valore di testo statico. Tutti i nomi di gruppo devono essere racchiusi tra parentesi graffe, ad esempio {group-name}. Si supponga che l'amministrazione voglia usare l'alias utente con un altro nome di dominio, ad esempio xyz.com, e unire il nome del paese con esso. In questo caso, il modello di sostituzione sarà {country}.{domain}@xyz.com, dove {country} è il valore del parametro di input e {domain} è l'output del gruppo risultante dalla valutazione dell'espressione regolare. In questo caso, il risultato previsto è US.swmal@xyz.com. |
| 7 | Test transformation |
La trasformazione RegexReplace() viene valutata solo se il valore dell'attributo utente selezionato per il parametro 1 corrisponde all'espressione regolare fornita nella casella di testo Modello regex. Se i valori non corrispondono, al token viene aggiunto il valore predefinito dell'attestazione. Per convalidare l'espressione regolare rispetto al valore del parametro di input, è possibile usare un'esperienza di test all'interno del pannello della trasformazione. Questa esperienza di test usa solo valori fittizi. Quando si usano più parametri di input, il nome del parametro viene aggiunto al risultato del test anziché al valore effettivo. Per accedere alla sezione test, selezionare Testa trasformazione. |
L'immagine seguente mostra un esempio di test delle trasformazioni:
Nella tabella seguente vengono fornite informazioni sul test delle trasformazioni. Le azioni elencate nella tabella corrispondono alle etichette dell'immagine precedente.
| Azione | Campo | Descrizione |
|---|---|---|
| 1 | Test transformation |
Selezionare il pulsante Chiudi o (X) per nascondere la sezione Test ed eseguire di nuovo il rendering del pulsante Testa trasformazione nel pannello. |
| 2 | Test regex input |
Accetta l'input usato per la valutazione del test dell'espressione regolare. Se la trasformazione delle attestazioni basate su regex è configurata come trasformazione di secondo livello, fornire un valore che rappresenti l'output previsto della prima trasformazione. |
| 3 | Run test |
Dopo aver specificato l'input regex di test e aver configurato Modello regex, Modello di sostituzione e Parametri di input, è possibile valutare l'espressione selezionando Esegui test. |
| 4 | Test transformation result |
Se la valutazione ha esito positivo, viene eseguito il rendering dell’output della trasformazione di test rispetto all’etichetta Testa risultato della trasformazione. |
| 5 | Remove transformation |
La trasformazione di secondo livello può essere rimossa selezionando Rimuovi trasformazione. |
| 6 | Specify output if no match |
Quando un valore di input regex viene configurato in base al parametro 1 che non corrisponde all'espressione regolare, la trasformazione viene ignorata. In questi casi, è possibile configurare l'attributo utente alternativo, che può essere aggiunto al token per l'attestazione selezionando Specifica output se non esiste alcuna corrispondenza. |
| 7 | Parameter 3 |
Se è necessario restituire un attributo utente alternativo quando non esiste alcuna corrispondenza e l’opzione Specificare l'output se non è selezionata alcuna corrispondenza è selezionata, è possibile selezionare un attributo utente alternativo tramite l'elenco a discesa. Questo elenco a discesa è disponibile nel parametro 3 (output in caso di non corrispondenza). |
| 8 | Summary |
Nella parte inferiore del pannello viene visualizzato un riepilogo completo del formato che spiega il significato della trasformazione in testo semplice. |
| 9 | Add |
Dopo aver verificato le impostazioni di configurazione della trasformazione, è possibile salvarle in un criterio delle attestazioni selezionando Aggiungi. Selezionare Salva nel pannello Gestisci attestazione per salvare le modifiche. |
La trasformazione RegexReplace() è disponibile anche per le trasformazioni delle attestazioni di gruppo.
Convalide della trasformazione
Un messaggio fornisce altre informazioni quando si verificano le condizioni seguenti dopo aver selezionato Aggiungi o Esegui test:
- Sono stati usati parametri di input con attributi utente duplicati.
- Sono stati trovati parametri di input inutilizzati. L’utilizzo dei parametri di input definiti deve essere indicato nel testo modello di sostituzione.
- L'input regex di test fornito non corrisponde all'espressione regolare fornita.
- Non vengono trovate origini per i gruppi nel modello di sostituzione.
Creare attestazioni in base a condizioni
È possibile specificare l'origine di un'attestazione in base al tipo di utente e al gruppo a cui appartiene.
Il tipo di utente può essere:
- Qualsiasi: tutti gli utenti possono accedere all’applicazione.
- Membri: membro nativo del tenant.
- Tutti gli utenti guest: l'utente è stato spostato da un'organizzazione esterna con o senza MICROSOFT Entra ID.
- Utenti guest di Microsoft Entra: l’utente guest appartiene a un'altra organizzazione che usa Microsoft Entra ID.
- Guest esterni: l’utente guest appartiene a un'organizzazione esterna che non usa Microsoft Entra ID.
Uno scenario in cui questo tipo di utente è utile è il caso in cui l’origine di un'attestazione è diversa per un utente guest e per un dipendente che accedono a un'applicazione. È possibile specificare che se l'utente è un dipendente, ottenere nameID da user.email. Se l'utente è un guest, nameID proviene da user.extensionattribute1.
Per aggiungere una condizione per l'attestazione:
- In Gestisci l'attestazione espandere Condizioni dell'attestazione.
- Selezionare il tipo di utente.
- Selezionare il gruppo o i gruppi a cui l'utente deve appartenere. È possibile selezionare fino a 50 gruppi univoci tra tutte le attestazioni per una determinata applicazione.
- Selezionare l'opzione di Origine da cui l'attestazione recupererà il valore. È possibile selezionare un attributo utente nell'elenco a discesa degli attributi di origine oppure applicare una trasformazione all'attributo utente prima di crearlo come attestazione.
L'ordine in cui si aggiungono le condizioni è importante. Microsoft Entra valuta prima tutte le condizioni con l’origine Attribute e quindi valuta tutte le condizioni con l'origine Transformation per decidere quale valore generare nell'attestazione. Microsoft Entra ID valuta le condizioni con la stessa origine dall'alto verso il basso. L'attestazione genera l'ultimo valore che corrisponde all'espressione nell'attestazione. Le trasformazioni, come IsNotEmpty e Contains, fungono da restrizioni.
Britta Simon, ad esempio, è un utente guest nel tenant di Contoso. Britta appartiene a un'altra organizzazione che usa anche Microsoft Entra ID. Data la configurazione seguente per l'applicazione Fabrikam, quando Britta tenta di accedere a Fabrikam, Microsoft Identity Platform valuta le condizioni.
Prima di tutto, Microsoft Identity Platform verifica se il tipo di utente di Britta è Tutti gli utenti guest. Poiché il tipo è Tutti gli utenti guest, Microsoft Identity Platform assegna l'origine per l'attestazione a user.extensionattribute1. Quindi, Microsoft Identity Platform verifica se il tipo di utente di Britta è Utenti guest di Microsoft Entra. Poiché il tipo è Tutti gli utenti guest, Microsoft Identity Platform assegna l'origine per l'attestazione a user.mail. Infine, l'attestazione viene creata con il valore user.mail per Britta.
Come altro esempio, considerare quando Britta Simon tenta di accedere usando la configurazione seguente. Microsoft Entra valuta innanzitutto tutte le condizioni con l'origine Attribute. L'origine dell'attestazione è user.mail quando il tipo di utente di Britta è microsoft Entra guest. Successivamente, Microsoft Entra ID valuta le trasformazioni. Poiché Britta è un guest, user.extensionattribute1 è la nuova origine per l'attestazione. Poiché Britta è in microsoft Entra guest, user.othermail è la nuova origine per questa attestazione. Infine, l'attestazione viene creata con il valore user.othermail per Britta.
Come esempio finale, considerare cosa accade se Britta non ha configurato user.othermail o è vuoto. L'attestazione torna a user.extensionattribute1 ignorare la voce della condizione in entrambi i casi.
Considerazioni relative alla sicurezza
Le applicazioni che ricevono token si basano su valori attestazioni che non possono essere manomessi. Quando si modifica il contenuto del token tramite la personalizzazione delle attestazioni, questi presupposti potrebbero non essere più corretti. Le applicazioni devono riconoscere in modo esplicito che i token sono stati modificati per proteggersi dalle personalizzazioni create da utenti malintenzionati. Protezione da personalizzazioni non appropriate in uno dei modi seguenti:
- Configurare una chiave di firma personalizzata
- aggiornare il manifesto dell'applicazione per accettare attestazioni mappate.
Senza questo, Microsoft Entra ID restituisce un codice di errore AADSTS50146.
Configurare una chiave di firma personalizzata
Per le app multi-tenant, deve essere usata una chiave di firma personalizzata. Non impostare acceptMappedClaims nel manifesto dell'app. Quando si configura un'app nella portale di Azure, si ottiene un oggetto di registrazione dell'app e un'entità servizio nel tenant. L'app usa la chiave di accesso globale di Azure, che non può essere usata per personalizzare le attestazioni nei token. Per ottenere attestazioni personalizzate nei token, creare una chiave di accesso personalizzata da un certificato e aggiungerla all'entità servizio. Per eseguire i test, è possibile usare un certificato autofirmato. Dopo aver configurato la chiave di firma personalizzata, il codice dell'applicazione deve convalidare la chiave di firma del token.
Aggiungere le informazioni seguenti all'entità servizio:
- Chiave privata (come credenziale della chiave)
- Password (credenziali password)
- Chiave pubblica (come credenziale chiave)
Estrarre la chiave pubblica e privata con codifica Base 64 dall'esportazione di file PFX del certificato. Assicurarsi che per l'oggetto keyId keyCredential usato per "Sign" corrisponda a keyId di .passwordCredential È possibile generare customkeyIdentifier recuperando l'hash dell'identificazione personale del certificato.
Richiedi
Nota
Disabilitare prima di tutto la configurazione del blocco dell'entità servizio nelle app appena create dal pannello registrazioni dell'app dell'interfaccia di amministrazione di Microsoft Entra prima di tentare di eseguire una patch nell'entità servizio, con conseguente richiesta non valida 400.
Nell'esempio seguente viene illustrato il formato della richiesta HTTP PATCH per aggiungere una chiave di firma personalizzata a un'entità servizio. Il valore "key" nella keyCredentials proprietà viene abbreviato per la leggibilità. Il valore è codificato in base 64. Per la chiave privata, l'utilizzo della proprietà è Sign. Per la chiave pubblica, l'utilizzo della proprietà è Verify.
PATCH https://graph.microsoft.com/v1.0/servicePrincipals/aaaaaaaa-bbbb-cccc-1111-222222222222
Content-type: servicePrincipals/json
Authorization: Bearer {token}
{
"keyCredentials":[
{
"customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
"endDateTime": "2021-04-22T22:10:13Z",
"keyId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
"startDateTime": "2020-04-22T21:50:13Z",
"type": "X509CertAndPassword",
"usage": "Sign",
"key":"cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
"displayName": "CN=contoso"
},
{
"customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
"endDateTime": "2021-04-22T22:10:13Z",
"keyId": "bbbbbbbb-1c1c-2d2d-3e3e-444444444444",
"startDateTime": "2020-04-22T21:50:13Z",
"type": "AsymmetricX509Cert",
"usage": "Verify",
"key": "cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
"displayName": "CN=contoso"
}
],
"passwordCredentials": [
{
"customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
"keyId": "cccccccc-2d2d-3e3e-4f4f-555555555555",
"endDateTime": "2022-01-27T19:40:33Z",
"startDateTime": "2020-04-20T19:40:33Z",
"secretText": "mypassword"
}
]
}
Configurare una chiave di firma personalizzata con PowerShell
Usare PowerShell per creare un'istanza di un'applicazione client pubblica MSAL e usare il flusso di concessione del codice di autorizzazione per ottenere un token di accesso con autorizzazione delegata per Microsoft Graph. Usare il token di accesso per chiamare Microsoft Graph e configurare una chiave di firma personalizzata per l'entità servizio. Dopo aver configurato la chiave di firma personalizzata, il codice dell'applicazione deve convalidare la chiave di firma del token.
Per eseguire questo script, è necessario:
- ID oggetto dell'entità servizio dell'applicazione, disponibile nel pannello Panoramica della voce dell'applicazione in Applicazioni aziendali nel portale di Azure.
- Registrazione dell'app per accedere a un utente e ottenere un token di accesso per chiamare Microsoft Graph. Ottenere l'ID applicazione (client) di questa app nel pannello Panoramica della voce dell'applicazione in Registrazioni app nel portale di Azure. La registrazione dell'app deve avere la configurazione seguente:
- URI di reindirizzamento "http://localhost" elencato nella configurazione della piattaforma applicazioni per dispositivi mobili e desktop .
- Nelle autorizzazioni API, le autorizzazioni delegate di Microsoft Graph Application.ReadWrite.All e User.Read (assicurarsi di concedere il consenso amministratore a queste autorizzazioni).
- Un utente che accede per ottenere il token di accesso di Microsoft Graph. L'utente deve essere uno dei seguenti ruoli amministrativi di Microsoft Entra (necessario per aggiornare l'entità servizio):
- Amministratore di applicazioni cloud
- Amministratore di applicazioni
- Certificato da configurare come chiave di firma personalizzata per l'applicazione. È possibile creare un certificato autofirmato o ottenerlo dall'autorità di certificazione attendibile. Nello script vengono usati i componenti del certificato seguenti:
- chiave pubblica (in genere un file di .cer )
- chiave privata in formato PKCS#12 (nel file pfx )
- password per la chiave privata (file pfx )
Importante
La chiave privata deve essere in formato PKCS#12 perché Microsoft Entra ID non supporta altri tipi di formato. L'uso del formato errato può generare l'errore "Certificato non valido: Il valore della chiave non è valido" quando si usa Microsoft Graph per APPLICARE PATCH all'entità servizio con un contenente keyCredentials le informazioni sul certificato.
##########################################################
# Replace the variables below with the appropriate values
$fqdn="yourDomainHere" # This is used for the 'issued to' and 'issued by' field of the certificate
$pwd="password" # password for exporting the certificate private key
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Replace with your Tenant ID
$appObjId = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" # Replace with the Object ID of the App Registration
##########################################################
# Create a self-signed cert
$cert = New-SelfSignedCertificate -certstorelocation cert:\currentuser\my -DnsName $fqdn
$pwdSecure = ConvertTo-SecureString -String $pwd -Force -AsPlainText
$path = 'cert:\currentuser\my\' + $cert.Thumbprint
$location="C:\\temp" # path to folder where both the pfx and cer file will be written to
$cerFile = $location + "\\" + $fqdn + ".cer"
$pfxFile = $location + "\\" + $fqdn + ".pfx"
# Export the public and private keys
Export-PfxCertificate -cert $path -FilePath $pfxFile -Password $pwdSecure
Export-Certificate -cert $path -FilePath $cerFile
$pfxpath = $pfxFile # path to pfx file
$cerpath = $cerFile # path to cer file
$password = $pwd # password for the pfx file
# Check PowerShell version (minimum 5.1) (.Net) or PowerShell Core (.Net Core) and read the certificate file accordingly
if ($PSVersionTable.PSVersion.Major -gt 5)
{
$core = $true
}
else
{
$core = $false
}
# this is for PowerShell Core
$Secure_String_Pwd = ConvertTo-SecureString $password -AsPlainText -Force
# reading certificate files and creating Certificate Object
if ($core)
{
$pfx_cert = get-content $pfxpath -AsByteStream -Raw
$cer_cert = get-content $cerpath -AsByteStream -Raw
$cert = Get-PfxCertificate -FilePath $pfxpath -Password $Secure_String_Pwd
}
else
{
$pfx_cert = get-content $pfxpath -Encoding Byte
$cer_cert = get-content $cerpath -Encoding Byte
# calling Get-PfxCertificate in PowerShell 5.1 prompts for password - using alternative method
$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfxpath, $password)
}
# base 64 encode the private key and public key
$base64pfx = [System.Convert]::ToBase64String($pfx_cert)
$base64cer = [System.Convert]::ToBase64String($cer_cert)
# getting id for the keyCredential object
$guid1 = New-Guid
$guid2 = New-Guid
# get the custom key identifier from the certificate thumbprint:
$hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
$hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($cert.Thumbprint))
$customKeyIdentifier = [System.Convert]::ToBase64String($hash)
# get end date and start date for our keycredentials
$endDateTime = ($cert.NotAfter).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
$startDateTime = ($cert.NotBefore).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
# building our json payload
$object = [ordered]@{
keyCredentials = @(
[ordered]@{
customKeyIdentifier = $customKeyIdentifier
endDateTime = $endDateTime
keyId = $guid1
startDateTime = $startDateTime
type = "AsymmetricX509Cert"
usage = "Sign"
key = $base64pfx
displayName = "CN=$fqdn"
},
[ordered]@{
customKeyIdentifier = $customKeyIdentifier
endDateTime = $endDateTime
keyId = $guid2
startDateTime = $startDateTime
type = "AsymmetricX509Cert"
usage = "Verify"
key = $base64cer
displayName = "CN=$fqdn"
}
)
passwordCredentials = @(
[ordered]@{
customKeyIdentifier = $customKeyIdentifier
displayName = "CN=$fqdn"
keyId = $guid1
endDateTime = $endDateTime
startDateTime = $startDateTime
secretText = $password
hint = $null
}
)
}
Connect-MgGraph -tenantId $tenantId -Scopes Application.ReadWrite.All
$graphuri = "https://graph.microsoft.com/v1.0/applications/$appObjId"
Invoke-MgGraphRequest -Method PATCH -Uri $graphuri -Body $object
$json = $object | ConvertTo-Json -Depth 99
Write-Host "JSON Payload:"
Write-Output $json
Convalidare la chiave di firma del token
Per le app con mapping delle attestazioni abilitato è necessario convalidare le chiavi di firma del token aggiungendo appid={client_id} alle richieste di metadati OpenID Connect. Nell'esempio seguente viene illustrato il formato del documento di metadati OpenID Connect da usare:
https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}
Aggiornare il manifesto dell'applicazione
Per le app a tenant singolo, è possibile impostare la acceptMappedClaims proprietà su true nel manifesto dell'applicazione. Come documentato nel apiApplication tipo di risorsa. L'impostazione della proprietà consente a un'applicazione di usare il mapping delle attestazioni senza specificare una chiave di firma personalizzata.
Avviso
Non impostare la proprietà acceptMappedClaims su true per le app multi-tenant, che possono consentire agli attori malintenzionati di creare criteri di mapping delle attestazioni per l'app.
Il gruppo di destinatari del token richiesto deve usare un nome di dominio verificato del tenant di Microsoft Entra, il che significa che è necessario impostare Application ID URI (rappresentato da identifierUris nel manifesto dell'applicazione) ad esempio https://contoso.com/my-api su o (semplicemente usando il nome del tenant predefinito). https://contoso.onmicrosoft.com/my-api
Se non si usa un dominio verificato, Microsoft Entra ID restituisce un AADSTS501461 codice di errore con il messaggio "_AcceptMappedClaims è supportato solo per un gruppo di destinatari del token corrispondente al GUID dell'applicazione o a un gruppo di destinatari all'interno dei domini verificati del tenant. Modificare l'identificatore della risorsa o usare una chiave di firma specifica dell'applicazione."
Opzioni avanzate per le attestazioni
Configurare le opzioni avanzate delle attestazioni per le applicazioni OIDC per esporre la stessa attestazione dei token SAML. Per le applicazioni che intendono usare la stessa attestazione sia per i token di risposta SAML2.0 che per i token di risposta OIDC.
Configurare le opzioni avanzate delle attestazioni selezionando la casella in Opzioni attestazioni avanzate nel pannello Gestisci attestazioni .