Generazione dei token di accesso per le API lato server generating-access-tokens-for-server-side-apis

Alcune architetture si basano sull’esecuzione di chiamate ad Adobe Experience Manager (AEM) as a Cloud Service da un’applicazione ospitata su un server al di fuori dell’infrastruttura AEM. Ad esempio, un’app mobile chiama un server, che quindi effettua richieste API ad AEM as a Cloud Service.

Utilizza AEM as a Cloud Service Developer Console per creare un account tecnico da server a server OAuth. L’applicazione scambia l’ID client e il segreto client con un token di accesso utilizzando la sovvenzione Adobe Identity Management Services (IMS) client_credentials. Non è richiesto alcun JWT firmato, chiave privata o certificato.

Flusso server-to-server the-server-to-server-flow

Gli utenti con un ruolo di amministratore dell’organizzazione IMS che sono anche membri del profilo di prodotto Utenti AEM o Amministratori AEM in AEM Author possono creare un account tecnico. Il segreto client viene mostrato solo all’utente che lo crea, al momento della creazione. L’utente con il ruolo di amministratore dell’ambiente AEM as a Cloud Service può visualizzare i dettagli dell’account, che non includono il segreto client.

Il flusso server-to-server prevede i seguenti passaggi:

Creare un account tecnico e recuperarne le credenziali fetch-the-aem-as-a-cloud-service-credentials

Per rivedere i dettagli di un segreto in un secondo momento, aprire il menu a righe del segreto client e selezionare Visualizza. La finestra di dialogo delle credenziali mostra l’endpoint IMS, gli ambiti, l’ID client, l’e-mail dell’account tecnico, l’ID segreto e lo stato di revoca. Non mostra il valore segreto client.

Installare le credenziali del servizio AEM su un server non AEM install-the-aem-service-credentials-on-a-non-aem-server

Rendi le credenziali disponibili solo per l’applicazione lato server che chiama AEM. Utilizza un gestore segreto o un altro meccanismo di archiviazione controllato dagli accessi.

Non inserire un segreto client nel codice lato browser, nelle applicazioni mobili, nel controllo del codice sorgente o nei registri. Tratta i token di accesso anche come segreti.

Richiedere un token di accesso OAuth request-an-oauth-access-token

Invia una richiesta HTTPS POST a https://<imsEndpoint>/ims/token/v3. imsEndpoint nelle credenziali JSON è un nome host IMS. Ad esempio, ims-na1.adobelogin.com utilizza https://ims-na1.adobelogin.com/ims/token/v3. Utilizza il nome host fornito nelle credenziali, incluso il nome host dell’area di visualizzazione quando utilizzi le credenziali dell’area di visualizzazione.

Utilizza Content-Type: application/x-www-form-urlencoded e includi questi campi modulo nel corpo della richiesta:

Codifica URL per ogni valore del modulo. Invia segreti nel corpo della richiesta, non nell’URL o nella stringa di query.

La risposta include access_token, token_type e expires_in. Utilizza access_token per chiamare AEM. Il valore expires_in è la durata del token in secondi. Utilizza tale valore anziché presupporre un tempo di scadenza fisso.

Memorizza in cache e riutilizza il token di accesso fino alla scadenza, quindi richiedi un nuovo token con le stesse credenziali client. Questa concessione non richiede uno scambio JWT o un token di aggiornamento.

Esempio di autenticazione di Node.js nodejs-authentication-example

Per un’implementazione minima da server a server OAuth, vedi l’esempio Libreria client API AEM-CS. Utilizza le API Node.js integrate e richiede Node.js 18 o versione successiva, senza dipendenze aggiuntive.

Nell’esempio sono previste le credenziali all’interno di un oggetto integration. Il file aem-s2s-credentials.json scaricato da AEM Developer Console contiene le credenziali senza questo wrapper. Racchiudi il contenuto prima di utilizzarlo con l’esempio, ad esempio con jq:

jq '{integration: .}' aem-s2s-credentials.json > downloaded_integration.json

In alternativa, modificare il file in modo che il relativo contenuto completo diventi il valore di un campo integration di primo livello. Da un checkout dell’archivio di esempio, esegui:

