Criando e Utilizando Chaves de API (API Keys) com Service Accounts (SAs)

Este guia descreve o processo completo para criar uma Chave de API (API Key) vinculada a uma Service Account (SA). Esse método é recomendado para autenticar aplicações, scripts e processos automatizados que precisam interagir com nossas APIs de forma segura, sem depender de credenciais de um usuário humano.

O processo envolve quatro etapas principais:

1. Criar a Service Account (a identidade).
2. Criar a API Key (a credencial) vinculada à Service Account.
3. Definir os Escopos (Scopes) da API Key (quais serviços ela pode acessar).
4. Conceder Permissões (Permissions) à Service Account (quais ações ela pode executar).

Usaremos a mgc CLI para todos os exemplos.

Passo 1: Criar a Service Account (SA)

A Service Account é a identidade não-humana que sua aplicação usará.

Execute o comando abaixo, substituindo os placeholders:

• [NOME_DA_CONTA]: Um nome único para identificar a SA (ex: app-integracao-prod).

• [EMAIL_PREFIXO]: O prefixo para o email da SA (ex: app-integracao-prod).

• [DESCRICAO]: Uma breve descrição da finalidade da SA.

mgc iam service-accounts create --description '[DESCRICAO]' --email [EMAIL_PREFIXO] --name [NOME_DA_CONTA]

Exemplo:

mgc iam service-accounts create --description 'Service Account para CI/CD' --email app-cicd --name app-cicd

Após a execução, o sistema retornará os detalhes da SA como no exemplo a seguir:

description: Service Account para CI/CD                                         
email: app-cicd@COU-6123.sa.idmagalu.com
name: app-cicd
tenant:
    legal_name: TRIA.RBC
    uuid: [TENANT_ID]
uuid: 11111111-2222-3333-4444-555555555555 

Anote o uuid exibido, pois ele será usado como [SA_UUID] nos próximos passos.

Passo 2: Criar a API Key

Agora, vamos criar a chave (credencial) que será vinculada à Service Account da etapa anterior.

• [SA_UUID]: O uuid da Service Account obtido no Passo 1.

• [NOME_DA_APIKEY]: Um nome para identificar esta chave (ex: chave-ci-cd).

mgc iam service-accounts api-keys create --sa-uuid [SA_UUID] --name [NOME_DA_APIKEY]

Exemplo:

mgc iam service-accounts api-keys create --sa-uuid 123-abc-456-def --name chave-ci-cd

Após a execução, o sistema retornará os detalhes da API Key como no exemplo a seguir:

api_key: 11111111-2222-3333-4444-555555555555                                   
description: ""
end_validity: null
key_pair_id: aaaaaaaa-1111-bbbb-2222-cccccccccccc
key_pair_secret: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
name: chave-ci-cd
revoked_at: null
revoked_by: null
scopes: []
scopes_pending_approval: []
start_validity: null
uuid: 11111111-aaaa-2222-bbbb-333333333333

Alguns valores serão importantes nas próximas etapas, dentre eles:

1. api-key: Esta é a chave secreta. Copie-a e guarde-a em local seguro (como um secret manager). Ela não poderá ser visualizada novamente. É este valor que você usará para autenticar suas chamadas (ex: 11111111-2222-3333-4444-555555555555).

2. uuid: Este é o identificador da chave (diferente do uuid da SA). Anote-o como [APIKEY_UUID] para o próximo passo.

Passo 3: Definir os Escopos (Scopes) da API Key

Os escopos definem um limite amplo de quais serviços a chave pode tentar acessar (ex: "esta chave pode ser usada para operações de máquina virtual e kubernetes").

• [SA_UUID]: O uuid da Service Account do Passo 1.

• [APIKEY_UUID]: O uuid da API Key obtido no Passo 2.

• [LISTA_DE_ESCOPOS]: Aspas simples com escopos separados por vírgulas (ex: 'virtual-machine.read, mke.write').

mgc iam service-accounts api-keys update --sa-uuid [SA_UUID] --apikey-uuid [APIKEY_UUID] --scopes '[LISTA_DE_ESCOPOS]'

Exemplo:

mgc iam service-accounts api-keys update --sa-uuid 123-abc-456-def --apikey-uuid 789-ghi-012-jkl --scopes 'virtual-machine.write, virtual-machine.read, mke.write, mke.read'

Dica: o comando mgc iam scopes list mostra todos os escopos existentes.

Passo 4: Conceder Permissões (Permissions) à Service Account

Enquanto os escopos definem o que a chave pode acessar, as permissões definem o que a Service Account (a identidade) pode fazer. Ambos são necessários.

Você deve conceder à Service Account as permissões granulares para cada ação que ela precisará executar.

• [SA_UUID]: O uuid da Service Account do Passo 1.

• [LISTA_DE_PERMISSOES]: Uma lista longa, separada por vírgulas, de todas as permissões necessárias.

mgc iam members grants update --uuid [SA_UUID] --operation add --permissions '[LISTA_DE_PERMISSOES]'

Exemplo (concedendo permissões para Kubernetes e VM):

mgc iam members grants update --uuid 123-abc-456-def --operation add --permissions 'kubernetes_cluster_create, kubernetes_cluster_delete, kubernetes_cluster_update, kubernetes_cluster_list, kubernetes_cluster_get, kubernetes_cluster_access, kubernetes_cluster_info, kubernetes_nodepool_create, kubernetes_nodepool_delete, kubernetes_nodepool_list, kubernetes_nodepool_get, kubernetes_nodepool_update, vm_instance_list, vm_instance_create, vm_instance_delete, vm_instance_action, vm_instance_get, vm_instance_rename, vm_instance_retype, vm_instance_nic, vm_instance_password, vm_image_list, vm_machine_type_list, vm_snapshot_create, vm_snapshot_delete, vm_snapshot_list, vm_snapshot_get, vm_snapshot_rename, vm_snapshot_restore, vm_snapshot_copy'

note

A concessão de permissões também pode ser realizada através do console (Turia IAM).

Dica: o comando mgc iam permissions list mostra todas as permissões existentes.

Passo 5: Testar e Utilizar a API Key

Com a Service Account criada, a API Key gerada, os escopos definidos e as permissões concedidas, sua chave está pronta para uso.

Para autenticar suas chamadas (via CLI ou API REST), utilize a chave secreta (api-key) obtida no Passo 2.

Exemplos de teste com a CLI:

Substitua [SUA_API_KEY_SECRETA] pelo valor da api-key (ex: 999-aaa-888-bbb).

Testando o acesso a Máquinas Virtuais

mgc virtual-machine instances list --api-key [SUA_API_KEY_SECRETA]

Testando o acesso ao Kubernetes

mgc kubernetes cluster list --api-key [SUA_API_KEY_SECRETA]

Se os comandos retornarem os recursos com sucesso, sua API Key está configurada corretamente.