Xsolla-logo

Überblick

Dieser Abschnitt beschreibt API-Aufrufe für die Arbeit mit Login. Konfigurieren Sie Ihr Login-Projekt im Kundenportal, bevor Sie Anfragen senden.

API-Definition herunterladen

Die API-Definition steht in zwei Formaten zum Download bereit:

Begriffserläuterung

Im Kundenportal haben Sie Zugriff auf die folgenden Login-Projekttypen:

  • Standard-Login-Projekt
  • Schatten-Login-Projekt

Weitere Informationen dazu finden Sie unter Plattformübergreifendes Konto.

Standard-Login-Projekt

Ist ein Login-Projekt, das zum Speichern von Hauptkonten verwendet wird.

Schatten-Login-Projekt

Ist ein Login-Projekt, das zum Speichern von Plattformkonten verwendet wird.

Hauptkonto

Ist ein in einem Standard-Login-Projekt erstellter Kontotyp und wird mit Plattformkonten verknüpft. Das Hauptkonto dient dazu, Spieler auf verschiedenen Plattformen zu identifizieren.

Plattformkonto

Ist ein in einem Schatten-Login-Projekt erstellter Kontotyp und wird mit einer bestimmten Publishing-Plattform verknüpft. Das Plattformkonto lässt sich mit keinem weiteren Plattformkonto verknüpfen. Zudem können Sie die Verknüpfung zwischen einem solchen Konto und einem Hauptkonto nicht aufheben.

Publishing-Plattform

Ist eine Plattform zur Distribution von Spielen (z. B. Steam, PlayStation, Xbox usw.).

Authentifizierung

Die Login API unterstützt die folgenden Tokentypen:

Benutzertoken abrufen

Senden Sie eine der folgenden Anfragen, um den Token abzurufen:

Nach der JWT-Authentifizierung wird der Benutzer mithilfe eines Tokens in einem Abfrageparameter zur Rückruf-URL weitergeleitet: <Callback URL>?token=<User token (JWT)>.

Senden Sie nach der auf dem OAuth 2.0-Protokoll basierenden Authentifizierung die Anfrage JWT generieren an den Xsolla-Login-Server, um den empfangenen code-Parameter gegen einen Benutzertoken (access_token) zu tauschen.

Servertoken abrufen

So rufen Sie ein Servertoken ab:

  1. Richten Sie den OAuth 2.0-Serverclient ein.
  2. Generieren Sie den JWT.

OAuth 2.0-Serverclient einrichten

  1. Öffnen Sie Ihr Projekt im Kundenportal, und wechseln Sie zum Abschnitt Login.
  2. Klicken Sie beim gewünschten Login-Projekt auf Konfigurieren.
  3. Scrollen Sie zum Block Sicherheit, und wählen Sie OAuth 2.0 aus.
  4. Click Add OAuth 2.0 Client.
  5. Aktivieren Sie das Kontrollkästchen Server (Server-zu-Server-Verbindung).
  6. Legen Sie die Tokenlebensdauer fest.
  7. Klicken Sie auf Verknüpfen.
  8. Kopieren und speichern Sie die Client-ID und den geheimen Schlüssel.

Server-JWT generieren

Implementieren Sie im Backend Ihrer Anwendung eine Methode, um den Server-JWT mithilfe des API-Aufrufs JWT generieren abzurufen. Die Anfrage muss folgende Parameter enthalten:

  • grant_type is the type of getting JWT, pass the client_credentials value.
  • client_secret is the secret key that is received when you set up the server OAuth 2.0 client.
  • client_id is the client ID received when you set up the server OAuth 2.0 client.

JWT-Struktur

Jeder Token hat ein JWT-Format und enthält eine bestimmte Information in einer Payload.

Benutzer-JWT

Ein Benutzer-JWT ist ein Token, der infolge einer Authentifizierung oder Registrierung empfangen wird. Eine Token-Payload enthält Informationen über den Benutzer und den Authentifizierungsaufruf.

Um einen Benutzertoken über das OAuth 2.0-Protokoll abzurufen, ist ein OAuth  2.0-Client erforderlich. Der Benutzertoken wird im Header Authorization: Bearer <JWT> übermittelt.

Wichtige Claims

