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

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 il processo utilizzando l'interfaccia utente, fare riferimento al documento di installazione della CMK UI.

Prerequisiti

Per visualizzare e visitare la sezione Crittografia in Adobe Experience Platform, è necessario aver creato un ruolo e assegnato l'autorizzazione Gestione chiave gestita dal cliente a tale ruolo. Qualsiasi utente con l'autorizzazione Gestione chiave gestita dal cliente può abilitare la CMK per la propria organizzazione.

Per ulteriori informazioni sull'assegnazione di ruoli e autorizzazioni in Experience Platform, consulta la documentazione sulla configurazione delle autorizzazioni.

Per abilitare CMK, l'insieme di credenziali delle chiavi Azure deve essere configurato con le impostazioni seguenti:

Configurare l’app CMK register-app

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

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, consulta la Guida all'autenticazione API di Platform.

Mentre la guida all'autenticazione fornisce istruzioni su come generare un valore univoco per l'intestazione richiesta x-api-key richiesta richiesta, tutte le operazioni API in questa guida utilizzano il valore statico acp_provisioning. È comunque necessario fornire valori personalizzati per {ACCESS_TOKEN} e {ORG_ID}.

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 l'organizzazione utilizza un'area geografica diversa, platform deve essere seguito da un trattino e il codice di area deve essere assegnato all'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 fetch-authentication-url

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 una proprietà 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 l'indirizzo applicationRedirectUrl in un browser per aprire una finestra di dialogo di autenticazione. Selezionare Accept per aggiungere l'entità servizio app CMK al tenant Azure.

Assegnare l'app CMK a un ruolo assign-to-role

Dopo aver completato il processo di autenticazione, torna all'insieme di credenziali delle chiavi Azure e seleziona Access control nell'area di navigazione a sinistra. Da qui, seleziona Add seguito da Add role assignment.

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

Nella schermata successiva, scegli 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, selezionare Save.

Abilita la configurazione della chiave di crittografia su Experience Platform send-to-adobe

Dopo aver installato l'app CMK in Azure, puoi inviare ad Adobe l'identificatore della chiave di crittografia. Selezionare Keys nel menu di navigazione a sinistra, seguito dal nome della chiave che si desidera inviare.

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.

Nel campo Identificatore chiave viene visualizzato l'identificatore URI della chiave. Copia questo valore URI da utilizzare nel passaggio successivo.

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

Richiesta

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

Risposta

{
  "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 check-status

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

Richiesta

Aggiungere name della configurazione da controllare al percorso (config1 nell'esempio seguente) e includere un parametro di query configType impostato su 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}'

Risposta

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

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

Passaggi successivi

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