Credenziali del servizio

Le integrazioni con AEM as a Cloud Service devono essere in grado di eseguire l’autenticazione in AEM in modo sicuro. La Console per sviluppatori di AEM consente l’accesso a Credenziali di servizio, utilizzate per facilitare l’interazione programmatica di applicazioni, sistemi e servizi esterni con i servizi Author o Publish di AEM tramite HTTP.

Le credenziali del servizio possono apparire simili Token di accesso allo sviluppo locale ma sono diverse in alcuni modi chiave:

• Le credenziali del servizio sono non token di accesso, ma sono credenziali utilizzate per ottenere token di accesso.
• Le credenziali del servizio sono più permanenti (scadono ogni 365 giorni) e non cambiano se non vengono revocate, mentre i token di accesso allo sviluppo locale scadono ogni giorno.
• Le credenziali del servizio per un ambiente AEM as a Cloud Service vengono mappate su un singolo utente dell’account tecnico AEM, mentre i token di accesso allo sviluppo locale si autenticano come l’utente AEM che ha generato il token di accesso.

Sia le credenziali del servizio che i token di accesso generati, nonché i token di accesso allo sviluppo locale, devono essere mantenuti segreti, in quanto possono essere utilizzati tutti e tre per ottenere l’accesso ai rispettivi ambienti AEM as a Cloud Service

Genera credenziali del servizio

La generazione delle credenziali del servizio è suddivisa in due passaggi:

1. Inizializzazione delle credenziali di servizio una tantum da parte di un amministratore dell’organizzazione Adobe IMS
2. Download e utilizzo del JSON delle credenziali del servizio

Inizializzazione delle credenziali del servizio

Le credenziali del servizio, a differenza dei token di accesso allo sviluppo locale, richiedono un inizializzazione una tantum da parte dell'amministratore IMS di Adobe Org prima di poter essere scaricate.

Inizializzazione una tantum per ambiente AEM as a Cloud Service

1. Verifica di aver effettuato l’accesso come amministratore dell’organizzazione Adobe IMS
2. Accedi a Adobe Cloud Manager
3. Apri il programma contenente l’ambiente AEM as a Cloud Service per integrare l’impostazione delle credenziali del servizio per
4. Tocca i puntini di sospensione accanto all’ambiente nella sezione Ambienti e seleziona Console per sviluppatori
5. Tocca la scheda Integrazioni .
6. Tocca il pulsante Ottieni credenziali servizio
7. Le credenziali del servizio verranno inizializzate e visualizzate come JSON

Una volta inizializzate le credenziali del servizio dell’ambiente AEM as Cloud Service, altri sviluppatori AEM nell’organizzazione Adobe IMS possono scaricarle.

Scaricare le credenziali del servizio

Il download delle credenziali del servizio segue gli stessi passaggi dell'inizializzazione. Se l'inizializzazione non si è ancora verificata, all'utente verrà visualizzato un errore premendo il pulsante Ottieni credenziali servizio .

