Configure o ID do Microsoft Entra para autenticação do cliente

Para clusters em execução no Azure, é recomendável usar o Microsoft Entra ID para proteger o acesso aos pontos de extremidade de gerenciamento. Este artigo descreve como configurar o Microsoft Entra ID para autenticar clientes de um cluster do Service Fabric.

No Linux, você deve concluir as etapas a seguir para poder criar o cluster. No Windows, também há a opção de configurar a autenticação do Microsoft Entra em um cluster existente.

Neste artigo, o termo "aplicativo" refere-se a aplicativos do Microsoft Entra, não aplicativos do Service Fabric; a distinção será feita quando necessário. O Microsoft Entra ID permite que organizações (conhecidas como locatários) gerenciem o acesso do usuário aos aplicativos.

Um cluster do Service Fabric oferece vários pontos de entrada para a funcionalidade de gerenciamento, incluindo o Service Fabric Explorer e o Visual Studio baseados na Web. Como resultado, você criará dois aplicativos do Microsoft Entra para controlar o acesso ao cluster: um aplicativo Web e um aplicativo nativo. Depois que os aplicativos forem criados, você atribuirá usuários a funções de administrador e somente leitura.

Pré-requisitos

Neste artigo, partimos do pressuposto que você já tenha criado um locatário. Caso contrário, comece lendo Como obter um locatário do Microsoft Entra. Para simplificar algumas das etapas envolvidas na configuração do Microsoft Entra ID com um cluster do Service Fabric, criamos um conjunto de scripts do Windows PowerShell. Algumas ações exigem acesso de nível administrativo ao Microsoft Entra ID. Se o script apresentar um erro 401 ou 403 ''Authorization_RequestDenied'', um administrador precisará executar o script.

1. Autentique com permissões administrativas do Azure.
2. Clone o repositório no seu computador.
3. Verifique se você tem todos os pré-requisitos para os scripts instalados.

Criar aplicativos do Microsoft Entra e atribuir usuários a funções

Usaremos os scripts para criar dois aplicativos Microsoft Entra para controlar o acesso ao cluster: um aplicativo Web e um aplicativo nativo. Depois de criar os aplicativos para representar seu cluster, crie usuários para as funções compatíveis com o Service Fabric: somente leitura e administrador.

SetupApplications.ps1

Execute SetupApplications.ps1 e forneça a ID de locatário, o nome do cluster, o URI do aplicativo Web e a URL de resposta do aplicativo Web como parâmetros. Use -remove para remover os registros do aplicativo. O uso de -logFile <log file path> gera um log de transcrição. Confira a ajuda de script (help .\setupApplications.ps1 -full) para obter informações adicionais. O script cria aplicativos Web e nativos para representar o seu cluster do Service Fabric. As duas novas entradas de registro de aplicativo estão no seguinte formato:

• ClusterName_Cluster
• ClusterName_Client

Parâmetros

• tenantId: você pode encontrar o seu TenantId executando o comando Get-AzureSubscription do PowerShell. A execução desse comando exibe a TenantId para cada assinatura.

• clusterName: ClusterName é utilizado para prefixar os aplicativos do Microsoft Entra criados pelo script. Não precisa corresponder exatamente ao nome real do cluster. Destina-se apenas a facilitar o mapeamento de artefatos do Microsoft Entra para o cluster do Service Fabric com o qual eles estão sendo usados.

• SpaApplicationReplyUrl: SpaApplicationReplyUrl é o ponto de extremidade padrão que o Microsoft Entra ID retorna aos usuários depois que eles terminam de entrar. Defina esse ponto de extremidade como o ponto de extremidade do Service Fabric Explorer para o seu cluster. Se você estiver criando aplicativos do Microsoft Entra para representar um cluster existente, certifique-se de que esse URL corresponde ao ponto de extremidade do cluster existente. Se você estiver criando aplicativos para um novo cluster, planeje o ponto de extremidade do seu cluster e certifique-se de não usar o ponto de extremidade de um cluster existente. Por padrão, o ponto de extremidade do Service Fabric Explorer é: https://<cluster_domain>:19080/Explorer/index.html

