Configurare un provider di attestazioni personalizzato per un evento di rilascio di token

Questo articolo descrive come configurare un provider di attestazioni personalizzato per un evento di avvio del rilascio di token. Usando un'API REST di Funzioni di Azure esistente, si registrerà un'estensione di autenticazione personalizzata e si aggiungeranno attributi da analizzare dall'API REST. Per testare l'estensione di autenticazione personalizzata, si registrerà un'applicazione OpenID di esempio Connessione per ottenere un token e visualizzare le attestazioni.

Prerequisiti

  • Una sottoscrizione di Azure con la possibilità di creare Funzioni di Azure. Se non si ha un account Azure esistente, iscriversi per ottenere una versione di valutazione gratuita o usare i vantaggi della sottoscrizione di Visual Studio quando si crea un account.
  • Un'app per le funzioni di Azure con una funzione trigger HTTP configurata per un evento di avvio del rilascio di token. Se non è disponibile, seguire la procedura descritta in Creare una funzione trigger HTTP per l'avvio dell'emissione di token.
  • Conoscenza di base dei concetti trattati in Panoramica delle estensioni di autenticazione personalizzate.
  • Tenant di Microsoft Entra ID. È possibile usare un tenant del cliente o della forza lavoro per questa guida pratica.
    • Per i tenant esterni, usare un flusso utente di iscrizione e accesso.

Passaggio 1: Registrare un'estensione di autenticazione personalizzata

A questo punto si configurerà un'estensione di autenticazione personalizzata, che verrà usata da Microsoft Entra ID per chiamare la funzione di Azure. L'estensione di autenticazione personalizzata contiene informazioni sull'endpoint dell'API REST, sulle attestazioni analizzate dall'API REST e su come eseguire l'autenticazione all'API REST. Seguire questa procedura per registrare un'estensione di autenticazione personalizzata nell'app per le funzioni di Azure.

Nota

È possibile avere un massimo di 100 criteri di estensione personalizzati.

Registrare un'estensione di autenticazione personalizzata

  1. Accedere al portale di Azure come almeno un Amministrazione istrator dell'applicazione e l'autenticazione Amministrazione istrator.
  2. Cercare e selezionare Microsoft Entra ID e selezionare Applicazioni aziendali.
  3. Selezionare Estensioni di autenticazione personalizzate e quindi selezionare Crea un'estensione personalizzata.
  4. In Informazioni di base selezionare il tipo di evento TokenIssuanceStart e selezionare Avanti.
  5. In Configurazione endpoint immettere le proprietà seguenti:
    • Nome : nome per l'estensione di autenticazione personalizzata. Ad esempio, evento di rilascio del token.
    • URL di destinazione: dell'URL {Function_Url} della funzione di Azure. Passare alla pagina Panoramica dell'app per le funzioni di Azure e quindi selezionare la funzione creata. Nella pagina Panoramica della funzione selezionare Recupera URL funzione e usare l'icona di copia per copiare l'URL.
    • Descrizione : una descrizione per le estensioni di autenticazione personalizzate.
  6. Selezionare Avanti.
  7. In Autenticazione API selezionare l'opzione Crea nuova registrazione app per creare una registrazione dell'app che rappresenta l'app per le funzioni.
  8. Assegnare all'app un nome, ad esempio Funzioni di Azure'API degli eventi di autenticazione.
  9. Selezionare Avanti.
  10. In Attestazioni immettere gli attributi previsti per l'analisi dell'estensione di autenticazione personalizzata dall'API REST e che verranno uniti al token. Aggiungere le attestazioni seguenti:
    • dateOfBirth
    • customRoles
    • apiVersion
    • correlationId
  11. Selezionare Avanti, quindi Crea, che registra l'estensione di autenticazione personalizzata e la registrazione dell'applicazione associata.
  12. Prendere nota dell'ID app in Autenticazione API, necessaria per impostare le variabili di ambiente nell'app per le funzioni di Azure.

