Aufrufen von OpenAPI-basierten AEM-APIs mithilfe der OAuth-Web-App-Authentifizierung

Erfahren Sie, wie Sie OpenAPI-basierte AEM-APIs in AEM as a Cloud Service mithilfe der benutzerbasierten Authentifizierung über eine benutzerdefinierte Web-App aufrufen, die die OAuth-Web-App verwendet.

Die OAuth-Web-App-Authentifizierung ist ideal für Web-Anwendungen mit Frontend- und Backend-Komponenten, die (eines Benutzers auf AEM-APIs zugreifen). Sie verwendet den Gewährungstyp OAuth 2.0 authorization_code, um ein Zugriffs-Token für den Benutzer abzurufen, der auf die AEM-APIs zugreift. Weitere Informationen finden Sie unter Unterschied zwischen OAuth Server-zu-Server- und OAuth Web App/Single Page App-Anmeldeinformationen.

Lerninhalt what-you-learn

In diesem Tutorial erfahren Sie, wie Sie:

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes überprüft haben:

Beispiel-Web-App: WKND-PIM - Übersicht und funktionaler Ablauf

Im Folgenden werden die Beispiel-Web-App, das WKND-Produktinformations-Management (PIM) und der funktionale Ablauf erläutert.

Die WKND-PIM-App ist eine Beispiel-Web-Anwendung, die zur Verwaltung von Produktattributen und deren in AEM as a Cloud Service gespeicherten Asset-Metadaten entwickelt wurde. Dieses Beispiel zeigt, wie Web-Apps nahtlos in Adobe-APIs integriert werden können, um effiziente, benutzerorientierte Workflows bereitzustellen.

Das Adobe Developer Console-Projekt (ADC) ist so konfiguriert, dass es über die OAuth-Web-App-Authentifizierung auf die Assets-Autoren-API zugreift. Sie stellt der WKND-PIM Web-App die erforderlichen client_id und client_secret bereit, um den authorization_code-Gewährungsfluss zu initiieren.

Die folgende Abbildung zeigt den Funktionsablauf der WKND-PIM-Web-App Abrufen benutzerspezifischer Zugriffstoken für die Interaktion mit der Assets Author-API.

Die WKND-PIM-Web-App wird mit Node.js und Express entwickelt. Express fungiert als Server, der private Geheimnisse und benutzerspezifische Zugriffstoken sicher verwaltet.

Andere Web-Stacks (Java, Python, .NET-basiert usw.) können mithilfe der in diesem Tutorial beschriebenen Ansätze zum Erstellen von Web-Apps verwendet werden, die sich mit den Adobe-APIs integrieren lassen.

Verwendung dieses Tutorials how-to-use-this-tutorial

Sie können entweder den Abschnitt Überprüfen von Code-Snippets für WebApps , um den Authentifizierungsfluss der OAuth-Web-App und die in der WKND-PIM-Web-App verwendeten Code-Snippets für API-Aufrufe zu verstehen. Oder fahren Sie direkt mit dem Abschnitt Einrichten und Ausführen der Web-Anwendung fort, um die Web-Anwendung WKND-PIM auf Ihrem lokalen Computer einzurichten und auszuführen und den OAuth-Authentifizierungsfluss und die API-Aufrufe zu verstehen.

Überprüfen von Web-App-Schlüssel-Code-Snippets review-web-app-key-code-snippets

Sehen wir uns die in der WKND-PIM-Web-App verwendeten Schlüssel-Code-Snippets an, um den Authentifizierungsfluss und die API-Aufrufe der OAuth-Web-App zu verstehen.

Herunterladen des WKND-PIM-Web-App-Codes

IMS-Benutzerauthentifizierung und App-Autorisierung

Überprüfen wir den Code, der die IMS-Benutzerauthentifizierung und die App-Autorisierung initiiert. Um die Asset-Metadaten zu überprüfen oder zu aktualisieren, müssen sich die Benutzenden beim Adobe IMS authentifizieren und die WKND-PIM-Web-App autorisieren, in ihrem Namen auf die Assets Author-API zuzugreifen.

Beim ersten Anmeldeversuch muss der Benutzer seine Zustimmung geben, damit die WKND-PIM-Web-App in seinem Namen auf die Assets Author-API zugreifen kann.

Wenn die Benutzerin bzw. der Benutzer nicht über Adobe IMS authentifiziert wird, wird die Adobe ID-Anmeldeseite angezeigt, auf der die Benutzerin bzw. der Benutzer zur Authentifizierung aufgefordert wird.

Wenn der Benutzer bereits authentifiziert ist, wird er mit einem authorization_code zurück zum angegebenen redirect_uri der WKND-PIM-Web-App umgeleitet.

Abrufen von Zugriffstoken

