Partilhar via

Configurar o Microsoft Entra ID para autenticação de cliente

  • Artigo

Aviso

No momento, a autenticação do cliente Microsoft Entra e o Serviço de Token de Identidade Gerenciado são mutuamente incompatíveis no Linux.

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

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

Neste artigo, o termo "aplicativo" refere-se aos aplicativos Microsoft Entra, não aos aplicativos do Service Fabric, a distinção é 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 sua funcionalidade de gerenciamento, incluindo o Service Fabric Explorer baseado na Web e o Visual Studio. Como resultado, você criará dois aplicativos Microsoft Entra para controlar o acesso ao cluster: um aplicativo Web e um aplicativo nativo. Depois que os aplicativos forem criados, você atribuirá aos usuários funções somente leitura e administrador.

Nota

No momento, o Service Fabric não oferece suporte à autenticação do Microsoft Entra para armazenamento.

Nota

É um problema conhecido que aplicativos e nós em clusters habilitados para ID do Microsoft Entra Linux não podem ser exibidos no Portal do Azure.

Nota

O Microsoft Entra ID agora requer que um domínio de editores de aplicativo (registro de aplicativo) seja verificado ou o uso do esquema padrão. Consulte Configurar o domínio do editor de um aplicativo e o Uri do AppId em aplicativos de locatário único requer o uso do esquema padrão ou domínios verificados para obter informações adicionais.

Nota

A partir do Service Fabric 11.0, o Service Fabric Explorer requer um URI de redirecionamento de aplicativo de página única em vez de um URI de redirecionamento da Web.

Pré-requisitos

Neste artigo, assumimos que já criou um inquilino. Se ainda não o fez, comece por ler Como obter um inquilino do Microsoft Entra. Para simplificar algumas das etapas envolvidas na configuração da ID do Microsoft Entra com um cluster do Service Fabric, criamos um conjunto de scripts do Windows PowerShell. Algumas ações requerem acesso de nível administrativo ao Microsoft Entra ID. Se o script tiver um erro 'Authorization_RequestDenied' 401 ou 403, um administrador precisará executar o script.

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

Criar aplicativos 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 aplicativos para representar seu cluster, você criará usuários para as funções suportadas pelo Service Fabric: somente leitura e administrador.

SetupApplications.ps1

Execute SetupApplications.ps1 e forneça o ID do 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. Usando -logFile <log file path> gera um log de transcrição. Consulte a ajuda do script (help .\setupApplications.ps1 -full) para obter informações adicionais. O script cria os aplicativos Web e nativos para representar seu cluster do Service Fabric. As duas novas entradas de registro do aplicativo estão no seguinte formato:

  • ClusterName_Cluster
  • ClusterName_Client

Nota

Para nuvens nacionais (por exemplo, Azure Government, Microsoft Azure operado pela 21Vianet), você também deve especificar o -Location parâmetro.

Parâmetros

  • tenantId: Você pode encontrar seu TenantId executando o comando Get-AzureSubscriptionPowerShell . A execução deste comando exibe o TenantId para cada assinatura.

  • clusterName: ClusterName é usado para prefixar os aplicativos do Microsoft Entra que são criados pelo script. Ele 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 ID do Microsoft Entra retorna aos seus usuários depois que eles terminam de entrar. Defina esse ponto de extremidade como o ponto de extremidade do Service Fabric Explorer para seu cluster. Se estiver a criar aplicações Microsoft Entra para representar um cluster existente, certifique-se de que este URL corresponde ao ponto de extremidade do cluster existente. Se você estiver criando aplicativos para um novo cluster, planeje o ponto de extremidade para 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 URI usando o formato de esquema de API de API://{{tenant Id}}/{{cluster name}}. Consulte AppId Uri em aplicativos de locatário único requer o uso de esquema padrão ou domínios verificados para obter informações adicionais.

    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 produz $configObj variável para comandos subsequentes e imprime o JSON exigido pelo modelo do Azure Resource Manager. Copie a saída JSON e use ao criar ou modificar o cluster existente para criar seu cluster habilitado para ID do Microsoft Entra.

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

azureActiveDirectory parâmetros objeto JSON

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

SetupUser.ps1

SetupUser.ps1 é usado para adicionar contas de usuário ao registro do 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 '-remover', removerá a conta de usuário, não apenas o registro do aplicativo.

Exemplo de usuário SetupUser.ps1 (ler)

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

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

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

SetupClusterResource.ps1

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

Exemplo de SetupClusterResource.ps1 -whatIf

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

