Configuración de Microsoft Entra ID para la autenticación de cliente

  • Artículo

Advertencia

En este momento, la autenticación de cliente de Microsoft Entra y el servicio de token de identidad administrada son mutuamente incompatibles en Linux.

Para los clústeres que se ejecutan en Azure, se recomienda Microsoft Entra ID para proteger el acceso a los extremos de administración. Este artículo se describe cómo configurar Microsoft Entra ID para autenticar clientes para un clúster de Service Fabric.

En Linux, debe realizar los pasos siguientes antes de crear el clúster. En Windows, también tiene la opción de configurar la autenticación de Microsoft Entra para un clúster existente.

En este artículo, el término "aplicación" hace referencia a aplicaciones de Microsoft Entra, no a las aplicaciones de Service Fabric; la distinción se realiza cuando sea necesario. Microsoft Entra ID permite a las organizaciones (conocidas como inquilinos) administrar el acceso de los usuarios a las aplicaciones.

Un clúster de Service Fabric ofrece diversos puntos de entrada a su funcionalidad de administración, como Service Fabric Explorer y Visual Studio basados en web. Como consecuencia, creará dos aplicaciones de Microsoft Entra para controlar el acceso al clúster: una aplicación web y una aplicación nativa. Una vez creadas las aplicaciones, asignará a los usuarios los roles de solo lectura y de administrador.

Nota:

En este momento, Service Fabric no admite la autenticación de Microsoft Entra para el almacenamiento.

Nota:

Es un problema conocido que las aplicaciones y los nodos en clústeres Linux habilitados para Microsoft Entra ID no se pueden ver en Azure Portal.

Nota:

Microsoft Entra ID ahora requiere que un dominio de publicadores de aplicación (registro de aplicaciones) se compruebe o use el esquema predeterminado. Para obtener información adicional, consulte Configuración del dominio del publicador de una aplicación y El URI de AppId en aplicaciones de inquilino único require el uso de un esquema predeterminado o dominios verificados.

Nota:

A partir de Service Fabric 11.0, Service Fabric Explorer necesita un URI de redirección de aplicación de página única en lugar de un URI de redirección web.

Requisitos previos

En este artículo se supone que ya ha creado un inquilino. Si no lo ha hecho, lea Cómo obtener un inquilinode Microsoft Entra. Para simplificar algunos de los pasos necesarios para configurar Microsoft Entra ID con un clúster de Service Fabric, hemos creado un conjunto de scripts de Windows PowerShell. Algunas acciones requieren acceso de nivel administrativo a Microsoft Entra ID. Si el script experimenta un error 401 o 403 "Authorization_RequestDenied", un administrador debe ejecutar el script.

  1. Autenticarse con permisos administrativos de Azure.
  2. Clone el repositorio en su equipo.
  3. Asegúrese de cumplir todos los requisitos previos para los scripts instalados.

Creación de aplicaciones de Microsoft Entra y asignación de usuarios a roles

Usaremos los scripts para crear dos aplicaciones de Microsoft Entra para controlar el acceso al clúster: una aplicación web y una aplicación nativa. Una vez que cree las aplicaciones para representar el clúster, creará usuarios para los roles compatibles con Service Fabric: solo lectura y administrador.

SetupApplications.ps1

Ejecute SetupApplications.ps1 y proporcione como parámetros el id. de inquilino, el nombre del clúster, el URI de la aplicación web y la dirección URL de respuesta de la aplicación web. Use -remove para quitar los registros de aplicaciones. El uso de -logFile <log file path> genera un registro de transcripción. Para obtener más información, consulte la ayuda del script (help .\setupApplications.ps1 -full). El script crea las aplicaciones web y nativas para representar el clúster de Service Fabric. Las dos nuevas entradas de registro de aplicaciones tendrán el siguiente formato:

  • ClusterName_Cluster
  • ClusterName_Client

Nota:

Para nubes nacionales (por ejemplo, Azure Government, Microsoft Azure operado por 21Vianet), también debe especificar el parámetro -Location.

Parámetros

  • tenantId: puede ejecutar el comando Get-AzureSubscription de PowerShell para encontrar su TenantId. Al ejecutar este comando se muestra el valor de TenantId para cada suscripción.

  • clusterName:ClusterName se usa para prefijar las aplicaciones de Microsoft Entra creadas por el script. No es necesario que coincida exactamente con el nombre del clúster real. Solo está pensado para facilitar la asignación de artefactos de Microsoft Entra al clúster de Service Fabric con el que se usan.

  • SpaApplicationReplyUrl:SpaApplicationReplyUrl es el punto de conexión predeterminado que Microsoft Entra ID devuelve a los usuarios cuando finalizan el inicio de sesión. Establézcalo como el punto de conexión de Service Fabric Explorer para el clúster. Si va a crear aplicaciones de Microsoft Entra para representar un clúster existente, asegúrese de que esta dirección URL coincide con el punto de conexión del clúster existente. Si va a crear aplicaciones para un nuevo clúster, planifique el punto de conexión para el clúster y asegúrese de no usar el punto de conexión de un clúster existente. De manera predeterminada, el punto de conexión Service Fabric Explorer es: https://<cluster_domain>:19080/Explorer/index.html

  • webApplicationUri:WebApplicationUri es el URI de un "dominio comprobado" o el URI que usa el formato de esquema de la API de API://{{id. de inquilino}}/{{nombre de clúster}}. Para más información, consulte El URI AppId en aplicaciones de inquilino único requiere el uso del esquema predeterminado o los dominios comprobados.

    Esquema de API de ejemplo: API://0e3d2646-78b3-4711-b8be-74a381d9890c/mysftestcluster