Die WKND-PIM-Web-App tauscht den authorization_code sicher mit dem Adobe IMS gegen ein benutzerspezifisches Zugriffstoken aus, indem sie die client_id und client_secret der OAuth-Web-App-Anmeldeinformationen des ADC-Projekts verwendet.

In der routes/adobe-ims-auth.js-Datei tauscht die /callback Route den authorization_code mit dem Adobe IMS gegen ein benutzerspezifisches Zugriffstoken aus.

...
// 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");
  }
});

Das Zugriffstoken wird in der Express-Sitzung für nachfolgende Anfragen an die Assets-Autoren-API gespeichert.

Zugriff auf OpenAPI-basierte AEM-APIs mithilfe des Zugriffstokens

Die WKND-PIM-Web-App verwendet auf sichere Weise das benutzerspezifische Zugriffstoken, um mit der Assets-Autoren-API zu interagieren, sodass Benutzende Produkt-Asset-Metadaten abrufen oder aktualisieren können.

In der routes/invoke-aem-apis.js-Datei rufen die /api/getAEMAssetMetadata- und /api/updateAEMAssetMetadata-Routen die Assets Author-APIs mithilfe des Zugriffstokens auf.

...
// 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],
  }));
}

Die OpenAPI-basierten AEM-API-Aufrufe erfolgen Server-seitig (Express-Middleware) und nicht direkt Client-seitig (Browser), um sicherzustellen, dass das Zugriffstoken sicher verwaltet wird und nicht Client-seitig verfügbar gemacht wird.

Aktualisieren des Zugriffstokens

Um das Zugriffstoken vor Ablauf zu aktualisieren, können Sie den Aktualisierungstokenfluss implementieren. Um das Tutorial jedoch einfach zu halten, implementiert die WKND-PIM-Web-App den Aktualisierungstoken-Fluss nicht.

Einrichten und Ausführen der Web-Anwendung

Konfigurieren wir die WKND-PIM-Web-App auf Ihrem lokalen Computer und führen sie aus, um den Authentifizierungsfluss und die API-Aufrufe der OAuth-Web-App zu verstehen.

Voraussetzungen

Zum Durchführen dieses Tutorials benötigen Sie Folgendes:

Entwicklungsschritte

Die allgemeinen Entwicklungsschritte lauten:

ADC-Projekt konfigurieren

Der Schritt zum Konfigurieren des ADC Projekts wird der OpenAPI-basierten AEM-APIs wiederholt. Wiederholt wird, um die Assets Author-API hinzuzufügen und ihre Authentifizierungsmethode als OAuth Web App zu konfigurieren.

Konfigurieren der AEM-Instanz zur Aktivierung der ADC-Projektkommunikation

Befolgen Sie die Anweisungen im Artikel Einrichten von OpenAPI-basierten AEMAPIs , um die AEM-Instanz so zu konfigurieren, dass die ADC-Projektkommunikation aktiviert wird.

Erstellen und Anwenden eines Asset-Metadatenschemas

Standardmäßig verfügt das WKND Sites-Projekt nicht über das erforderliche Asset-Metadatenschema zum Anzeigen der Produktattribute. Erstellen wir nun das Asset-Metadatenschema und wenden es auf einen Asset-Ordner in der AEM-Instanz an.

Als Nächstes erstellen wir das PIM-Attribut-spezifische Metadatenschema und wenden es auf den Ordner PIM an.

Mit den oben genannten Schritten können die Assets aus dem PIM-Ordner die Metadaten der Produktattribute speichern.

Konfigurieren und Ausführen der WKND-PIM-Web-App

Überprüfen des End-to-End-Flusses

Überprüfen des Anwendungs-Codes

Sehen wir uns die allgemeine Code-Struktur und die wichtigsten Einstiegspunkte der WKND-PIM-Web-App an. Die Anwendung wird mit Node.js + Express entwickelt.

Sie können die vorhandene Web-App mit den Adobe-APIs entwickeln oder integrieren, indem Sie andere Server-seitige Technologien wie Java, Python oder .NET verwenden.

Zusammenfassung

In diesem Tutorial haben Sie erfahren, wie Sie OpenAPI-basierte AEM-APIs für AEM as a Cloud Service über eine benutzerdefinierte Web-App mithilfe der OAuth-Web-App-Authentifizierung aufrufen. Sie haben die in der WKND-PIM-Web-App verwendeten Schlüssel-Code-Snippets gelesen, um den Authentifizierungsfluss der OAuth-Web-App zu verstehen.

Sie können das Tutorial als Referenz verwenden, um die OpenAPI-basierten AEM-APIs in Ihre benutzerdefinierten Web-Anwendungen zu integrieren und so effiziente, benutzerorientierte Workflows bereitzustellen.

Zusätzliche Ressourcen