Ativar chaves de segurança com o Login do SO

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 da seguinte maneira.

    Selecione a guia para como planeja usar as amostras nesta página:

    Console

    Quando você usa o console do Google Cloud para acessar os serviços e as APIs do Google Cloud, não é necessário configurar a autenticação.

    gcloud

    1. Instale a Google Cloud CLI e inicialize-a executando o seguinte comando: 

      gcloud init
    2. Defina uma região e uma zona padrão.

    REST

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

      Instale a Google Cloud CLI e inicialize-a executando o seguinte comando: 

      gcloud init

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 sua Conta do Google.

  • 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 sistemas operacionais da VM do Compute Engine a seguir 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.

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

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

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.

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.

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.

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.

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.

    compute/oslogin/physical_security_key_ssh.py 
    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