Anropa OpenAPI-baserade AEM API:er med OAuth Web App-autentisering

Lär dig hur du anropar OpenAPI-baserade AEM API:er på AEM as a Cloud Service med användarbaserad autentisering från en anpassad webbapp som använder OAuth Web App.

OAuth Web App-autentiseringen är idealisk för webbprogram med klientkomponenter och backend -komponenter som behöver komma åt AEM API:er för en användares räkning. Den använder OAuth 2.0-anslagstypen permission_code för att få en åtkomsttoken åt användaren för att få åtkomst till AEM API:er. Mer information finns i Skillnad mellan autentiseringsuppgifter för OAuth Server-to-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:

Innan du börjar bör du kontrollera följande:

Exempel på webbprogram: WKND-PIM - översikt och funktionsflöde

Låt oss förstå exempelwebbprogrammet, WKND Product Information Management (PIM) och dess funktionella flöde.

WKND PIM-appen är ett exempelwebbprogram som är utformat för att hantera produktattribut och metadata för resurser som lagras i AEM as a Cloud Service. I det här exemplet visas hur webbprogram kan integreras smidigt med Adobe API:er för att leverera effektiva, användarcentrerade arbetsflöden.

Adobe Developer Console-projektet (ADC) har konfigurerats för åtkomst till Assets Author API med hjälp av OAuth Web App-autentisering. Den tillhandahåller nödvändiga client_id och client_secrets till WKND-PIM-webbprogrammet för att initiera permission_code-anslagsflödet.

Följande diagram visar det funktionella flödet för WKND-PIM-webbprogrammet som hämtar användarspecifika åtkomsttoken för interaktion med Assets Author API.

WKND-PIM-webbappen har utvecklats med Node.js och Express. Express fungerar som den server som på ett säkert sätt hanterar privata hemligheter och användarspecifika åtkomsttoken.

Andra webbstackar (Java, Python, .NET-baserade osv.) kan användas för att skapa webbappar som 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 antingen Granska kodfragment för webbprogram för att förstå autentiseringsflödet för OAuth-webbprogram och API-anropa kodfragment som används i WKND-PIM-webbprogrammet. Eller gå direkt till avsnittet Konfigurera och kör webbprogrammet för att konfigurera och köra webbappen WKND-PIM på den lokala datorn för att förstå autentiseringsflödet för OAuth-webbappen och API-anropen.

Granska kodfragment för webbprogramnycklar review-web-app-key-code-snippets

Låt oss granska de kodfragment som används i WKND-PIM-webbappen för att förstå autentiseringsflödet i OAuth Web App och API-anrop.

Hämta WKND-PIM-webbprogramkoden

IMS-användarautentisering och appauktorisering

Låt oss granska koden som initierar IMS-användarautentisering och appauktorisering. Om du vill granska eller uppdatera metadata för resursen måste användaren autentisera mot Adobe IMS och godkänna WKND-PIM-webbappen så att den får åtkomst till API:t för Assets Author för sina räkning.

Vid det allra första inloggningsförsöket måste användaren ge sitt medgivande för att tillåta att WKND-PIM-webbprogrammet får åtkomst till Assets Author API åt dem.

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 angivet redirect_uri för WKND-PIM-webbprogrammet med en permission_code.

Hämtning av åtkomsttoken

WKND-PIM-webbprogrammet utbyter permission_code med Adobe IMS på ett säkert sätt mot en användarspecifik åtkomsttoken med hjälp av client_id och client_secrets i ADC-projektets OAuth Web App-autentiseringsuppgifter.

I filen routes/adobe-ims-auth.js byter /callback-vägen permission_code med Adobe IMS för en användarspecifik åtkomsttoken.

...
// Callback route to exchange authorization code for access token
router.get("/callback", async (req, res) => {
  // Extracting authorization code from the query parameters
  const authorizationCode = req.query.code;

  if (!authorizationCode) {
    return res.status(400).send("Missing authorization code");
  }

  // Exchange authorization code for access token
  try {
    // Fetch access token from Adobe IMS token endpoint
    const response = await fetch(adobeIMSConfig.tokenEndpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        Authorization: `Basic ${Buffer.from(
          `${adobeADCConfig.clientId}:${adobeADCConfig.clientSecret}`
        ).toString("base64")}`,
      },
      body: new URLSearchParams({
        code: authorizationCode,
        grant_type: "authorization_code",
      }),
    });

    if (!response.ok) {
      console.error("Failed to fetch access token:", response.statusText);
      return res.status(500).send("Failed to fetch access token");
    }

    const data = await response.json();

    if (!data.access_token) {
      console.error("Access token missing in the response:", data);
      return res.status(500).send("Invalid response from token endpoint");
    }

    // For debugging purposes
    console.log("Access token:", data.access_token);

    // Store the access token in the session
    req.session.accessToken = data.access_token;

    // Redirect user to update product attributes
    res.redirect("/update-product-attributes");
  } catch (error) {
    console.error("Error exchanging authorization code:", error);
    res.status(500).send("Error during token exchange");
  }
});

