Criar gMSAs para contêineres do Windows

Aplica-se a: Windows Server 2025, Windows Server 2022, Windows Server 2019

As redes baseadas no Windows geralmente usam o Active Directory (AD) para facilitar a autenticação e a autorização entre usuários, computadores e outros recursos de rede. Os desenvolvedores de aplicativos empresariais geralmente projetam seus aplicativos para serem integrados ao AD e executados em servidores ingressados no domínio para aproveitar a Autenticação Integrada do Windows, o que facilita que usuários e outros serviços entrem automaticamente e de forma transparente no aplicativo com suas identidades. Este artigo explica como começar a usar contas de serviço gerenciadas de grupo do Active Directory com contêineres do Windows.

Embora os contêineres do Windows não possam ser associados a um domínio, eles ainda podem utilizar identidades de domínio do Active Directory para dar suporte a vários cenários de autenticação. Para isso, você pode configurar um contêiner do Windows para ser executado com um grupo gMSA (Managed Service Account), que é um tipo especial de conta de serviço introduzida no Windows Server 2012 e projetada para permitir que vários computadores compartilhem uma identidade sem precisar saber sua senha. Os contêineres do Windows não podem ser associados ao domínio, mas muitos aplicativos do Windows executados em contêineres do Windows ainda precisam de Autenticação de AD. Para usar a Autenticação do AD, você pode configurar um contêiner do Windows para ser executado com uma Conta de Serviço Gerenciado de Grupo (gMSA).

Quando a gMSA para contêineres do Windows foi introduzida, era necessário que o host do contêiner estivesse ingressado no domínio, o que gerava muita sobrecarga para os usuários que precisavam ingressar manualmente os nós de execução do Windows em um domínio. Essa limitação foi tratada com o suporte de contêineres gMSA para Windows para hosts de contêiner não conectados ao domínio. A funcionalidade gMSA original continuará sendo compatível para o uso de um host de contêiner ingressado no domínio.

Os aprimoramentos na gMSA ao usar um host de contêiner não conectado ao domínio incluem:

• Eliminação do requisito de ingressar manualmente nós de trabalho do Windows em um domínio, o que causava muita sobrecarga para os usuários. Para cenários de dimensionamento, o uso de um host de contêiner não associado ao domínio simplifica o processo.
• Em cenários de atualização contínua, os usuários não precisam mais fazer o reingresso do nó em um domínio.
• Um processo mais fácil para gerenciar as contas de computador do nó de trabalho a fim de recuperar senhas de contas de serviço da gMSA.
• Configurar a gMSA com o Kubernetes é um processo de ponta a ponta menos complicado.

Arquitetura e melhorias da gMSA

Para resolver as limitações da implementação inicial do gMSA para contêineres do Windows, o novo suporte ao gMSA para hosts de contêiner que não fazem parte do domínio utiliza uma identidade de usuário portátil em vez de uma conta do computador host para recuperar as credenciais do gMSA. Portanto, a junção manual de nós de trabalho do Windows a um domínio não é mais necessária, embora ainda tenha suporte. A identidade/as credenciais do usuário são armazenadas em um repositório secreto acessível ao host do contêiner (por exemplo, como um segredo do Kubernetes) em que os usuários autenticados podem recuperá-lo.

Diagrama

O suporte gMSA para hosts de contêiner não associados ao domínio oferece a flexibilidade de criar contêineres com gMSA sem a necessidade de associar o nó hospedeiro ao domínio. A partir do Windows Server 2019, há suporte para ccg.exe que permite que um mecanismo de plug-in recupere credenciais gMSA do Active Directory. Você pode usar essa identidade para iniciar o contêiner. Para obter mais informações sobre esse mecanismo de plug-in, consulte a interface ICcgDomainAuthCredentials.

Veja o diagrama abaixo para seguir as etapas do processo do Container Credential Guard:

1. Usando um arquivo CredSpec como entrada, o processo de ccg.exe é iniciado no nó host.

