Creación de gMSA para contenedores de Windows

Artículo
02/05/2025

Se aplica a: Windows Server 2025, Windows Server 2022, Windows Server 2019

Las redes basadas en Windows suelen usar Active Directory (AD) para facilitar la autenticación y autorización entre usuarios, equipos y otros recursos de red. Los desarrolladores de aplicaciones empresariales suelen diseñar sus aplicaciones para que se integren en AD y se ejecuten en servidores unidos a un dominio para aprovechar la autenticación integrada de Windows, lo que facilita a los usuarios y otros servicios iniciar sesión automáticamente y de forma transparente en la aplicación con sus identidades. En este artículo se explica cómo empezar a usar cuentas de servicio administradas de grupo de Active Directory con contenedores de Windows.

Aunque los contenedores de Windows no pueden estar unidos a un dominio, todavía pueden usar identidades de dominio de Active Directory para admitir varios escenarios de autenticación. Para ello, puede configurar un contenedor de Windows para que se ejecute con una cuenta de servicio administrada de grupo (gMSA), que es un tipo especial de cuenta de servicio introducida en Windows Server 2012 y diseñada para permitir que varios equipos compartan una identidad sin necesidad de conocer su contraseña. Los contenedores de Windows no se pueden unir a un dominio, pero muchas aplicaciones de Windows que se ejecutan en contenedores de Windows todavía necesitan autenticación de AD. Para usar la autenticación de AD, puede configurar un contenedor de Windows para que se ejecute con una cuenta de servicio administrada de grupo (gMSA).

Cuando se introdujo gMSA para contenedores de Windows inicialmente, requería que el host de contenedor estuviera unido a un dominio, lo que creó una gran sobrecarga para que los usuarios unan manualmente nodos de trabajo de Windows a un dominio. Esta limitación se ha solucionado con la compatibilidad de gMSA para contenedores de Windows con hosts de contenedor no unidos a un dominio. Continuaremos admitiendo la funcionalidad de gMSA original para usar un host de contenedor unido a un dominio.

Entre las mejoras de gMSA al usar un host de contenedor no unido a un dominio se incluyen:

El requisito de unir manualmente nodos de trabajo de Windows a un dominio se elimina porque provocó una gran sobrecarga para los usuarios. Para escenarios de escalado, el uso de un host de contenedor no unido a un dominio simplifica el proceso.
En escenarios de actualización gradual, los usuarios ya no deben volver a unir el nodo a un dominio.
La administración de las cuentas de máquina del nodo de trabajo para recuperar contraseñas de cuenta de servicio gMSA es un proceso más sencillo.
La configuración de gMSA con Kubernetes es un proceso de un extremo a otro menos complicado.

Nota

Para obtener información sobre cómo la comunidad de Kubernetes admite el uso de gMSA con contenedores de Windows, consulte configuración de gMSA.

Arquitectura y mejoras de gMSA

Para abordar las limitaciones de la implementación inicial de gMSA para contenedores de Windows, la nueva compatibilidad con gMSA para hosts de contenedor no unidos a un dominio usa una identidad de usuario portátil en lugar de una cuenta de equipo host para recuperar las credenciales de gMSA. Por lo tanto, la unión manual de nodos de trabajo de Windows a un dominio ya no es necesaria, aunque todavía se admite. La identidad o credenciales de usuario se almacenan en un almacén de secretos accesible para el host de contenedor (por ejemplo, como un secreto de Kubernetes) donde los usuarios autenticados pueden recuperarlo.

Diagrama de cuentas de servicio administradas de grupo versión dos

La compatibilidad de gMSA con hosts de contenedor no unidos a un dominio proporciona la flexibilidad de crear contenedores con gMSA sin unir el nodo host al dominio. A partir de Windows Server 2019, se admite ccg.exe que permite que un mecanismo de complemento recupere las credenciales de gMSA de Active Directory. Puede usar esa identidad para iniciar el contenedor. Para obtener más información sobre este mecanismo de complemento, consulte la interfaz ICcgDomainAuthCredentials.

Nota

En Azure Kubernetes Service en Azure Stack HCI, puede usar el complemento para comunicarse desde ccg.exe a AD y, a continuación, recuperar las credenciales de gMSA. Para más información, vea Configuración de cuentas de servicio administrado de grupo con AKS en Azure Stack HCI.

Vea el diagrama siguiente para seguir los pasos del proceso de Container Credential Guard:

Con un archivo CredSpec como entrada, el proceso de ccg.exe se inicia en el host del nodo.
ccg.exe usa información del archivo CredSpec para iniciar un complemento y, después, recuperar las credenciales de la cuenta en el almacén de secretos asociado al complemento.
ccg.exe usa las credenciales de cuenta recuperadas para recuperar la contraseña de gMSA de AD.
ccg.exe hace que la contraseña de gMSA esté disponible para un contenedor que haya solicitado credenciales.
El contenedor se autentica en el controlador de dominio usando la contraseña gMSA para obtener un ticket Kerberos Ticket-Granting (TGT).
Las aplicaciones que se ejecutan como servicio de red o sistema local en el contenedor ahora pueden autenticarse y acceder a recursos de dominio, como gMSA.

diagrama de

Prerrequisitos

Para ejecutar un contenedor de Windows con una cuenta de servicio administrada de grupo, necesitará lo siguiente:

Un dominio de Active Directory con al menos un controlador de dominio que ejecute Windows Server 2012 o posterior. No hay ningún requisito de nivel funcional de bosque o dominio para usar gMSAs, pero las contraseñas de gMSAs solo pueden ser distribuidas por controladores de dominio que ejecuten Windows Server 2012 o una versión posterior. Para más información, vea Requisitos de Active Directory para gMSA.
Permiso para crear una cuenta de gMSA. Para crear una cuenta de gMSA, deberá ser Administrador de Dominios o usar una cuenta a la que se le haya delegado el permiso Crear objetos msDS-GroupManagedServiceAccount.
Acceso a Internet para descargar el módulo de PowerShell CredentialSpec. Si trabaja en un entorno desconectado, puede guardar el módulo en un equipo con acceso a Internet y copiarlo en el equipo de desarrollo o host del contenedor.

Preparación única de Active Directory

Si aún no ha creado una gMSA en el dominio, deberá generar la clave raíz del Servicio de distribución de claves (KDS). KDS es responsable de crear, rotar y liberar la contraseña de gMSA a hosts autorizados. Cuando un host de contenedor necesite usar la gMSA para ejecutar un contenedor, se pondrá en contacto con el KDS para recuperar la contraseña actual.

Para comprobar si ya se ha creado la clave raíz de KDS, ejecute el siguiente cmdlet de PowerShell como administrador de dominio en un controlador de dominio o miembro de dominio con las herramientas de PowerShell de AD instaladas:

Get-KdsRootKey

Si el comando devuelve un identificador de clave, todos están configurados y pueden ir directamente a la sección crear una cuenta de servicio administrada de grupo. De lo contrario, continúe para crear la clave raíz de KDS.

Importante

Solo debe crear una clave raíz de KDS por bosque. Si se crean varias claves raíz de KDS, se empezarán a producir errores en la gMSA después de cambiar su contraseña.

En un entorno de producción o en un entorno de prueba con varios controladores de dominio, ejecute el siguiente cmdlet en PowerShell como administrador de dominio para crear la clave raíz de KDS.

# For production environments
Add-KdsRootKey -EffectiveImmediately

Aunque el comando implica que la clave será efectiva inmediatamente, deberá esperar 10 horas antes de que se replique la clave raíz KDS y esté disponible para su uso en todos los controladores de dominio.

Si solo tiene un controlador de dominios en su dominio, puede agilizar el proceso estableciendo que la clave sea efectiva desde hace 10 horas.

Importante

No use esta técnica en un entorno de producción.

# For single-DC test environments only
Add-KdsRootKey -EffectiveTime (Get-Date).AddHours(-10)

Creación de una cuenta de servicio administrada de grupo

Cada contenedor que usa autenticación integrada de Windows necesita al menos una gMSA. La gMSA principal se usa cada vez que las aplicaciones que se ejecutan como un sistema o un servicio de red acceden a los recursos de la red. El nombre de la gMSA se convertirá en el nombre del contenedor en la red, independientemente del nombre de host asignado al contenedor. Los contenedores también se pueden configurar con gMSA adicionales, en caso de que quiera ejecutar un servicio o una aplicación en el contenedor como una identidad diferente de la cuenta de equipo contenedor.

Al crear una gMSA, también se crea una identidad compartida que se puede usar simultáneamente en muchas máquinas diferentes. El acceso a la contraseña de gMSA está protegido por una lista de control de acceso de Active Directory. Se recomienda crear un grupo de seguridad para cada cuenta de gMSA y agregar los hosts de contenedor pertinentes al grupo de seguridad para limitar el acceso a la contraseña.

Por último, dado que los contenedores no registran automáticamente ningún Service Principal Name (SPN), deberá crear manualmente al menos un SPN de host para la cuenta de gMSA.