• webApplicationUri: WebApplicationUri é o URI de um ''domínio verificado'' ou o URI que usa o formato de esquema de API da API://{{Id do locatário}}/{{nome do cluster}}. Confira o URI do AppId em aplicativos de locatário único exige que o uso de esquema padrão ou de domínios verificados para obter mais informações.

  Exemplo de esquema de API: API://0e3d2646-78b3-4711-b8be-74a381d9890c/mysftestcluster

Exemplo de 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

O script gera a variável $configObj para comandos subsequentes e imprime o JSON exigido pelo modelo do Azure Resource Manager. Copie a saída JSON e utilize-a ao criar ou modificar o cluster existente, consulte criar o cluster habilitado para Microsoft Entra ID.

Saída do exemplo de 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"
},

objeto de parâmetros JSON azureActiveDirectory

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

SetupUser.ps1

SetupUser.ps1 é usado para adicionar contas de usuário ao registro de aplicativo recém-criado usando $configObj variável de saída acima. Especifique o nome de usuário para a conta de usuário a ser configurada com o registro do aplicativo e especifique 'isAdmin' para permissões administrativas. Se a conta de usuário for nova, forneça a senha temporária para o novo usuário também. A senha precisa ser alterada no primeiro logon. Se você usar ''-remove'', removerá a conta de usuário, não apenas o registro do aplicativo.

SetupUser.ps1 exemplo de usuário (leitura)

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

SetupUser.ps1 exemplo de administrador (leitura/gravação)

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

SetupClusterResource.ps1

SetupClusterResource.ps1 pode ser usado opcionalmente para exportar o modelo do ARM de recurso de cluster existente, adicionar/modificar a configuração 'azureActiveDirectory' e reimplantar o modelo. Use '-Whatif' para apenas exportar e modificar o modelo, mas não reimplantar a alteração de configuração. Esse script exige o módulo 'Az' do Azure e o nome do grupo de recursos para cluster.

SetupClusterResource.ps1 -whatIf exemplo

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

Depois que o modelo for verificado e estiver pronto para ser processado, execute novamente o script sem '-WhatIf' ou use o commandlet do PowerShell 'New-AzResourceGroupDeployment' para implantar o modelo.

SetupClusterResource.ps1 exemplo

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

Concedendo consentimento do administrador

Pode ser necessário "Conceder consentimento do administrador" para as "permissões de API" que estão sendo configuradas. Navegue até a folha Registros do aplicativo Azure e adicione o nome do cluster ao filtro. Para ambos os registros, abra "Permissões de API" e selecione "Conceder consentimento do administrador" se disponível.

Verificar a configuração do Microsoft Entra

Navegue até a URL do SFX (Service Fabric Explorer). Isso deve ser o mesmo que o parâmetro spaApplicationReplyUrl. Uma caixa de diálogo de autenticação do Azure deve ser exibida. Faça logon com uma conta configurada com a nova configuração do Microsoft Entra. Verifique se a conta de administrador tem acesso de leitura/gravação e se o usuário tem acesso de leitura. Qualquer modificação no cluster, por exemplo, executando uma ação, é uma ação administrativa.

Ajuda para solução de problemas na configuração do Microsoft Entra ID

Configurar o Microsoft Entra ID e utilizá-lo poderá ser um desafio, então, aqui estão algumas dicas sobre o que é possível fazer para depurar o problema. O log de transcrição do PowerShell pode ser habilitado usando o argumento '-logFile' em scripts 'SetupApplications.ps1' e 'SetupUser.ps1' para examinar a saída.

Request_BadRequest

Problema

Não é uma atualização de referência válida. Código de status 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

As alterações de configuração não foram propagadas. Os scripts repetem determinadas solicitações com códigos de status HTTP 400 e 404.

Solução

Os scripts repetem novamente determinadas solicitações com os códigos de status HTTP 400 e 404 até o ''-timeoutMin'' fornecido, que, por padrão, é 5 minutos. O script pode ser executado novamente conforme necessário.

O Service Fabric Explorer solicita que você selecione um certificado

Problema

Após entrar com êxito no Microsoft Entra ID no Service Fabric Explorer, o navegador retornará à página inicial, mas, uma mensagem solicitará que você selecione um certificado.

Razão

O usuário não recebeu uma função no aplicativo de cluster do Microsoft Entra ID. Assim, a autenticação do Microsoft Entra falhará no cluster Service Fabric. O Service Fabric Explorer reverterá para autenticação de certificado.