Nach der Authentifizierung oder Bestätigung der E-Mail-Adresse enthält ein Token die wichtigsten Claims. Ob diese Claims vorhanden sind, hängt nicht von der Nutzerdatenbank und dem Authentifizierungsaufruf ab.

 
Claim Typ Erforderlich Beschreibung
exp Unix-Zeitstempel Ja Datum und Uhrzeit des Tokenverfalls. Die Standardverfallszeit beträgt 24 Stunden. Sie können die Verfallszeit für jedes Login-Projekt individuell festlegen.
iss String Ja Dienst, der den Token signiert hat: https://login.xsolla.com.
iat Unix-Zeitstempel Ja Datum und Uhrzeit der Tokenübermittlung.
sub String (UUID) Ja Aufseiten des Xsolla-Login-Servers geschriebene Benutzer-ID.
groups Array Ja

Liste der Gruppen, denen der Benutzer zugeordnet ist. Jede Gruppe wird in dem folgendem Format geschrieben:

  • id – Gruppen-ID
  • name – Gruppenname
  • is_default – ob es sich um eine Standardgruppe handelt oder nicht (true oder false).

Es kann nur eine Standardgruppe geben. Diese Gruppe umfasst zunächst alle Benutzer, bevor diese verschiedenen Gruppen zugeordnet werden.

xsolla_login_project_id String (UUID) Ja Login-Projekt-ID.
type String

Authentifizierungsoption:

  • xsolla_login – Anmeldung über Benutzername/E-Mail-Adresse und Passwort
  • social – Anmeldung über soziale Netzwerke
  • email – passwortlose Anmeldung über einen per E-Mail erhaltenen Einmalcode.
  • phone – passwortlose Anmeldung über einen per SMS erhaltenen Einmalcode.
  • firebase – Anmeldung über Benutzername/E-Mail-Adresse und Passwort, wenn die Nutzerdaten bei Firebase gespeichert sind.
  • playfab – Anmeldung über Benutzername/E-Mail-Adresse und Passwort, wenn die Nutzerdaten bei PlayFab gespeichert sind.
  • proxy — Anmeldung über Benutzername/E-Mail-Adresse und Passwort, wenn die Nutzerdaten im eigenen Speicher gespeichert sind.
  • device – Anmeldung mit Geräte-ID.
  • server_custom_id – Anmeldung mit selbst definierter ID.

Es kann nur eine Standardgruppe geben. Diese Gruppe umfasst zunächst alle Benutzer, bevor diese verschiedenen Gruppen zugeordnet werden.

avatar String Benutzer-Avatar-URL.
username String Benutzername.
publisher_id Integer ID eines Händlers, dem ein Login-Projekt gehört.
email String E-Mail-Adresse des Benutzers.
payload String Zusätzliche Informationen, die während der Authentifizierung im Payload-Parameter übermittelt werden.
promo_email_agreement boolesch

Folgende Werte sind möglich:

  • true, wenn der Benutzer dem Erhalt eines Newsletters zustimmt.
  • andernfalls false.
true ist standardmäßig eingestellt.

So fügen Sie die Funktion der Registrierungsmaske des Login-Widgets hinzu:

  • Wenden Sie sich an Ihren Account Manager, wenn Sie das Widget 2.0 verwenden.
  • Fügen Sie den Parameter fields mit dem Wert promo_email_agreement in den Initialisierungscode ein, wenn Sie eine vorherige Version des Widgets verwenden.

connection_information String Zeigt an, ob der Benutzer sein Geburtsdatum bestätigt hat oder nicht. Die Bestätigung erfolgt über den Dienst okname.

PlayFab-Speicher

Claims, die nach der Authentifizierung im Token enthalten sind, sofern Sie den PlayFab-Speicher verwenden.

Claim Typ Erforderlich Beschreibung
external_account_id String Ja PlayFab-ID des Benutzers.
session_ticket String Ja

Ein während einer Authentifizierungsanfrage oder während Anfragen an die PlayFab API empfangener SessionTicket-Parameter.

Ein Token enthält diesen Claim, wenn Sie Benutzer über das OAuth 2.0-Protokoll authentifizieren und dabei den Wert playfab an den Parameter scope übermitteln.

entity_token String Ja Ein EntityToken.EntityToken-Parameter.
entity_type String Ja Ein EntityToken.Entity.Type-Parameter. Einzig möglicher Wert:title_player_account.
entity_id String Ja Ein EntityToken.Entity.Id-Parameter.