Normalmente, el host o el SPN http se registran con el mismo nombre que la cuenta de gMSA, pero es posible que tenga que usar otro nombre de servicio si los clientes acceden a la aplicación contenedorizada desde detrás de un equilibrador de carga o un nombre DNS distinto del nombre de gMSA.

Por ejemplo, si la cuenta gMSA se llama "WebApp01", pero los usuarios acceden al sitio en mysite.contoso.com, debe registrar un SPN de http/mysite.contoso.com en la cuenta gMSA.

Algunas aplicaciones pueden requerir SPN adicionales para sus protocolos únicos. Por ejemplo, SQL Server requiere el SPN de MSSQLSvc/hostname.

En la tabla siguiente se enumeran los atributos necesarios para crear una gMSA.

Propiedad gMSA	Valor obligatorio	Ejemplo
Nombre	Cualquier nombre de cuenta válido.	`WebApp01`
DnsHostName	Nombre de dominio anexado al nombre de cuenta.	`WebApp01.contoso.com`
ServicePrincipalNames	Establezca al menos el SPN de host y agregue otros protocolos según sea necesario.	`'host/WebApp01', 'host/WebApp01.contoso.com'`
PrincipalsAllowedToRetrieveManagedPassword	El grupo de seguridad que contiene los hosts de contenedor.	`WebApp01Hosts`

Una vez que haya decidido el nombre de la gMSA, ejecute los siguientes cmdlets en PowerShell para crear el grupo de seguridad y gMSA.

Sugerencia

Tendrá que usar una cuenta que pertenezca al grupo de seguridad de administradores de dominio o que tenga delegado el permiso Crear objetos msDS-GroupManagedServiceAccount para ejecutar los siguientes comandos. El cmdlet New-ADServiceAccount forma parte de las herramientas de PowerShell de AD de Herramientas de administración remota del servidor.

Se recomienda crear cuentas de gMSA independientes para los entornos de desarrollo, prueba y producción.

Caso de uso para crear una cuenta de gMSA para hosts de contenedor unidos a un dominio

# Replace 'WebApp01' and 'contoso.com' with your own gMSA and domain names, respectively.

# To install the AD module on Windows Server, run Install-WindowsFeature RSAT-AD-PowerShell
# To install the AD module on Windows 10 version 1809 or later, run Add-WindowsCapability -Online -Name 'Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0'
# To install the AD module on older versions of Windows 10, see https://aka.ms/rsat

# Create the security group
New-ADGroup -Name "WebApp01 Authorized Hosts" -SamAccountName "WebApp01Hosts" -GroupScope DomainLocal

# Create the gMSA
New-ADServiceAccount -Name "WebApp01" -DnsHostName "WebApp01.contoso.com" -ServicePrincipalNames "host/WebApp01", "host/WebApp01.contoso.com" -PrincipalsAllowedToRetrieveManagedPassword "WebApp01Hosts"

# Add your container hosts to the security group
Add-ADGroupMember -Identity "WebApp01Hosts" -Members "ContainerHost01$", "ContainerHost02$", "ContainerHost03$"

Caso de uso para crear una cuenta de gMSA para hosts de contenedor no unidos a un dominio

Al usar gMSA para contenedores con hosts no unidos a un dominio, en lugar de agregar hosts de contenedor al grupo de seguridad WebApp01Hosts, cree y agregue una cuenta de usuario estándar.

# Replace 'WebApp01' and 'contoso.com' with your own gMSA and domain names, respectively.

# To install the AD module on Windows Server, run Install-WindowsFeature RSAT-AD-PowerShell
# To install the AD module on Windows 10 version 1809 or later, run Add-WindowsCapability -Online -Name 'Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0'
# To install the AD module on older versions of Windows 10, see https://aka.ms/rsat

# Create the security group
New-ADGroup -Name "WebApp01 Authorized Accounts" -SamAccountName "WebApp01Accounts" -GroupScope DomainLocal

# Create the gMSA
New-ADServiceAccount -Name "WebApp01" -DnsHostName "WebApp01.contoso.com" -ServicePrincipalNames "host/WebApp01", "host/WebApp01.contoso.com" -PrincipalsAllowedToRetrieveManagedPassword "WebApp01Accounts"

# Create the standard user account. This account information needs to be stored in a secret store and will be retrieved by the ccg.exe hosted plug-in to retrieve the gMSA password. Replace 'StandardUser01' and 'p@ssw0rd' with a unique username and password. We recommend using a random, long, machine-generated password.
New-ADUser -Name "StandardUser01" -AccountPassword (ConvertTo-SecureString -AsPlainText "p@ssw0rd" -Force) -Enabled 1