2. O ccg.exe usa informações no arquivo CredSpec para iniciar um plug-in e recuperar as credenciais da conta no repositório de segredos associado ao plug-in.

3. ccg.exe usa as credenciais de conta recuperadas para recuperar a senha gMSA do AD.

4. ccg.exe disponibiliza a senha gMSA para um contêiner que solicitou credenciais.

5. O contêiner autentica-se no controlador de domínio usando a senha gMSA para obter um Kerberos Ticket-Granting Ticket (TGT).

6. Aplicativos em execução como Serviço de Rede ou Sistema Local no contêiner agora podem autenticar e acessar recursos de domínio, como o gMSA.

   Diagrama

Pré-requisitos

Para executar um contêiner do Windows com uma conta de serviço gerenciada de grupo, você precisará do seguinte:

• Um domínio do Active Directory com pelo menos um controlador de domínio executando o Windows Server 2012 ou posterior. Não há requisitos de nível funcional de floresta ou domínio para usar gMSAs, mas as senhas gMSA só podem ser distribuídas por controladores de domínio que executam o Windows Server 2012 ou posterior. Para obter mais informações, confira Requisitos do Active Directory para gMSAs.
• Permissão para criar uma conta gMSA. Para criar uma conta gMSA, você precisará ser um Administrador de Domínio ou usar uma conta à qual que tenha sido delegada a permissão Criar objetos msDS-GroupManagedServiceAccount.
• Acesso à Internet para baixar o módulo CredentialSpec PowerShell. Se você estiver trabalhando em um ambiente desconectado, poderá salvar o módulo em um computador com acesso à Internet e copiá-lo para seu computador de desenvolvimento ou host de contêiner.

Preparação única do Active Directory

Se você ainda não tiver criado um gMSA em seu domínio, precisará gerar a chave raiz do KDS (Serviço de Distribuição de Chaves). O KDS é responsável por criar, alterar e liberar a senha gMSA para servidores autorizados. Quando um host de contêiner precisar usar a gMSA para executar um contêiner, ele entrará em contato com o KDS para recuperar a senha atual.

Para verificar se a chave raiz do KDS já foi criada, execute o seguinte cmdlet do PowerShell como administrador de domínio em um controlador de domínio ou membro de domínio com as ferramentas do PowerShell do AD instaladas:

Get-KdsRootKey

Se o comando retornar uma identificação de chave, você estará pronto e poderá ir para a seção criar uma conta de serviço gerenciada de grupo. Caso contrário, continue criando a chave-raiz do KDS.

Em um ambiente de produção ou ambiente de teste com vários controladores de domínio, execute o seguinte cmdlet no PowerShell como administrador de domínio para criar a chave raiz do KDS.

# For production environments
Add-KdsRootKey -EffectiveImmediately

Embora o comando indira que a chave entrará em vigor imediatamente, você precisará aguardar 10 horas antes que a chave raiz do KDS seja replicada e disponível para uso em todos os controladores de domínio.

Se você tiver apenas um controlador de domínio em seu domínio, poderá agilizar o processo definindo a chave para entrar em vigor há 10 horas.

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

Criar uma conta de serviço gerenciada de grupo

Cada contêiner que usa a Autenticação Integrada do Windows precisa de pelo menos um gMSA. A gMSA primária é usada sempre que aplicativos em execução como um sistema ou um serviço de rede acessam recursos na rede. O nome da gMSA se tornará o nome do contêiner na rede, independentemente do nome do host atribuído ao contêiner. Os contêineres também podem ser configurados com gMSAs adicionais, caso você queira executar um serviço ou aplicativo no contêiner como uma identidade diferente da conta de computador do contêiner.

Ao criar uma gMSA, você também cria uma identidade compartilhada que pode ser usada simultaneamente em vários computadores diferentes. O acesso à senha gMSA é protegido por uma Lista de Controle de Acesso do Active Directory. É recomendável criar um grupo de segurança para cada conta gMSA e adicionar os hosts de contêiner relevantes ao grupo de segurança para limitar o acesso à senha.

