Ativar chaves de segurança com o Login do SO

---

Visualização

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Este documento descreve como usar as chaves de segurança física registradas na sua Conta do Google para se conectar a instâncias de máquina virtual (VM) que usam o Login do SO.

As chaves de segurança física são usadas para gerar arquivos de chaves SSH privadas para se conectar a VMs. Quando você usa a ferramenta SSH no navegador do console do Google Cloud ou a CLI do Google Cloud para se conectar a VMs usando chaves de segurança, o Login do SO recupera o arquivo de chave SSH privada associado à sua chave de segurança e configura o arquivo de chave SSH por você. Ao usar ferramentas de terceiros para se conectar, use a API OS Login para recuperar as informações da chave SSH e configurar o arquivo da chave SSH.

Antes de começar

• Adicionar uma chave de segurança à sua Conta do Google.
• Configurar o Login do SO.
• Configure a autenticação, caso ainda não tenha feito isso. A autenticação é o processo de verificação da sua identidade para acesso a serviços e APIs do Google Cloud. Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine selecionando uma das seguintes opções:
  

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI, then initialize it by running the following command:

     gcloud init

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  2. Set a default region and zone.

  REST

  Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

Limitações

• As VMs com chaves de segurança ativadas aceitam apenas conexões de chaves SSH anexadas às chaves de segurança físicas registradas na Conta do Google.
• Não é possível usar o Cloud Shell para se conectar a VMs com chaves de segurança ativadas.

• A VM a que você está se conectando e a estação de trabalho de onde você está se conectando precisa usar uma versão do OpenSSH 8.2 ou posterior compatível com os tipos SSH de chave de segurança. Os seguintes sistemas operacionais de VM do Compute Engine são compatíveis com chaves de segurança:

  • Debian 11 ou posterior
  • SUSE Linux Enterprise Server (GiB) 15 (ou mais recente)
  • Ubuntu 20.04 LTS (ou posterior)
  • Container-Optimized OS 93 LTS (ou mais recente)
  • Rocky Linux 9 (ou posterior)

  Para verificar se o ambiente é compatível com chaves de segurança, execute o seguinte comando:

  ssh -Q key | grep ^sk-
  

  Se o comando não retornar nenhuma saída, seu ambiente não será compatível com chaves de segurança.

• O cliente SSH na estação de trabalho de onde você está se conectando precisa oferecer suporte a chaves de segurança e incluir as bibliotecas necessárias, como libfido2.

Observação: as contas de serviço continuam se conectando a VMs sem usar chaves de segurança. Se você estiver se conectando de um serviço ou aplicativo que não é compatível com chaves de segurança, conectar-se à VM como uma conta de serviço.

Ativar chaves de segurança com o Login do SO

É possível ativar o uso de chaves de segurança para todas as VMs que usam o Login do SO no seu projeto ou para VMs únicas.

Ativar chaves de segurança para todas as VMs ativadas para o Login do SO em um projeto

Para ativar as chaves de segurança em todas as VMs que usam o Login do SO no projeto, use o console do Google Cloud ou a CLI gcloud.

Console

Para ativar as chaves de segurança de todas as VMs com Login do SO ativado, use o console do Google Cloud para definir enable-oslogin e enable-oslogin-sk como TRUE nos metadados do projeto:

1. Acesse a página Metadados.

   Acessar a página "Metadados"

2. Clique em Editar.

3. Clique em Adicionar item.

   1. No campo Chave, digite enable-oslogin.
   2. No campo Valor, insira TRUE.

4. Clique em Adicionar item.

   1. No campo Chave, digite enable-oslogin-sk.
   2. No campo Valor, insira TRUE.

5. Clique em Salvar.

gcloud

Se quiser ativar chaves de segurança para todas as VMs ativadas para Login do SO, use o comando gcloud compute project-info add-metadata para definir enable-oslogin=TRUE e enable-oslogin-sk=TRUE nos metadados do projeto:

gcloud compute project-info add-metadata \
    --metadata enable-oslogin=TRUE,enable-oslogin-sk=TRUE

Ativar chaves de segurança em uma única VM ativada para Login do SO

Para ativar chaves de segurança em uma VM que usa o Login do SO, use o console do Google Cloud ou a CLI gcloud.

