Configurare Microsoft Entra ID per l'autenticazione client

Avviso

Attualmente, l'autenticazione client Microsoft Entra e il servizio token di identità gestita sono reciprocamente incompatibili in Linux.

Per i cluster in esecuzione in Azure, è consigliabile proteggere l'accesso agli endpoint di gestione tramite Microsoft Entra ID. Questo articolo descrive come configurare Microsoft Entra ID per autenticare i client per un cluster di Service Fabric.

In Linux è necessario completare i passaggi seguenti prima di creare il cluster. In Windows è anche possibile configurare l'autenticazione di Microsoft Entra per un cluster esistente.

In questo articolo il termine "applicazione" si riferisce alle applicazioni Microsoft Entra, non alle applicazioni di Service Fabric; la distinzione viene specificata ove necessario. Microsoft Entra ID consente alle organizzazioni (note come tenant) di gestire l'accesso degli utenti alle applicazioni.

Un cluster di Service Fabric offre diversi punti di accesso alle proprie funzionalità di gestione, tra cui Service Fabric Explorer e Visual Studio basati sul Web. Si creano quindi due applicazioni Microsoft Entra per controllare l'accesso al cluster: un'applicazione Web e un'applicazione nativa. Dopo aver creato le applicazioni, si assegnano gli utenti ai ruoli di sola lettura e di amministratore.

Nota

Al momento, Service Fabric non supporta l'autenticazione di Microsoft Entra per l'archiviazione.

Nota

Esiste un problema noto per cui le applicazioni e i nodi nei cluster abilitati per Microsoft Entra in Linux non possono essere visualizzati nel portale di Azure.

Nota

Microsoft Entra ID richiede ora la verifica o l'uso di uno schema predefinito per un dominio di autori di applicazioni (registrazione app). Per altre informazioni, vedere Configurare il dominio publisher di un'applicazione e Per l'URI AppId nelle applicazioni a tenant singolo sarà necessario l'uso di uno schema predefinito o di domini verificati.

Nota

A partire da Service Fabric 11.0, Service Fabric Explorer richiede un URI di reindirizzamento dell'applicazione a pagina singola anziché un URI di reindirizzamento Web.

Prerequisiti

In questo articolo si presuppone che sia già stato creato un tenant. In caso contrario, leggere Come ottenere un tenant di Microsoft Entra. Per semplificare alcuni dei passaggi richiesti per la configurazione di Microsoft Entra ID con un cluster di Service Fabric è stato creato un set di script di Windows PowerShell. Alcune azioni richiedono l'accesso a livello amministrativo a Microsoft Entra ID. Se lo script riscontra un errore 401 o 403 "Authorization_RequestDenied", un amministratore deve eseguire lo script.

1. Eseguire l'autenticazione con autorizzazioni amministrative di Azure.
2. Clonare il repository nel computer.
3. Assicurarsi di disporre di tutti i prerequisiti per gli script installati.

Creare applicazioni Microsoft Entra e assegnare utenti ai ruoli

Si useranno gli script per creare due applicazioni Microsoft Entra per controllare l'accesso al cluster: un'applicazione Web e un'applicazione nativa. Dopo aver creato le applicazioni per rappresentare il cluster, si creeranno gli utenti per i ruoli supportati da Service Fabric: sola lettura e amministratore.

SetupApplications.ps1

Eseguire SetupApplications.ps1 e indicare l'ID tenant, il nome del cluster, l'URI dell'applicazione Web e l'URL di risposta dell'applicazione Web come parametri. Usare -remove per rimuovere le registrazioni dell'app. L'uso di -logFile <log file path> genera un log di trascrizione. Per altre informazioni, vedere la guida dello script (help .\setupApplications.ps1 -full). Lo script crea l'applicazione Web e l'applicazione nativa per rappresentare il cluster di Service Fabric. Le due nuove voci di registrazione dell'app sono nel formato seguente:

• ClusterName_Cluster
• ClusterName_Client

Nota