Solução

Siga as instruções para configurar o Microsoft Entra ID e atribuir funções de usuário. Além disso, recomendamos que você habilite a "Atribuição de usuário necessária para acessar o aplicativo" da mesma forma feita por SetupApplications.ps1.

A conexão com o PowerShell falha e exibe o seguinte erro: “as credenciais especificadas são inválidas”

Problema

Quando você utiliza o PowerShell para conectar o cluster usando o modo de segurança "AzureActiveDirectory", após entrar com êxito no Microsoft Entra ID, a conexão falhará com um erro: "As credenciais especificadas são inválidas."

Solução

Essa solução é igual à anterior.

O Service Fabric Explorer retorna uma falha quando você entra: "AADSTS50011"

Problema

Ao tentar entrar no Microsoft Entra ID no Service Fabric Explorer, a página retornará uma falha: "AADSTS50011: a <url> do endereço de resposta não corresponde aos endereços de resposta configurados para o aplicativo: <guid>."

Razão

O aplicativo de cluster (Web) que representa o Service Fabric Explorer tenta se autenticar no Microsoft Entra ID e, como parte da solicitação, fornece a URL de retorno de redirecionamento. Mas o URL não está listado na lista URL DE RESPOSTA do aplicativo do Microsoft Entra.

Solução

Na página de registro do aplicativo do Microsoft Entra do cluster selecione Autenticação e, na seção Redirecionar URIs, adicione a URL do Service Fabric Explorer à lista. Salve sua alteração.

Conectar o cluster utilizando a autenticação do Microsoft Entra por meio do PowerShell gerará um erro ao entrar: "AADSTS50011"

Problema

Quando você tentar conectar um cluster do Service Fabric utilizando o Microsoft Entra ID por meio do PowerShell, a página de entrada retornará uma falha: "AADSTS50011: o URL de resposta especificado na solicitação não corresponde aos URLs de resposta configurados para o aplicativo: <guid>."

Motivo

Semelhante ao problema anterior, o PowerShell tentará fazer a autenticação no Microsoft Entra ID, que fornecerá uma URL de redirecionamento que não está na lista de URLs de resposta do aplicativo do Microsoft Entra.

Solução

Use o mesmo processo do problema anterior, mas desta vez a URL deve ser definida como urn:ietf:wg:oauth:2.0:oob, um redirecionamento especial para autenticação de linha de comando.

A execução do script resulta em erro no erro de autorização

Problema

O script do PowerShell poderá falhar ao executar todos os comandos REST necessários para concluir a configuração do Microsoft Entra com o erro "Authorization_RequestDenied","Privilégios insuficientes para concluir a operação". Erro de exemplo:

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

Esse erro é retornado quando a conta de usuário que executa o script não tem as permissões para executar a chamada REST. Isso poderá ocorrer se o usuário não tiver permissões de Administrador/Gerenciar/Gravar para os objetos que estão sendo criados ou modificados.

Solução

Trabalhe com um Administrador do locatário do Azure ou Microsoft Entra ID para concluir todas as ações restantes. Os scripts fornecidos são idempotentes, portanto, podem ser executados novamente para concluir o processo.

Conecte o cluster utilizando a autenticação Microsoft Entra por meio do PowerShell

Para se conectar ao cluster do Service Fabric, use o seguinte exemplo de comando do PowerShell:

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

Para saber mais, consulte o cmdlet Connect-ServiceFabricCluster.

É possível reutilizar o mesmo locatário do Microsoft Entra em vários clusters?

Sim. Mas lembre-se de adicionar a URL do Service Fabric Explorer ao aplicativo do cluster (Web). Caso contrário, o Service Fabric Explorer não funcionará.

Por que ainda é necessário ter um certificado de servidor enquanto o Microsoft Entra ID está habilitado?

FabricClient e FabricGateway realizam autenticação mútua. Durante a autenticação do Microsoft Entra, a integração do Microsoft Entra fornecerá uma identidade de cliente ao servidor e o certificado do servidor será utilizado pelo cliente para verificar a identidade do servidor. Para saber mais sobre certificados do Service Fabric, confira Certificados X.509 e Service Fabric.

Próximas etapas

Após configurar os aplicativos do Microsoft Entra e definir as funções dos usuários, configure e implante um cluster.