Integrationsprozess

Der SaaS-Produktintegrationsprozess sollte die folgenden Punkte umfassen:

Der Anbieter stellt eine Anmelde-URL bereit, unter der sich ein STACKIT-Kunde registrieren und das Produkt nutzen kann.
Der Anbieter kann dem Kunden auch eine Login- oder Instanz-URL zur Verfügung stellen, damit der Kunde das Produkt nach der Subskription nutzen kann.
Der Anbieter löst Anfragen aus, z. B. durch Genehmigung ausstehender Subskription Anfragen.
Ein STACKIT Marketplace-Kunde löst Anfragen aus, z. B. durch die Subskription eines SaaS-Produkts.
Der Status im STACKIT Marketplace ändert sich, z. B. wenn der Gültigkeitszeitraum der Subskription endet. Wenn Ihr SaaS-Produkt keine Web-Benutzeroberfläche hat, kontaktieren Sie bitte das STACKIT Marketplace-Team unter marketplace@stackit.cloud. Das Produktinformationsblatt ist der Ausgangspunkt, um ein STACKIT Marketplace-Anbieter zu werden und den Integrationsprozess zu beginnen. Sie können die Weiterleitungs-URLs in diesem Blatt angeben. Die Instanz-URL können Sie dynamisch bereitstellen, wenn eine Subskription genehmigt wird. Das STACKIT Marketplace-Team wird Ihnen die Vorlage aushändigen.

Voraussetzungen

Stellen Sie sicher, dass Sie die folgenden Schritte ausgeführt haben, bevor Sie beginnen:

Sie haben Ihr Anbieter-Projekt eingerichtet und den API-Zugriff erfolgreich getestet. Weitere Informationen finden Sie unter: Einrichtung Ihres Anbieter-Projekts.
Ihr Produkt wurde den Produktdaten des STACKIT Marketplace hinzugefügt. Das STACKIT Marketplace-Team wird Sie bei diesem Schritt unterstützen.

Häufige Szenarien

1. Ein Kunde abonniert ein SaaS-Produkt

Wenn ein STACKIT-Kunde ein Produkt auf dem STACKIT Marketplace abonniert, wird er auf die Anmelde-URL des SaaS-Produkts weitergeleitet. Dies geschieht über eine GET-Anfrage, die einen x-stackit-marketplace-token-Parameter enthält. Ein Subskriptionsobjekt wird erstellt, um den Kauf zu erfassen.

Die Anbieter-API muss die Subskription genehmigen, um die Abrechnung des Kunden zu starten. Ausstehende Subskriptionen haben eine Time-to-Live (TTL) von einer Stunde. Wenn diese Zeit überschritten wird, ändert sich der Subskriptionsstatus in SUBSCRIPTION_REJECTED, was bedeutet, dass die Anfrage fehlgeschlagen ist. Beispiel:

GET https://marketplace-app.eu/register?x-stackit-marketplace-token=[token]

Anforderungen an die Landingpage

Die Landingpage muss die folgenden Anforderungen erfüllen:

Die Registrierungs-URL muss öffentlich zugänglich sein und von STACKIT Marketplace-Kunden geöffnet werden können.
Sie sollten während der Anmeldung und des Onboardings alle erforderlichen Benutzerinformationen erhalten, um die Funktionsweise des SaaS-Produkts zu ermöglichen.
Der Kunde muss auf der SaaS-Produktseite eine neue Identität und ein neues Konto anlegen. Sie können weder die STACKIT-Benutzeridentität noch die Föderation nutzen. Der STACKIT Marketplace gibt niemals persönliche Informationen eines Benutzers weiter.
Passen Sie bei Bedarf den Onboarding-Prozess für den Kunden an, um die Kundenerfahrung zu verbessern. Dies kann eine spezielle Landingpage für STACKIT Marketplace-Kunden beinhalten.
Der x-stackit-marketplace-token zeigt an, dass der Benutzer von der STACKIT Marketplace-Plattform weitergeleitet wurde. Sie müssen den Wert des Tokens (JWT) überprüfen, um sicherzustellen, dass er authentisch ist und nicht manipuliert wurde. Siehe „JWT-Verifizierung“ unten.

