Configurare e configurare le chiavi gestite dal cliente tramite l’API

Ultimo aggiornamento: 2023-10-31
  • Creato per:
  • Developer
    User
    Admin
    Leader

Questo documento descrive il processo di abilitazione della funzione chiavi gestite dal cliente (CMK) in Adobe Experience Platform utilizzando l’API. Per istruzioni su come completare questo processo utilizzando l’interfaccia utente, consulta Documento di configurazione della CMK per l’interfaccia utente.

Prerequisiti

Per visualizzare e visitare il Crittografia in Adobe Experience Platform, è necessario aver creato un ruolo e assegnato il Gestisci chiave gestita dal cliente autorizzazione per quel ruolo. Qualsiasi utente che dispone di Gestisci chiave gestita dal cliente L’autorizzazione può abilitare la CMK per la loro organizzazione.

Per ulteriori informazioni sull’assegnazione di ruoli e autorizzazioni in Experienci Platform, consulta configurare la documentazione sulle autorizzazioni.

Per attivare la CMK, Azure L’insieme di credenziali delle chiavi deve essere configurato con le seguenti impostazioni:

Configurare l’app CMK

Dopo aver configurato l'insieme di credenziali delle chiavi, il passaggio successivo consiste nel registrarsi per l'applicazione CMK che verrà collegata al Azure tenant.

Introduzione

La registrazione dell’app CMK richiede di effettuare chiamate alle API di Platform. Per informazioni dettagliate su come raccogliere le intestazioni di autenticazione necessarie per effettuare queste chiamate, vedi Guida all’autenticazione API di Platform.

La guida all’autenticazione fornisce istruzioni su come generare un valore univoco per il x-api-key richiesta, tutte le operazioni API in questa guida utilizzano il valore statico acp_provisioning invece. Devi comunque fornire i tuoi valori per {ACCESS_TOKEN} e {ORG_ID}, tuttavia.

In tutte le chiamate API mostrate in questa guida, platform.adobe.io viene utilizzato come percorso principale, che per impostazione predefinita corrisponde all'area VA7. Se la tua organizzazione utilizza un’area geografica diversa, platform deve essere seguito da un trattino e dal codice di regione assegnato alla tua organizzazione: nld2 per NLD2 o aus5 per AUS5 (ad esempio: platform-aus5.adobe.io). Se non conosci l’area geografica della tua organizzazione, contatta l’amministratore di sistema.

Recuperare un URL di autenticazione

GET Per avviare il processo di registrazione, effettua una richiesta all’endpoint di registrazione dell’app per recuperare l’URL di autenticazione richiesto per la tua organizzazione.

Richiesta

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}'

Risposta

In caso di esito positivo, la risposta restituisce applicationRedirectUrl contenente l'URL di autenticazione.

{
    "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"
}

Copiare e incollare applicationRedirectUrl in un browser per aprire una finestra di dialogo di autenticazione. Seleziona Accept per aggiungere l’entità del servizio app CMK al tuo Azure tenant.

Finestra di dialogo per la richiesta di autorizzazione di Microsoft con Accetta evidenziato.

Assegnare l'app CMK a un ruolo

Dopo aver completato il processo di autenticazione, torna al Azure Key Vault e selezione Access control nel menu di navigazione a sinistra. Da qui, seleziona Add seguito da Add role assignment.

Dashboard di Microsoft Azure con Add e Add role assignment evidenziato.

Nella schermata successiva viene richiesto di scegliere un ruolo per l'assegnazione. Seleziona Key Vault Crypto Service Encryption User prima di selezionare Next per continuare.

Dashboard di Microsoft Azure con Key Vault Crypto Service Encryption User evidenziato.

Nella schermata successiva scegliere Select members per aprire una finestra di dialogo nella barra a destra. Utilizzare la barra di ricerca per individuare l'entità servizio per l'applicazione CMK e selezionarla dall'elenco. Al termine, seleziona Save.

NOTA

Se l'applicazione non è presente nell'elenco, l'entità servizio non è stata accettata nel tenant. Per assicurarti di disporre dei privilegi corretti, utilizza Azure amministratore o rappresentante.

