Métodos de autenticação OKMS

Objetivo

Este guia explica como autenticar-se no plano de dados OKMS — a API REST regional exposta no seu domínio OKMS (por exemplo https://eu-west-rbx.okms.ovh.net). Esta API é partilhada pelo Key Management Service (KMS) e pelo Secret Manager.

Estão disponíveis três métodos de autenticação para a API REST. As integrações KMIP suportam apenas certificados de acesso — recomendamos reservar os certificados para os casos de utilização KMIP, uma vez que a sua configuração é mais complexa do que a dos tokens.

Requisitos

• Uma conta de cliente OVHcloud.
• Um domínio OKMS na região pretendida (criado ao encomendar um KMS ou ao ativar o Secret Manager nessa região).

Instruções

Compreender o plano de dados OKMS

O plano de dados OKMS é o ponto de acesso API regional para as operações criptográficas (KMS) e o armazenamento de segredos (Secret Manager). É distinto do plano de controlo centralizado da API OVHcloud (/v2/okms/...), que gere o aprovisionamento e a configuração dos domínios OKMS.

Pode interagir com o plano de dados através da interface Swagger unificada no endereço https://<region>.okms.ovh.net/swagger/, da CLI OKMS ou do SDK Go.

Escolher o seu método de autenticação

Configurar a autenticação

curl -H "Authorization: Bearer <your_pat>" \
  https://eu-west-rbx.okms.ovh.net/v1/servicekey

curl -H "Authorization: Bearer <access_token>" \
  https://eu-west-rbx.okms.ovh.net/v1/servicekey

Utilizar a interface Swagger OKMS

O domínio OKMS expõe uma interface Swagger unificada no endereço https://<region>.okms.ovh.net/swagger/. Por exemplo, para um domínio em eu-west-rbx: https://eu-west-rbx.okms.ovh.net/swagger/.

Também pode abri-la a partir do link Swagger no painel de controlo do seu domínio OKMS.

A interface Swagger suporta os três métodos de autenticação da API REST. Realize os passos de configuração para o método escolhido, incluindo a política IAM necessária, antes de executar pedidos.

Token de acesso pessoal (PAT)

1. Clique no botão Authorize (ícone de cadeado) na interface Swagger.
2. Em personalAccessToken (HTTP Bearer, formato JWT), cole o PAT que criou para o seu utilizador local.
3. Clique em Authorize e, em seguida, em Close.

O Swagger envia o seu token num cabeçalho Authorization: Bearer <token> em cada pedido que executa.

Conta de serviço

1. Clique no botão Authorize na interface Swagger.
2. Em oAuth2ClientCredentials, introduza o client_id e o client_secret da sua conta de serviço. Consulte Como utilizar contas de serviço para se ligar às API OVHcloud para obter estas credenciais.
3. O Swagger obtém um token de acesso OAuth2 através do fluxo client-credentials e adiciona-o aos pedidos seguintes.

Certificado de acesso

A autenticação por certificado de acesso utiliza TLS mútuo (mTLS) ao nível do transporte. O certificado é apresentado pelo seu navegador ao ligar-se ao URL do Swagger — não é configurado através da caixa de diálogo Authorize.

Importar o seu certificado no navegador

Converta o seu certificado OKMS e a sua chave privada para o formato PKCS#12 (assumindo ficheiros com os nomes ID_certificate.pem e ID_privatekey.pem):

openssl pkcs12 -export -in ID_certificate.pem -inkey ID_privatekey.pem -out client.p12

Ser-lhe-á pedido que defina uma palavra-passe para o ficheiro encriptado. Importe client.p12 no seu navegador:

No Firefox

• Escreva about:preferences#privacy na barra de endereço.
• Desça até à secção Certificados.

• Clique em Ver certificados..., abra o separador Os seus certificados, depois Importar... e selecione o seu ficheiro client.p12.
• Introduza a palavra-passe PKCS#12 quando lhe for pedido.

No Chrome/Chromium

• Escreva chrome://settings/certificates na barra de endereço.
• Abra o separador Os seus certificados, clique em Importar e selecione o seu ficheiro client.p12.
• Introduza a palavra-passe PKCS#12 quando lhe for pedido.

Aceder ao Swagger com o seu certificado

Abra https://<region>.okms.ovh.net/swagger/ no seu navegador. Ser-lhe-á pedido que selecione o certificado importado:

Agora pode executar chamadas API de forma interativa a partir da interface Swagger.

Direitos IAM para OKMS

As ações IAM do OKMS seguem o modelo okms:<channel>:<resource>/<operation>:

Ações okms:apiovh comuns

Consulte a lista completa de ações na consola da API OVHcloud no tipo de produto Key Management System (KMS), ou nas políticas IAM ao criar uma política.

Modelos de políticas IAM sugeridos

Aplique estes modelos ao recurso do seu domínio OKMS (urn:v1:<region>:resource:okms:<okmsId>). Substitua <identity_urn> e <okms_urn> pelos seus valores. Crie as políticas através da área de cliente ou da API IAM.

Administração completa — controlo total do domínio OKMS através da API REST:

{
  "name": "okms-full-admin",
  "description": "Full administrative access to an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": ["okms:apiovh:*"]
}

Apenas leitura — listar e inspecionar os recursos sem operações de escrita ou criptográficas:

{
  "name": "okms-read-only",
  "description": "Read-only access to an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apiovh:serviceKey/get",
    "okms:apiovh:secret/get",
    "okms:apiovh:credential/get",
    "okms:apiovh:secretConfig/get",
    "okms:apiovh:log/get"
  ]
}

Adicione okms:apiovh:secret/version/getData se a identidade tiver de ler os valores dos segredos.

Apenas operações criptográficas — utilizar as chaves para encriptar, desencriptar, assinar e verificar sem gerir as chaves ou os segredos:

{
  "name": "okms-crypto-only",
  "description": "Cryptographic operations on an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apiovh:serviceKey/get",
    "okms:apiovh:serviceKey/encrypt",
    "okms:apiovh:serviceKey/decrypt",
    "okms:apiovh:serviceKey/sign",
    "okms:apiovh:serviceKey/verify",
    "okms:apiovh:serviceKey/datakey",
    "okms:apiovh:serviceKey/datakeyDecrypt"
  ]
}

Apenas acesso aos segredos — ler os segredos do Secret Manager sem acesso às chaves KMS, aos certificados ou à configuração do domínio:

{
  "name": "okms-secret-access-only",
  "description": "Read-only access to Secret Manager secrets on an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apiovh:secret/get",
    "okms:apiovh:secret/version/getData",
    "okms:apikms:secret/version/getData"
  ]
}

Adicione okms:apiovh:secret/create, okms:apiovh:secret/update e okms:apiovh:secret/delete se a identidade tiver de gerir os segredos.

Quer saber mais?

Utilizar o seu OVHcloud Key Management Service (KMS)

Utilizar o Secret Manager com a API REST

Como ligar um produto compatível utilizando o protocolo KMIP

Gerar um certificado de acesso OKMS

Fale com a nossa comunidade de utilizadores.