Åtkomsttoken lagras i Express-sessionen för efterföljande begäranden till Assets Author API.

Åtkomst till OpenAPI-baserade AEM API:er med åtkomsttoken

Webbprogrammet WKND-PIM använder på ett säkert sätt den användarspecifika åtkomsttoken för att interagera med API:t för Assets Author, vilket gör att användaren kan hämta eller uppdatera metadata för produktresurser.

I filen routes/invoke-aem-apis.js anropar vägarna /api/getAEMAssetMetadata och /api/updateAEMAssetMetadata API:erna för Assets Author med hjälp av åtkomsttoken.

...
// API Route: Get AEM Asset Metadata
router.get("/api/getAEMAssetMetadata", async (req, res) => {
  const assetId = req.query.assetId;
  const bucketName = getBucketName(aemAssetsConfig.hostname);

  if (!assetId || !bucketName) {
    return res.status(400).json({ error: "Missing AEM Information" });
  }

  // Get the access token from the session
  const accessToken = req.session.accessToken;

  if (!accessToken) {
    return res.status(401).json({ error: "Not Authenticated with Adobe IMS" });
  }

  try {
    const assetMetadata = await invokeGetAssetMetadataAPI(
      bucketName,
      assetId,
      accessToken
    );

    const filteredMetadata = getFilteredMetadata(JSON.parse(assetMetadata));
    res.status(200).json(filteredMetadata);
  } catch (error) {
    console.error("Error getting asset metadata:", error.message);
    res.status(500).json({ error: `Internal Server Error: ${error.message}` });
  }
});

// Helper function to invoke the AEM API to get asset metadata
async function invokeGetAssetMetadataAPI(bucketName, assetId, accessToken) {
  const apiUrl = `https://${bucketName}.adobeaemcloud.com/adobe/assets/${assetId}/metadata`;


  // For debugging purposes
  console.log("API URL:", apiUrl);
  console.log("Access Token:", accessToken);
  console.log("API Key:", adobeADCConfig.clientId);

  try {
    const response = await fetch(apiUrl, {
      method: "GET",
      headers: {
        "If-None-Match": "string",
        "X-Adobe-Accept-Experimental": "1",
        Authorization: `Bearer ${accessToken}`,
        "X-Api-Key": adobeADCConfig.clientId,
      },
    });

    console.log("Response Status:", response.status);

    if (!response.ok) {
      throw new Error(`AEM API Error: ${response.statusText}`);
    }

    return await response.text();
  } catch (error) {
    throw new Error(`Failed to fetch asset metadata: ${error.message}`);
  }
}

// Helper function to filter the metadata properties like pim: and dc:
function getFilteredMetadata(data) {
  if (!data || !data.assetMetadata) {
    throw new Error("Invalid metadata structure received from API");
  }

  const properties = data.assetMetadata;
  return Object.keys(properties).reduce((filtered, key) => {
    if (
      key.startsWith("pim:") ||
      key === "dc:title" ||
      key === "dc:description"
    ) {
      filtered[key] = properties[key];
    }
    return filtered;
  }, {});
}

// API Route: Update AEM Asset Metadata
router.post("/api/updateAEMAssetMetadata", async (req, res) => {
  const { assetId, metadata } = req.body;

  if (!assetId || !metadata || typeof metadata !== "object") {
    return res.status(400).json({ error: "Invalid or Missing Metadata" });
  }

  const bucketName = getBucketName(aemAssetsConfig.hostname);
  if (!bucketName) {
    return res.status(400).json({ error: "Missing AEM Information" });
  }

  const accessToken = req.session.accessToken;
  if (!accessToken) {
    return res.status(401).json({ error: "Not Authenticated with Adobe IMS" });
  }

  try {
    const updatedMetadata = await invokePatchAssetMetadataAPI(
      bucketName,
      assetId,
      metadata,
      accessToken
    );
    res.status(200).json(updatedMetadata);
  } catch (error) {
    console.error("Error updating asset metadata:", error.message);
    res.status(500).json({ error: `Internal Server Error: ${error.message}` });
  }
});