Abilita la configurazione della chiave di crittografia su Experienci Platform

Dopo aver installato l’app CMK su Azure, puoi inviare l’identificatore della chiave di crittografia ad Adobe. Seleziona Keys nel menu di navigazione a sinistra, seguito dal nome della chiave che desideri inviare.

Dashboard di Microsoft Azure con Keys e il nome chiave evidenziato.

Seleziona la versione più recente della chiave e viene visualizzata la pagina dei relativi dettagli. Da qui, puoi facoltativamente configurare le operazioni consentite per la chiave.

IMPORTANTE

Le operazioni minime richieste per la chiave sono le Wrap Key e Unwrap Key autorizzazioni. Puoi includere Encrypt, Decrypt, Sign, e Verify dovrebbe volere.

Il Identificatore chiave visualizza l’identificatore URI della chiave. Copia questo valore URI da utilizzare nel passaggio successivo.

I dettagli della chiave del dashboard di Microsoft Azure con Permitted operations ed evidenziate le sezioni copia URL chiave.

Dopo aver ottenuto l’URI dell’insieme di credenziali delle chiavi, puoi inviarlo utilizzando una richiesta POST all’endpoint di configurazione CMK.

NOTA

Con Adobe vengono memorizzati solo l’insieme di credenziali delle chiavi e il nome della chiave, non la versione della chiave.

Richiesta

 Richiesta di esempio per inviare l’URI dell’insieme di credenziali delle chiavi all’endpoint di configurazione CMK.
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"
        }
      }'
Proprietà Descrizione
name Un nome per la configurazione. Assicurati di ricordare questo valore in quanto necessario per controllare lo stato della configurazione in un passaggio successivo. Il valore distingue tra maiuscole e minuscole.
type Il tipo di configurazione. Deve essere impostato su BYOK_CONFIG.
imsOrgId Il tuo ID organizzazione. Questo ID deve essere lo stesso valore fornito in x-gw-ims-org-id intestazione.
configData Questa proprietà contiene i seguenti dettagli sulla configurazione:
  • providerType: Deve essere impostato su AZURE_KEYVAULT.
  • keyVaultKeyIdentifier: URI dell’insieme di credenziali delle chiavi copiato precedente.

Risposta

 In caso di esito positivo, la risposta restituisce i dettagli del processo di configurazione.
{
  "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"
}

L’elaborazione del processo dovrebbe essere completata entro pochi minuti.

Verificare lo stato della configurazione

Per controllare lo stato della richiesta di configurazione, puoi effettuare una richiesta GET.

Richiesta

È necessario aggiungere name della configurazione da controllare nel percorso (config1 nell’esempio seguente) e includono un configType parametro query impostato su BYOK_CONFIG.

 Una richiesta di esempio per controllare lo stato della richiesta di configurazione.
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}'

Risposta

 In caso di esito positivo, la risposta restituisce lo stato del processo.
{
  "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"
}

Il status l'attributo può avere uno dei quattro valori con i seguenti significati:

  1. RUNNING: verifica che Platform possa accedere all’insieme di credenziali delle chiavi e delle chiavi.
  2. UPDATE_EXISTING_RESOURCES: il sistema sta aggiungendo l’insieme di credenziali e il nome della chiave agli archivi di dati in tutte le sandbox dell’organizzazione.
  3. COMPLETED: l’insieme di credenziali delle chiavi e il nome della chiave sono stati aggiunti correttamente agli archivi dati.
  4. FAILED: si è verificato un problema, principalmente relativo alla chiave, all’insieme di credenziali delle chiavi o alla configurazione di app multi-tenant.

Passaggi successivi

Completando i passaggi precedenti, hai abilitato correttamente la CMK per la tua organizzazione. I dati acquisiti negli archivi di dati primari ora vengono crittografati e decrittografati utilizzando le chiavi nella Azure Key Vault Per ulteriori informazioni sulla crittografia dei dati in Adobe Experience Platform, consulta documentazione sulla crittografia.

In questa pagina