Eigener Speicher

Claims, die nach der Authentifizierung im Token enthalten sind, sofern Sie einen eigenen Speicher verwenden.

Claim Typ Erforderlich Beschreibung
provider String Ja Name des sozialen Netzwerks, das zur Authentifizierung verwendet wird. Wenn sich der Benutzer über einen Benutzernamen und ein Passwort authentifiziert, hat der Claim den Wert xsolla.
external_account_id String Benutzer-ID aufseiten Ihres Servers.
partner_data Daten beliebigen Typs, die von Ihrem Server während der Authentifizierung im Antwortrumpf zurückgegeben werden.

Authentifizierung über soziale Netzwerke

Claims, die nach der Authentifizierung über ein soziales Netzwerk im Token enthalten sind. Ob diese Claims vorhanden sind, hängt nicht von der Nutzerdatenbank ab.

Claim Typ Erforderlich Beschreibung
provider String Ja Name des zur Authentifizierung verwendeten sozialen Netzwerks.
id String Ja Benutzer-ID im sozialen Netzwerk.
is_cross_auth boolesch Zeigt an, dass die Stille-Authentifizierung-Anfrage läuft.
social_access_token String Der zur Authentifizierung genutzte access_token-Parameter des Social-Media-Kontos. Wenden Sie sich an Ihren Account Manager, um die Funktion einzurichten.
picture String (URL) Link zum Profilbild des Benutzers in einem sozialen Netzwerk.
birthday Datum (RFC3339) Geburtsdatum des Benutzers in einem sozialen Netzwerk.
gender String Geschlecht des Benutzers in einem sozialen Netzwerk.
name String Nickname des Benutzers in einem sozialen Netzwerk.

Authentifizierung über das OAuth 2.0-Protokoll

Claims, die nach der OAuth 2.0-Authentifizierung im Token enthalten sind.

Claim Typ Erforderlich Beschreibung
jti String Ja Eindeutige Token-ID.

Authentifizierung über eine Telefonnummer

Claim, der nach der Authentifizierung über eine Telefonnummer im Token enthalten ist.

Claim Typ Erforderlich Beschreibung
phone_number String Ja Die zur Authentifizierung verwendete Telefonnummer des Benutzers. Das Telefonnummernformat setzt sich zusammen aus Landesvorwahl, nationaler Vorwahl und Anschlusskennung ohne Trennzeichen.

Server-JWT

Der Servertoken wird im X-SERVER-AUTHORIZATION-Header übermittelt.

Die Token-Payload enthält Informationen über Ressourcen, die dem OAuth  2.0-Client gehören. Der Token kann auf diese Ressourcen durch Aufrufe mit serverbasierter Authentifizierung zugreifen.

Claim Typ Erforderlich Beschreibung
xsolla_login_project_id String (UUID) Ja ID eines Login-Projekts, das dem OAuth 2.0-Client gehört.
resources Array Ja

Liste der Ressourcen, die einem OAuth 2.0-Client gehören. Mögliche Ressourcentypen:

  • publisher_id – Ressourcen eines Händlers, dem das Login-Projekts gehört
  • publisher_project_id – Ressourcen eines Projekts im Kundenportal.

Jede Gruppe wird im folgenden Format geschrieben:

  • name – Ressourcentyp
  • value – Ressourcen-ID

jti String Ja Eindeutige Token-ID.

JWT-Validierung

Nach erfolgreicher Authentifizierung wird für jeden Benutzer ein JWT generiert. Der generierte JWT wird mit einem geheimen Schlüssel signiert. Um sicherzustellen, dass ein JWT relevant ist und dem Benutzer Ihres Login-Projekts gehört, sollten Sie seinen Wert validieren.

So validieren Sie einen JWT:

  1. Öffnen Sie Ihr Projekt im Kundenportal, und wechseln Sie zum Abschnitt Login.
  2. Klicken Sie beim gewünschten Login-Projekt auf Konfigurieren.
  3. Scrollen Sie auf der Navigationsseite zum Block Sicherheit, und wählen Sie JWT-Signatur aus.
  4. Wählen Sie die Verschlüsselungsmethode aus, und kopieren Sie den Wert des Feldes Geheimer Schlüssel bzw. Neuer öffentlicher JSON-Webschlüssel, je nach ausgewählter Methode.
  5. Wählen Sie die Bibliothek, und verknüpfen Sie diese serverseitig mit Ihrer Anwendung.
  6. Übermitteln Sie den in Schritt 4 kopierten Wert an den Validierungsfunktionseintrag.