Dopo aver creato l'estensione di autenticazione personalizzata, è necessario concedere le autorizzazioni all'API. L'estensione di autenticazione personalizzata usa client_credentials per eseguire l'autenticazione all'app per le funzioni di Azure usando l'autorizzazione Receive custom authentication extension HTTP requests .

  1. Aprire la pagina Panoramica della nuova estensione di autenticazione personalizzata. Prendere nota dell'ID app in Autenticazione API, perché sarà necessario quando si aggiunge un provider di identità.

  2. In Autenticazione API selezionare Concedi autorizzazione.

  3. Viene aperta una nuova finestra e, dopo l'accesso, vengono richieste le autorizzazioni per ricevere richieste HTTP dell'estensione di autenticazione personalizzate. In questo modo l'estensione di autenticazione personalizzata può eseguire l'autenticazione all'API. Selezionare Accetto.

    Screenshot che mostra come concedere il consenso amministratore.

Passaggio 2: Configurare un'app openID Connessione per ricevere token arricchiti

Per ottenere un token e testare l'estensione di autenticazione personalizzata, è possibile usare l'app https://jwt.ms . Si tratta di un'applicazione Web di proprietà di Microsoft che visualizza il contenuto decodificato di un token (il contenuto del token non lascia mai il browser).

2.1 Registrare un'applicazione Web di test

Seguire questa procedura per registrare l'applicazione Web jwt.ms :

  1. Nella home page del portale di Azure selezionare Microsoft Entra ID.

  2. Selezionare Registrazioni app>Nuova registrazione.

  3. Immettere un nome per l'applicazione. Ad esempio, Applicazione test personale.

  4. In Tipi di account supportati selezionare Account solo in questa directory organizzativa.

  5. Nell'elenco a discesa Selezionare una piattaforma in URI di reindirizzamento selezionare Web e quindi immettere https://jwt.ms nella casella di testo URL.

  6. Selezionare Registra per completare la registrazione dell'app.

    Screenshot che mostra come selezionare il tipo di account supportato e l'URI di reindirizzamento.

  7. Nella pagina Panoramica della registrazione dell'app copiare l'ID applicazione (client). L'ID app viene definito come {App_to_enrich_ID} nei passaggi successivi. In Microsoft Graph viene fatto riferimento alla proprietà appId .

    Screenshot che mostra come copiare l'ID applicazione.

2.2 Abilitare il flusso implicito

L'applicazione di test jwt.ms usa il flusso implicito. Abilitare il flusso implicito nella registrazione dell'applicazione Test personale:

  1. In Gestisci selezionare Autenticazione.
  2. In Concessione implicita e flussi ibridi selezionare la casella di controllo Token ID (usati per i flussi impliciti e ibridi).
  3. Seleziona Salva.

2.3 Abilitare l'app per i criteri di mapping delle attestazioni

Un criterio di mapping delle attestazioni viene usato per selezionare gli attributi restituiti dall'estensione di autenticazione personalizzata di cui viene eseguito il mapping nel token. Per consentire l'aumento dei token, è necessario abilitare in modo esplicito la registrazione dell'applicazione per accettare attestazioni mappate:

  1. Nella registrazione dell'applicazione Test personale, in Gestisci selezionare Manifesto.
  2. Nel manifesto individuare l'attributo acceptMappedClaims e impostare il valore su true.
  3. Imposta accessTokenAcceptedVersion su 2.
  4. Seleziona Salva per salvare le modifiche.

Il frammento di codice JSON seguente illustra come configurare queste proprietà.

{
	"id": "22222222-0000-0000-0000-000000000000",
	"acceptMappedClaims": true,
	"accessTokenAcceptedVersion": 2,  
    ...
}

Avviso

Non impostare la acceptMappedClaims proprietà su true per le app multi-tenant, che possono consentire agli attori malintenzionati di creare criteri di mapping delle attestazioni per l'app. Configurare invece una chiave di firma personalizzata.

