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

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

Die OAuth-Web-Anwendungs-Authentifizierung eignet sich ideal für Web-Anwendungen mit Frontend- und Backend-Komponenten, die im Namen einer Benutzerin bzw. eines Benutzers auf AEM-APIs zugreifen müssen. Verwendet wird der OAuth 2.0-Grant-Typ authorization_code, um ein Zugriffs-Token im Namen der Benutzerin bzw. des Benutzers abzurufen, die bzw. der auf die AEM-APIs zugreift. Weitere Informationen finden Sie unter Unterschied zwischen OAuth-Server-zu-Server-, Web-Anwendungs- und Single-Page-Application-Anmeldedaten.

Lerninhalt what-you-learn

In diesem Tutorial lernen Sie Folgendes:

Bevor Sie beginnen, stellen Sie sicher, dass Sie sich Folgendes angesehen haben:

Beispiel-Web-Anwendung: WKND-PIM – Überblick und Funktionsfluss

Erfahren Sie mehr über die Beispiel-Web-Anwendung, das WKND-Produktinformations-Management (PIM) und den Funktionsfluss.

Die WKND-PIM-Anwendung 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-Anwendungen nahtlos in Adobe-APIs integriert werden können, um effiziente, benutzerorientierte Workflows bereitzustellen.

Das Adobe Developer Console(ADC)-Projekt ist so konfiguriert, dass es über die OAuth-Web-Anwendungs-Authentifizierung auf die Assets Author-API zugreift. Es stellt der Web-Anwendung WKND-PIM die erforderliche client_id und das erforderliche client_secret bereit, um den authorization_code-Grant-Fluss zu initiieren.

Die folgende Abbildung zeigt den Funktionsfluss der Web-Anwendung WKND-PIM zum Abrufen benutzerspezifischer Zugriffs-Token für die Interaktion mit dem Assets Author-API.

Die Web-Anwendung WKND-PIM wird mit Node.js und Express entwickelt. Express dient als Server, der private Geheimnisse und benutzerspezifische Zugriffs-Token sicher verwaltet.

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

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

Im Abschnitt Überprüfen der wichtigsten Code-Snippets der Web-Anwendung finden Sie weitere Informationen zum Authentifizierungsfluss der OAuth-Web-Anwendung und den in der Web-Anwendung WKND-PIM verwendeten Code-Snippets für API-Aufrufe. Sie können auch direkt mit dem Abschnitt Einrichten und Ausführen der Web-Anwendung fortfahren, um die Web-Anwendung WKND-PIM auf Ihrem lokalen Computer einzurichten und auszuführen und den OAuth-Web-Anwendungs-Authentifizierungsfluss sowie die API-Aufrufe zu verstehen.

Überprüfen der wichtigsten Code-Snippets der Web-Anwendung review-web-app-key-code-snippets

Sehen wir uns nun die wichtigsten Code-Snippets in der Web-Anwendung WKND-PIM an, um den OAuth-Web-Anwendungs-Authentifizierungsfluss und die API-Aufrufe zu verstehen.

Herunterladen des Codes der Web-Anwendung WKND-PIM

IMS-Benutzerauthentifizierung und Anwendungsautorisierung

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

Beim ersten Anmeldeversuch müssen Benutzende ihr Einverständnis geben, damit die Web-Anwendung WKND-PIM in ihrem Namen auf das Assets Author-API zugreifen darf.

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.

Bei bereits erfolgter Authentifizierung wird die Person mit einem authorization_code wieder an den angegebenen redirect_uri der Web-Anwendung WKND-PIM umgeleitet.

Abrufen des Zugriffs-Token

Die Web-Anwendung WKND-PIM tauscht den authorization_code auf sichere Weise mit dem IMS von Adobe gegen ein benutzerspezifisches Zugriffs-Token aus. Hierzu verwendet sie die client_id und das client_secret der OAuth-Web-Anwendungs-Anmeldedaten des ADC-Projekts.

In der Datei routes/adobe-ims-auth.js tauscht die /callback-Route den authorization_code mit dem IMS von Adobe gegen ein benutzerspezifisches Zugriffs-Token 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 Zugriffs-Token wird für nachfolgende Anfragen an das Assets Author-API in der Express-Sitzung gespeichert.

Zugreifen auf OpenAPI-basierte AEM-APIs mithilfe des Zugriffs-Token

Die Web-Anwendung WKND-PIM verwendet auf sichere Weise das benutzerspezifische Zugriffs-Token, um mit dem Assets Author-API zu interagieren, sodass Benutzende Produkt-Asset-Metadaten abrufen oder aktualisieren können.

In der Datei routes/invoke-aem-apis.js rufen die /api/getAEMAssetMetadata- und /api/updateAEMAssetMetadata-Routen die Assets Author-APIs über das Zugriffs-Token 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 Zugriffs-Token sicher verwaltet und nicht Client-seitig verfügbar gemacht wird.

Aktualisieren des Zugriffs-Token

Um das Zugriffs-Token vor Ablauf zu aktualisieren, können Sie den Token-Aktualisierungsfluss implementieren. Um das Tutorial jedoch einfach zu halten, wird der Token-Aktualisierungsfluss nicht in der Web-Anwendung WKND-PIM implementiert.

Einrichten und Ausführen der Web-Anwendung

Konfigurieren Sie nun die Web-Anwendung WKND-PIM auf Ihrem lokalen Computer und führen Sie sie aus, um den OAuth-Web-Anwendungs-Authentifizierungsfluss und die API-Aufrufe zu verstehen.

Voraussetzungen

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

Entwicklungsschritte

Die allgemeinen Entwicklungsschritte lauten:

Konfigurieren des ADC-Projekts

Der Schritt zum Konfigurieren des ADC-Projekts ist mit dem entsprechenden Schritt unter Einrichten der OpenAPI-basierten AEM-APIs identisch und wird wiederholt. Er wird wiederholt, um das Assets Author-API hinzuzufügen und „OAuth-Web-Anwendung“ als zugehörige Authentifizierungsmethode zu konfigurieren.

Konfigurieren der AEM-Instanz zur Aktivierung der ADC-Projektkommunikation

Befolgen Sie die Anweisungen im Artikel Einrichten von OpenAPI-basierten AEM-APIs, 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.

Erstellen Sie als Nächstes das PIM-Attribut-spezifische Metadatenschema und wenden es auf den Ordner PIM an.

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

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

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

Überprüfen des Anwendungs-Codes

Sehen Sie sich die allgemeine Code-Struktur und die wichtigsten Einstiegspunkte der Web-Anwendung WKND-PIM an. Die Anwendung wird mit Node.js und Express entwickelt.

Sie können die vorhandene Web-Anwendung 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 aus einer benutzerdefinierten Web-Anwendung mithilfe der OAuth-Web-Anwendungs-Authentifizierung aufrufen. Sie haben sich die wichtigsten Code-Snippets in der Web-Anwendung WKND-PIM angesehen, um den OAuth-Web-Anwendungs-Authentifizierungsfluss zu verstehen.

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

Zusätzliche Ressourcen