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 procedura dettagliata: Aggiungere un connettore API a una guida al 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

L'autenticazione di base HTTP è 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 come almeno un amministratore utente.
2. Passare a Entra ID>Identità Esterne>Panoramica.
3. Selezionare Tutti i connettori API e quindi selezionare il connettore API da configurare.
4. Per Tipo di autenticazione selezionare Basic.
5. Specificare il nome utente e la password dell'endpoint dell'API REST.
6. Selezionare Salva.

Autenticazione HTTPS con certificato client

L'autenticazione del certificato client è un'autenticazione reciproca basata su certificati. Il client, Microsoft Entra ID, fornisce al server il certificato client per dimostrare la propria identità come parte 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 autofirmato 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 permanente: 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 .pfx il file)

È 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.

Finestre

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 l'opzione Gestisci certificati utente

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

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

5. Selezionare Avanti>Sì, esportare la chiave> privataAvanti.

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

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

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

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

10. Selezionare 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: certificato-autofirmato.p12.
5. In Formato file selezionare Scambio di informazioni personali (.p12).
6. Selezionare Salva.
7. Immettere una password nelle caselle Password e Verifica .
8. Sostituire l'estensione del file con .pfx. Ad esempio: certificato-autofirmato.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 come almeno un amministratore utente.
2. Passare a Entra ID>Identità Esterne>Panoramica.
3. Selezionare Tutti i connettori API e quindi selezionare il connettore API da configurare.
4. Per Tipo di autenticazione selezionare Certificato.
5. Nella casella Carica certificato selezionare il file pfx del certificato con una chiave privata.
6. Nella casella Immetti password digitare la password del certificato.
7. Selezionare 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 davanti 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. È necessario generare un nuovo certificato e ripetere i passaggi descritti in questo articolo 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. Microsoft Entra ID usa automaticamente il certificato caricato più di recente che non è scaduto e la cui data di inizio è passata.

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, includere code come parametro di query nell'URL dell'endpoint del connettore API. Ad esempio, https://contoso.azurewebsites.net/api/endpoint?code=0123456789.

Non è consigliabile usare questo meccanismo 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

• Inizia con i nostri esempi di avvio rapido.