Continuare con il passaggio successivo, Assegnare un provider di attestazioni personalizzato all'app.

Passaggio 3: Assegnare un provider di attestazioni personalizzato all'app

Affinché i token vengano emessi con attestazioni in ingresso dall'estensione di autenticazione personalizzata, è necessario assegnare un provider di attestazioni personalizzato all'applicazione. Questo è basato sul gruppo di destinatari del token, quindi il provider deve essere assegnato all'applicazione client per ricevere attestazioni in un token ID e all'applicazione di risorse per ricevere attestazioni in un token di accesso. Il provider di attestazioni personalizzate si basa sull'estensione di autenticazione personalizzata configurata con il listener dell'evento di avvio del rilascio del token. È possibile scegliere se tutti o un sottoinsieme di attestazioni dal provider di attestazioni personalizzato vengono mappati al token.

Nota

È possibile creare solo 250 assegnazioni univoche tra applicazioni ed estensioni personalizzate. Se si vuole applicare la stessa chiamata di estensione personalizzata a più app, è consigliabile usare l'API Microsoft Graph authenticationEventListeners per creare listener per più applicazioni. Questa operazione non è supportata nella portale di Azure.

Seguire questa procedura per connettere l'applicazione My Test con l'estensione di autenticazione personalizzata:

Per assegnare l'estensione di autenticazione personalizzata come origine del provider di attestazioni personalizzato;

  1. Nella home page del portale di Azure selezionare Microsoft Entra ID.

  2. Selezionare Applicazioni aziendali, quindi in Gestisci selezionare Tutte le applicazioni. Trovare e selezionare My Test application (Applicazione test personale) dall'elenco.

  3. Nella pagina Panoramica dell'applicazione Test personale passare a Gestisci e selezionare Single Sign-On.

  4. In Attributi e attestazioni selezionare Modifica.

    Screenshot che mostra come configurare le attestazioni dell'app.

  5. Espandere il menu Impostazioni avanzate.

  6. Accanto a Provider di attestazioni personalizzate selezionare Configura.

  7. Espandere la casella di riepilogo a discesa Provider di attestazioni personalizzate e selezionare l'evento di rilascio del token creato in precedenza.

  8. Seleziona Salva.

Assegnare quindi gli attributi del provider di attestazioni personalizzate, che devono essere rilasciati nel token come attestazioni:

  1. Selezionare Aggiungi nuova attestazione per aggiungere una nuova attestazione. Specificare un nome per l'attestazione da rilasciare, ad esempio dateOfBirth.

  2. In Origine selezionare Attributo e scegliere customClaimsProvider.dateOfBirth nella casella a discesa Attributo di origine.

    Screenshot che mostra come aggiungere un mapping di attestazioni all'app.

  3. Seleziona Salva.

  4. Ripetere questo processo per aggiungere gli attributi customClaimsProvider.customRoles, customClaimsProvider.apiVersion e customClaimsProvider.correlationId e il nome corrispondente. È consigliabile associare il nome dell'attestazione al nome dell'attributo.

Passaggio 4: Proteggere la funzione di Azure

L'estensione di autenticazione personalizzata di Microsoft Entra usa il flusso del server per ottenere un token di accesso inviato nell'intestazione HTTP Authorization alla funzione di Azure. Quando si pubblica la funzione in Azure, in particolare in un ambiente di produzione, è necessario convalidare il token inviato nell'intestazione dell'autorizzazione.

Per proteggere la funzione di Azure, seguire questa procedura per integrare l'autenticazione di Microsoft Entra per convalidare i token in ingresso con la registrazione dell'applicazione API degli eventi di autenticazione Funzioni di Azure. Scegliere una delle schede seguenti in base al tipo di tenant.

Nota

Se l'app per le funzioni di Azure è ospitata in un tenant di Azure diverso rispetto al tenant in cui è registrata l'estensione di autenticazione personalizzata, scegliere la scheda Apri ID Connessione.

4.1 Uso del provider di identità Microsoft Entra

