Definir e configurar chaves gerenciadas pelo cliente usando a API

Este documento aborda o processo de ativação do recurso de chaves gerenciadas pelo cliente (CMK) no Adobe Experience Platform usando a API. Para obter instruções sobre como concluir esse processo usando a interface do usuário, consulte o documento de configuração do CMK da interface do usuário.

Pré-requisitos

Para exibir e visitar a seção Criptografia no Adobe Experience Platform, você deve ter criado uma função e atribuído a permissão Gerenciar chave gerenciada pelo cliente a essa função. Qualquer usuário com a permissão Gerenciar Chave gerenciada pelo cliente pode habilitar o CMK para sua organização.

Para obter mais informações sobre atribuição de funções e permissões no Experience Platform, consulte a documentação sobre configuração de permissões.

Para habilitar o CMK, o Azure Cofre da Chave deve ser configurado com as seguintes configurações:

Configurar o aplicativo CMK register-app

Após configurar o cofre de chaves, a próxima etapa é se registrar para o aplicativo CMK que será vinculado ao locatário Azure.

Introdução

Para registrar o aplicativo CMK, é necessário fazer chamadas para APIs da plataforma. Para obter detalhes sobre como coletar os cabeçalhos de autenticação necessários para fazer essas chamadas, consulte o guia de autenticação da API da plataforma.

Embora o guia de autenticação forneça instruções sobre como gerar seu próprio valor exclusivo para o cabeçalho de solicitação x-api-key necessário, todas as operações de API neste guia usam o valor estático acp_provisioning. No entanto, você ainda deve fornecer seus próprios valores para {ACCESS_TOKEN} e {ORG_ID}.

Em todas as chamadas de API mostradas neste guia, platform.adobe.io é usado como o caminho raiz, que assume como padrão a região VA7. Se sua organização usar uma região diferente, platform deverá ser seguido por um traço e o código de região atribuído a sua organização: nld2 para NLD2 ou aus5 para AUS5 (por exemplo: platform-aus5.adobe.io). Caso não saiba a região da organização, entre em contato com o administrador do sistema.

Buscar um URL de autenticação fetch-authentication-url

Para iniciar o processo de registro, faça uma solicitação GET ao endpoint de registro do aplicativo para buscar o URL de autenticação necessário para sua organização.

Solicitação

curl -X GET \
  https://platform.adobe.io/data/infrastructure/manager/byok/app-registration \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: acp_provisioning' \
  -H 'x-gw-ims-org-id: {ORG_ID}'

Resposta

Uma resposta bem-sucedida retorna uma propriedade applicationRedirectUrl, contendo a URL de autenticação.

{
    "id": "byok",
    "name": "acpebae9422Caepcmkmultitenantapp",
    "applicationUri": "https://adobe.com/acpebae9422Caepcmkmultitenantapp",
    "applicationId": "e463a445-c6ac-4ca2-b36a-b5146fcf6a52",
    "applicationRedirectUrl": "https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id=e463a445-c6ac-4ca2-b36a-b5146fcf6a52&redirect_uri=https://adobe.com/acpebae9422Caepcmkmultitenantapp&scope=user.read"
}

Copie e cole o endereço applicationRedirectUrl em um navegador para abrir uma caixa de diálogo de autenticação. Selecione Accept para adicionar a entidade de serviço do aplicativo CMK ao locatário Azure.

Atribuir o aplicativo CMK a uma função assign-to-role

Após concluir o processo de autenticação, volte para o Cofre da Chave do Azure e selecione Access control na navegação à esquerda. Aqui, selecione Add seguido por Add role assignment.

A próxima tela solicita que você escolha uma função para esta atribuição. Selecione Key Vault Crypto Service Encryption User antes de selecionar Next para continuar.

Na próxima tela, escolha Select members para abrir uma caixa de diálogo no painel direito. Use a barra de pesquisa para localizar a entidade de serviço para a aplicação CMK e selecione-a na lista. Quando terminar, selecione Save.

