• Version: 1.0.0
• Server: https://login.xsolla.com/api
• Protokolle: https
• Akzeptiert: application/json
• Antwortet mit: application/json
• Kontaktieren Sie uns per E-Mail
• Kontakt-URL: https://xsolla.com/

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

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

• [YAML](https://api.redocly.com/registry/bundle/xsolla/login- api/v1/openapi.yaml?branch=main)
• [JSON](https://api.redocly.com/registry/bundle/xsolla/login- api/v1/openapi.json?branch=main)

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.

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

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

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.

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.

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

Die Login API unterstützt die folgenden Tokentypen:

• Benutzertoken. Damit werden Anfragen an die folgenden Benutzerressourcen gesendet:
  • Profil
  • Freunde
  • Attribute
• Servertoken. Damit werden Anfragen an Anwendungsressourcen (z. B. Einstellungen oder Benutzerdaten) gesendet. Folgende Anfragen stehen zur Verfügung:
  • Plattformkonten erstellen
  • Benutzerdaten abrufen
  • Konten verknüpfen
  • Benutzerkonten über externe ID verknüpfen

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

• Benutzerregistrierung (JWT oder OAuth  2.0)
• Authentifizierung durch Benutzername und Passwort (JWT, OAuth  2.0, oder JWT-Authentifizierung durch Benutzername und Passwort)
• Authentifizierung über soziale Netzwerke (JWT oder OAuth  2.0)
• stille Authentifizierung (JWT oder OAuth  2.0)
• Authentifizierung über einen Social-Media- Zugriffstoken
• Authentifizierung über eine Publishing- Plattform

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.

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. Klicken Sie auf OAuth 2.0 hinzufügen.
5. Geben Sie die OAuth 2.0-URIs für die Weiterleitung an.
6. Aktivieren Sie das Kontrollkästchen Server (Server-zu-Server-Verbindung).
7. Legen Sie die Tokenlebensdauer fest.
8. Klicken Sie auf Verknüpfen.
9. 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 ist der JWT-Typ, übermitteln Sie den Wert client_credentials.
• client_secret ist der geheime Schlüssel, den Sie beim Einrichten des OAuth  2.0-Serverclients erhalten haben.
• client_id ist die Client-ID, die Sie beim Einrichten des OAuth  2.0-Serverclients erhalten haben.

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

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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"
  }
}