OAuth 2.0-Authentifizierung | Dokumentation

Die OAuth 2.0-Authentifizierung ist eine Beta-Funktion, die Änderungen in zukünftigen Versionen unterliegen kann. Alle Open Cloud-Endpunkte unterstützen auch die API-Schlüssel-Authentifizierung.

Für vollständige Implementierungsanleitungen und Informationen zu OAuth 2.0, einschließlich einer Beispielanwendung, siehe die OAuth 2.0-Übersicht.

Dieses Dokument beschreibt die Endpunkte, die Sie aufrufen, um den OAuth 2.0-Authorization-Code-Fluss zu implementieren, sowie andere Endpunkte, die für die Implementierung der Authentifizierung in Ihren Apps nützlich sind.

Basis-URL
https://apis.roblox.com/oauth

Endpunkte
GET v1/authorize
POST v1/token
POST v1/token/introspect
POST v1/token/resources
POST v1/token/revoke
GET v1/userinfo
GET .well-known/openid-configuration

Autorisierung

GET v1/authorize

Erhält die Autorisierung des Benutzers zur Authentifizierung mit seinem Roblox-Konto. Erwartet eine gültige Autorisierungs-URL, die mit den gegebenen Parametern erstellt wurde. Dieser Endpunkt unterstützt die PKCE-Autorisierung.

Abfrageparameter

