Abilitare l'autenticazione di Microsoft Entra ID

Microsoft Entra ID è una soluzione di identità basata sul cloud progettata per gestire l'accesso utente e le autorizzazioni per servizi, risorse e applicazioni Microsoft. Le organizzazioni che sottoscrivono i servizi aziendali online di Microsoft, ad esempio Microsoft Azure, hanno accesso a Microsoft Entra ID.

Microsoft Entra ID consente di autenticare le richieste alle risorse di Intelligenza artificiale di Azure senza la necessità di password o chiavi. Viene invece creato un solido livello di sicurezza registrando un'applicazione di identità con la piattaforma Microsoft Entra ID. Questa registrazione consente all'applicazione di identità di effettuare richieste sicure all'API delle risorse di Intelligenza artificiale di Azure, stabilendo così una relazione di trust con Microsoft Identity Platform.

Questo articolo illustra come creare e usare un'applicazione di identità Id Entra Microsoft per autenticare le richieste alle risorse di Intelligenza artificiale di Azure. Ecco i passaggi seguenti:

• Configurare i prerequisiti.
• Disabilitare l'autenticazione basata su chiave (locale)
• Registrare un'applicazione di identità con Microsoft Entra ID
• Aggiungere un segreto del client
• Assegnare un RBAC ruolo (controllo degli accessi in base al ruolo) per concedere le autorizzazioni di accesso all'applicazione.
• Ottenere un token di accesso
• Effettuare una richiesta all'API Translator per intelligenza artificiale di Azure

Prerequisiti

Prima di iniziare, sono necessari un account Azure e una sottoscrizione dei servizi di intelligenza artificiale di Azure.

• Una sottoscrizione di Azure attiva. Se non si possiede una sottoscrizione di Azure, è possibile crearne una gratuitamente.

• Una risorsa di Azure AI Translator. Dopo aver ottenuto la sottoscrizione di Azure, crea una risorsa globale a servizio singolo Translator nel portale di Azure.

Importante

Gli endpoint regionali non supportano l'autenticazione Microsoft Entra.

• Strumento da riga di comando cURL installato.

  • Windows
  • Mac o Linux

• PowerShell versione 7.*+ o un'applicazione della riga di comando simile.

  • Windows
  • macOS
  • Linux

• Per controllare la versione di PowerShell, digitare il comando seguente relativo al sistema operativo:

  • Windows: Get-Host | Select-Object Version
  • macOS o Linux: $PSVersionTable

Disabilitare l'autenticazione con chiave

Per usare l'autenticazione Microsoft Entra, è necessario disattivare l'autenticazione basata su chiave (locale). Una volta disabilitato l'accesso alla chiave, Microsoft Entra ID diventa l'unico metodo di autorizzazione. L'organizzazione può scegliere di disattivare l'autenticazione locale e imporre a Microsoft Entra per le risorse di intelligenza artificiale di Azure. In caso contrario, è possibile disabilitare l'autenticazione della chiave per risorse specifiche seguendo questa procedura in PowerShell:

1. Connettersi ad Azure

    Connect-AzAccount
   

2. Verificare lo stato di autenticazione locale

    Get-AzCognitiveServicesAccount
   