Por fim, como os contêineres não registram automaticamente nenhum SPN (Nomes de Entidade de Serviço), você precisará criar manualmente pelo menos um SPN de host para sua conta gMSA.

Normalmente, o host ou http SPN é registrado usando o mesmo nome da conta gMSA, mas talvez seja necessário usar um nome de serviço diferente se os clientes acessarem o aplicativo em contêineres por trás de um balanceador de carga ou um nome DNS diferente do nome gMSA.

Por exemplo, se a conta gMSA for denominada "WebApp01", mas seus usuários acessarem o site no endereço mysite.contoso.com, você deverá registrar o SPN http/mysite.contoso.com na conta gMSA.

Alguns aplicativos podem exigir SPNs adicionais para seus protocolos exclusivos. Por exemplo, o SQL Server requer o SPN MSSQLSvc/hostname.

A tabela a seguir lista os atributos necessários para criar uma gMSA.

Depois de decidir o nome do gMSA, execute os seguintes cmdlets no PowerShell para criar o grupo de segurança e a gMSA.

Recomendamos que você crie contas gMSA separadas para seus ambientes de desenvolvimento, teste e produção.

Caso de uso de criação de uma conta da gMSA para hosts de contêiner ingressados no domínio

# 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 de criação de uma conta da gMSA para hosts de contêiner não conectados ao domínio

Ao usar a gMSA para contêineres com hosts não conectados ao domínio, em vez de adicionar hosts de contêiner ao grupo de segurança WebApp01Hosts, crie e adicione uma conta de usuário padrão.

# 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"

Preparar o host do contêiner

Caso de uso de preparação do host de contêiner para se tornar ingressado no domínio

Cada host de contêiner que executará um contêiner do Windows com um gMSA deve estar ingressado no domínio e ter acesso para recuperar a senha do gMSA.

1. Conecte o seu computador ao domínio do Active Directory.

2. Verifique se o host pertence ao grupo de segurança que controla o acesso à senha gMSA.

3. Reinicie o computador para obter sua nova associação de grupo.

4. Configure Docker Desktop para Windows 10 ou Docker para Windows Server.

5. (Recomendado) Verifique se o host pode usar a conta gMSA executando Test-ADServiceAccount. Se o comando retornar False, siga as instruções de solução de problemas .

   # 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 de preparação do host de contêiner para se tornar não conectado ao domínio

Ao usar gMSA para contêineres do Windows em hosts de contêiner não associados ao domínio, cada host de contêiner deve ter um plug-in para ccg.exe instalado que será usado para recuperar a conta de usuário portátil e as credenciais especificadas na etapa anterior. Os plug-ins são exclusivos do repositório secreto usado para proteger as credenciais da conta de usuário portátil. Por exemplo, diferentes plug-ins seriam necessários para armazenar credenciais de conta no Azure Key Vault versus em um repositório secreto do Kubernetes.

No momento, o Windows não oferece um plug-in interno e padrão. As instruções de instalação para plug-ins serão específicas para a implementação. Para obter mais informações sobre como criar e registrar plug-ins para ccg.exe, consulte interface ICcgDomainAuthCredentials.

Criar uma especificação de credencial

Um arquivo de especificação de credencial é um documento JSON que contém metadados sobre as contas gMSA que você deseja que um contêiner use. Mantendo a configuração de identidade separada da imagem de contêiner, você pode alterar qual gMSA o contêiner usa simplesmente trocando o arquivo de especificação de credencial, nenhuma alteração de código é necessária.

O arquivo de especificação de credencial é criado usando o módulo CredentialSpec PowerShell em uma máquina conectada ao domínio. Depois de criar o arquivo, você pode copiá-lo para outros hosts de contêiner ou para o orquestrador de contêineres. O arquivo de especificação de credencial não contém segredos, como a senha gMSA, já que o host do contêiner recupera a gMSA em nome do contêiner.

