Appeler des API AEM basées sur OpenAPI à l’aide de l’application d’une seule page OAuth
Découvrez comment appeler les API AEM basées sur OpenAPI sur AEM as a Cloud Service à l’aide de l’authentification par application d’une seule page OAuth. Elle suit le flux PKCE (Proof Key for Code Exchange) OAuth 2.0 pour l’authentification basée sur les utilisateurs et utilisatrices dans une application d’une seule page (SPA).
L’authentification par application d’une seule page OAuth est idéale pour les applications JavaScript exécutées dans le navigateur. S’il manque un serveur principal ou si les jetons d’accès doivent être récupérés pour interagir avec les API d’AEM au nom d’un utilisateur ou d’une utilisatrice.
Le flux PKCE étend le type d’octroi OAuth 2.0 authorization_code, ce qui renforce la sécurité en empêchant l’interception du code d’autorisation. Pour plus d’informations, consultez la section Différence entre les informations d’identification OAuth de serveur à serveur, d’application web et d’application d’une seule page.
Ce que vous apprenez what-you-learn
Dans cet article, vous apprenez ce qui suit :
-
Configurez un projet Adobe Developer Console (ADC) pour accéder aux API AEM basées sur OpenAPI à l’aide de l’authentification Application d’une seule page OAuth ou du flux PKCE OAuth 2.0.
-
Implémentez le flux d’authentification d’application d’une seule page OAuth dans une SPA personnalisée.
- Authentification de l’utilisateur ou de l’utilisatrice IMS et autorisation de l’application.
- Récupération du jeton d’accès à l’aide du flux PKCE OAuth 2.0.
- Utilisez le jeton d’accès pour appeler les API AEM basées sur OpenAPI.
Avant de commencer, vérifiez les points suivants :
Vue d’ensemble et flux fonctionnel de la SPA WKND wknd-spa-overview-and-functional-flow
Examinons ce qu’est la SPA WKND, comment elle est créée et comment elle fonctionne.
La SPA WKND est une application d’une seule page basée sur React qui montre comment obtenir en toute sécurité un jeton d’accès spécifique à l’utilisateur ou à l’utilisatrice et interagir avec les API AEM directement du côté client. Elle implémente le flux d’authentification PKCE OAuth 2.0 via Adobe IMS et s’intègre à deux API AEM essentielles :
- API Sites : pour accéder aux modèles de fragment de contenu
- API Assets : pour la gestion des dossiers de gestion des ressources numériques
Le projet Adobe Developer Console (ADC) est configuré pour activer l’authentification de l’application d’une seule page OAuth, fournissant le client_id requis pour lancer le flux PKCE OAuth 2.0.
Le diagramme suivant illustre le flux fonctionnel de la SPA WKND obtenant un jeton d’accès spécifique à l’utilisateur ou à l’utilisatrice pour appeler les API AEM basées sur OpenAPI :
- La SPA lance le flux d’authentification en dirigeant l’utilisateur ou l’utilisatrice vers le système Adobe Identity Management (IMS) via une demande d’autorisation.
- Dans le cadre de la demande d’autorisation, la SPA envoie les client_id, redirect_uri et code_challenge à IMS, en suivant le flux PKCE OAuth 2.0. La SPA génère un code_verifier aléatoire, le hache à l’aide de SHA-256 et Base64 code le résultat pour créer le code_challenge.
- IMS authentifie l’utilisateur ou l’utilisatrice et, une fois l’authentification réussie, émet un authorization_code, qui est renvoyé à la SPA via redirect_uri.
- La SPA échange le code authorization_code contre un jeton d’accès en envoyant une requête POST au point d’entrée du jeton IMS. Elle inclut le code_verifier dans la requête de validation du code_challenge envoyé précédemment. Cela permet de s’assurer que la demande d’autorisation (étape 2) et la demande de jeton (étape 4) sont liées au même flux d’authentification, empêchant les attaques d’interception.
- IMS valide le code_verifier et renvoie le jeton d’accès spécifique à l’utilisateur ou à l’utilisatrice.
- La SPA inclut le jeton d’accès dans les requêtes API à AEM pour authentifier et récupérer le contenu spécifique à l’utilisateur ou à l’utilisatrice.
La SPA WKND est une application basée sur React qui utilise le contexte React pour la gestion de l’état d’authentification et le routeur React pour la navigation.
D’autres frameworks SPA comme Angular, Vue ou Vanilla JavaScript peuvent être utilisés pour créer des SPA qui s’intègrent aux API Adobe à l’aide des approches illustrées dans ce tutoriel.
Comment utiliser ce tutoriel how-to-use-this-tutorial
Vous pouvez approcher ce tutoriel de deux manières différentes :
- Vérifier les fragments de code de clé SPA : comprenez le flux d’authentification de l’application d’une seule page OAuth et explorez les implémentations d’appels API clés dans la SPA WKND.
- Configurer et exécuter la SPA : suivez les instructions détaillées pour configurer et exécuter la SPA WKND sur votre ordinateur local.
Choisissez la méthode qui vous correspond le mieux.
Vérifier les fragments de code de clé SPA review-spa-key-code-snippets
Examinons les fragments de code de clé de la SPA WKND qui montrent comment accomplir ce qui suit :
-
Obtenez un jeton d’accès spécifique à l’utilisateur ou à l’utilisatrice à l’aide du flux d’authentification d’application d’une seule page OAuth.
-
Appelez les API AEM basées sur OpenAPI directement du côté client.
Ces extraits vous aident à comprendre le processus d’authentification et les interactions d’API dans la SPA.
Télécharger le code SPA download-the-spa-code
-
Téléchargez le fichier zip SPA WKND et API AEM - Application de démonstration et extrayez-le.
-
Accédez au dossier extrait et ouvrez le fichier
.env.example
dans votre éditeur de code préféré. Vérifiez les paramètres de configuration requis.code language-plaintext ######################################################################## # Adobe IMS, Adobe Developer Console (ADC), and AEM as a Cloud Service Information ######################################################################## # Adobe IMS OAuth endpoints REACT_APP_ADOBE_IMS_AUTHORIZATION_ENDPOINT=https://ims-na1.adobelogin.com/ims/authorize/v2 REACT_APP_ADOBE_IMS_TOKEN_ENDPOINT=https://ims-na1.adobelogin.com/ims/token/v3 # Adobe Developer Console (ADC) Project's OAuth Single-Page App credential REACT_APP_ADC_CLIENT_ID=<ADC Project OAuth Single-Page App credential ClientID> REACT_APP_ADC_SCOPES=<ADC Project OAuth Single-Page App credential Scopes> # AEM Assets Information REACT_APP_AEM_ASSET_HOSTNAME=<AEMCS Hostname, e.g., https://author-p63947-e1502138.adobeaemcloud.com/> ################################################ # Single Page Application Information ################################################ # Enable HTTPS for local development HTTPS=true PORT=3001 # SSL Certificate and Key for local development SSL_CRT_FILE=./ssl/server.crt SSL_KEY_FILE=./ssl/server.key # The URL to which the user will be redirected after the OAuth flow is complete REACT_APP_REDIRECT_URI=https://localhost:3000/callback
Vous devez remplacer les espaces réservés par les valeurs réelles du projet Adobe Developer Console (ADC) et de l’instance AEM as a Cloud Service Assets.
Authentification de l’utilisateur ou de l’utilisatrice IMS et autorisation SPA ims-user-authentication-and-spa-authorization
Explorons le code qui gère l’authentification des utilisateurs et utilisatrices IMS et l’autorisation SPA. Pour récupérer les modèles de fragment de contenu et les dossiers de gestion des ressources numériques, l’utilisateur ou l’utilisatrice doit s’authentifier auprès d’Adobe IMS et accorder à la SPA WKND l’autorisation d’accéder aux API AEM en son nom.
Lors de la connexion initiale, la personne est invitée à donner son consentement, ce qui permet à la SPA WKND d’accéder en toute sécurité aux ressources requises.
-
Dans le fichier
src/context/IMSAuthContext.js
, la fonctionlogin
lance l’authentification de l’utilisateur ou de l’utilisatrice IMS et le flux d’autorisation de l’application. Cela génère des élémentscode_verifier
etcode_challenge
aléatoires pour échanger en toute sécurité lecode
contre un jeton d’accès. Lecode_verifier
est stocké dans le stockage local pour une utilisation ultérieure. Comme mentionné précédemment, la SPA ne stocke pas et n’utilise pas lesclient_secret
. Elle en génère un à la volée et l’utilise en deux étapes : les demandesauthorize
ettoken
.code language-javascript ... const login = async () => { try { const codeVerifier = generateCodeVerifier(); const codeChallenge = generateCodeChallenge(codeVerifier); localStorage.setItem(STORAGE_KEYS.CODE_VERIFIER, codeVerifier); const params = new URLSearchParams( getAuthParams(AUTH_METHODS.S256, codeChallenge, codeVerifier) ); window.location.href = `${ APP_CONFIG.adobe.ims.authorizationEndpoint //https://ims-na1.adobelogin.com/ims/authorize/v2 }?${params.toString()}`; } catch (error) { console.error("Login initialization failed:", error); throw error; } }; ... // Generate a random code verifier export function generateCodeVerifier() { const array = new Uint8Array(32); window.crypto.getRandomValues(array); const wordArray = CryptoJS.lib.WordArray.create(array); return base64URLEncode(wordArray); } // Generate code challenge using SHA-256 export function generateCodeChallenge(codeVerifier) { const hash = CryptoJS.SHA256(codeVerifier); return base64URLEncode(hash); } // Get authorization URL parameters const getAuthParams = useCallback((method, codeChallenge, codeVerifier) => { const baseParams = { client_id: APP_CONFIG.adobe.adc.clientId, // ADC Project OAuth Single-Page App credential ClientID scope: APP_CONFIG.adobe.adc.scopes, // ADC Project OAuth Single-Page App credential Scopes response_type: "code", redirect_uri: APP_CONFIG.adobe.spa.redirectUri, // SPA redirect URI https://localhost:3000/callback code_challenge_method: method, // S256 or plain }; return { ...baseParams, code_challenge: method === AUTH_METHODS.S256 ? codeChallenge : codeVerifier, }; }, []); ...
Si la personne n’est pas authentifiée sur Adobe IMS, la page de connexion d’Adobe ID s’affiche et demande à la personne de s’authentifier.
Si la personne est déjà authentifiée, elle est redirigée vers l’URI redirect_uri spécifié de la SPA WKND avec un code authorization_code.
Récupération du jeton d’accès à l’aide du flux PKCE OAuth 2.0 access-token-retrieval-using-oauth-20-pkce-flow
La SPA WKND échange en toute sécurité le code authorization_code avec Adobe IMS contre un jeton d’accès spécifique à l’utilisateur ou à l’utilisatrice à l’aide des client_id et code_verifier.
-
Dans le fichier
src/context/IMSAuthContext.js
, la fonctionexchangeCodeForToken
échange le code authorization_code contre un jeton d’accès spécifique à l’utilisateur ou à l’utilisatrice.code language-javascript ... // Handle the callback from the Adobe IMS authorization endpoint const handleCallback = async (code) => { if (authState.isProcessingCallback) return; try { updateAuthState({ isProcessingCallback: true }); const data = await exchangeCodeForToken(code); if (data.access_token) { handleStorageToken(data.access_token); localStorage.removeItem(STORAGE_KEYS.CODE_VERIFIER); } } catch (error) { console.error("Error exchanging code for token:", error); throw error; } finally { updateAuthState({ isProcessingCallback: false }); } }; ... // Exchange the authorization code for an access token const exchangeCodeForToken = useCallback(async (code) => { const codeVerifier = localStorage.getItem(STORAGE_KEYS.CODE_VERIFIER); if (!codeVerifier) { throw new Error("No code verifier found"); } //https://ims-na1.adobelogin.com/ims/token/v3 const response = await fetch(APP_CONFIG.adobe.ims.tokenEndpoint, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ grant_type: "authorization_code", client_id: APP_CONFIG.adobe.adc.clientId, // ADC Project OAuth Single-Page App credential ClientID code_verifier: codeVerifier, // Code verifier generated during login code, // Authorization code received from the IMS redirect_uri: `${window.location.origin}/callback`, }), }); if (!response.ok) { throw new Error("Token request failed"); } return response.json(); }, []); const handleStorageToken = useCallback( (token) => { if (token) { localStorage.setItem(STORAGE_KEYS.ACCESS_TOKEN, token); updateAuthState({ isLoggedIn: true, accessToken: token }); } }, [updateAuthState] ); ...
Le jeton d’accès est stocké dans le stockage local du navigateur et utilisé dans les appels API suivants aux API AEM.
Accès aux API AEM basées sur OpenAPI à l’aide du jeton d’accès accessing-openapi-based-aem-apis-using-the-access-token
La SPA WKND utilise le jeton d’accès spécifique à l’utilisateur ou à l’utilisatrice pour appeler les modèles de fragment de contenu et les points d’entrée de l’API des dossiers de gestion des ressources numériques.
Dans le fichier src/components/InvokeAemApis.js
, la fonction fetchContentFragmentModels
explique comment utiliser le jeton d’accès pour appeler les API AEM basées sur OpenAPI à partir du côté client.
...
// Fetch Content Fragment Models
const fetchContentFragmentModels = useCallback(async () => {
try {
updateState({ isLoading: true, error: null });
const data = await makeApiRequest({
endpoint: `${API_PATHS.CF_MODELS}?cursor=0&limit=10&projection=summary`,
});
updateState({ cfModels: data.items });
} catch (err) {
updateState({ error: err.message });
console.error("Error fetching CF models:", err);
} finally {
updateState({ isLoading: false });
}
}, [makeApiRequest, updateState]);
// Common API request helper
const makeApiRequest = useCallback(
async ({ endpoint, method = "GET", passAPIKey = false, body = null }) => {
// Get the access token from the local storage
const token = localStorage.getItem("adobe_ims_access_token");
if (!token) {
throw new Error("No access token available. Please login again.");
}
const headers = {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
...(passAPIKey && { "x-api-key": APP_CONFIG.adobe.adc.clientId }),
};
const response = await fetch(
`${APP_CONFIG.adobe.aem.hostname}${endpoint}`,
{
method,
headers,
...(body && { body: JSON.stringify(body) }),
}
);
if (!response.ok) {
throw new Error(`API request failed: ${response.statusText}`);
}
return method === "DELETE" ? null : response.json();
},
[]
);
...
Configurer et exécuter la SPA setup-and-run-the-spa
Configurez et exécutez la SPA WKND sur votre ordinateur local pour comprendre le flux d’authentification de l’application d’une seule page OAuth et les appels API.
Prérequis prerequisites
Les éléments suivants sont requis afin de terminer ce tutoriel :
-
Environnement AEM as a Cloud Service modernisé avec les éléments suivants :
- AEM version
2024.10.18459.20241031T210302Z
ou version ultérieure. - Profils de produit avec un nouveau style (si l’environnement a été créé avant novembre 2024)
Consultez l’article Configurer des API AEM basées sur OpenAPI pour plus d’informations.
- AEM version
-
L’exemple de projet WKND Sites doit être déployé dessus.
-
Accédez à Adobe Developer Console.
-
Installez Node.js sur votre ordinateur local pour exécuter l’exemple d’application NodeJS.
Étapes de développement development-steps
Les étapes de développement générales sont les suivantes :
-
Configurer le projet ADC
- Ajoutez les API Assets et Sites.
- Configurez les informations d’identification de l’application d’une seule page OAuth.
-
Configurer l’instance AEM
- Pour activer la communication de projet ADC
- Pour autoriser la SPA à accéder aux API AEM en configurant les paramètres CORS.
-
Configurer et exécuter la SPA WKND sur votre ordinateur local
-
Vérifier le flux de bout en bout
Configurer le projet ADC configure-adc-project
L’étape Configurer le projet ADC est répétée à partir de Configurer les API AEM basées sur OpenAPI. Elle est répétée pour ajouter l’API Assets et Sites et configurer sa méthode d’authentification en tant qu’application d’une seule page OAuth.
-
Ouvrez le projet souhaité à partir d’Adobe Developer Console.
-
Pour ajouter des API AEM, cliquez sur le bouton Ajouter une API.
-
Dans la boîte de dialogue Ajouter une API, filtrez par Experience Cloud et sélectionnez la carte Gestion de contenu AEM CS Sites et cliquez sur Suivant.
note tip TIP Si la carte d’API AEM souhaitée est désactivée et les informations Pourquoi est-ce désactivé ? indiquent le message Licence requise, l’une des raisons peut être que vous n’avez PAS modernisé votre environnement AEM as a Cloud Service. Pour plus d’informations, consultez Modernisation de l’environnement AEM as a Cloud Service. -
Ensuite, dans la boîte de dialogue Configurer l’API, sélectionnez l’option d’authentification Authentification de l’utilisateur ou de l’utilisatrice et cliquez sur Suivant.
-
Dans la boîte de dialogue Configurer l’API suivante, sélectionnez l’option d’authentification Application d’une seule page OAuth et cliquez sur Suivant.
-
Dans la boîte de dialogue Configurer l’application d’une seule page OAuth, saisissez les détails suivants, puis cliquez sur Suivant.
- URI de redirection par défaut :
https://localhost:3001/callback
- Modèle d’URI de redirection :
https://localhost:3001/callback
- URI de redirection par défaut :
-
Vérifiez les portées disponibles et cliquez sur Enregistrer l’API configurée.
-
Répétez les étapes ci-dessus pour ajouter l’API de création AEM Assets.
-
Examinez l’API AEM et la configuration de l’authentification.
Configurer l’instance AEM pour activer la communication du projet ADC configure-aem-instance-to-enable-adc-project-communication
Suivez les instructions de l’article Configurer les API AEM basées sur OpenAPI pour configurer l’instance AEM afin d’activer la communication de projet ADC.
Configuration CORS d’AEM aem-cors-configuration
Le partage des ressources entre origines multiples (CORS) d’Adobe Experience Manager as a Cloud Service facilite les propriétés web non-AEM pour effectuer des appels côté client basés sur un navigateur vers les API AEM.
-
Dans le projet AEM, recherchez ou créez le fichier
com.adobe.granite.cors.impl.CORSPolicyImpl~wknd-graphql.cfg.json
à partir du dossier/ui.config/src/main/content/jcr_root/apps/wknd/osgiconfig/config.author/
. -
Ajoutez la configuration suivante au fichier.
code language-json { "alloworigin":[ "" ], "alloworiginregexp":[ "https://localhost:.*", "http://localhost:.*" ], "allowedpaths": [ "/adobe/sites/.*", "/graphql/execute.json.*", "/content/_cq_graphql/wknd-shared/endpoint.json", "/content/experience-fragments/.*" ], "supportedheaders": [ "Origin", "Accept", "X-Requested-With", "Content-Type", "Access-Control-Request-Method", "Access-Control-Request-Headers", "Authorization" ], "supportedmethods":[ "GET", "HEAD", "POST" ], "maxage:Integer": 1800, "supportscredentials": true, "exposedheaders":[ "" ] }
-
Validez les modifications de configuration et envoyez les modifications au référentiel Git distant auquel le pipeline Cloud Manager est connecté.
-
Déployez les modifications ci-dessus à l’aide du pipeline FullStack dans Cloud Manager.
Configurer et exécuter la SPA configure-and-run-the-spa
-
Téléchargez le fichier zip WKND SPA & AEM APIs - Demo App et extrayez-le.
-
Accédez au dossier extrait et copiez le fichier
.env.example
vers.env
. -
Mettez à jour le fichier
.env
avec les paramètres de configuration requis à partir du projet Adobe Developer Console (ADC) et de l’environnement AEM as a Cloud Service. Par exemple :code language-plaintext ######################################################################## # Adobe IMS, Adobe Developer Console (ADC), and AEM as a Cloud Service Information ######################################################################## # Adobe IMS OAuth endpoints REACT_APP_ADOBE_IMS_AUTHORIZATION_ENDPOINT=https://ims-na1.adobelogin.com/ims/authorize/v2 REACT_APP_ADOBE_IMS_TOKEN_ENDPOINT=https://ims-na1.adobelogin.com/ims/token/v3 REACT_APP_ADOBE_IMS_USERINFO_ENDPOINT=https://ims-na1.adobelogin.com/ims/userinfo/v2 # Adobe Developer Console (ADC) Project's OAuth Single-Page App credential REACT_APP_ADC_CLIENT_ID=ddsfs455a4a440c48c7474687c96945d REACT_APP_ADC_SCOPES=AdobeID,openid,aem.folders,aem.assets.author,aem.fragments.management # AEM Assets Information REACT_APP_AEM_ASSET_HOSTNAME=https://author-p69647-e1453424.adobeaemcloud.com/ ################################################ # Single Page Application Information ################################################ # Enable HTTPS for local development HTTPS=true PORT=3001 # SSL Certificate and Key for local development SSL_CRT_FILE=./ssl/server.crt SSL_KEY_FILE=./ssl/server.key # The URL to which the user will be redirected after the OAuth flow is complete REACT_APP_REDIRECT_URI=https://localhost:3000/callback
-
Ouvrez une fenêtre de terminal et accédez au dossier extrait. Installez les dépendances requises et démarrez la SPA WKND à l’aide de la commande suivante.
code language-bash $ npm install $ npm start
Vérifier le flux de bout en bout verify-the-end-to-end-flow
-
Ouvrez un navigateur et accédez à
https://localhost:3001
pour accéder à la SPA WKND. Acceptez l’avertissement de certificat auto-signé. -
Cliquez sur le bouton Connexion Adobe IMS pour lancer le flux d’authentification de l’application d’une seule page OAuth.
-
Authentifiez-vous auprès d’Adobe IMS et autorisez la SPA WKND à accéder aux ressources en votre nom.
-
Une fois l’authentification réussie, on vous redirige vers l’itinéraire
/invoke-aem-apis
de la SPA WKND et le jeton d’accès est stocké dans l’espace de stockage local du navigateur. -
Dans l’itinéraire
https://localhost:3001/invoke-aem-apis
, cliquez sur le bouton Récupérer des modèles de fragment de contenu pour appeler l’API des modèles de fragment de contenu. La SPA affiche la liste des modèles de fragment de contenu. -
De même, dans l’onglet Assets - API de dossiers, vous pouvez répertorier, créer et supprimer des dossiers de gestion des ressources numériques.
-
Dans les outils de développement du navigateur, vous pouvez examiner les requêtes et les réponses du réseau pour comprendre les appels API.
Vérifier le code de la SPA review-the-spa-code
Examinons la structure générale de code et les points d’entrée principaux de la SPA WKND. La SPA est créée à l’aide du framework React et utilise l’API React Context pour l’authentification et la gestion des états.
-
Le fichier
src/App.js
est le point d’entrée principal de la SPA WKND. Le composant Application enveloppe l’ensemble de l’application et initialise le contexteIMSAuthProvider
. -
L’élément
src/context/IMSAuthContext.js
crée l’élément Adobe IMSAuthContext pour fournir l’état d’authentification aux composants enfant. Cela comprend les fonctions de connexion, de déconnexion et handleCallback pour lancer le flux d’authentification de l’application d’une seule page OAuth. -
Le dossier
src/components
contient différents composants pour démontrer les appels API aux API AEM. Le composantInvokeAemApis.js
montre comment utiliser le jeton d’accès pour appeler les API AEM. -
Le fichier
src/config/config.js
charge les variables d’environnement à partir du fichier.env
et les exporte en vue de les utiliser dans l’application. -
Le fichier
src/utils/auth.js
contient des fonctions utilitaires pour générer le code_verifier et le code_challenge pour le flux PKCE OAuth 2.0. -
Le dossier
ssl
contient le certificat autosigné et les fichiers de clé pour exécuter le proxy HTTP SSL local.
Vous pouvez développer ou intégrer la SPA existante aux API Adobe à l’aide des approches illustrées dans ce tutoriel.
Résumé summary
Dans ce tutoriel, vous avez appris à appeler les API AEM basées sur OpenAPI sur AEM as a Cloud Service à l’aide de l’authentification de l’utilisateur ou de l’utilisatrice à partir d’une application d’une seule page (SPA) via le flux PKCE OAuth 2.0.