Console

Para ativar chaves de segurança em uma única VM, use o console do Google Cloud para definir enable-oslogin e enable-oslogin-sk como TRUE nos metadados da instância:

1. Acesse a página Instâncias da VM.

   Acessar instâncias de VM

2. Clique no nome da VM em que você quer ativar as chaves de segurança.

3. Clique em Editar.

4. Na seção Metadados, clique em Adicionar item.

   1. No campo Chave, digite enable-oslogin.
   2. No campo Valor, insira TRUE.

5. Clique em Adicionar item.

   1. No campo Chave, digite enable-oslogin-sk.
   2. No campo Valor, insira TRUE.

6. Clique em Salvar.

gcloud

Para ativar chaves de segurança em uma única VM, use o comando gcloud compute instances add-metadata para definir enable-oslogin=TRUE e enable-oslogin-sk=TRUE nos metadados da instância:

gcloud compute instances add-metadata VM_NAME \
    --metadata enable-oslogin=TRUE,enable-oslogin-sk=TRUE

Substitua VM_NAME pelo nome da VM.

Conectar a uma VM usando uma chave de segurança

É possível se conectar a uma VM que usa chaves de segurança usando o console do Google Cloud, a gcloud CLI ou ferramentas de terceiros. Se você se conectar a VMs usando o console do Google Cloud ou a gcloud CLI, o Compute Engine vai configurar sua chave SSH para você. Se você se conectar a VMs usando ferramentas de terceiros, será preciso executar a configuração por conta própria.

Observação: as VMs que têm chaves de segurança ativadas não são compatíveis com as conexões da CLI gcloud das estações de trabalho do Windows. Conecte-se usando o console do Google Cloud ou ferramentas de terceiros.

Console

Quando você se conecta a VMs usando a ferramenta SSH no navegador do console do Google Cloud, o SSH no navegador recupera as chaves privadas associadas às suas chaves de segurança.

Observação: o arquivo de chave privada não pode ser usado para acessar a VM sem acesso físico ao dispositivo da chave de segurança.

Para se conectar a uma VM com chaves de segurança ativadas, faça isto:

1. No console do Google Cloud, acesse a página Instâncias de VMs.

2. Na lista de VMs, clique em SSH na linha da VM à qual você quer se conectar.

3. Quando solicitado, toque na sua chave de segurança.

gcloud

Quando você se conecta às VMs usando a CLI gcloud, a CLI gcloud recupera as chaves privadas associadas às chaves de segurança e configura os arquivos das chaves privadas. Essa configuração é persistente e se aplica a todas as VMs que usam chaves de segurança.

Observação: o arquivo de chave privada não pode ser usado para acessar a VM sem acesso físico ao dispositivo da chave de segurança.

Use o comando gcloud beta compute ssh para se conectar a uma VM com chaves de segurança ativadas:

gcloud beta compute ssh VM_NAME

Ferramentas de terceiros

Antes de se conectar a uma VM com chaves de segurança ativadas, é necessário recuperar as chaves privadas associadas às chaves de segurança e configurar os arquivos das chaves privadas. Neste exemplo, usamos a biblioteca de cliente do Python para executar a configuração.

Observação: o arquivo de chave privada não pode ser usado para acessar a VM sem acesso físico ao dispositivo da chave de segurança.

Você só precisará realizar esta configuração na primeira vez que se conectar a uma VM. A configuração é persistente e se aplica a todas as VMs que usam chaves de segurança no projeto.

Em um terminal na estação de trabalho, faça o seguinte:

1. Instale a biblioteca de cliente do Google para Python, se ainda não tiver feito isso, executando o comando a seguir:

   pip3 install google-api-python-client
   

