Anropa OpenAPI-baserade AEM-API:er med OAuth Single Page App
Lär dig hur du anropar OpenAPI-baserade AEM-API:er på AEM as a Cloud Service med OAuth Single Page App-autentisering. Det följer OAuth 2.0 PKCE-flödet (Proof Key for Code Exchange) för användarbaserad autentisering i ett Single Page-program (SPA).
OAuth Single Page App-autentisering är idealisk för JavaScript-baserade program som körs i webbläsaren. Oavsett om de saknar en serverdelsserver eller behöver hämta åtkomsttoken för att kunna interagera med AEM API:er för en användares räkning.
PKCE-flödet utökar anslagstypen OAuth 2.0 permission_code och förbättrar säkerheten genom att förhindra avlyssning av auktoriseringskoden. Mer information finns i avsnittet Skillnad mellan autentiseringsuppgifter för OAuth Server-till-Server och Web App respektive Single Page App.
Vad du lär dig what-you-learn
I den här självstudiekursen får du lära dig att:
-
Konfigurera ett Adobe Developer Console-projekt (ADC) så att du får tillgång till OpenAPI-baserade AEM-API:er med OAuth Single Page App -autentisering eller så kallas OAuth 2.0 PKCE-flöde .
-
Implementera autentiseringsflödet för OAuth Single Page App i en anpassad SPA.
- IMS-användarautentisering och appauktorisering.
- Få åtkomst till tokenhämtning med OAuth 2.0 PKCE-flöde.
- Använd åtkomsttoken för att anropa OpenAPI-baserade AEM API:er.
Innan du börjar bör du kontrollera följande:
Översikt över WKND SPA och funktionella flöden wknd-spa-overview-and-functional-flow
Låt oss utforska vad WKND SPA är, hur det har byggts och hur det fungerar.
WKND SPA är ett React-baserat Single Page-program som demonstrerar hur du på ett säkert sätt får en användarspecifik åtkomsttoken och interagerar med AEM API:er direkt från klientsidan. Det implementerar autentiseringsflödet OAuth 2.0 PKCE via Adobe IMS och integreras med två viktiga AEM API
- Webbplats-API: För åtkomst till modeller för innehållsfragment
- Assets API: För hantering av DAM-mappar
Adobe Developer Console-projektet (ADC) är konfigurerat för att aktivera autentisering med OAuth Single Page App, vilket ger det client_id som krävs för att initiera OAuth 2.0 PKCE-flödet.
I följande diagram visas det funktionella flödet för WKND SPA med användarspecifik åtkomsttoken för att anropa OpenAPI-baserade AEM API:er:
- SPA initierar autentiseringsflödet genom att dirigera användaren till Adobe Identity Management System (IMS) via en auktoriseringsbegäran.
- Som en del av auktoriseringsbegäran skickar SPA client_id, redirect_uri och code_enge till IMS efter OAuth 2.0 PKCE-flödet. SPA genererar ett slumpmässigt code_verifier, hashas det med SHA-256 och Base64 kodar resultatet för att skapa code_enge.
- IMS-programmet autentiserar användaren och utfärdar, vid lyckad autentisering, permission_code som skickas tillbaka till SPA via redirect_uri.
- SPA utbyter permission_code för en åtkomsttoken genom att skicka en POST-begäran till IMS-tokenslutpunkten. Den innehåller code_verifier i begäran om validering av den code_enge som skickades tidigare. Detta säkerställer att auktoriseringsbegäran (steg 2) och tokenbegäran (steg 4) länkas till samma autentiseringsflöde, vilket förhindrar avlyssningsattacker.
- IMS-programmet validerar code_verifier och returnerar den användarspecifika åtkomsttoken.
- SPA innehåller åtkomsttoken i API-begäranden till AEM för att autentisera och hämta användarspecifikt innehåll.
WKND SPA är ett React-baserat program och använder React Context för hantering av autentiseringstillstånd, React Router för navigering.
Andra SPA-ramverk som Angular, Vue och vanilla JavaScript kan användas för att skapa SPA som kan integreras med Adobe API:er med de metoder som illustreras i den här självstudiekursen.
Så här använder du den här självstudien how-to-use-this-tutorial
Du kan använda den här självstudiekursen på två sätt:
- Granska SPA-nyckelkodfragment: Förstå autentiseringsflödet för OAuth Single Page App och utforska nyckelimplementeringarna för API-anrop i WKND SPA.
- Konfigurera och kör SPA: Följ stegvisa instruktioner för att konfigurera och köra WKND SPA på den lokala datorn.
Välj den väg som passar dina behov bäst!
Granska SPA-kodfragment review-spa-key-code-snippets
Låt oss dyka upp i de nyckelkodfragment från WKND SPA som visar hur man:
-
Hämta en användarspecifik åtkomsttoken med autentiseringsflödet OAuth Single Page App.
-
Anropa OpenAPI-baserade AEM-API:er direkt från klientsidan.
Dessa fragment hjälper dig att förstå autentiseringsprocessen och API-interaktioner i SPA.
Hämta SPA-koden download-the-spa-code
-
Hämta zip-filen WKND SPA & AEM APIs - Demo App och extrahera den.
-
Navigera till den extraherade mappen och öppna filen
.env.example
i din favoritkodredigerare. Granska de konfigurationsparametrar som krävs.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
Du måste ersätta platshållarna med de faktiska värdena från Adobe Developer Console (ADC) Project och AEM as a Cloud Service Assets.
IMS-användarautentisering och SPA-auktorisering ims-user-authentication-and-spa-authorization
Låt oss utforska koden som hanterar IMS-användarautentisering och SPA-auktorisering. För att kunna hämta innehållsfragmentmodeller och DAM-mappar måste användaren autentisera med Adobe IMS och ge WKND SPA behörighet att komma åt AEM API:er för deras räkning.
Under den första inloggningen uppmanas användaren att ge sitt medgivande så att WKND SPA kan komma åt de nödvändiga resurserna på ett säkert sätt.
-
I filen
src/context/IMSAuthContext.js
initierar funktionenlogin
IMS-användarautentisering och appauktoriseringsflöde. Det genererar ett slumpmässigtcode_verifier
ochcode_challenge
för att på ett säkert sätt utbytacode
för en åtkomsttoken.code_verifier
lagras i den lokala lagringsplatsen för senare bruk. Som vi nämnt tidigare lagras eller används inteclient_secret
i SPA, utan det genereras en direkt och används i två steg:authorize
- ochtoken
-begäranden.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, }; }, []); ...
Om användaren inte är autentiserad mot Adobe IMS visas inloggningssidan för Adobe ID där användaren uppmanas att autentisera.
Om den redan är autentiserad omdirigeras användaren tillbaka till angiven redirect_uri i WKND SPA med en permission_code.
Få åtkomst till tokenhämtning med OAuth 2.0 PKCE-flöde access-token-retrieval-using-oauth-20-pkce-flow
WKND SPA utbyter på ett säkert sätt permission_code med Adobe IMS för en användarspecifik åtkomsttoken med client_id och code_verifier.
-
I filen
src/context/IMSAuthContext.js
byter funktionenexchangeCodeForToken
ut permission_code mot en användarspecifik åtkomsttoken.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] ); ...
Åtkomsttoken lagras i webbläsarens lokala lager och används i efterföljande API-anrop till AEM API:er.
Åtkomst till OpenAPI-baserade AEM API:er med åtkomsttoken accessing-openapi-based-aem-apis-using-the-access-token
WKND SPA använder den användarspecifika åtkomsttoken för att anropa innehållsfragmentmodellerna och API-slutpunkterna för DAM-mappar.
I filen src/components/InvokeAemApis.js
visar funktionen fetchContentFragmentModels
hur du använder åtkomsttoken för att anropa OpenAPI-baserade AEM-API:er från klientsidan.
...
// 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();
},
[]
);
...
Konfigurera och kör SPA setup-and-run-the-spa
Låt oss konfigurera och köra WKND SPA på din lokala dator för att förstå autentiseringsflödet för OAuth Single Page App och API-anrop.
Förutsättningar prerequisites
För att kunna genomföra den här självstudiekursen behöver du:
-
Moderniserad AEM as a Cloud Service-miljö med följande:
- AEM version
2024.10.18459.20241031T210302Z
eller senare. - Nya produktprofiler (om miljön skapades före november 2024)
Mer information finns i artikeln Konfigurera OpenAPI-baserade AEM API:er .
- AEM version
-
Exempelprojektet WKND Sites måste distribueras till det.
-
Åtkomst till Adobe Developer Console.
-
Installera Node.js på den lokala datorn för att köra exempelprogrammet NodeJS.
Utvecklingssteg development-steps
Utvecklingsstegen på hög nivå är följande:
-
Konfigurera ADC-projekt
- Lägg till API:er för Assets och Sites.
- Konfigurera autentiseringsuppgifter för OAuth Single Page App.
-
Konfigurera AEM-instansen
- Aktivera ADC-projektkommunikation
- Om du vill att SPA ska få åtkomst till AEM API:er genom att konfigurera CORS-inställningarna.
-
Konfigurera och kör WKND SPA på den lokala datorn
-
Verifiera flödet från början till slut
Konfigurera ADC-projekt configure-adc-project
Konfigurationssteget för ADC-projekt är upprepat från Konfigurera OpenAPI-baserade AEM-API:er. Den upprepas för att lägga till Assets, Sites API och konfigurera autentiseringsmetoden som OAuth Single Page App.
-
Öppna önskat projekt från Adobe Developer Console.
-
Om du vill lägga till AEM API:er klickar du på knappen Lägg till API .
-
I dialogrutan Lägg till API kan du filtrera efter Experience Cloud, markera AEM CS Sites Content Management-kortet och klicka på Nästa.
note tip TIP Om AEM API-kortet är inaktiverat och Varför är det inaktiverat? information visar meddelandet Licens krävs. En av orsakerna kan vara att du INTE har moderniserat din AEM as a Cloud Service-miljö. Mer information finns i Modernisering av AEM as a Cloud Service-miljön. -
I dialogrutan Konfigurera API väljer du autentiseringsalternativet Användarautentisering och klickar på Nästa.
-
I nästa dialogruta Konfigurera API väljer du autentiseringsalternativet OAuth Single-Page App och klickar på Next.
-
Ange följande information i dialogrutan Konfigurera OAuth-enkelsidig app och klicka på Nästa.
- Standardomdirigerings-URI:
https://localhost:3001/callback
- Omdirigerings-URI-mönster:
https://localhost:3001/callback
- Standardomdirigerings-URI:
-
Granska de tillgängliga scopen och klicka på Spara konfigurerad API.
-
Upprepa stegen ovan om du vill lägga till AEM Assets Author API.
-
Granska AEM API och autentiseringskonfigurationen.
Konfigurera AEM-instans för att aktivera ADC-projektkommunikation configure-aem-instance-to-enable-adc-project-communication
Följ instruktionerna i artikeln Konfigurera OpenAPI-baserade AEM API:er för att konfigurera AEM-instansen så att ADC-projektkommunikation aktiveras.
AEM CORS-konfiguration aem-cors-configuration
AEM as a Cloud Service Cross-Origin Resource Sharing (CORS) underlättar för andra webbegenskaper än AEM att göra webbläsarbaserade klientanrop till AEM API:er.
-
Leta reda på eller skapa filen
com.adobe.granite.cors.impl.CORSPolicyImpl~wknd-graphql.cfg.json
från mappen/ui.config/src/main/content/jcr_root/apps/wknd/osgiconfig/config.author/
i AEM Project. -
Lägg till följande konfiguration i filen.
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":[ "" ] }
-
Bekräfta konfigurationsändringarna och skicka ändringarna till Git-fjärrdatabasen som Cloud Manager pipeline är ansluten till.
-
Distribuera ovanstående ändringar med FullStack Pipeline i Cloud Manager.
Konfigurera och kör SPA configure-and-run-the-spa
-
Hämta zip-filen WKND SPA & AEM APIs - Demo App och extrahera den.
-
Navigera till den extraherade mappen och kopiera filen
.env.example
till.env
. -
Uppdatera filen
.env
med de konfigurationsparametrar som krävs från Adobe Developer Console (ADC) Project- och AEM as a Cloud Service-miljön. Till exempel: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
-
Öppna en terminal och navigera till den extraherade mappen. Installera nödvändiga beroenden och starta WKND SPA med följande kommando.
code language-bash $ npm install $ npm start
Verifiera flödet från början till slut verify-the-end-to-end-flow
-
Öppna en webbläsare och gå till
https://localhost:3001
för att komma åt WKND SPA. Acceptera den självsignerade certifikatvarningen. -
Klicka på knappen Adobe IMS-inloggning för att initiera autentiseringsflödet för OAuth Single Page App.
-
Autentisera mot Adobe IMS och ge ditt medgivande till att WKND SPA får åtkomst till resurserna åt dig.
-
När autentiseringen lyckades omdirigeras du tillbaka till WKND SPA:s
/invoke-aem-apis
-väg och åtkomsttoken lagras i webbläsarens lokala lagring. -
Klicka på knappen
https://localhost:3001/invoke-aem-apis
Hämta innehållsfragmentmodeller i-vägen för att anropa API:t för innehållsfragmentmodeller. I SPA visas en lista med innehållsfragmentmodeller. -
På samma sätt kan du visa, skapa och ta bort DAM-mappar på fliken Assets - Mappar API .
-
I webbläsarens utvecklingsverktyg kan du inspektera nätverksförfrågningar och svar för att förstå API-anropen.
Granska SPA-koden review-the-spa-code
Låt oss granska den övergripande kodstrukturen och de viktigaste startpunkterna i WKND SPA. SPA byggs med React Framework och använder React Context API för autentisering och statushantering.
-
Filen
src/App.js
är huvudstartpunkten i WKND SPA. Programkomponenten kapslar in hela programmet och initierarIMSAuthProvider
-kontexten. -
src/context/IMSAuthContext.js
skapar Adobe IMSAuthContext för att ge de underordnade komponenterna autentiseringstillstånd. Den innehåller inloggnings-, utloggnings- och handleCallback-funktioner som initierar autentiseringsflödet för OAuth Single Page App. -
Mappen
src/components
innehåller olika komponenter som demonstrerar API-anropen till AEM API:er. KomponentenInvokeAemApis.js
visar hur du använder åtkomsttoken för att anropa AEM API:er. -
Filen
src/config/config.js
läser in miljövariablerna från filen.env
och exporterar dem för användning i programmet. -
Filen
src/utils/auth.js
innehåller verktygsfunktioner som genererar kodverifieraren och kodutmaningen för OAuth 2.0 PKCE-flödet. -
Mappen
ssl
innehåller det självsignerade certifikatet och nyckelfilerna som ska köra den lokala SSL HTTP-proxyn.
Du kan utveckla eller integrera befintliga SPA med Adobe API:er med hjälp av de metoder som illustreras i den här självstudiekursen.
Sammanfattning summary
I den här självstudiekursen lärde du dig att anropa OpenAPI-baserade AEM-API:er på AEM as a Cloud Service med användarbaserad autentisering från en Single Page App (SPA) via OAuth 2.0 PKCE-flödet.