# Add your container hosts to the security group
Add-ADGroupMember -Identity "WebApp01Accounts" -Members "StandardUser01"

Preparación del host de contenedor

Caso de uso para preparar el host de contenedor para un host de contenedor unido a un dominio

Cada host de contenedor que ejecutará un contenedor de Windows con una gMSA debe estar unido a un dominio y tener acceso para recuperar la contraseña de gMSA.

Une el equipo al dominio de Active Directory.
Asegúrese de que el host pertenece al grupo de seguridad que controla el acceso a la contraseña de gMSA.
Reinicie el equipo para obtener su nueva pertenencia al grupo.
Configure Docker Desktop para Windows 10 o Docker Desktop para Windows Server.

(Recomendado) Compruebe que el host puede usar la cuenta de gMSA ejecutando Test-ADServiceAccount. Si el comando devuelve False, siga las instrucciones de solución de problemas de .

# To install the AD module on Windows Server, run Install-WindowsFeature RSAT-AD-PowerShell
# To install the AD module on Windows 10 version 1809 or later, run Add-WindowsCapability -Online -Name 'Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0'
# To install the AD module on older versions of Windows 10, see https://aka.ms/rsat

Test-ADServiceAccount WebApp01

Caso de uso para preparar el host de contenedor para un host de contenedor que no esté unido a un dominio

Al usar gMSA para contenedores de Windows en hosts de contenedor no unidos a un dominio, cada host de contenedor debe tener un complemento para ccg.exe instalado, que se usará para recuperar la cuenta de usuario portátil y las credenciales especificadas en el paso anterior. Los complementos son exclusivos del almacén de secretos utilizado para proteger las credenciales de cuentas de usuario portátiles. Por ejemplo, se necesitarían complementos diferentes para almacenar las credenciales de cuenta en Azure Key Vault frente a en un almacén de secretos de Kubernetes.

Windows no ofrece actualmente un complemento predeterminado integrado. Las instrucciones de instalación de los complementos serán específicas de la implementación. Para obtener más información sobre cómo crear y registrar complementos para ccg.exe, consulte interfaz ICcgDomainAuthCredentials.

Creación de una especificación de credenciales

Un archivo de especificación de credenciales es un documento JSON que contiene metadatos sobre las cuentas de gMSA que desea que use un contenedor. Al mantener la configuración de identidad independiente de la imagen de contenedor, puede cambiar qué gMSA usa el contenedor simplemente intercambiando el archivo de especificación de credenciales, no es necesario realizar ningún cambio en el código.

El archivo de especificación de credenciales se crea mediante el módulo de PowerShell credentialSpec de en una máquina unida a un dominio. Una vez creado el archivo, puede copiarlo en otros hosts de contenedor o en el orquestador de contenedores. El archivo de especificación de credenciales no contiene ningún secreto, como la contraseña de gMSA, ya que el host del contenedor recupera la gMSA en nombre del contenedor.

Docker espera encontrar el archivo de especificación de credenciales en el directorio CredentialSpecs en el directorio de datos de Docker. En una instalación predeterminada, encontrará esta carpeta en C:\ProgramData\Docker\CredentialSpecs.

Para crear un archivo de especificación de credenciales en el host de contenedor:

Instalación de las herramientas de PowerShell de RSAT AD
- Para Windows Server, ejecute Install-WindowsFeature RSAT-AD-PowerShell.
- Para Windows 10, versión 1809 o posterior, ejecute Add-WindowsCapability -Online -Name "Rsat.ActiveDirectory.DS-LDS.Tools~~~0.0.1.0".
- Para versiones anteriores de Windows 10, consulta https://aka.ms/rsat.
Ejecute el siguiente cmdlet para instalar la versión más reciente del módulo CredentialSpec de PowerShell:
```
Install-Module CredentialSpec
```
Si no tiene acceso a Internet en el host de contenedor, ejecute Save-Module CredentialSpec en un equipo conectado a Internet y copie la carpeta del módulo en C:\Program Files\WindowsPowerShell\Modules o en otra ubicación en $env:PSModulePath en el host del contenedor.
Ejecute el siguiente cmdlet para crear el nuevo archivo de especificación de credenciales:
```
# Replace 'WebApp01' with your own gMSA
New-CredentialSpec -AccountName WebApp01
```
De forma predeterminada, el cmdlet creará una especificación de credenciales con el nombre de gMSA proporcionado como la cuenta de equipo del contenedor. El archivo se guardará en el directorio CredentialSpecs de Docker, utilizando el dominio gMSA y el nombre de cuenta como nombre de archivo.