node oauth-s2s-cli.js downloaded_integration.json

Per uso programmatico, l’helper OAuth accetta l’oggetto racchiuso come requestAccessToken(credentials). Utilizza il nome host IMS, l’ID client, il segreto client e gli ambiti in integration.

Mantenere privato il file delle credenziali. CLI stampa un token di accesso. Non inviare il relativo output ai registri condivisi e non pubblicarlo. Il file README dell’esempio mostra anche come utilizzare il token in una richiesta API di AEM.

Chiamata dell’API AEM calling-the-aem-api

Includi il token di accesso nell’intestazione Authorization delle richieste per l’ambiente AEM as a Cloud Service, utilizzando il valore Bearer <access_token>.

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  "https://author-p<program-id>-e<environment-id>.adobeaemcloud.com/content/dam.json"

Utilizza il nome host per l’ambiente e il livello a cui accede l’applicazione. Richiama solo le risorse a cui l’account tecnico è autorizzato ad accedere.

Impostare le autorizzazioni appropriate per l’utente dell’account tecnico in AEM set-the-appropriate-permissions-for-the-technical-account-user-in-aem

Per ulteriori informazioni su utenti e gruppi IMS e AEM, consulta Supporto IMS.

Flusso per sviluppatori developer-flow

Per i test locali, gli sviluppatori possono generare un token di accesso allo sviluppo direttamente in AEM Developer Console senza creare un account tecnico OAuth Server-to-Server. Il token può essere utilizzato per chiamare gli ambienti AEM a cui lo sviluppatore può accedere. Per le applicazioni lato server automatizzate, utilizza le credenziali da server a server di OAuth anziché un token di sviluppo locale.

Consulta le Linee guida per sviluppatori per informazioni sulle autorizzazioni necessarie per utilizzare AEM Developer Console.

Generazione del token di accesso generating-the-access-token

Chiamare l’applicazione AEM con un token di accesso call-the-aem-application-with-an-access-token

Utilizzare il token di accesso allo sviluppo locale come token Bearer nell’intestazione Authorization, come descritto in Chiamata dell’API AEM.

Per un progetto AEM in esecuzione sul computer locale, non è necessario un token di accesso IMS.

Ruota segreti client refresh-credentials

Le credenziali da server a server OAuth non richiedono il rinnovo annuale del certificato. Ruota periodicamente i segreti del client e ogni volta che viene esposto un segreto. Crea un nuovo segreto, passa alle applicazioni e solo dopo revoca il vecchio segreto.

La creazione e la revoca dei segreti richiede i valori segreti salvati. AEM Developer Console utilizza un segreto immesso solo per autenticare la richiesta con IMS e non la memorizza.

Revoca credenziali credentials-revocation

Revoca disabilita un segreto selezionato per le nuove richieste di token. Richiede il valore del segreto da revocare. La propagazione della revoca può richiedere del tempo. Non presumere che la revoca di un segreto invalidi immediatamente i token di accesso già rilasciati.

Elimina su un segreto revocato rimuove i metadati, quali l’ID segreto e lo stato di revoca, da AEM Developer Console. Non esegue una revoca IMS separata e non è disponibile per i segreti attivi.

Eliminare un account tecnico delete-a-technical-account

L’eliminazione di un account tecnico comporta la revoca immediata dell’account e di tutti i segreti client in IMS. Non vengono rilasciati nuovi token di accesso per alcuna credenziale nell’account e le integrazioni che li utilizzano non funzionano più alla scadenza dei token correnti. Per ripristinare l’accesso, devi creare un nuovo account tecnico, aggiornare le applicazioni con le relative credenziali e assegnare nuovamente le autorizzazioni necessarie in AEM.

L’eliminazione dell’account non può essere annullata. Conferma solo dopo aver verificato quali applicazioni dipendono dall’account e non utilizzarlo come passaggio di rotazione individuale-segreto.

Migrare un’integrazione basata su JWT migrate-a-jwt-based-integration

Per le operazioni relative ai certificati e alle chiavi private sul vecchio account, consulta la Guida legacy JWT. Non rimuovere il vecchio account prima della verifica dell’integrazione di sostituzione.