Ejemplo 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

El script genera la variable $configObj para los comandos posteriores e imprime el JSON que requiere la plantilla de Azure Resource Manager. Copie la salida JSON y úselo al crear o modificar el clúster existente crear el clúster habilitado para Microsoft Entra ID.

Salida de ejemplo 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"
},

JSON del objeto de parámetros de azureActiveDirectory

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

SetupUser.ps1

SetupUser.ps1 se usa para agregar cuentas de usuario al registro de aplicaciones recién creado mediante la variable de salida $configObj anterior. Especifique el nombre de usuario de la cuenta de usuario que se va a configurar con el registro de aplicaciones e "isAdmin" para los permisos administrativos. Si la cuenta de usuario es nueva, proporcione también la contraseña temporal para el nuevo usuario. La contraseña debe cambiarse en el primer inicio de sesión. Si usa "-remove", quitará la cuenta de usuario, no solo el registro de la aplicación.

Ejemplo de usuario de SetupUser.ps1 (lectura)

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

Ejemplo de administrador de SetupUser.ps1 (lectura y escritura)

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

SetupClusterResource.ps1

SetupClusterResource.ps1 se puede usar de manera opcional para exportar la plantilla de ARM del recurso de clúster existente, agregar o modificar la configuración de "azureActiveDirectory", así como volver a implementar la plantilla. Use "-Whatif" solo para exportar y modificar la plantilla, pero no para volver a implementar el cambio de configuración. Este script necesita el módulo "Az" de Azure y el nombre del grupo de recursos para el clúster.

Ejemplo de SetupClusterResource.ps1 -whatIf

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

Una vez se haya comprobado la plantilla y esté lista para procesarse, vuelva a ejecutar el script sin "-WhatIf" o use el commandlet de PowerShell "New-AzResourceGroupDeployment" para implementar la plantilla.

Ejemplo de SetupClusterResource.ps1

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

Nota:

Actualice las plantillas o scripts de ARM de aprovisionamiento de clústeres con los nuevos cambios de configuración de Microsoft Entra de recurso de clúster.

Es posible que sea necesario "Conceder el consentimiento del administrador" para que se configuren los "permisos de API". Vaya a la hoja Registros de aplicaciones de Azure y agregue el nombre del clúster al filtro. Para ambos registros, abra "Permisos de API" y, si está disponible, seleccione "Conceder consentimiento del administrador para".

Screenshot that shows Grant admin consent selected on the Azure App registrations blade.

Screenshot that shows the Grant admin consent confirmation with Yes highlighted.

Comprobación de la configuración de Microsoft Entra

Vaya a la dirección URL de Service Fabric Explorer (SFX). Debe ser el mismo que el parámetro spaApplicationReplyUrl. Se debe mostrar un cuadro de diálogo de autenticación de Azure. Inicie sesión con una cuenta configurada con la nueva configuración de Microsoft Entra. Compruebe que la cuenta de administrador tiene acceso de lectura y escritura y que el usuario tiene acceso de lectura. Cualquier modificación del clúster, por ejemplo, la realización de una acción, es una acción administrativa.

Solución de problemas de ayuda para configurar el Microsoft Entra ID

Configurar Microsoft Entra ID y al usarlo puede ser difícil, por lo que estos son algunos punteros sobre lo que puede hacer para depurar el problema. El registro de transcripciones de PowerShell se puede habilitar mediante el argumento "-logFile" en los scripts "SetupApplications.ps1" y "SetupUser.ps1" para revisar la salida.

Nota:

Con la migración de plataformas de identidades (ADAL a MSAL), el desuso de AzureRM en favor de Azure AZ y la compatibilidad con varias versiones de PowerShell, es posible que las dependencias no siempre sean correctas o estén actualizadas, lo que provoca errores en la ejecución del script. La ejecución de comandos y scripts de PowerShell desde Azure Cloud Shell reduce la posibilidad de errores con la autenticación automática de sesión y la identidad administrada.

Button to launch the Azure Cloud Shell.

Request_BadRequest

Problema

No es una actualización de referencia válida. Código de estado 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

Los cambios de configuración no se han propagado. Los scripts reintentan determinadas solicitudes con códigos de estado HTTP 400 y 404.

Solución

Los scripts reintentan determinadas solicitudes con los códigos de estado HTTP 400 y 404 hasta que se proporcione "-timeoutMin", que es 5 minutos de manera predeterminada. El script se puede volver a ejecutar según sea necesario.