2. Salve o exemplo de script Python a seguir, que recupera as chaves privadas associadas às chaves de segurança, configura os arquivos da chave privada e se conecta à VM.

   import argparse
   import os
   import subprocess
   from typing import Optional
   
   import googleapiclient.discovery
   
   
   def write_ssh_key_files(security_keys: list[dict], directory: str) -> list[str]:
       """
       Store the SSH key files.
   
       Saves the SSH keys into files inside specified directory. Using the naming
       template of `google_sk_{i}`.
   
       Args:
           security_keys: list of dictionaries representing security keys retrieved
               from the OSLogin API.
           directory: path to directory in which the security keys will be stored.
   
       Returns:
           List of paths to the saved keys.
       """
       key_files = []
       for index, key in enumerate(security_keys):
           key_file = os.path.join(directory, f"google_sk_{index}")
           with open(key_file, "w") as f:
               f.write(key.get("privateKey"))
               os.chmod(key_file, 0o600)
               key_files.append(key_file)
       return key_files
   
   
   def ssh_command(key_files: list[str], username: str, ip_address: str) -> list[str]:
       """
       Construct the SSH command for a given IP address and key files.
   
       Args:
           key_files: SSH keys to be used for authentication.
           username: username used to authenticate.
           ip_address: the IP address or hostname of the remote system.
   
       Returns:
           SSH command as a list of strings.
       """
       command = ["ssh"]
       for key_file in key_files:
           command.extend(["-i", key_file])
       command.append(f"{username}@{ip_address}")
       return command
   
   
   def main(
       user_key: str, ip_address: str, dryrun: bool, directory: Optional[str] = None
   ) -> None:
       """
       Configure SSH key files and print SSH command.
   
       Args:
           user_key: name of the user you want to authenticate as. Usually an email address.
           ip_address: the IP address of the machine you want to connect to.
           dryrun: bool flag to do dry run, without connecting to the remote machine.
           directory: the directory to store SSH private keys.
       """
       directory = directory or os.path.join(os.path.expanduser("~"), ".ssh")
   
       # Create the OS Login API object.
       oslogin = googleapiclient.discovery.build("oslogin", "v1beta")
   
       # Retrieve security keys and OS Login username from a user's Google account.
       profile = (
           oslogin.users()
           .getLoginProfile(name=f"users/{user_key}", view="SECURITY_KEY")
           .execute()
       )
   
       if "posixAccounts" not in profile:
           print("You don't have a POSIX account configured.")
           print("Please make sure that you have enabled OS Login for your VM.")
           return
   
       username = profile.get("posixAccounts")[0].get("username")
   
       # Write the SSH private key files.
       security_keys = profile.get("securityKeys")
   
       if security_keys is None:
           print(
               "The account you are using to authenticate does not have any security keys assigned to it."
           )
           print(
               "Please check your Application Default Credentials "
               "(https://cloud.google.com/docs/authentication/application-default-credentials)."
           )
           print(
               "More info about using security keys: https://cloud.google.com/compute/docs/oslogin/security-keys"
           )
           return
   
       key_files = write_ssh_key_files(security_keys, directory)
   
       # Compose the SSH command.
       command = ssh_command(key_files, username, ip_address)
   
       if dryrun:
           # Print the SSH command.
           print(" ".join(command))
       else:
           # Connect to the IP address over SSH.
           subprocess.call(command)
   
   
   if __name__ == "__main__":
       parser = argparse.ArgumentParser(
           description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
       )
       parser.add_argument("--user_key", help="Your primary email address.")
       parser.add_argument(
           "--ip_address", help="The external IP address of the VM you want to connect to."
       )
       parser.add_argument("--directory", help="The directory to store SSH private keys.")
       parser.add_argument(
           "--dryrun",
           dest="dryrun",
           default=False,
           action="store_true",
           help="Turn off dryrun mode to execute the SSH command",
       )
       args = parser.parse_args()
   
       main(args.user_key, args.ip_address, args.dryrun, args.directory)

3. Execute o script para configurar as chaves e se conectar opcionalmente à VM.

   python3 SCRIPT_NAME.py --user_key=USER_KEY --ip_address=IP_ADDRESS [--dryrun]
   

   Substitua:

   • SCRIPT_NAME: o nome do script de configuração
   • USER_KEY: seu endereço de e-mail principal.
   • IP_ADDRESS: o endereço IP externo da VM à qual você está se conectando.
   • [--dryrun]: (opcional) adicione a sinalização --dryrun para imprimir o comando de conexão sem se conectar à VM. Se você não especificar essa sinalização, o script executará o comando de conexão.

A seguir

• Saiba como configurar o login do SO com a verificação em duas etapas.
• Saiba como gerenciar o Login do SO em uma organização.