Si desea guardar el archivo en otro directorio, use el parámetro -Path:
```
New-CredentialSpec -AccountName WebApp01 -Path "C:\MyFolder\WebApp01_CredSpec.json"
```
También puede crear una especificación de credenciales que incluya cuentas de gMSA adicionales si ejecuta un servicio o proceso como una gMSA secundaria en el contenedor. Para ello, use el parámetro -AdditionalAccounts:
```
New-CredentialSpec -AccountName WebApp01 -AdditionalAccounts LogAgentSvc, OtherSvc
```
Para obtener una lista completa de los parámetros admitidos, ejecute Get-Help New-CredentialSpec -Full.
Puede mostrar una lista de todas las especificaciones de credenciales y su ruta de acceso completa con el siguiente cmdlet:
```
Get-CredentialSpec
```

Este es un ejemplo de una especificación de credenciales:

{
    "CmsPlugins": [
        "ActiveDirectory"
    ],
    "DomainJoinConfig": {
        "Sid": "S-1-5-21-702590844-1001920913-2680819671",
        "MachineAccountName": "webapp01",
        "Guid": "56d9b66c-d746-4f87-bd26-26760cfdca2e",
        "DnsTreeName": "contoso.com",
        "DnsName": "contoso.com",
        "NetBiosName": "CONTOSO"
    },
    "ActiveDirectoryConfig": {
        "GroupManagedServiceAccounts": [
            {
                "Name": "webapp01",
                "Scope": "contoso.com"
            },
            {
                "Name": "webapp01",
                "Scope": "CONTOSO"
            }
        ]
    }
}

Configuración adicional de la especificación de credenciales para el caso de uso del host de contenedor no unido a un dominio

Al usar gMSA con hosts de contenedor no unidos a un dominio, es necesario agregar información sobre el complemento de ccg.exe que va a usar a la especificación de credenciales. Esto se agregará a una sección de la especificación de credenciales denominada HostAccountConfig. La sección hostAccountConfig tiene tres campos que deben rellenarse:

PortableCcgVersion: debe establecerse en "1".
PluginGUID: CLSID COM para el complemento ccg.exe. Esto es único para el complemento que se está usando.
PluginInput: entrada específica del complemento para recuperar la información de la cuenta de usuario del almacén de secretos.

Este es un ejemplo de una especificación de credenciales con la sección hostAccountConfig agregada:

{
    "CmsPlugins": [
        "ActiveDirectory"
    ],
    "DomainJoinConfig": {
        "Sid": "S-1-5-21-702590844-1001920913-2680819671",
        "MachineAccountName": "webapp01",
        "Guid": "56d9b66c-d746-4f87-bd26-26760cfdca2e",
        "DnsTreeName": "contoso.com",
        "DnsName": "contoso.com",
        "NetBiosName": "CONTOSO"
    },
    "ActiveDirectoryConfig": {
        "GroupManagedServiceAccounts": [
            {
                "Name": "webapp01",
                "Scope": "contoso.com"
            },
            {
                "Name": "webapp01",
                "Scope": "CONTOSO"
            }
        ],
        "HostAccountConfig": {
            "PortableCcgVersion": "1",
            "PluginGUID": "{GDMA0342-266A-4D1P-831J-20990E82944F}",
            "PluginInput": "contoso.com:gmsaccg:<password>"
        }
    }
}

Pasos siguientes

Ahora que ha configurado la cuenta de gMSA, puede usarla para:

Si tiene algún problema durante la instalación, consulte nuestra guía de solución de problemas de para ver posibles soluciones.

Recursos adicionales

Para más información sobre las gMSA, vea la Información general de las cuentas de servicio administradas de grupo.

Compartir a través de

Creación de gMSA para contenedores de Windows

Arquitectura y mejoras de gMSA

Prerrequisitos

Preparación única de Active Directory

Creación de una cuenta de servicio administrada de grupo

Caso de uso para crear una cuenta de gMSA para hosts de contenedor unidos a un dominio

Caso de uso para crear una cuenta de gMSA para hosts de contenedor no unidos a un dominio

Preparación del host de contenedor

Caso de uso para preparar el host de contenedor para un host de contenedor unido a un dominio

Caso de uso para preparar el host de contenedor para un host de contenedor que no esté unido a un dominio

Creación de una especificación de credenciales

Configuración adicional de la especificación de credenciales para el caso de uso del host de contenedor no unido a un dominio

Pasos siguientes

Recursos adicionales

Comentarios

Recursos adicionales