Hinweis

Geben Sie Ihren geheimen Schlüssel niemals weiter. Falls er kompromittiert wurde, aktualisieren Sie ihn bitte.

Fehler

Bei Fehlermeldungen gibt der Xsolla-Login-Server ein JSON-Objekt mit den folgenden Feldern zurück:

Feld Typ Beschreibung
code String Fehlercode des Xsolla-Login-Servers.
Beschreibung String Fehlerbeschreibung. Der Text ist immer in Englisch. Verwenden Sie diesen Text nicht im Falle eines Fehlers, da sich der Wert in Zukunft ändern kann.
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

400 Bad Request

Code Beschreibung
0 Anfrage enthält ungültige Parameter.
010–019 Client-Authentifizierung fehlgeschlagen (z. B. unbekannter Client, keine Client-Authentifizierung enthalten oder nicht unterstützte Authentifizierungsmethode).
010–022 Parameterstatus fehlt oder ist zu schwach, weil er weniger als 8 Zeichen umfasst.
010–023 Die Autorisierungserlaubnis oder der Aktualisierungstoken ist ungültig, ist abgelaufen, wurde widerrufen, stimmt nicht mit der in der Autorisierungsanfrage verwendeten Weiterleitungs-URI überein oder wurde für einen anderen Client ausgestellt.

401 Unauthorized

Code Beschreibung
002–016 Ungültiger Token.
002–040 Benutzer ist gesperrt, Autorisierung nicht möglich.
003–001 Falscher Benutzername oder falsches Passwort.
003–007 Benutzerkonto nicht bestätigt.
003–025 Beim Abrufen des OAuth 2.0-Zugriffstokens ist ein Fehler aufgetreten.
003–040 Nicht autorisierter Benutzer.
010–026 Der Xsolla-Login-Server oder der Ressourceneigentümer hat die Anfrage abgelehnt.

403 Forbidden

Code Beschreibung
1901–0001 Ungültiger Token.

404 Not Found

Code Beschreibung
003–002 Benutzer nicht gefunden.
003–019 Projekt nicht gefunden.
003–061 Objekt nicht gefunden.

418 I’m a teapot

Code Beschreibung
004–001 Etwas ist schiefgelaufen.

422 Unprocessable Entity

Code Beschreibung
0 In der Abfrage fehlt der Nickname.
002–050 Die Benutzereinstellungen für die Zwei-Faktor-Authentifizierung wurden nicht geändert.
003–003 Benutzer mit dem angegebenen Benutzernamen existiert bereits.
003–020 Aufruf für dieses Login-Projekt nicht verfügbar.
003–022 Dieses Login-Projekt ist falsch konfiguriert. Ändern Sie die Login-Projekteinstellungen im Xsolla-Kundenportal oder wenden Sie sich an Ihren Account Manager.
003–033 Projekttyp falsch zugeordnet.
006–003 OAuth 2.0-Clients mit dem Grant-Typ client_credentials dürfen nur eine Zugriffsliste besitzen.
010–015 Authentifizierung über soziales Netzwerk fehlgeschlagen: SERVICE_NAME.
010–016 Dieses Social-Media-Konto ist bereits mit einem anderen Benutzer verknüpft.
010–032 Die Authentifizierung über dieses soziale Netzwerk ist bei diesem Login-Projekt nicht aktiviert. Aktivieren Sie die Option unter Xsolla-Kundenportal > Login > Ihr Login-Projekt > Social-Media-Einbindung.
030–024 Passwort zurücksetzen ist bei diesem Login-Projekt deaktiviert.
2002–0001 Attribute doppelt vorhanden.

429 Too Many Requests

Code Beschreibung
002–054 Zulässige Anzahl von Suchanfragen überschritten. Warten Sie eine Sekunde, bevor Sie die nächste Anfrage starten.
010–005 Zulässige Anzahl von Anfragen überschritten.
1900–0001 Zulässige Anzahl von Anfragen überschritten.