// Helper function to invoke the AEM API to update asset metadata
async function invokePatchAssetMetadataAPI(
  bucketName,
  assetId,
  metadata,
  accessToken
) {
  const apiUrl = `https://${bucketName}.adobeaemcloud.com/adobe/assets/${assetId}/metadata`;
  const headers = {
    "Content-Type": "application/json-patch+json",
    "If-Match": "*",
    "X-Adobe-Accept-Experimental": "1",
    Authorization: `Bearer ${accessToken}`,
    "X-Api-Key": adobeADCConfig.clientId,
  };

  try {
    const response = await fetch(apiUrl, {
      method: "PATCH",
      headers,
      body: JSON.stringify(getTransformedMetadata(metadata)),
    });

    if (!response.ok) {
      throw new Error(`AEM API Error: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    throw new Error(`Failed to update asset metadata: ${error.message}`);
  }
}

// Helper function to transform metadata into JSON Patch format, e.g. [{ op: "add", path: "dc:title", value: "New Title" }]
function getTransformedMetadata(metadata) {
  return Object.keys(metadata).map((key) => ({
    op: "add",
    path: `/${key}`,
    value: metadata[key],
  }));
}

De OpenAPI-baserade AEM API-anropen görs från serversidan (Express-mellanvara) och inte direkt från klientsidan (webbläsare) för att säkerställa att åtkomsttoken hanteras på ett säkert sätt och inte exponeras för klientsidan.

Uppdaterar åtkomsttoken

Om du vill uppdatera åtkomsttoken innan den upphör att gälla kan du implementera uppdateringstokenflödet. För att göra självstudiekursen enkel implementerar inte webbprogrammet WKND-PIM uppdateringstokenflödet.

Konfigurera och köra webbprogram

Låt oss konfigurera och köra WKND-PIM-webbprogrammet på din lokala dator för att förstå autentiseringsflödet för OAuth-webbappen och API-anrop.

Förutsättningar

För att kunna genomföra den här självstudiekursen behöver du:

Utvecklingssteg

Utvecklingsstegen på hög nivå är följande:

Konfigurera ADC-projekt

Konfigurationssteget för ADC-projekt är upprepat från Konfigurera OpenAPI-baserade AEM-API:er. Det upprepas att lägga till Assets Author API och konfigurera autentiseringsmetoden som OAuth Web App.

Konfigurera AEM-instans för att aktivera ADC-projektkommunikation

Följ instruktionerna i artikeln Konfigurera OpenAPI-baserade AEM API:er för att konfigurera AEM-instansen så att ADC-projektkommunikation aktiveras.

Skapa och tillämpa metadatamatchemat för resurser

Som standard har WKND Sites-projektet inte det nödvändiga metadata-schemat för resurser för att visa produktattributen. Låt oss skapa och använda metadatamatchemat för resurser i AEM-instansen.

Låt oss sedan skapa det PIM-attributspecifika metadataschemat och använda det i mappen PIM.

Med ovanstående steg kan resurserna i mappen PIM lagra metadata för produktattribut.

Konfigurera och kör webbprogrammet WKND-PIM

Verifiera flödet från början till slut

Granska programkoden

Låt oss granska den övergripande kodstrukturen och de viktigaste startpunkterna i WKND-PIM-webbprogrammet. Programmet utvecklas med Node.js + Express.

Du kan utveckla eller integrera det befintliga webbprogrammet med Adobe API:er med andra servertekniker som Java, Python eller .NET.

Sammanfattning

I den här självstudiekursen lärde du dig att anropa OpenAPI-baserade AEM API:er på AEM as a Cloud Service från en anpassad webbapp med hjälp av OAuth Web App-autentisering. Du har granskat de kodfragment som används i WKND-PIM-webbappen för att förstå autentiseringsflödet för OAuth-webbappen.

Du kan använda självstudiekursen som referens för att integrera de OpenAPI-baserade AEM-API:erna med dina anpassade webbprogram för att leverera effektiva, användarcentrerade arbetsflöden.

Ytterligare resurser