Proteggere l'API usata da un connettore API nei flussi utente di iscrizione self-service di Microsoft Entra per ID esterno

Si applica a: Tenant della forza lavoro Tenant esterni (altre informazioni)

Quando si integra un'API REST all'interno di un flusso utente di iscrizione self-service di Microsoft Entra per ID esterno, è necessario proteggere l'endpoint dell'API REST con l'autenticazione. L'autenticazione dell'API REST garantisce che solo i servizi con credenziali appropriate, ad esempio Microsoft Entra ID, possano effettuare chiamate all'endpoint. Questo articolo illustra come proteggere l'API REST.

Prerequisiti

Completare la procedura descritta nella guida Procedura dettagliata: aggiungere un connettore API a un flusso utente di iscrizione.

È possibile proteggere l'endpoint API usando l'autenticazione HTTP di base o l'autenticazione con certificato client HTTPS. In entrambi i casi, specificare le credenziali usate da Microsoft Entra ID per chiamare l'endpoint API. Quindi, l'endpoint API controlla le credenziali ed esegue decisioni di autorizzazione.

Autenticazione HTTP di base

Suggerimento

I passaggi descritti in questo articolo possono variare leggermente in base al portale di partenza.

L'autenticazione HTTP di base è definita in RFC 2617. L'autenticazione di base funziona come segue: Microsoft Entra ID invia una richiesta HTTP con le credenziali client (username e password) nell'intestazione Authorization. Le credenziali vengono formattate come stringa con codifica base64 username:password. L'API è quindi responsabile del controllo di questi valori per eseguire altre decisioni di autorizzazione.

Per configurare un connettore API con l'autenticazione di base HTTP, seguire questa procedura:

1. Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Amministratore utenti.
2. Andare a Identità>Identità esterne>Informazioni generali.
3. Selezionare Tutti i connettori API, quindi selezionare il connettore API da configurare.
4. Per Tipo di autenticazione, selezionare Basic.
5. Specificare nome utente e password dell'endpoint API REST.
6. Seleziona Salva.

Autenticazione HTTPS con certificato client

L'autenticazione con certificato client è un'autenticazione reciproca basata su certificati, in cui il client, ossia Microsoft Entra ID, fornisce il certificato client al server per dimostrare la propria identità. Questo avviene nell'ambito dell'handshake SSL. L'API è responsabile della convalida dei certificati a un client valido, ad esempio Microsoft Entra ID, e dell'esecuzione di decisioni di autorizzazione. Il certificato client è un certificato digitale X.509.

Importante

Negli ambienti di produzione, il certificato deve essere firmato da un'autorità di certificazione.

Creare un certificato

Opzione 1: Usare Azure Key Vault (scelta consigliata)

Per creare un certificato, è possibile usare Azure Key Vault, che include opzioni per i certificati autofirmati e le integrazioni con i provider di autorità di certificazione per i certificati firmati. Le impostazioni consigliate includono:

• Oggetto: CN=<yourapiname>.<tenantname>.onmicrosoft.com
• Tipo di contenuto: PKCS #12
• Tipo di azione di durata: Email all contacts at a given percentage lifetime o Email all contacts a given number of days before expiry
• Tipo di chiave: RSA
• Dimensioni chiave: 2048
• Chiave privata esportabile: Yes (per poter esportare il file .pfx)

È quindi possibile esportare il certificato.

Opzione 2: Preparare un certificato autofirmato con PowerShell

Se non si ha già un certificato, per questa esercitazione è possibile usarne uno autofirmato. Un certificato autofirmato è un certificato di sicurezza non firmato da un'autorità di certificazione (CA) e non fornisce le garanzie di sicurezza di un certificato firmato da una CA.

Windows

In Windows, usare il cmdlet New-SelfSignedCertificate in PowerShell per generare un certificato.

1. Eseguire il seguente comando di PowerShell per generare un certificato autofirmato. Modificare -Subjectl'argomento in base al nome dell'applicazione e del tenant Azure AD B2C, come contosowebapp.contoso.onmicrosoft.com. 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"
   

2. Nel computer Windows, cercare e selezionare Gestisci certificati utente

3. In Certificati - Utente corrente, selezionare Certificati>personali>yourappname.yourtenant.onmicrosoft.com.

