Delegieren von Benutzerregistrierung und Produktabonnierung

Delegierung ermöglicht, dass Ihre Website die Benutzerdaten besitzt und eine benutzerdefinierte Validierung durchführen kann. Mit der Delegierung können Sie Anmeldung/Registrierung und Produktabonnierung von Entwicklern mithilfe Ihrer bestehenden Website verarbeiten, anstatt die integrierte Funktion im Entwicklerportal zu verwenden.

Verfügbarkeit

Wichtig

Diese Funktion ist auf den Ebenen Premium, Standard, Basic und Entwickler von API Management verfügbar.

Delegieren der Anmeldung und Registrierung für Entwickler

Um die Anmeldung und Registrierung für Entwickler bei Ihrer vorhandenen Website zu delegieren, erstellen Sie einen speziellen Delegierungsendpunkt für Ihre Website. Diese spezielle Delegierung fungiert als Einstiegspunkt für alle über das API Management-Entwicklerportal initiierte Anmelde-/Registrierungsanforderungen.

Der endgültige Workflow sieht wie folgt aus:

  1. Ein Entwickler klickt auf den Anmeldungs- oder Registrierungslink im API Management-Entwicklerportal.
  2. Der Browser leitet zum Delegierungsendpunkt um.
  3. Der Delegierungsendpunkt wiederum leitet den Benutzer zur Anmeldung/Registrierung um oder zeigt diese an.
  4. Nach erfolgreicher Anmeldung/Registrierung wird der Benutzer wieder an die Stelle im API Management-Entwicklerportal zurückgeleitet, von der er ursprünglich gekommen ist.

Einrichten von API Management zur Weiterleitung von Anforderungen über einen Delegierungsendpunkt

  1. Suchen Sie im Azure-Portal in Ihrer API Management-Ressource nach dem Entwicklerportal.
  2. Klicken Sie auf das ElementDelegierung.
  3. Klicken Sie auf das Kontrollkästchen, um Anmeldung und Registrierung delegieren& zu aktivieren.

Delegation overview

  1. Legen Sie die URL für Ihren speziellen Delegierungsendpunkt fest, und geben Sie sie in das Feld Delegierungsendpunkt-URL ein.
  2. Führen Sie im Feld Schlüssel für die Überprüfung der Delegierung eine der folgenden Optionen durch:
    • Geben Sie ein Geheimnis ein, das zum Berechnen einer Signatur verwendet wird, die präsentiert wird, um zu verifizieren, dass die Anforderung von API Management stammt.
    • Klicken Sie auf die Schaltfläche Generieren, damit API Management nach einen zufälligen Schlüssel für Sie generiert.
  3. Klicken Sie auf Speichern.

Erstellen Ihres Delegierungsendpunkts

Hinweis

Das folgende Verfahren bietet Ihnen zwar Beispiele für den VorgangSignIn (Anmeldung), doch Sie können die Kontenverwaltung mit jedem der verfügbaren Vorgänge anhand der folgenden Schritte durchführen.

Empfohlene Schritte zum Erstellen eines neuen Delegierungsendpunkts zur Implementierung in Ihren Standort:

  1. Empfang einer Anforderung in der folgenden Form:

    http://www.yourwebsite.com/apimdelegation?operation=SignIn&returnUrl={URL of source page}&salt={string}&sig={string}

    Abfrageparameter für den Anmeldungs-/Registrierungsfall:

    Parameter Beschreibung
    operation Identifiziert den Typ der Delegierungsanforderung. Verfügbare Vorgänge: SignIn (Anmeldung), ChangePassword (Kennwort ändern), ChangeProfile (Profil ändern), CloseAccount (Konto schließen) und SignOut (Abmelden).
    returnUrl Die URL der Seite, auf der der Benutzer auf einen Anmeldungs- oder Registrierungslink geklickt hat.
    Salt Eine spezielle Salt-Zeichenfolge, mit der ein Sicherheitshash berechnet wird.
    sig Ein berechneter Sicherheitshash, der für den Vergleich mit dem von Ihnen generierten Hash verwendet wird.
  2. Überprüfen, ob die Anforderung von Azure API Management stammt (optional, aus Sicherheitsgründen jedoch dringend empfohlen).

    • Berechnen Sie einen HMAC-SHA512-Hash für eine Zeichenfolge, basierend auf den Abfrageparametern returnUrl und salt. Weitere Informationen finden Sie in unserem Beispielcode.

          HMAC(salt + '\n' + returnUrl)
      
    • Vergleichen Sie den generierten Hash mit dem Wert des sig-Abfrageparameters. Wenn die beiden Hashes übereinstimmen, fahren Sie mit dem nächsten Schritt fort. Lehnen Sie die Anforderung andernfalls ab.

  3. Verifizieren, dass Sie eine Anforderung für eine Anmeldung/Registrierung empfangen.

    • Der Abfrageparameter operation (Vorgang) wird auf „SignIn“ festgelegt.
  4. Zeigen Sie dem Benutzer die Benutzeroberfläche für die Anmeldung/Registrierung an.

    • Wenn sich der Benutzer registriert, erstellen Sie ein entsprechendes Konto für ihn in API Management.
      • Erstellen Sie einen Benutzer mit der REST-API für API Management.
      • Legen Sie die Benutzer-ID entweder auf denselben Wert wie in Ihrem Benutzerspeicher fest oder auf eine neue, leicht verfolgbare ID.
  5. Nach erfolgreicher Authentifizierung des Benutzers:

    • Fordern Sie ein Token für gemeinsamen Zugriff über die REST-API von API Management an.

    • Fügen Sie der SSO-URL, die Sie aus dem obigen API-Aufruf erhalten haben, einen returnUrl-Abfrageparameter an. Zum Beispiel:

      https://contoso.developer.azure-api.net/signin-sso?token=<URL-encoded token>&returnUrl=%2Freturn%2Furl

    • Leiten Sie den Benutzer an die oben erzeugte URL um.