STACKIT Marketplace-Token

Wenn der STACKIT Marketplace auf Ihre SaaS-Anwendung weiterleitet, hängt er einen x-stackit-marketplace-token-Parameter an. Der Token-Wert ist ein kurzlebiges JSON Web Token (JWT), das die Subskriptions-ID des Anbieters enthält. Das JWT wird mit RS256 (RSA mit SHA-256) signiert.

JWT-Benutzerdaten

Header

{
    "alg": "RS256",
    "kid": "uuid",
   "typ": "JWT"
}

alg: Gibt den Algorithmus an, der zum Signieren des Tokens verwendet wird (RSA with SHA-256). Dieses Feld hat immer diesen Wert.
kid: Die Schlüssel-ID, die verwendet wird, um den Schlüssel zum Signieren des Tokens zu erhalten. Dies ist nützlich für Schlüsselrotationsszenarien.
type: Gibt den Token-Typ an. Dieses Feld hat immer diesen Wert. Payload

{
    "subscriptionId": "uuid",
    "iss": "[https://keys.marketplace.stackit.cloud/v1/resolve-customer/keys.json](https://keys.marketplace.stackit.cloud/v1/resolve-customer/keys.json)",
  "exp": 1683081000,
    "iat": 1683077400
}

subscriptionId: Die eindeutige Kennung für die Subskription des Anbieters.
iss: Der Issuer-Claim, der angibt, wo die öffentlichen Schlüssel zur Überprüfung des Tokens öffentlich verfügbar sind.
exp: Das Ablauffeld ist ein Zeitstempel (in Sekunden seit der Unix-Epoche), der angibt, wann der Token abläuft. Er liegt immer 5 Minuten nach dem issued at-Zeitstempel.
iat: Das issued at-Feld ist ein Zeitstempel, der angibt, wann der Token erstellt wurde.

JWT-Verifizierung

Der x-stackit-marketplace-token zeigt an, dass der Benutzer vom STACKIT Marketplace weitergeleitet wurde. Sie müssen den Wert des JWT überprüfen, um seine Authentizität und Integrität zu gewährleisten und eine Manipulation zu verhindern.

Laden Sie die öffentlichen Schlüssel des STACKIT Marketplace herunter: https://keys.marketplace.stackit.cloud/v1/resolve-customer/keys.json.
Dekodieren Sie das JWT und lesen Sie die Schlüssel-ID aus dem Header.
Verwenden Sie die Schlüssel-ID, um den richtigen öffentlichen Schlüssel aus den heruntergeladenen Schlüsseln auszuwählen.
Verifizieren Sie die JWT-Signatur mithilfe der öffentlichen Schlüssel des STACKIT Marketplace.
Stellen Sie sicher, dass das JWT nicht abgelaufen ist.
Prüfen Sie, ob der Aussteller mit dem STACKIT Marketplace-Aussteller übereinstimmt.
Stellen Sie sicher, dass die Subskriptions-ID mit der Subskriptions-ID übereinstimmt, die vom Resolve Customer-Flow zurückgegeben wurde.

Ein Beispiel für die technische Implementierung dieses Prozesses finden Sie in den Python- oder Go-Beispielen im STACKIT Marketplace-Codebeispiele-Repository.

2. Kunden ermitteln

Der STACKIT Marketplace leitet den Kunden auf die registrierte SaaS-Landingpage weiter und fügt einen x-stackit-marketplace-token hinzu. Der Token-Wert ist ein fünfminütiges JSON Web Token (JWT), das die Subskriptions-ID des Anbieters enthält. Dieser Token kann über die Anbieter-API gegen Subskriptionsinformationen ausgetauscht werden.