Name	Beschreibung	Erforderlich	Beispiel
client_id	Die Client-ID der App.	ja	816547628409595165403873012
redirect_uri	Die URL, zu der die Benutzer nach Abschluss des Autorisierungsflusses zurückgeleitet werden.	ja	`https://www.roblox.com/example-redirect``
scope	Die angeforderten Bereiche, durch Leerzeichen getrennt. Verwenden Sie den Bereich openid, um ein ID-Token zu erhalten. Verwenden Sie die Bereiche openid und profile, um weitere Benutzerinformationen zu erhalten.	ja	openid profile
response_type	Die Anmeldeinformationen, die die App zurückgegeben haben möchte. Der Standardwert ist der Autorisierungscode.	ja	none, code
prompt	Gibt an, welche Authentifizierungs- und Zustimmungsseiten den Benutzern angezeigt werden. Bestimmte Bildschirme sind für Drittanbieter-Apps erforderlich und können nicht übersprungen werden.	nein	none, login, consent, select_account
nonce	Die kryptografische Zahl, die das Token mit dem Client bindet.	nein	<random_value_1>
state	Ein undurchsichtiger Wert, der Cross-Site-Request-Forgery verhindert, eine Art bösartiger Angriff. Wird nach der Autorisierung an die App zurückgegeben.	nein	<app-provided-opaque-value>
code_challenge	Der resultierende String aus der Anwendung der code_challenge_method auf den code_verifier.	nein	Base64-URL-kodierter String
code_challenge_method	Die Funktion, die auf den code_verifier angewendet wird.	nein	S256

Anfrage

Beispiel Anfrage zur Weiterleitung des Autorisierungsflusses
https://apis.roblox.com/oauth/v1/authorize?client_id=816547628409595165403873012&redirect_uri=https://my-app.com/redirect&scope=openid&response_type=code&nonce=12345&state=6789

Antwort

Nachdem dieser Endpunkt aufgerufen wurde, wird der Benutzer an die angegebene Umleitungs-URL mit dem Autorisierungscode in einem code-Abfrageparameter weitergeleitet. Der Autorisierungscode:

Hat eine Lebensdauer von einer Minute.
Kann nur einmal eingelöst werden.
Ist nach einer Verwendung ungültig.

Token-Austausch

Um Tokens zum Zugriff auf APIs zu erhalten, tauschen Sie einen Autorisierungscode gegen ein Set von vertraulichen Tokens. Alle Token-Endpunkte unterstützen zwei Arten der Client-Authentifizierung:

HTTP Basic Authentication-Schema mit einem Autorisierungsheader: Authorization: Basic Base64-kodiert(<client_id>:<client_secret>).
Client-ID und Secret im Anfragetext als Parameter.

Die folgende Liste beschreibt die verschiedenen Tokens, die Sie von diesem Endpunkt erhalten.

Zugriffstoken - Stellt die Autorisierung eines Erstellers oder Benutzers für eine Drittanbieter-App dar, um auf ihre geschützten Roblox-Ressourcen zuzugreifen. Es ist eine Zeichenkette, die einen spezifischen Bereich, eine Lebensdauer und andere Zugriffsattribute angibt. Sobald der Roblox-Autorisierungsserver ein Zugriffstoken an eine App ausstellt, ist das Token:
- 15 Minuten lang gültig.
- Kann mehrere Male verwendet werden, bevor es abläuft.
- Kann ungültig gemacht werden, bevor es abläuft, wenn ein App-Benutzer die Autorisierung widerruft.
Auffrischungstoken - Erneuert eine Autorisierungssitzung. Eine App kann das Auffrischungstoken verwenden, um ein neues Set von Tokens zu erhalten, das ein Zugriffstoken, ein Auffrischungstoken und ein ID-Token umfasst. Ein Auffrischungstoken:
- Ist 90 Tage lang gültig.
- Kann nur einmal verwendet werden, bevor es abläuft, um Tokens zu erneuern.
- Kann ungültig gemacht werden, bevor es abläuft, wenn ein App-Benutzer die Autorisierung widerruft.
ID-Token - Bietet den Nachweis, dass die Identität eines Benutzers authentifiziert wurde. Der Inhalt hängt von den angeforderten Bereichen ab und kann grundlegende Benutzerinformationen enthalten, einschließlich des Roblox-Anzeigenamens und des Benutzernamens eines Benutzers. Das ID-Token dient nur zu Identifikationszwecken und gewährt keinen Zugriff auf Roblox-Ressourcen.

POST v1/token

Erhalten Sie ein Set von Tokens mit einem Autorisierungscode.

Anfrage

(x-www-form-urlencoded)

Schlüssel	Wert
code	<authorization code>
code_verifier	<pkce code verifier value>
grant_type	authorization_code
client_id	<client_id>
client_secret	<client_secret>

Beispiel Anfrage Token erhalten
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=yCnq4ofX1...XmGpdx'

Antwort

Beispiel Antwort Token erhalten
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 899,
  "scope": "universe-messaging-service:publish"
}

POST v1/token

Erhalten Sie ein Set von Tokens mit einem Auffrischungstoken.

Anfrage

(x-www-form-urlencoded)

Schlüssel	Wert
grant_type	refresh_token
refresh_token	<refresh_token>
client_id	<client_id>
client_secret	<client_secret>

Beispiel Anfrage Auffrischungstoken erhalten
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=Ujfstayclfdlbm...BGydlsnU' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

Antwort

Beispiel Antwort Auffrischungstoken erhalten
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 899,
  "scope": "universe-messaging-service:publish"
}

POST v1/token/introspect

Erhalten Sie Informationen über ein Token. Überprüft, ob das Token derzeit gültig ist und noch nicht abgelaufen ist. Nützlich für zustandslose Validierung. Verwenden Sie diesen Endpunkt nur, wenn die API, auf die Sie zugreifen, keine Ressource benötigt, wie die Assets-API, oder wenn Sie nur bestimmte Ansprüche des Tokens sehen möchten.

Selbst wenn der Benutzer die mit dem Zugriffstoken verknüpfte Autorisierung widerrufen hat, zeigt der Endpunkt das Zugriffstoken immer noch als valid: true an, weil er überprüft, ob das Token basierend auf seiner Lebensdauer aktiv ist (typischerweise 15 Minuten für Zugriffstoken).

Anfrage

(x-www-form-urlencoded)

Schlüssel	Wert
token	<access_token>, <refresh_token> oder <id_token>
client_id	<client_id>
client_secret	<client_secret>

Beispiel Anfrage Token inspizieren
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/introspect' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=eyjlflabtfl...4gxqYBG' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

Antwort

Beispiel Antwort Token inspizieren
{
  "active": true,
  "jti": "RT.2GcjvTduKzk6QY9tjTfm",
  "iss": "https://apis.roblox.com/oauth/",
  "token_type": "Bearer",
  "client_id": "840974200211308101",
  "aud": "4239311013248676173",
  "sub": "1516563360",
  "scope": "universe-messaging-service:publish",
  "exp": 1676394509,
  "iat": 1660842510
}

POST v1/token/resources

Überprüfen Sie, ob ein Token auf eine bestimmte Ressource zugreifen kann, indem Sie die Liste der Benutzerressourcen abrufen, für die der Benutzer eine Berechtigung erteilt hat. Dies ist nützlich für zustandsabhängige Validierung.

Anfrage

(x-www-form-urlencoded)

Schlüssel	Wert
token	<access_token>
client_id	<client_id>
client_secret	<client_secret>

Beispiel Anfrage Tokens auf Ressourcen abrufen
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/resources' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=eyjlflabtfl...4gxqYBG' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

Antwort

Der Wert U in ids zeigt an, dass ein Bereich Zugriff auf eine Ressource gewährt hat, die dem autorisierenden Besitzer gehört.

Beispiel Antwort Tokens auf Ressourcen abrufen
{
  "resource_infos": [
    {
      "owner": {
        "id": "1516563360",
        "type": "User"
      },
      "resources": {
        "universe": {
          "ids": ["3828411582"]
        },
        "creator": {
          "ids": ["U"]
        }
      }
    }
  ]
}

POST v1/token/revoke

Widerrufen Sie eine Autorisierungssitzung mit dem bereitgestellten Auffrischungstoken.

Anfrage

(x-www-form-urlencoded)

Schlüssel	Wert
token	<refresh_token>
client_id	<client_id>
client_secret	<client_secret>

Beispiel Anfrage Token widerrufen
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=Ujfstayclfdlbm...BGydlsnU' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

Antwort

200 OK mit einer leeren Antwort

Benutzerinformationen

GET /v1/userinfo

Erhält die Roblox-Benutzer-ID und andere Benutzer-Metadaten.

Anfrage

Autorisierungsheader: Authorization: Bearer <access_token>

Beispiel Anfrage Benutzerinformationen abrufen
curl --location --request GET 'https://apis.roblox.com/oauth/v1/userinfo' \
--header 'Authorization: Bearer eyjlflabtfl...4gxqYBG'

Antwort

Sie können den Wert sub verwenden, um den Benutzer eindeutig zu identifizieren. Benutzer können ihren Roblox-Benutzernamen und Anzeigenamen ändern, verwenden Sie diese also nicht als eindeutige Identifikatoren, um Benutzer in Ihrer App zu referenzieren.

Anspruch	Beschreibung
sub	Roblox-Benutzer-ID.
name	Roblox-Anzeigename.
nickname	Roblox-Anzeigename.
preferred_username	Roblox-Benutzername.
created_at	Erstellungszeit des Roblox-Kontos als Unix-Zeitstempel.
profile	URL zum Roblox-Konto-Profil.
picture	Roblox-Avatar-Kopfaufnahme-Bild. Kann null sein, wenn das Avatar-Kopfaufnahme-Bild noch nicht generiert oder überprüft wurde.

Beispiel Benutzer mit Profilbereich
{
  "sub": "1516563360",
  "name": "exampleuser",
  "nickname": "exampleuser",
  "preferred_username": "exampleuser",
  "created_at": 1584682495,
  "profile": "https://www.roblox.com/users/1516563360/profile",
  "picture": "https://tr.rbxcdn.com/03dc2a9abe7b1aacaaf93ea46d5c0646/150/150/AvatarHeadshot/Png"
}

Beispiel Benutzer ohne Profilbereich
{
  "sub": "1516563360"
}

Entdeckung

Das OpenID Connect (OIDC) Discovery-Dokument ist ein JSON-Dokument, das Metadaten über die Open Cloud-Konfigurationsdetails enthält, einschließlich einer Liste von identitätsbezogenen Berechtigungen und Ansprüchen, die unterstützt werden. Sie können es verwenden, um Informationen über die Open Cloud OAuth 2.0-Endpunkte und Konfiguration dynamisch zu entdecken, wie den Autorisierungsendpunkt, Token-Endpunkt und den Satz von öffentlichen Schlüsseln.

Nachdem Sie das Discovery-Dokument von der Discovery-Dokument-URI abgerufen haben, können Sie entweder die Felder in der Antwort manuell inspizieren, um die Informationen zu überprüfen, oder Sie können Ihre eigene benutzerdefinierte Bibliothek erstellen, die die Felder im Antwortschema kartiert, um Ihren Workflow zu automatisieren.

GET .well-known/openid-configuration

Antwort

Alle Antworten des Discovery-Dokuments folgen demselben Schema wie die folgende Beispielantwort.

Nicht alle folgenden Bereiche und Ansprüche sind für Drittanbieter-App-Ersteller verfügbar, da einige nur von offiziellen Roblox-Apps verwendet werden können.

Beispiel Antwort Discovery-Dokument
{
  "issuer": "https://apis.roblox.com/oauth/",
  "authorization_endpoint": "https://apis.roblox.com/oauth/v1/authorize",
  "token_endpoint": "https://apis.roblox.com/oauth/v1/token",
  "introspection_endpoint": "https://apis.roblox.com/oauth/v1/token/introspect",
  "revocation_endpoint": "https://apis.roblox.com/oauth/v1/token/revoke",
  "resources_endpoint": "https://apis.roblox.com/oauth/v1/token/resources",
  "userinfo_endpoint": "https://apis.roblox.com/oauth/v1/userinfo",
  "jwks_uri": "https://apis.roblox.com/oauth/v1/certs",
  "registration_endpoint": "https://create.roblox.com/dashboard/credentials",
  "service_documentation": "https://create.roblox.com/docs/reference/cloud",
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "verification",
    "credentials",
    "age",
    "premium",
    "roles"
  ],
  "response_types_supported": ["none", "code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["ES256"],
  "claims_supported": [
    "sub",
    "type",
    "iss",
    "aud",
    "exp",
    "iat",
    "nonce",
    "name",
    "nickname",
    "preferred_username",
    "created_at",
    "profile",
    "email",
    "email_verified",
    "verified",
    "age_bracket",
    "premium",
    "roles",
    "internal_user"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ]
}