Usare la procedura seguente per aggiungere Microsoft Entra come provider di identità all'app per le funzioni di Azure.

  1. Nella portale di Azure trovare e selezionare l'app per le funzioni pubblicata in precedenza.

  2. In Impostazioni selezionare Autenticazione.

  3. Selezionare Aggiungi provider di identità.

  4. Selezionare Microsoft come provider di identità.

  5. Selezionare Workforce come tipo di tenant.

  6. In Registrazione app selezionare Selezionare una registrazione dell'app esistente in questa directory per il tipo di registrazione dell'app e selezionare la registrazione dell'app per gli eventi di autenticazione Funzioni di Azure creata in precedenza durante la registrazione del provider di attestazioni personalizzate.

  7. Immettere l'URL dell'autorità di certificazione seguente, https://login.microsoftonline.com/{tenantId}/v2.0, dove {tenantId} è l'ID tenant del tenant della forza lavoro.

  8. In Richieste non autenticate selezionare HTTP 401 Non autorizzato come provider di identità.

  9. Deselezionare l'opzione Archivio token.

  10. Selezionare Aggiungi per aggiungere l'autenticazione alla funzione di Azure.

    Screenshot che mostra come aggiungere l'autenticazione all'app per le funzioni in un tenant della forza lavoro.

4.2 Uso di OpenID Connessione provider di identità

Se è stato configurato il provider di identità Microsoft, ignorare questo passaggio. In caso contrario, se la funzione di Azure è ospitata in un tenant diverso rispetto al tenant in cui è registrata l'estensione di autenticazione personalizzata, seguire questa procedura per proteggere la funzione:

Creare un segreto client

  1. Nella home page del portale di Azure selezionare Microsoft Entra ID> Registrazioni app.
  2. Selezionare la registrazione dell'app per le API degli eventi di autenticazione Funzioni di Azure creata in precedenza.
  3. Selezionare Certificati e segreti Segreti>>client Nuovo segreto client.
  4. Selezionare una scadenza per il segreto o specificare una durata personalizzata, aggiungere una descrizione e selezionare Aggiungi.
  5. Registrare il valore del segreto da usare nel codice dell'applicazione client. Questo valore del segreto non viene mai più visualizzato dopo aver lasciato questa pagina.

Aggiungere il provider di identità OpenID Connessione all'app per le funzioni di Azure.

  1. Trovare e selezionare l'app per le funzioni pubblicata in precedenza.

  2. In Impostazioni selezionare Autenticazione.

  3. Selezionare Aggiungi provider di identità.

  4. Selezionare OpenID Connessione come provider di identità.

  5. Specificare un nome, ad esempio Contoso Microsoft Entra ID.

  6. Nella voce Metadati immettere l'URL seguente per l'URL del documento. Sostituire con l'ID {tenantId} tenant di Microsoft Entra.

    https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
    
  7. In Registrazione app immettere l'ID applicazione (ID client) della registrazione dell'app per le API degli eventi di autenticazione Funzioni di Azure creata in precedenza.

  8. Tornare alla funzione di Azure, nella registrazione dell'app, immettere il segreto client.

  9. Deselezionare l'opzione Archivio token.

  10. Selezionare Aggiungi per aggiungere il provider di identità OpenID Connessione.

Passaggio 5: Testare l'applicazione

Per testare il provider di attestazioni personalizzate, seguire questa procedura:

  1. Aprire un nuovo browser privato e passare e accedere tramite l'URL seguente.

    https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
    
  2. Sostituire {tenantId} con l'ID tenant, il nome del tenant o uno dei nomi di dominio verificati. Ad esempio: contoso.onmicrosoft.com.

  3. Sostituire {App_to_enrich_ID} con l'ID client dell'applicazione My Test.

  4. Dopo l'accesso, verrà visualizzato il token decodificato all'indirizzo https://jwt.ms. Verificare che le attestazioni della funzione di Azure vengano presentate nel token decodificato, dateOfBirthad esempio .

Vedi anche