POST /v1/vendors/projects/[projectId]/resolve-customer

Benutzerdaten der Anfrage, wobei [Token] der Token ist:

{
    "token": "[token]"
}

Antwort-Payload:

{
  "lifecycleState": "SUBSCRIPTION_PENDING",
  "product": {
    "deliveryMethod": "SAAS",
    "lifecycleState": "PRODUCT_LIVE",
    "priceType": "CONTRACT",
    "pricingPlan": "Test Plan",
    "productId": "2ea4b536-07c8-479e-a7a7-41ff724e053f",
    "productName": "Test Product Name",
    "vendorName": "STACKIT",
    "vendorPlanId": "custom-plan-id-123", // vendor-provided identifier;
optional
    "vendorProductId": "vendor-custom-id", // vendor-provided identifier; optional
    "vendorWebsiteUrl": "[https://example.com](https://example.com)"
  },
  "projectId": "c5fedcab-920d-40cd-a06f-e7443db8e7f7",
  "subscriptionId": "e93750b2-3d5c-496e-844d-67c947e34c67"
}

Beispiele finden Sie in den Abschnitten Go und Python im STACKIT Marketplace-Codebeispiele-Repository.

3. Subskription genehmigen

Sie sollten die Subskription genehmigen, wenn die folgenden Bedingungen erfüllt sind:

Der Kunde hat sich erfolgreich auf der SaaS-Produktseite registriert und wurde dem System hinzugefügt. Dies beinhaltet eine erfolgreiche Kundenanmeldung und die Speicherung der STACKIT Marketplace-Mapping-Kennungen, wie z. B. der Subskriptions-ID des Anbieters.
Das SaaS-Produkt ist vollständig bereitgestellt und der SaaS-Benutzer kann es verwenden.

POST /v1/vendors/projects/{projectId}/subscriptions/{subscriptionId}/approve

Beispiele für die Implementierung mit den Go- oder Python-STACKIT-SDKs finden Sie in den Abschnitten Go und Python im STACKIT Marketplace-Codebeispiele-Repository.

Wenn die Anmeldung oder das Onboarding fehlschlägt

Wenn während der Kundenregistrierung oder des Onboardings Fehler auftreten, die das SaaS-Produkt unbrauchbar machen, dürfen Sie die Subskriptionsanfrage nicht genehmigen. Bitte öffnen Sie umgehend ein STACKIT-Support-Ticket oder kontaktieren Sie das STACKIT Marketplace-Team unter marketplace@stackit.cloud, um Hilfe zu erhalten.

Kundenanmeldung

Wenn ein Kunde eine aktive Produktsubskription hat, kann der STACKIT Marketplace ihn mit einer GET-Anfrage auf eine Anmeldeseite für das SaaS-Produkt weiterleiten. Es wird kein x-stackit-marketplace-token-Parameter angehängt.

Wenn Sie keine Anmelde-URL angeben, wird die Registrierungs-URL verwendet (ohne den x-stackit-marketplace-token-Parameter).
Der STACKIT Marketplace unterstützt eine eindeutige Anmelde-URL für jede Subskription. Diese URL kann auf eine bestimmte Kunden-App-Instanz verweisen. Bitte geben Sie die Anmelde-URL in der Approve Subscription-Anfrage an.

STACKIT Marketplace-Statusänderungen

Der Subskriptionsstatus auf der Anbieterseite muss mit dem Status auf dem STACKIT Marketplace synchronisiert werden. Dies beinhaltet neue Subskriptionen, Kündigungen und Updates. Sie sollten einen Abfragemechanismus mit einer angemessenen Frequenz implementieren, um den aktuellen Status der Subskriptionen zu erhalten. Wenn Subskriptionen erstellt oder gelöscht werden, können Sie automatisch per E-Mail benachrichtigt werden, damit Sie Maßnahmen ergreifen und Änderungen planen können. Wenden Sie sich an das STACKIT Marketplace-Team, um Unterstützung zu erhalten.