1. Assicurati di essere membro del profilo di prodotto Cloud Manager - Developer IMS (che consente l'accesso ad AEM Developer Console)
   • Gli ambienti AEM as a Cloud Service sandbox richiedono l’iscrizione solo nel profilo di prodotto Amministratori AEM o Utenti AEM
2. Accedi a Adobe Cloud Manager
3. Apri il programma contenente l’ambiente AEM as a Cloud Service con cui eseguire l’integrazione
4. Tocca i puntini di sospensione accanto all’ambiente nella sezione Ambienti e seleziona Console per sviluppatori
5. Tocca la scheda Integrazioni .
6. Tocca il pulsante Ottieni credenziali servizio
7. Tocca il pulsante di download nell’angolo in alto a sinistra per scaricare il file JSON contenente il valore delle credenziali del servizio e salvare il file in una posizione sicura.
   • Se le credenziali del servizio sono compromesse, contatta immediatamente il supporto Adobe per richiederne la revoca

Installare le credenziali del servizio

Le credenziali del servizio forniscono i dettagli necessari per generare un JWT, scambiato con un token di accesso utilizzato per l’autenticazione con AEM as a Cloud Service. Le credenziali del servizio devono essere memorizzate in un percorso sicuro accessibile dalle applicazioni, dai sistemi o dai servizi esterni che le utilizzano per accedere ad AEM. Come e dove vengono gestite le credenziali del servizio saranno univoci per cliente.

Per semplicità, questa esercitazione passa le credenziali di servizio in tramite la riga di comando, tuttavia, collabora con il team di sicurezza IT per comprendere come archiviare e accedere a tali credenziali in conformità alle linee guida di sicurezza della tua organizzazione.

1. Copia il scaricato Service Credentials JSON in un file denominato service_token.json nella directory principale del progetto
   • Ma ricorda, non impegnare mai nessuna creatività a Git!

Utilizzare le credenziali del servizio

Le credenziali del servizio, un oggetto JSON completo, non sono uguali né al JWT né al token di accesso. Le credenziali del servizio (che contengono una chiave privata) vengono invece utilizzate per generare un JWT, che viene scambiato con le API Adobe IMS per un token di accesso.

1. Scarica le credenziali del servizio da AEM Developer Console in un percorso protetto
2. Un’applicazione esterna deve interagire programmaticamente con gli ambienti AEM as a Cloud Service
3. L'applicazione esterna legge le credenziali del servizio da una posizione protetta
4. L’applicazione esterna utilizza le informazioni provenienti dalle credenziali del servizio per creare un token JWT
5. Il token JWT viene inviato ad Adobe IMS per scambiare un token di accesso
6. Adobe IMS restituisce un token di accesso che può essere utilizzato per accedere ad AEM as a Cloud Service
   • La scadenza dei token di accesso può essere richiesta. È consigliabile mantenere la vita breve del token di accesso e aggiornarlo quando necessario.
7. L’applicazione esterna invia richieste HTTP ad AEM as a Cloud Service, aggiungendo il token di accesso come token portatore all’intestazione Autorizzazione delle richieste HTTP
8. AEM as a Cloud Service riceve la richiesta HTTP, autentica la richiesta ed esegue il lavoro richiesto dalla richiesta HTTP e restituisce una risposta HTTP all’applicazione esterna

Aggiornamenti dell’applicazione esterna

Per accedere ad AEM as a Cloud Service utilizzando le credenziali del servizio, l’applicazione esterna deve essere aggiornata in 3 modi:

1. Leggi nelle credenziali del servizio
   • Per semplicità, li leggeremo dal file JSON scaricato, ma in scenari di utilizzo reale, le credenziali del servizio devono essere memorizzate in modo sicuro in conformità alle linee guida per la sicurezza della tua organizzazione
2. Generare una JWT dalle credenziali del servizio
3. Scambio JWT per un token di accesso
   • Quando sono presenti le credenziali del servizio, la nostra applicazione esterna utilizza questo token di accesso invece del token di accesso allo sviluppo locale, quando si accede ad AEM as a Cloud Service

In questa esercitazione, il modulo npm di Adobe @adobe/jwt-auth viene utilizzato per entrambi, (1) generare il JWT dalle credenziali del servizio e (2) scambiarlo per un token di accesso, in una singola chiamata della funzione. Se la tua applicazione non è basata su JavaScript, controlla il codice di esempio in altri linguaggi per sapere come creare un JWT dalle credenziali del servizio e scambialo per un token di accesso con Adobe IMS.

Leggi le credenziali del servizio

Rivedi la sezione getCommandLineParams() e scopri che è possibile leggere nei file JSON delle credenziali del servizio utilizzando lo stesso codice utilizzato per leggere nel JSON del token di accesso allo sviluppo locale.

function getCommandLineParams() {
    ...

    // Read in the credentials from the provided JSON file
    // Since both the Local Development Access Token and Service Credentials files are JSON, this same approach can be re-used
    if (parameters.file) {
        parameters.developerConsoleCredentials = JSON.parse(fs.readFileSync(parameters.file));
    }

    ...
    return parameters;
}

Creare un JWT e scambiare un token di accesso

Una volta lette le credenziali del servizio, vengono utilizzate per generare un JWT che viene poi scambiato con le API Adobe IMS per un token di accesso, che può quindi essere utilizzato per accedere ad AEM as a Cloud Service.

Questa applicazione di esempio è basata su Node.js, quindi è meglio utilizzare il modulo @adobe/jwt-auth npm per facilitare la generazione (1) JWT e (20 scambio con Adobe IMS. Se l'applicazione viene sviluppata utilizzando un'altra lingua, controlla gli esempi di codice appropriati su come creare la richiesta HTTP ad Adobe IMS utilizzando altri linguaggi di programmazione.

1. Aggiorna il getAccessToken(..) per controllare il contenuto del file JSON e determinare se rappresenta un token di accesso allo sviluppo locale o le credenziali del servizio. Questo può essere facilmente ottenuto controllando l’esistenza della proprietà .accessToken , che esiste solo per il token di accesso allo sviluppo locale JSON.

   Se vengono fornite le credenziali di servizio, l’applicazione genera un JWT e lo scambia con Adobe IMS per un token di accesso. Useremo la funzione @adobe/jwt-auth auth(...) che genera un JWT e lo scambia per un token di accesso in una singola chiamata di funzione. I parametri a auth(..) è un oggetto JSON composto da informazioni specifiche disponibile dal JSON delle credenziali del servizio, come descritto di seguito nel codice.

    async function getAccessToken(developerConsoleCredentials) {
   
        if (developerConsoleCredentials.accessToken) {
            // This is a Local Development access token
            return developerConsoleCredentials.accessToken;
        } else {
            // This is the Service Credentials JSON object that must be exchanged with Adobe IMS for an access token
            let serviceCredentials = developerConsoleCredentials.integration;
   
            // Use the @adobe/jwt-auth library to pass the service credentials generated a JWT and exchange that with Adobe IMS for an access token.
            // If other programming languages are used, please see these code samples: https://www.adobe.io/authentication/auth-methods.html#!AdobeDocs/adobeio-auth/master/JWT/samples/samples.md
            let { access_token } = await auth({
                clientId: serviceCredentials.technicalAccount.clientId, // Client Id
                technicalAccountId: serviceCredentials.id,              // Technical Account Id
                orgId: serviceCredentials.org,                          // Adobe IMS Org Id
                clientSecret: serviceCredentials.technicalAccount.clientSecret, // Client Secret
                privateKey: serviceCredentials.privateKey,              // Private Key to sign the JWT
                metaScopes: serviceCredentials.metascopes.split(','),   // Meta Scopes defining level of access the access token should provide
                ims: `https://${serviceCredentials.imsEndpoint}`,       // IMS endpoint used to obtain the access token from
            });
   
            return access_token;
        }
    }
   

   Ora, a seconda del file JSON - il JSON del token di accesso allo sviluppo locale o il JSON delle credenziali del servizio - viene passato tramite il parametro della riga di comando file , l’applicazione deriva un token di accesso.

   Tieni presente che, mentre le credenziali del servizio non scadono, il JWT e il token di accesso corrispondente funzionano e devono essere aggiornati prima della scadenza. Per farlo, utilizza un refresh_token fornito da Adobe IMS.

2. Con queste modifiche, e il JSON delle credenziali del servizio scaricato da AEM Developer Console (e per semplicità, salvato come service_token.json la stessa cartella di questo index.js), esegui l’applicazione sostituendo il parametro della riga di comando file con service_token.json e aggiorna il propertyValue a un nuovo valore in modo che gli effetti siano evidenti in AEM.

   $ node index.js \
       aem=https://author-p1234-e5678.adobeaemcloud.com \
       folder=/wknd/en/adventures/napa-wine-tasting \
       propertyName=metadata/dc:rights \
       propertyValue="WKND Restricted Use" \
       file=service_token.json
   

   L'output sul terminale sarà simile al seguente:

   200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting.json
   403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_277654931.jpg.json
   403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_239751461.jpg.json
   403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_280313729.jpg.json
   403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_286664352.jpg.json
   

   Le righe 403 - Forbidden indicano gli errori nelle chiamate API HTTP ad AEM as a Cloud Service. Questi 403 Errori proibiti si verificano quando si tenta di aggiornare i metadati delle risorse.

   Questo perché il token di accesso derivato da Service Credentials autentica la richiesta ad AEM utilizzando un account tecnico creato automaticamente dall’utente AEM, che per impostazione predefinita dispone solo dell’accesso in lettura. Per fornire l’accesso in scrittura all’applicazione AEM, all’utente tecnico AEM associato al token di accesso deve essere concessa l’autorizzazione in AEM.

Configurare l’accesso in AEM

Il token di accesso derivato da Credenziali del servizio utilizza un account tecnico AEM User che è membro del gruppo di utenti AEM dei collaboratori.

Una volta che l’account tecnico AEM esiste in AEM (dopo la prima richiesta HTTP con il token di accesso), le autorizzazioni di questo utente AEM possono essere gestite come gli altri utenti AEM.

1. Per prima cosa, individua il nome di accesso AEM dell’account tecnico aprendo il JSON delle credenziali del servizio scaricato da AEM Developer Console e individua il valore integration.email che deve essere simile a: 12345678-abcd-9000-efgh-0987654321c@techacct.adobe.com.
2. Accedi al servizio Author dell’ambiente AEM corrispondente come amministratore AEM
3. Passa a Strumenti > Sicurezza > Utenti
4. Individua l’utente AEM con il Nome di accesso identificato nel passaggio 1 e apri le relative Proprietà
5. Passa alla scheda Gruppi e aggiungi il gruppo Utenti DAM (che come accesso in scrittura alle risorse)
6. Tocca Salva e chiudi

Se l’account tecnico in AEM dispone delle autorizzazioni di scrittura sulle risorse, esegui nuovamente l’applicazione:

$ node index.js \
    aem=https://author-p1234-e5678.adobeaemcloud.com \
    folder=/wknd/en/adventures/napa-wine-tasting \
    propertyName=metadata/dc:rights \
    propertyValue="WKND Restricted Use" \
    file=service_token.json

L'output sul terminale sarà simile al seguente:

200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_277654931.jpg.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_286664352.jpg.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_239751461.jpg.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd/en/adventures/napa-wine-tasting/AdobeStock_280313729.jpg.json

Verifica le modifiche

1. Accedi all’ambiente AEM as a Cloud Service che è stato aggiornato (utilizzando lo stesso nome host fornito nel parametro della riga di comando aem )
2. Passa a Risorse > File
3. Spostati nella cartella risorse specificata dal parametro della riga di comando folder, ad esempio WKND > Inglese > Avventure > Degustazione dei vini Napa
4. Apri Proprietà per qualsiasi risorsa nella cartella
5. Passa alla scheda Avanzate
6. Rivedi il valore della proprietà aggiornata, ad esempio Copyright mappata alla proprietà metadata/dc:rights JCR aggiornata, che ora riflette il valore fornito nel parametro propertyValue, ad esempio Uso limitato WKND

Congratulazioni!

Ora che abbiamo effettuato l’accesso a livello di programmazione ad AEM as a Cloud Service utilizzando un token di accesso per lo sviluppo locale e un token di accesso da servizio a servizio pronto per la produzione!