Per i cloud nazionali (ad esempio Azure per enti pubblici, Microsoft Azure gestito da 21Vianet), è necessario anche specificare il parametro -Location.

Parametri

• tenantId: è possibile trovare il TenantId eseguendo il comando di PowerShell Get-AzureSubscription. Eseguendo questo comando, viene visualizzato il TenantId per ogni sottoscrizione.

• clusterName: ClusterName viene usato come prefisso per le applicazioni Microsoft Entra create dallo script. Non è necessario che corrisponda esattamente al nome effettivo del cluster. Ha solo lo scopo di facilitare il mapping degli elementi di Microsoft Entra al cluster di Service Fabric con cui vengono usati.

• SpaApplicationReplyUrl: SpaApplicationReplyUrl è l'endpoint predefinito che Microsoft Entra ID restituisce agli utenti dopo che hanno completato l'accesso. Impostare questo endpoint come endpoint di Service Fabric Explorer per il cluster. Se si creano applicazioni Microsoft Entra per rappresentare un cluster esistente, assicurarsi che questo URL corrisponda all'endpoint del cluster esistente. Se si creano applicazioni per un nuovo cluster, pianificare l'endpoint per il cluster e assicurarsi di non usare l'endpoint di un cluster esistente. Per impostazione predefinita, l'endpoint di Service Fabric Explorer è: https://<cluster_domain>:19080/Explorer/index.html

• webApplicationUri: WebApplicationUri è l'URI di un "dominio verificato" o l'URI che usa il formato dello schema API API://{{ID tenant}}/{{nome cluster}}. Per altre informazioni, vedere Per l'URI AppId nelle applicazioni a tenant singolo sarà necessario l'uso di uno schema predefinito o di domini verificati.

  Schema API di esempio: API://0e3d2646-78b3-4711-b8be-74a381d9890c/mysftestcluster

Esempio SetupApplications.ps1

# if using cloud shell
# cd clouddrive 
# git clone https://github.com/Azure-Samples/service-fabric-aad-helpers
# cd service-fabric-aad-helpers
# code .

$tenantId = '0e3d2646-78b3-4711-b8be-74a381d9890c'
$clusterName = 'mysftestcluster'
$spaApplicationReplyUrl = 'https://mysftestcluster.eastus.cloudapp.azure.com:19080/Explorer/index.html' # <--- client browser redirect url
#$webApplicationUri = 'https://mysftestcluster.contoso.com' # <--- must be verified domain due to AAD changes
$webApplicationUri = "API://$tenantId/$clusterName" # <--- doesn't have to be verified domain

$configObj = .\SetupApplications.ps1 -TenantId $tenantId `
  -ClusterName $clusterName `
  -SpaApplicationReplyUrl $spaApplicationReplyUrl `
  -AddResourceAccess `
  -WebApplicationUri $webApplicationUri `
  -Verbose

Lo script restituisce la variabile $configObj per i comandi successivi e stampa il codice JSON richiesto dal modello di Azure Resource Manager. Copiare l'output JSON e usarlo quando si crea o si modifica un cluster esistente creare il cluster abilitato per Microsoft Entra ID.

Output di esempio SetupApplications.ps1

Name                           Value
----                           -----
WebAppId                       f263fd84-ec9e-44c0-a419-673b1b9fd345
TenantId                       0e3d2646-78b3-4711-b8be-74a381d9890c
ServicePrincipalId             3d10f55b-1876-4a62-87db-189bfc54a9f2
NativeClientAppId              b22cc0e2-7c4e-480c-89f5-25f768ecb439

-----ARM template-----
"azureActiveDirectory": {
  "tenantId":"0e3d2646-78b3-4711-b8be-74a381d9890c",
  "clusterApplication":"f263fd84-ec9e-44c0-a419-673b1b9fd345",
  "clientApplication":"b22cc0e2-7c4e-480c-89f5-25f768ecb439"
},

JSON dell'oggetto dei parametri azureActiveDirectory

"azureActiveDirectory": {
  "tenantId":"<guid>",
  "clusterApplication":"<guid>",
  "clientApplication":"<guid>"
},

SetupUser.ps1

SetupUser.ps1 viene usato per aggiungere account utente alla registrazione dell'app appena creata usando la variabile di output $configObj precedente. Specificare il nome utente per l'account utente da configurare con la registrazione dell'app e specificare "isAdmin" per le autorizzazioni amministrative. Se l'account utente è nuovo, specificare anche la password temporanea per il nuovo utente. La password deve essere modificata al primo accesso. Se si usa "-remove", si rimuoverà l'account utente, non solo la registrazione dell'app.

Esempio di utente SetupUser.ps1 (lettura)

.\SetupUser.ps1 -ConfigObj $configobj `
  -UserName 'TestUser' `
  -Password 'P@ssword!123' `
  -Verbose