Quando o modelo tiver sido verificado e estiver pronto para ser processado, execute novamente o script sem '-WhatIf' ou use o commandlet powershell 'New-AzResourceGroupDeployment' para implantar o modelo.

Exemplo de SetupClusterResource.ps1

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

Nota

Atualize os modelos ou scripts ARM de provisionamento de cluster com as alterações de configuração do novo recurso de cluster Microsoft Entra.

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

Captura de ecrã que mostra a confirmação de consentimento de administrador Conceder com Sim realçado.

Verificando a configuração do Microsoft Entra

Navegue até a URL do Service Fabric Explorer (SFX). 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 usá-lo pode ser um desafio, então aqui estão algumas dicas sobre o que você pode fazer para depurar o problema. O log de transcrição do PowerShell pode ser habilitado usando o argumento '-logFile' nos scripts 'SetupApplications.ps1' e 'SetupUser.ps1' para revisar a saída.

Nota

Com a migração de plataformas de Identidades (ADAL para MSAL), a substituição do AzureRM em favor do Azure AZ e o suporte a várias versões do PowerShell, as dependências nem sempre estão corretas ou atualizadas, causando erros na execução do script. A execução de comandos e scripts do PowerShell a partir do Azure Cloud Shell reduz o potencial de erros com autenticação automática de sessão e identidade gerenciada.

Botão para iniciar o Azure Cloud Shell.

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

Razão

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

Solução

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

O Service Fabric Explorer solicita que você selecione um certificado

Problema

Depois de entrar com êxito na ID do Microsoft Entra no Service Fabric Explorer, o navegador retorna à home page, mas uma mensagem solicita que você selecione um certificado.

Caixa de diálogo de certificado SFX

Razão

O usuário não recebe uma função no aplicativo de cluster Microsoft Entra ID. Assim, a autenticação do Microsoft Entra falha no cluster do Service Fabric. O Service Fabric Explorer retorna à 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ê ative "Atribuição de usuário necessária para acessar o aplicativo", assim como SetupApplications.ps1 faz.

A conexão com o PowerShell falha com um erro: "As credenciais especificadas são inválidas"

Problema

Quando você usa o PowerShell para se conectar ao cluster usando o modo de segurança "AzureActiveDirectory", depois de entrar com êxito na ID do Microsoft Entra, a conexão falha com um erro: "As credenciais especificadas são inválidas".

Solução

Esta solução é a mesma que a anterior.

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

Problema

Quando você tenta entrar no ID do Microsoft Entra no Service Fabric Explorer, a página retorna uma falha: "AADSTS50011: A URL do endereço <de resposta não corresponde aos endereços de resposta configurados para o aplicativo: <guid>.">

O endereço de resposta SFX não corresponde

Razão

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

Solução

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

URL de resposta do aplicativo Web

Conectar-se ao cluster usando a autenticação do Microsoft Entra via PowerShell dá um erro quando você entra: "AADSTS50011"

Problema

Quando você tenta se conectar a um cluster do Service Fabric usando a ID do Microsoft Entra via PowerShell, a página de entrada retorna uma falha: "AADSTS50011: A URL de resposta especificada na solicitação não corresponde às urls de resposta configuradas para o aplicativo: <guid>."

Razão

Semelhante ao problema anterior, o PowerShell tenta autenticar no Microsoft Entra ID, que fornece uma URL de redirecionamento que não está listada na lista URLs de resposta do aplicativo Microsoft Entra.

Solução

Use o mesmo processo da edição anterior, mas 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 pode 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". Exemplo de erro:

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

Razão

Este erro é retornado quando a conta de usuário que executa o script não tem as permissões para executar a chamada REST. Isso pode 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 ID do Microsoft Entra para concluir todas as ações restantes. Os scripts fornecidos são idempotentes, para que possam ser reexecutados para concluir o processo.

Conectar o cluster usando a autenticação do Microsoft Entra via PowerShell

Para conectar o 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 Cmdlet Connect-ServiceFabricCluster.

Posso 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 seu aplicativo de cluster (Web). Caso contrário, o Service Fabric Explorer não funcionará.

Por que ainda preciso de um certificado de servidor enquanto o Microsoft Entra ID está habilitado?

FabricClient e FabricGateway executam uma autenticação mútua. Durante a autenticação do Microsoft Entra, a integração do Microsoft Entra fornece uma identidade de cliente para o servidor e o certificado do servidor é usado pelo cliente para verificar a identidade do servidor. Para obter mais informações sobre certificados do Service Fabric, consulte Certificados X.509 e Service Fabric.

Próximos passos

Depois de configurar aplicativos Microsoft Entra e definir funções para usuários, configure e implante um cluster.