Hinweis

Übergeben Sie für Kontoverwaltungsvorgänge (ChangePassword, ChangeProfile und CloseAccount) die folgenden Abfrageparameter:

Parameter Beschreibung
operation Identifiziert den Typ der Delegierungsanforderung.
userId Die Benutzer-ID des Kontos, das Sie verwalten möchten.
Salt Eine spezielle Salt-Zeichenfolge, mit der ein Sicherheitshash berechnet wird.
sig Ein berechneter Sicherheitshash, der für den Vergleich mit dem von Ihnen generierten Hash verwendet wird.

Delegieren der Produktabonnierung

Die Delegierung von Produktabonnements funktioniert genauso wie die Delegierung der Benutzeranmeldung/-registrierung. Der komplette Workflow sieht wie folgt aus:

  1. Ein Entwickler wählt ein Produkt im API Management-Entwicklerportal aus und klickt auf die Schaltfläche Abonnieren.
  2. Der Browser leitet zum Delegierungsendpunkt um.
  3. Der Delegierungsendpunkt führt die erforderlichen Schritte für die Produktabonnierung aus, die Sie entwerfen. Diese können umfassen:
    • Umleiten an eine andere Seite zur Anforderung von Abrechnungsinformationen.
    • Stellen weiterer Fragen.
    • Speichern der Informationen ohne Erfordernis einer Benutzeraktion.

Aktivieren der API Management-Funktionalität

Klicken Sie auf der Seite Delegierung auf Produktabonnement delegieren.

Erstellen Ihres Delegierungsendpunkts

Empfohlene Schritte zum Erstellen eines neuen Delegierungsendpunkts zur Implementierung in Ihren Standort:

  1. Empfangen Sie eine Anforderung in der folgenden Form.

    http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={product to subscribe to}&userId={user making request}&salt={string}&sig={string}

    Abfrageparameter für die Produktabonnierung:

    Parameter Beschreibung
    operation Identifiziert den Typ der Delegierungsanforderung. Gültige Optionen für die Produktabonnementanforderung sind:
    • Subscribe: Eine Anforderung für ein Benutzerabonnement eines Produkts mit der angegebenen ID (siehe unten).
    • Unsubscribe: Eine Anforderung zur Kündigung eines Benutzerabonnements für ein Produkt.
    • Renew: Eine Anforderung zur Verlängerung eines Abonnements (weil dieses z. B. demnächst abläuft).
    productId Bei Subscribe die ID des Produkts, dessen Abonnement der Benutzer angefordert hat.
    subscriptionId Bei Unsubscribe und Renew das Produktabonnement.
    userId Bei Subscribe die ID des anfordernden Benutzers.
    Salt Eine spezielle Salt-Zeichenfolge, mit der ein Sicherheitshash berechnet wird.
    sig Ein berechneter Sicherheitshash, der für den Vergleich mit dem von Ihnen generierten Hash verwendet wird.
  2. Überprüfen, ob die Anfrage von Azure API Management stammt (optional, aus Sicherheitsgründen jedoch dringend empfohlen)

    • Generieren Sie einen HMAC-SHA512-Hash für eine Zeichenfolge aus den Abfrageparametern productId, userId und salt:
      HMAC(**salt** + '\n' + **productId** + '\n' + **userId**)
      
    • Vergleichen Sie den generierten Hash mit dem Wert des sig-Abfrageparameters. Wenn die beiden Hashes übereinstimmen, fahren Sie mit dem nächsten Schritt fort. Lehnen Sie die Anforderung andernfalls ab.
  3. Verarbeiten Sie das Produktabonnement basierend auf dem im Parameter operation angeforderten Vorgangstyp (z. B. Abrechnung, weitere Fragen usw.).

  4. Nach erfolgreichem Abonnement des Produkts durch den Benutzer auf Ihrer Seite abonnieren Sie das Produkt in API Management für den Benutzer, indem Sie die REST-API für Abonnements aufrufen.

Beispielcode

Die Codebeispiele zeigen Folgendes:

  • Abrufen des Validierungsschlüssels für Delegierungen, der auf dem Bildschirm Delegierung im Azure-Portal festgelegt wird.
  • Erstellen Sie einen HMAC, mit dem die Signatur überprüft und dadurch die Gültigkeit der übergebenen „returnUrl“ nachgewiesen wird.

Mit kleineren Änderungen können Sie denselben Code für die productId und userID verwenden.

C#-Code zum Generieren des Hashwerts von returnUrl

using System.Security.Cryptography;

string key = "delegation validation key";
string returnUrl = "returnUrl query parameter";
string salt = "salt query parameter";
string signature;
using (var encoder = new HMACSHA512(Convert.FromBase64String(key)))
{
    signature = Convert.ToBase64String(encoder.ComputeHash(Encoding.UTF8.GetBytes(salt + "\n" + returnUrl)));
    // change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
    // compare signature to sig query parameter
}

NodeJS-Code zum Generieren des Hashwerts von returnUrl

var crypto = require('crypto');

var key = 'delegation validation key'; 
var returnUrl = 'returnUrl query parameter';
var salt = 'salt query parameter';

var hmac = crypto.createHmac('sha512', new Buffer(key, 'base64'));
var digest = hmac.update(salt + '\n' + returnUrl).digest();
// change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
// compare signature to sig query parameter

var signature = digest.toString('base64');

Wichtig

Sie müssen Sie das Entwicklerportal erneut veröffentlichen, damit die Delegierungsänderungen wirksam werden.

Nächste Schritte