Esempio di amministratore setupUser.ps1 (lettura/scrittura)

.\SetupUser.ps1 -ConfigObj $configobj `
  -UserName 'TestAdmin' `
  -Password 'P@ssword!123' `
  -IsAdmin `
  -Verbose

SetupClusterResource.ps1

SetupClusterResource.ps1 può essere usato facoltativamente per esportare il modello di Resource Manager della risorsa cluster esistente, aggiungere/modificare la configurazione di "azureActiveDirectory" e ridistribuire il modello. Usare "-Whatif" solo per esportare e modificare il modello ma non ridistribuire la configurazione. Questo script richiede il modulo "Az" di Azure e il nome del gruppo di risorse per il cluster.

Esempio SetupClusterResource.ps1 -whatIf

# requires azure module 'az'
# install-module az
$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
  -resourceGroupName $resourceGroupName `
  -WhatIf

Dopo aver verificato il modello e dopo che questo è pronto per l'elaborazione, eseguire di nuovo lo script senza "-WhatIf" o usare il cmdlet di PowerShell "New-AzResourceGroupDeployment" per distribuirlo.

Esempio SetupClusterResource.ps1

$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
  -resourceGroupName $resourceGroupName

Nota

Aggiornare i modelli o gli script di Resource Manager di provisioning del cluster con nuove modifiche alla configurazione di Microsoft Entra della risorsa cluster.

Concessione del consenso amministratore

Potrebbe essere necessario usare l'opzione "Concedi consenso amministratore" per la configurazione delle "Autorizzazioni API". Passare al pannello Registrazioni app di Azure e aggiungere il nome del cluster al filtro. Per entrambe le registrazioni, aprire "Autorizzazioni API" e selezionare "Concedi consenso amministratore per", se disponibile.

Verifica della configurazione di Microsoft Entra

Passare all'URL di Service Fabric Explorer (SFX). Deve corrispondere al parametro spaApplicationReplyUrl. Verrà visualizzata una finestra di dialogo di autenticazione di Azure. Accedere con un account con la nuova configurazione di Microsoft Entra. Verificare che l'account amministratore abbia accesso in lettura/scrittura e che l'utente abbia accesso in lettura. Qualsiasi modifica al cluster, ad esempio l'esecuzione di un'azione, è un'azione amministrativa.

Risoluzione dei problemi relativi alla configurazione di Microsoft Entra ID

La configurazione di Microsoft Entra ID e il suo utilizzo possono comportare difficoltà, pertanto di seguito verranno fornite alcune indicazioni per risolvere gli eventuali problemi. La registrazione della trascrizione di PowerShell può essere abilitata usando l'argomento "-logFile" negli script "SetupApplications.ps1" e "SetupUser.ps1" per esaminare l'output.

Nota

Con la migrazione delle piattaforme di identità (da ADAL a MSAL), la deprecazione di AzureRM a favore di Azure AZ e il supporto di più versioni di PowerShell, le dipendenze potrebbero non essere sempre corrette o aggiornate, causando errori nell'esecuzione di script. L'esecuzione di comandi e script di PowerShell da Azure Cloud Shell riduce il rischio di errori con l'autenticazione automatica della sessione e l'identità gestita.

Request_BadRequest

Problema

Non è un aggiornamento di riferimento valido. Codice di stato HTTP: 400.

VERBOSE: POST with 157-byte payload
VERBOSE: received -byte response of content type application/json
>> TerminatingError(Invoke-WebRequest): "{"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}"
confirm-graphApiRetry returning:True
VERBOSE: invoke-graphApiCall status: 400
exception:
Response status code doesn't indicate success: 400 (Bad Request).

Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
 239 |  …   $result = Invoke-WebRequest $uri -Method $method -Headers $headers  …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}

at invoke-graphApiCall, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 239
at invoke-graphApi, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 275
at add-roleAssignment, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 193
at add-user, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 244
at enable-AADUser, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 178
at main, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 136
at <ScriptBlock>, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 378
at <ScriptBlock>, /home/<user>/clouddrive/aad-test.ps1: line 43
at <ScriptBlock>, <No file>: line 1
WARNING: invoke-graphApiCall response status: 400
invoke-graphApi count:0 statuscode:400 -uri https://graph.microsoft.com/v1.0/0e3d2646-78b3-4711-b8be-74a381d9890c/servicePrincipals/3d10f55b-1876-4a62-87db-189bfc54a9f2/appRoleAssignedTo -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
confirm-graphApiRetry returning:True

Motivo

Le modifiche alla configurazione non sono state propagate. Gli script eseguono retry su determinate richieste con codici di stato HTTP 400 e 404.

Soluzione

Gli script eseguono retry su determinate richieste con codici di stato HTTP 400 e 404 fino al valore "-timeoutMin" forniti, ovvero 5 minuti per impostazione predefinita. Lo script può essere eseguito nuovamente in base alle esigenze.

Service Fabric Explorer richiede di selezionare un certificato

Problema

Dopo avere eseguito l'accesso a Microsoft Entra ID in Service Fabric Explorer, il browser torna alla home page, ma un messaggio chiede di selezionare un certificato.

Motivo

All'utente non è assegnato un ruolo nell'applicazione cluster Microsoft Entra ID. Di conseguenza, l'autenticazione di Microsoft Entra non riesce nel cluster di Service Fabric. Service Fabric Explorer ritorna all'autenticazione del certificato.

Soluzione

Seguire le istruzioni per la configurazione di Microsoft Entra ID e assegnare i ruoli utente. È anche consigliabile attivare "Assegnazione utente obbligatoria per l'accesso all'app", come in SetupApplications.ps1.

La connessione a PowerShell non riesce con un errore: "Le credenziali specificate non sono valide"

Problema

Quando si usa PowerShell per connettersi al cluster con la modalità di sicurezza "AzureActiveDirectory", eseguito l'accesso a Microsoft Entra ID, la connessione ha esito negativo con un errore: "Le credenziali specificate non sono valide".

Soluzione

Questa soluzione è identica a quella precedente.

Service Fabric Explorer restituisce un errore durante l'accesso: "AADSTS50011"

Problema

Quando si prova a eseguire l'accesso a Microsoft Entra ID in Service Fabric Explorer, la pagina restituisce l'errore AADSTS50011, che indica che l'<URL> dell'indirizzo di risposta non corrisponde agli indirizzi configurati per l'applicazione: <GUID>.

Motivo

L'applicazione cluster (Web) che rappresenta Service Fabric Explorer prova a eseguire l'autenticazione per Microsoft Entra ID e come parte della richiesta indica l'URL di reindirizzamento restituito. L'URL non è tuttavia elencato nell'elenco URL DI RISPOSTA dell'applicazione Microsoft Entra.

Soluzione

Nella pagina di registrazione dell'app Microsoft Entra per il cluster selezionare Autenticazione e nella sezione URI di reindirizzamento aggiungere l'URL di Service Fabric Explorer all'elenco. Salvare la modifica.

LA connessione al cluster tramite l'autenticazione di Microsoft Entra con PowerShell genera un errore quando si accede: "AADSTS50011"

Problema

Quando si tenta di connettersi a un cluster di Service Fabric usando Microsoft Entra ID tramite PowerShell, la pagina di accesso restituisce un errore: "AADSTS50011: l'URL di risposta specificato nella richiesta non corrisponde agli URL di risposta configurati per l'applicazione: <guid>".

Motivo

Analogamente al problema precedente, PowerShell tenta di eseguire l'autenticazione con Microsoft Entra ID, che fornisce un URL di reindirizzamento non elencato nell'elenco URL di risposta dell'applicazione Microsoft Entra.

Soluzione

Usare lo stesso processo del problema precedente, ma impostando l'URL su urn:ietf:wg:oauth:2.0:oob, un reindirizzamento speciale per l'autenticazione da riga di comando.

L'esecuzione dello script genera un errore in Errore di autorizzazione

Problema

Lo script di PowerShell potrebbe non riuscire a eseguire tutti i comandi REST necessari per completare la configurazione di Microsoft Entra con errore "Authorization_RequestDenied","Privilegi insufficienti per completare l'operazione". Errore di esempio:

Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
 239 |  …   $result = Invoke-WebRequest $uri -Method $method -Headers $headers  …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"error":{"code":"Authorization_RequestDenied","message":"Insufficient privileges to complete the
     | operation.","innerError":{"date":"2022-08-29T14:46:37","request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0","client-request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0"}}}
...
invoke-graphApi count:0 statuscode:403 -uri https://graph.microsoft.com/v1.0/72f988bf-86f1-41af-91ab-2d7cd011db47/oauth2PermissionGrants -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:364
Line |
 364 |      assert-notNull $result "aad app service principal oauth permissio …
     |      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | aad app service principal oauth permissions User.Read configuration failed

Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:656
Line |
 656 |  main
     |  ~~~~
     | exception:  exception: assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed  Exception:
     | /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:22 Line |   22 |          throw "assertion failure: object:$obj message:$msg"      |         
     | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      | assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed  
...

Motivo

Questo errore viene restituito quando l'account utente che esegue lo script non dispone delle autorizzazioni per eseguire la chiamata REST. Ciò può verificarsi se l'utente non dispone di autorizzazioni di amministratore/gestione/scrittura per gli oggetti creati o modificati.

Soluzione

Collaborare con un amministratore del tenant di Azure o di Microsoft Entra ID per completare tutte le azioni rimanenti. Gli script forniti sono idempotenti, quindi possono essere rielaborati per completare il processo.

Connettere il cluster usando l'autenticazione di Microsoft Entra tramite PowerShell

Per connettere il cluster di Service Fabric, usare il comando di PowerShell di esempio seguente:

Connect-ServiceFabricCluster -ConnectionEndpoint <endpoint> -KeepAliveIntervalInSec 10 -AzureActiveDirectory -ServerCertThumbprint <thumbprint>

Per altre informazioni, vedere il cmdlet Connect-ServiceFabricCluster.

È possibile riutilizzare lo stesso tenant di Microsoft Entra in più cluster?

Sì. Ricordarsi però di aggiungere l'URL di Service Fabric Explorer all'applicazione cluster (Web). In caso contrario, Service Fabric Explorer non funzionerà.

Perché è ancora necessario un certificato del server se Microsoft Entra ID è abilitato?

FabricClient e FabricGateway eseguono un'autenticazione reciproca. Durante l'autenticazione di Microsoft Entra, l'integrazione di Microsoft Entra consente di assegnare un'identità del client al server e il certificato del server viene usato dal client per verificare l'identità del server. Per altre informazioni sui certificati di Service Fabric, vedere Certificati X.509 e Service Fabric.

Passaggi successivi

Dopo aver configurato le applicazioni Microsoft Entra e aver impostato i ruoli per gli utenti, configurare e distribuire un cluster.