3. Verificare che la proprietà DisableLocalAuth sia impostata su $true (l'autenticazione locale è disabilitata)

   Get-AzCognitiveServicesAccount -ResourceGroupName "my-resource-group" -Name "my-resource-name"
   

   Se è DisableLocalAuth vuoto o impostato su False, è necessario impostarlo su $true.

4. Disabilita autenticazione locale

   Set-AzCognitiveServicesAccount -ResourceGroupName "my-resource-group" -Name "my-resource-name" -DisableLocalAuth $true
   
   

È possibile verificare ancora una volta che l'autenticazione locale sia disabilitata usando il Get-AzCognitiveServicesAccount cmdlet . Il valore True indica che l'autenticazione locale è disabilitata.

Registrare un'applicazione di identità con Microsoft Entra ID

1. Passare al portale di Azure

2. Immettere Microsoft Entra ID nella casella di ricerca nella parte superiore della pagina.

   

3. Selezionare il Microsoft Entra ID servizio dal menu a discesa.

   

4. Microsoft Entra ID Selezionando si apre la pagina di panoramica dell'organizzazione nel portale di Azure.

5. Nel nodo del menu Manage della barra a sinistra selezionare App registrations.

   

6. Selezionare New registration dal menu nella parte superiore della finestra principale.

   

7. Completare i campi di registrazione dell'applicazione:
   
   

   • Nome. Selezionare un nome per l'applicazione. In questo caso, si userà azure-ai-auth-app.
   • Tipi di account supportati. Specificare chi può usare l'applicazione.
   • URI di reindirizzamento. Questa selezione è facoltativa. Decidiamo di saltarlo per questo progetto.
   • Registra. Selezionare il pulsante Register e completare il App registration.

   Per altre informazioni sulla registrazione di un'applicazione, vedereRegistrare un'applicazione

8. Al termine della registrazione, viene visualizzato il App's registration riquadro Panoramica. L'ID applicazione (client), detto anche client ID, identifica in modo univoco l'applicazione nella piattaforma di identità Microsoft.

   

9. Prima di lasciare la pagina di panoramica della registrazione dell'app, copiare e incollare i valori seguenti in una posizione sicura e comoda, ad esempio Blocco note di Windows:

   • Application (client) ID
   • Directory (tenant) ID

La registrazione dell'app è stata completata. Aggiungere quindi un segreto client all'applicazione.

Aggiungere una credenziale segreta del client

Le applicazioni client usano le credenziali per ottenere l'accesso a un'API Web. Queste credenziali consentono all'applicazione di eseguire l'autenticazione in modo indipendente, eliminando la necessità di interazione dell'utente, come l'inserimento della chiave, durante l'esecuzione. Il segreto client dell'applicazione (password dell'applicazione) è una stringa usata dall'applicazione per dimostrare la propria identità quando si richiede un token.

1. Selezionare la pagina Panoramica dal menu di spostamento a sinistra.

   

2. Seleziona Add a certificate or secret.

   

3. Prima selezionare New client secret.

   

4. Add a client secret Nella finestra aggiungere una descrizione, impostare un periodo di scadenza e quindi selezionare il Add pulsante .

   

5. Copiare e incollare il segreto Value client nella stessa posizione sicura di Application (client) ID e Directory (tenant) ID, ad esempio Blocco note di Windows. I valori dei segreti client possono essere visualizzati solo subito dopo la creazione. Assicurarsi di salvare il segreto prima di uscire dalla pagina.

   

Ora che l'applicazione ha le credenziali di autenticazione appropriate, aggiungere le autorizzazioni per l'applicazione per accedere alle risorse di Azure AI Foundry.

Aggiungere le autorizzazioni API

Aggiungere quindi un'autorizzazione che consenta all'applicazione di accedere alle API servizi cognitivi (Servizi cognitivi) di Azure, tra cui Azure AI Translator, come utente.

1. Nel menu di spostamento a sinistra passare a API permissions e quindi selezionare Add a permission dalla finestra principale.

   

2. Nella nuova finestra visualizzata selezionare APIs my organization uses e quindi digitare Microsoft Cognitive Services nella barra di ricerca.

   

3. Selezionare Microsoft Cognitive Services tra i risultati della ricerca.

   • Nella nuova finestra, in Permissions, selezionare Delegated permissions.

   • Contrassegnare la Access Cognitive Services API as organization users casella di controllo.

   • Seleziona Add permissions.

     

Questo è tutto! La configurazione per l'applicazione Microsoft Entra ID è completa. Successivamente, la risorsa Traduttore deve concedere all'applicazione l'accesso aggiungendo un'assegnazione di ruolo specificamente per la risorsa Traduttore. Per altre informazioni, vedereControllo degli accessi in base al ruolo di Azure

Assegnare il ruolo utente di Servizi cognitivi alla risorsa di Azure AI Translator

Il controllo degli accessi in base al ruolo (Azure RBAC) è un'entità di sicurezza che consente di controllare l'accesso alle risorse di Azure. È possibile usare RBAC per concedere l'accesso a qualsiasi risorsa che supporti l'autenticazione di Microsoft Entra, in questo caso, l'istanza di Azure AI Translator. Per concedere all'applicazione Microsoft Entra ID l'accesso alla risorsa Translator, assegnare un ruolo di Azure utilizzando il controllo degli accessi basato sui ruoli di Azure (Azure RBAC).

1. Accedendo al portale di Azure, naviga verso la tua risorsa globale Azure AI Translator.

2. Nel menu a sinistra selezionare Access control (IAM).

3. Selezionare Add role assignment dalla finestra principale.

   

4. Nel menu di navigazione a sinistra, seleziona Cognitive Services User e fai clic sul pulsante Next.

5. Assegnare l'accesso su Add role assignment page a User, group, or service principal.

6. Scegliere Select members.

   

7. Nella finestra visualizzata digitare il nome dell'applicazione registrata nella casella di ricerca, ad esempio text-translation-app. Selezionare l'applicazione e scegliere il Select pulsante .

   

8. Completare il processo di assegnazione selezionando il Review + assign pulsante .

A questo punto, è possibile testare l'uso dell'applicazione per ottenere un token di sicurezza per le chiamate API REST.

Ottenere un token di accesso utilizzando il flusso delle credenziali del client OAuth

I token di accesso sono un tipo di token di sicurezza progettato per l'autorizzazione, concedendo l'accesso a risorse specifiche per conto di un utente autenticato e consentendo ai client di chiamare in modo sicuro le API Web protette. In questo caso, il token di accesso concede alla tua applicazione registrata su Microsoft Entra ID l'autorizzazione ad accedere alla risorsa Translator per conto dell'utente.

Annotazioni

• La durata predefinita di un token di accesso non è fissa.
• Al momento del rilascio, Microsoft Identity Platform assegna una durata casuale compresa tra 60 e 90 minuti, con una media di 75 minuti.
• Alla scadenza del token, ripeti la richiesta all'endpoint /token per acquisire un nuovo token di accesso.
• I token di aggiornamento non vengono rilasciati con il flusso delle credenziali client. Poiché client_id e client_secret (necessari per ottenere un token di aggiornamento) sono già utilizzati per ottenere un token di accesso, ciò elimina la necessità di un token di aggiornamento in questo contesto. Per altre informazioni, vedereFlusso di credenziali client OAuth 2.0

1. Preparare la richiesta di token. Per l'applicazione registrata sono necessari i valori seguenti:

   • ID applicazione (client). Disponibile nella pagina di panoramica dell'applicazione registrata. Copiato e archiviato durante il precedente passaggio di registrazione di un'applicazione di identità. (#register-an-identity-application-with-microsoft-entra-id).
   • ID del tenant. Disponibile nella pagina di panoramica dell'applicazione registrata. Copiato e archiviato durante il passaggio precedente di registrazione di un'applicazione di identità.
   • Valore del segreto cliente. Copiato e archiviato durante il passaggio precedente di Aggiungere una credenziale segreta client.

2. Si userà cURL ora per effettuare una richiesta di token. Ecco il codice:

   Linux o macOS

   curl -X POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id={client-id}" \
     -d "scope= https://cognitiveservices.azure.com/.default" \
     -d "client_secret={client-secret}" \
     -d "grant_type=client_credentials" |json_pp
   

   Windows

   curl -X POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token ^
     -H "Content-Type: application/x-www-form-urlencoded" ^
     -d "client_id={client-id}" ^
     -d "scope= https://cognitiveservices.azure.com/.default" ^
     -d "client_secret={client-secret}" ^
     -d "grant_type=client_credentials" |json
   

3. Sostituire {tenant-id} nell'URL della richiesta, {client-id}e {client-secret} con i valori effettivi.

   • I comandi |json_pp (macOS) e |json (Windows) permettono di formattare Json in modo bello con cURL.

   • Il token di accesso viene ricevuto nella risposta.

4. Salvare l'accesso ottenuto in una posizione sicura e comoda, ad esempio Blocco note di Windows.

Ottimo. A questo punto si eseguirà una chiamata API REST all'API per intelligenza artificiale di Azure Translator.

Usare l'autenticazione del token di accesso per una richiesta api REST

Per effettuare una richiesta API REST valida, sono necessari i valori seguenti:

• Identità dell'istanza di Translator. È possibile fornire questo in due modi (scegli uno):

  • Utilizzare l'endpoint globale e passare resourceId come intestazione di richiesta.

  • Usare l'endpoint personalizzato come parte dell'URL della richiesta POST.

• Un token di accesso microsoft Entra ID acquisito dall'applicazione Microsoft Entra ID.

Utilizzare l'endpoint globale

1. Passare alla pagina immediata della risorsa nel portale di Azure.

   • L'endpoint globale è disponibile in Resource Management → → Keys and EndpointWeb API → Text translation.

   • L'oggetto ResourceID è disponibile in Resource Management → Properties.

   • Formato ID risorsa: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

     

2. Sostituire {your-resource-ID} con il valore del portale di Azure e {access-token} con il valore ottenuto nel passaggio precedente: ottenere un token di accesso.

   Linux o macOS

   curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=en" \
        -H "Authorization: Bearer {access-token}"\
        -H "Ocp-Apim-ResourceId: {your-resource-ID}" \
        -H "Content-Type: application/json" \
        -d "[{'Text':'Hola'}]"
   

   Windows

   curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=en" ^
        -H "Authorization: Bearer {access-token}" ^
        -H "Ocp-Apim-ResourceId: {your-resource-id}" ^
        -H "Content-Type: application/json" ^
        -d "[{'Text':'Hola'}]"
   

Usare l'endpoint di dominio personalizzato

L'endpoint di dominio personalizzato è un URL formattato con il nome della risorsa e il nome host ed è disponibile nel portale di Azure. Quando è stata creata la risorsa Translator, il valore immesso nel Name campo è il parametro del nome di dominio personalizzato per l'endpoint. È possibile trovare l'URL dell'endpoint di dominio personalizzato nei campi Traduzione documento e Traduzione testuale contenitori.

Linux o macOS

curl -X POST "https://{your-custom-domain}.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=en" \
  -H "Authorization: Bearer {access-token}" \
  -H "Content-Type: application/json" \
  -d "[{'Text':'Hola'}]"

Windows

curl -X POST "https://{your-custom-domain}.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=en" ^
  -H "Authorization: Bearer {access-token}" ^
  -H "Content-Type: application/json" ^
  -d "[{'Text':'Hola'}]"

Sostituire {your-custom-domain} con il valore del portale di Azure e {access-token} con il token ottenuto dal passaggio precedente, ottenere un token di accesso.

Ecco un esempio della risposta JSON:

[{"detectedLanguage":{"language":"es","score":1.0},"translations":[{"text":"Hello","to":"en"}]}]

Ben fatto! Si è ora appreso come usare Microsoft Entra ID per autenticare le richieste alla risorsa di Intelligenza artificiale di Azure.