Service Fabric Explorer le solicita que seleccione el certificado

Problema

Después de conectarse correctamente a Microsoft Entra ID en Service Fabric Explorer, el explorador vuelve a la página principal, pero un mensaje le pide que seleccione un certificado.

SFX certificate dialog

Motivo

El usuario no tiene asignado un rol en la aplicación de clúster de Microsoft Entra ID. Por lo tanto, se produce un error en la autenticación de Microsoft Entra en el clúster de Service Fabric. Service Fabric Explorer recurre a la autenticación de certificado.

Solución

Siga las instrucciones de configuración de Microsoft Entra ID y de asignación de roles de usuario. Además, se recomienda activar "Asignación de usuario necesaria para acceder a la aplicación", como hace SetupApplications.ps1.

La conexión con PowerShell genera un error: "Las credenciales especificadas no son válidas".

Problema

Al utilizar PowerShell para conectarse al clúster utilizando el modo de seguridad "AzureActiveDirectory", después de iniciar sesión de manera correcta en Microsoft Entra ID, la conexión da error: "Las credenciales especificadas no son válidas".

Solución

Esta solución es la mismo que la anterior.

Service Fabric Explorer devuelve un error al iniciar sesión: "AADSTS50011"

Problema

Al intentar iniciar sesión en Microsoft Entra ID en Service Fabric Explorer, la página devuelve un error: "AADSTS50011: la dirección de respuesta <dirección URL> no coincide con las direcciones de respuesta configuradas para la aplicación: <guid>".

SFX reply address doesn't match

Motivo

La aplicación de clúster (web) que representa Service Fabric Explorer intenta autenticarse en Microsoft Entra ID, y como parte de la solicitud, proporciona la dirección URL de retorno de redirección. Pero no aparece en la lista URL DE RESPUESTA de la aplicación Microsoft Entra.

Solución

En la página de registro de la aplicación Microsoft Entra para su clúster, seleccione Autenticación, y en la sección Redirigir direcciones URI, agregue la dirección URL del Service Fabric Explorer a la lista. Guarde el cambio.

Web application reply URL

Conectarse al clúster mediante la autenticación de Microsoft Entra a través de PowerShell produce un error al iniciar sesión: "AADSTS50011"

Problema

Al intentar conectarse a un clúster de Service Fabric mediante Microsoft Entra ID a través de PowerShell, la página de inicio de sesión devuelve un error: "AADSTS50011: la dirección URL de respuesta especificada en la solicitud no coincide con las direcciones URL de respuesta configuradas para la aplicación: <guid>".

Motivo

De forma similar al problema anterior, PowerShell intenta autenticarse en Microsoft Entra ID, que proporciona una dirección URL de redireccionamiento que no aparece en la aplicación Microsoft Entra lista de Direcciones URL de RESPUESTA.

Solución

Use el mismo proceso que en el problema anterior, pero establezca la dirección URL en urn:ietf:wg:oauth:2.0:oob (un redireccionamiento especial para la autenticación de la línea de comandos).

La ejecución del script da lugar a un error de autorización

Problema

Es posible que el script PowerShell no pueda ejecutar todos los comandos REST necesarios para completar la configuración de Microsoft Entra con el error "Authorization_RequestDenied", "Privilegios insuficientes para completar la operación". Ejemplo de error:

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

Este error se devuelve cuando la cuenta de usuario que ejecuta el script no tiene los permisos para realizar la llamada DE REST. Esto puede ocurrir en el caso de que el usuario no tenga permisos de administrador, administración o escritura para los objetos que se crean o modifican.

Solución

Colabore con un administrador de Azure inquilino o Microsoft Entra ID para completar todas las acciones restantes. Los scripts proporcionados son idempotentes, por lo que se pueden volver a ejecutar para completar el proceso.

Conexión del clúster mediante la autenticación de Microsoft Entra mediante PowerShell

Para conectar el clúster de Service Fabric, use el siguiente ejemplo de comando de PowerShell:

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

Para obtener más información, consulte el cmdlet Connect-ServiceFabricCluster.

¿Se puede reutilizar el mismo inquilino de Microsoft Entra para varios clústeres?

Sí. Pero recuerde agregar la dirección URL de Service Fabric Explorer a la aplicación del clúster (web). De lo contrario, Service Fabric Explorer no funciona.

¿Por qué todavía necesito el certificado de servidor con Microsoft Entra ID habilitado?

FabricClient y FabricGateway realizan una autenticación mutua. En el proceso de autenticación de Microsoft Entra, la integración de Microsoft Entra proporciona una identidad de cliente al servidor, y el certificado del servidor es utilizado por el cliente para verificar la identidad del servidor. Para más información sobre cómo funciona el certificado en Service Fabric, consulte Certificados X.509 y Service Fabric.

Pasos siguientes

Después de configurar las aplicaciones de Microsoft Entra y establecer los roles para los usuarios, configure e implemente un clúster.