O Docker espera encontrar o arquivo de especificação de credencial no diretório CredentialSpecs no diretório de dados do Docker. Em uma instalação padrão, você encontrará essa pasta em C:\ProgramData\Docker\CredentialSpecs.

Para criar um arquivo de especificação de credencial no host do contêiner:

1. Instalar as ferramentas do PowerShell do RSAT AD

   • Para o Windows Server, execute Install-WindowsFeatureRSAT-AD-PowerShell.
   • Para Windows 10, versão 1809 ou posterior, execute Add-WindowsCapability -Online -Name 'Rsat.ActiveDirectory.DS-LDS.Tools~~~0.0.1.0'.
   • Para versões mais antigas do Windows 10, consulte https://aka.ms/rsat.

2. Execute o seguinte cmdlet para instalar a versão mais recente do módulo CredentialSpec PowerShell:

   Install-Module CredentialSpec
   

   Se você não tiver acesso à Internet no host do contêiner, execute Save-Module CredentialSpec em um computador conectado à Internet e copie a pasta do módulo para C:\Program Files\WindowsPowerShell\Modules ou para outro local em $env:PSModulePath no host do contêiner.

3. Execute o seguinte cmdlet para criar o novo arquivo de especificação de credencial:

   # Replace 'WebApp01' with your own gMSA
   New-CredentialSpec -AccountName WebApp01
   

   Por padrão, o cmdlet criará uma especificação de credencial usando o nome gMSA fornecido como a conta de computador do contêiner. O arquivo será salvo no diretório Docker CredentialSpecs usando o domínio gMSA e o nome da conta para o nome do arquivo.

   Se você quiser salvar o arquivo em outro diretório, use o parâmetro -Path:

   New-CredentialSpec -AccountName WebApp01 -Path "C:\MyFolder\WebApp01_CredSpec.json"
   

   Você também pode criar uma especificação de credencial que inclui contas gMSA adicionais se estiver executando um serviço ou processo como um gMSA secundário no contêiner. Para fazer isso, use o parâmetro -AdditionalAccounts:

   New-CredentialSpec -AccountName WebApp01 -AdditionalAccounts LogAgentSvc, OtherSvc
   

   Para obter uma lista completa de parâmetros com suporte, execute Get-Help New-CredentialSpec -Full.

4. Você pode mostrar uma lista de todas as especificações de credencial e seu caminho completo com o seguinte cmdlet:

   Get-CredentialSpec
   

Este é um exemplo de uma especificação de credencial:

{
    "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"
            }
        ]
    }
}

Configuração de especificação de credencial adicional para caso de uso de host de contêiner não associado ao domínio

Ao usar gMSA com hosts de contêiner que não estão conectados ao domínio, é necessário adicionar à especificação de credenciais as informações sobre o plug-in ccg.exe que você utilizará. Essas informações serão incluídas em uma seção da especificação de credenciais chamada HostAccountConfig. A seção HostAccountConfig tem três campos que precisam ser preenchidos:

• PortableCcgVersion: deve ser definido como "1".
• PluginGUID: o COM CLSID para o plug-in ccg.exe. Isso é exclusivo para o plug-in que está sendo usado.
• PluginInput: entrada específica do plug-in para recuperar as informações da conta de usuário do repositório de segredos.

Este é um exemplo de uma especificação de credencial com a seção HostAccountConfig adicionada:

{
    "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>"
        }
    }
}

Próximas etapas

Agora que você configurou sua conta gMSA, você pode usá-la para:

• Configurar aplicativos
• Executar contêineres
• Orquestrar contêineres

Se você encontrar problemas durante a instalação, verifique nosso guia de solução de problemas para possíveis soluções.

Recursos adicionais

• Para saber mais sobre gMSAs, confira a Visão geral das Contas de Serviço Gerenciado do grupo.