4. Selezionare il certificato, quindi selezionare Azione>Tutte le attività>Esporta.

5. Selezionare Avanti>Sì, esporta la chiave privata>Avanti.

6. Accettare le impostazioni predefinite per Formato file di esportazione, quindi selezionare Avanti.

7. Abilitare l'opzione Password, immettere una password per il certificato, quindi selezionare Avanti.

8. Per specificare un percorso per salvare il certificato, selezionare Sfoglia e accedere a una directory di propria scelta.

9. Nella finestra Salva con nome, immettere un Nome file, quindi selezionare Salva.

10. Selezionare Next>Finish (Avanti > Fine).

Per consentire ad Azure AD B2C di accettare la password del file pfx, la password deve essere crittografata con l'opzione TripleDES-SHA1 nell'utilità di esportazione dell'Archivio certificati di Windows, anziché AES256-SHA256.

macOS

In macOS, usare Assistente certificati in Accesso Portachiavi per generare un certificato.

1. Seguire le istruzioni per creare certificati autofirmati in Accesso Portachiavi su un Mac.
2. Nell'app Accesso Portachiavi sul proprio Mac, selezionare il certificato creato.
3. Selezionare File>Esporta elementi.
4. Selezionare un nome file per salvare il certificato. Ad esempio: self-signed-certificate.p12.
5. In Formato file, selezionare Scambio informazioni personali (.p12).
6. Seleziona Salva.
7. Immettere una password nelle casellePassword e Verifica.
8. Sostituire l'estensione del file con .pfx. Ad esempio: self-signed-certificate.pfx.

Configurare il connettore API

Per configurare un connettore API con l'autenticazione del certificato client, seguire questa procedura:

1. Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Amministratore utenti.
2. Andare a Identità>Identità esterne>Informazioni generali.
3. Selezionare Tutti i connettori API, quindi selezionare il connettore API da configurare.
4. Per Tipo di autenticazione, selezionare Certificato.
5. Nella casella Caricamento file, selezionare il file con estensione .pfx del certificato con una chiave privata.
6. Nella casella Immetti password, digitare la password del certificato.
7. Seleziona Salva.

Eseguire decisioni di autorizzazione

L'API deve implementare l'autorizzazione in base ai certificati client inviati per proteggere gli endpoint API. Per Servizio app di Azure e Funzioni di Azure, vedere Configurare l'autenticazione reciproca TLS per informazioni su come abilitare e convalidare il certificato dal codice API. In alternativa, è possibile usare Gestione API di Azure come livello di fronte a qualsiasi servizio API per controllare le proprietà del certificato client rispetto ai valori desiderati.

Rinnovo dei certificati

È consigliabile impostare avvisi di promemoria per la scadenza del certificato. Sarà necessario generare un nuovo certificato e ripetere i passaggi precedenti quando i certificati usati stanno per scadere. Durante il passaggio all'uso di un nuovo certificato, il servizio API può continuare ad accettare i certificati vecchi e nuovi per un periodo di tempo temporaneo durante la distribuzione del nuovo certificato.

Per caricare un nuovo certificato in un connettore API esistente, selezionare il connettore API in Connettori API e selezionare Carica nuovo certificato. Il certificato caricato più di recente che non è scaduto e la cui data di inizio è passata verrà utilizzata automaticamente da Microsoft Entra ID.

Autenticazione tramite chiave API

Alcuni servizi usano un meccanismo di "chiave API" per oscurare l'accesso agli endpoint HTTP durante lo sviluppo richiedendo al chiamante di includere una chiave univoca come intestazione HTTP o parametro di query HTTP. Per Funzioni di Azure, è possibile eseguire questa operazione includendo code come parametro di query nell'URL di endpoint del connettore API. Ad esempio, https://contoso.azurewebsites.net/api/endpoint?code=0123456789.

Questo meccanismo non deve essere usato da solo nell'ambiente di produzione. Pertanto, la configurazione per l'autenticazione di base o con certificato è sempre necessaria. Se non si vuole implementare alcun metodo di autenticazione (non consigliato) a scopo di sviluppo, è possibile selezionare l'autenticazione di base nella configurazione del connettore API e usare i valori temporanei per username e password che l'API può ignorare mentre si implementa l'autorizzazione appropriata.

Passaggi successivi

• Attività iniziali con esempi di avvio rapido.