Habilitar a configuração da chave de criptografia no Experience Platform send-to-adobe

Depois de instalar o aplicativo CMK em Azure, você pode enviar o identificador de chave de criptografia para o Adobe. Selecione Keys na navegação à esquerda, seguido pelo nome da chave que você deseja enviar.

Selecione a versão mais recente da chave e sua página de detalhes será exibida. Aqui, você pode configurar opcionalmente as operações permitidas para a chave.

O campo Identificador de Chave exibe o identificador de URI para a chave. Copie este valor de URI para usar na próxima etapa.

Depois de obter o URI do cofre de chaves, você pode enviá-lo usando uma solicitação POST para o endpoint de configuração do CMK.

Solicitação

curl -X POST \
  https://platform.adobe.io/data/infrastructure/manager/customer/config \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: acp_provisioning' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -d '{
        "name": "Config1",
        "type": "BYOK_CONFIG",
        "imsOrgId": "{ORG_ID}",
        "configData": {
          "providerType": "AZURE_KEYVAULT",
          "keyVaultKeyIdentifier": "https://adobecmkexample.vault.azure.net/keys/adobeCMK-key/7c1d50lo28234cc895534c00d7eb4eb4"
        }
      }'

Resposta

{
  "id": "4df7886b-a122-4391-880b-47888d5c5b92",
  "config": {
    "configData": {
      "keyVaultUri": "https://adobecmkexample.vault.azure.net",
      "keyVaultKeyIdentifier": "https://adobecmkexample.vault.azure.net/keys/adobeCMK-key/7c1d50lo28234cc895534c00d7eb4eb4",
      "keyVersion": "7c1d50lo28234cc895534c00d7eb4eb4",
      "keyName": "Config1",
      "providerType": "AZURE_KEYVAULT"
    },
    "name": "acpcf978863Aaepcmkmultitenantapp",
    "type": "BYOK_CONFIG",
    "imsOrgId": "{ORG_ID}",
    "status": "NEW"
  },
  "status": "CREATED"
}

O processo deve ser concluído em alguns minutos.

Verificar o status da configuração check-status

Para verificar o status da solicitação de configuração, faça uma solicitação GET.

Solicitação

Você deve anexar o name da configuração que deseja verificar ao caminho (config1 no exemplo abaixo) e incluir um parâmetro de consulta configType definido como BYOK_CONFIG.

curl -X GET \
  https://platform.adobe.io/data/infrastructure/manager/customer/config/config1?configType=BYOK_CONFIG \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: acp_provisioning' \
  -H 'x-gw-ims-org-id: {ORG_ID}'

Resposta

{
  "name": "acpcf978863Aaepcmkmultitenantapp",
  "type": "BYOK_CONFIG",
  "status": "COMPLETED",
  "configData": {
    "keyVaultUri": "https://adobecmkexample.vault.azure.net",
    "keyVaultKeyIdentifier": "https://adobecmkexample.vault.azure.net/keys/adobeCMK-key/7c1d50lo28234cc895534c00d7eb4eb4",
    "keyVersion": "7c1d50lo28234cc895534c00d7eb4eb4",
    "keyName": "Config1",
    "providerType": "AZURE_KEYVAULT"
  },
  "imsOrgId": "{ORG_ID}",
  "subscriptionId": "cf978863-7325-47b1-8fd9-554b9fdb6c36",
  "id": "4df7886b-a122-4391-880b-47888d5c5b92",
  "rowType": "BYOK_KEY"
}

O atributo status pode ter um de quatro valores com os seguintes significados:

Próximas etapas

Ao concluir as etapas acima, você ativou o CMK com êxito para sua organização. Os dados assimilados nos armazenamentos de dados principais agora serão criptografados e descriptografados usando a(s) chave(s) no Cofre da Chave do Azure. Para saber mais sobre a criptografia de dados no Adobe Experience Platform, consulte a documentação sobre criptografia.