OAuth 2.0 kimlik doğrulaması | Dokümantasyon

OAuth 2.0 kimlik doğrulaması, gelecekteki sürümlerde değişiklik gösterebilecek bir beta özelliğidir. Tüm Open Cloud uç noktaları ayrıca API anahtarı kimlik doğrulaması da destekler.

Tam uygulama kılavuzları ve OAuth 2.0 hakkında bilgi, örnek bir uygulama ile birlikte, OAuth 2.0 genel bakış kısmında bulunabilir.

Bu belge, OAuth 2.0 yetkilendirme kodu akışını uygulamak için çağıracağınız uç noktaları ve uygulamalarınızda kimlik doğrulaması uygulamak için yararlı diğer uç noktaları açıklar.

Temel URL
https://apis.roblox.com/oauth

Uç Noktalar
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

Yetkilendirme

GET v1/authorize

Kullanıcıdan Roblox hesabıyla kimlik doğrulaması yapmak için yetki alır. Belirtilen parametrelerle oluşturulmuş geçerli bir yetkilendirme URL'si bekler. Bu uç nokta PKCE yetkilendirmesini destekler.

Sorgu parametreleri

Ad	Açıklama	Gereklilik	Örnek
client_id	Uygulamanın istemci kimliği.	evet	816547628409595165403873012
redirect_uri	Kullanıcıların yetkilendirme akışını tamamladıktan sonra geri yönlendirileceği URL.	evet	`https://www.roblox.com/example-redirect``
scope	İstenen kapsama alanları, boşlukla ayrılmış. ID token almak için openid kapsamını kullanın. Daha fazla kullanıcı bilgisi almak için openid ve profile kapsama alanlarını kullanın.	evet	openid profile
response_type	Uygulamanın döndürmek istediği kimlik bilgileri. Varsayılan olarak yetkilendirme kodu verilme türüdür.	evet	none, code
prompt	Kullanıcılara gösterilecek kimlik doğrulama ve onay sayfalarını belirtir. Üçüncü taraf uygulamalar için bazı ekranlar zorunludur ve atlanamaz.	hayır	none, login, consent, select_account
nonce	Tokenı istemci ile bağlayan kriptografik sayı.	hayır	<random_value_1>
state	Cross-site request forgery'yi önleyen, opak bir değer. Yetkilendirmeden sonra uygulamaya geri gönderilir.	hayır	<app-provided-opaque-value>
code_challenge	code_verifier üzerine code_challenge_method uygulanarak elde edilen dize.	hayır	Base64-URL-encoded dize
code_challenge_method	code_verifier üzerine uygulanan işlev.	hayır	S256

İstek

Yetkilendirme Akışına Yönlendirme Örneği
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

Cevap

Bu uç noktayı aradıktan sonra, kullanıcı yetkilendirme kodunu code sorgu parametresinde içeren belirtilen geri yönlendirme URL'sine yönlendirilir. Yetkilendirme kodu:

Bir dakikalık bir geçerliliğe sahiptir.
Yalnızca bir kez kullanılabilir.
Bir kez kullanıldıktan sonra geçersizdir.

Token değiştirme

API'lere erişmek için token almak için bir yetkilendirme kodu ile bir grup gizli token'ı değiştirin. Tüm token uç noktaları iki tür istemci kimlik doğrulamasını destekler:

Yetkilendirme başlığı ile HTTP Temel Kimlik Doğrulama Şeması: Authorization: Basic Base64 encoded(<client_id>:<client_secret>).
İstemci kimliği ve gizli anahtarın istek gövdesinde parametreler olarak verilmesi.

Aşağıdaki liste, bu uç noktadan aldığınız çeşitli token'ları açıklar.

Erişim token’ı - Üçüncü taraf bir uygulamanın korunan Roblox kaynaklarına erişmesi için bir oluşturucudan veya kullanıcıdan alınan yetkiyi temsil eder. Belirli bir kapsamı, geçerliliği ve diğer erişim özelliklerini belirten bir dizedir. Roblox yetkilendirme sunucusu bir erişim token'ı bir uygulamaya verdiğinde, token:
- 15 dakika boyunca geçerlidir.
- Süresi dolmadan önce birden fazla kez kullanılabilir.
- Bir uygulama kullanıcısı yetkiyi iptal ederse süresi dolmadan önce geçersiz hale getirilebilir.
Yenileme token’ı - Bir yetki oturumunu yeniler. Bir uygulama, yeni bir token seti elde etmek için yenileme token'ını kullanabilir, bu da bir erişim token'ı, bir yenileme token'ı ve bir ID token'ı içerir. Yenileme token'ı:
- 90 gün boyunca geçerlidir.
- Süresi dolmadan önce yalnızca bir kez token'ları yenilemek için kullanılabilir.
- Bir uygulama kullanıcısı yetkiyi iptal ederse süresi dolmadan önce geçersiz hale getirilebilir.
ID token’ı - Bir kullanıcının kimliğinin doğrulandığını kanıtlar. İçeriği istenen kapsamlarına bağlı olarak değişir ve bir kullanıcının Roblox görüntü adını ve kullanıcı adını içerebilir. ID token'ı yalnızca kimlik doğrulama amaçları için kullanılır ve hiçbir Roblox kaynaklarına erişim sağlamaz.

POST v1/token

Bir yetkilendirme kodu ile bir grup token alın.

İstek

(x-www-form-urlencoded)

Anahtar	Değer
code	<authorization code>
code_verifier	<pkce code verifier value>
grant_type	authorization_code
client_id	<client_id>
client_secret	<client_secret>

Token Alma İsteği Örneği
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'

Cevap

Token Alma Cevabı Örneği
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 899,
  "scope": "universe-messaging-service:publish"
}

POST v1/token

Bir yenileme token'ı ile bir grup token alın.

İstek

(x-www-form-urlencoded)

Anahtar	Değer
grant_type	refresh_token
refresh_token	<refresh_token>
client_id	<client_id>
client_secret	<client_secret>

Yenileme Token Alma İsteği Örneği
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'

Cevap

Yenileme Token Alma Cevabı Örneği
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 899,
  "scope": "universe-messaging-service:publish"
}

Bir token hakkında bilgi alın. Token'ın şu anda geçerli olup olmadığını ve süresinin dolup dolmadığını doğrular. Durumsuz doğrulama için yararlıdır. Yalnızca erişim ihtiyacı olmayan herhangi bir API'ye erişmek için kullanın; örneğin, Varlık API'si ya da yalnızca token'ın belirli beyanlarını görmek istiyorsanız.

Kullanıcı, erişim token'ıyla bağlantılı yetkiyi iptal etmiş olsa bile, uç nokta hala erişim token'ını valid: true olarak gösterir çünkü token'ın aktif olup olmadığını süresine (genellikle erişim token'ları için 15 dakika) göre kontrol eder.

İstek

(x-www-form-urlencoded)

Anahtar	Değer
token	<access_token>, <refresh_token> veya <id_token>
client_id	<client_id>
client_secret	<client_secret>

Token İnceleme İsteği Örneği
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'

Cevap

Token İnceleme Cevabı Örneği
{
  "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

Bir token'ın belirli bir kaynağa erişip erişemeyeceğini kontrol edin; kullanıcının izin verdiği kullanıcı kaynaklarının listesini alarak. Bu, durumsal doğrulama için yararlıdır.

İstek

(x-www-form-urlencoded)

Anahtar	Değer
token	<access_token>
client_id	<client_id>
client_secret	<client_secret>

Token Kaynak Alma İsteği Örneği
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'

Cevap

ids içindeki U değeri, bir kapsamın yetkilendiren sahip tarafından sahip olunan bir kaynağa erişim verdiğini gösterir.

Token Kaynak Alma Cevabı Örneği
{
  "resource_infos": [
    {
      "owner": {
        "id": "1516563360",
        "type": "User"
      },
      "resources": {
        "universe": {
          "ids": ["3828411582"]
        },
        "creator": {
          "ids": ["U"]
        }
      }
    }
  ]
}

POST v1/token/revoke

Verilen yenileme token'ını kullanarak bir yetki oturumunu iptal edin.

İstek

(x-www-form-urlencoded)

Anahtar	Değer
token	<refresh_token>
client_id	<client_id>
client_secret	<client_secret>

Token İptal İsteği Örneği
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'

Cevap

200 OK boş bir cevap ile

Kullanıcı Bilgileri

GET /v1/userinfo

Roblox kullanıcı kimliğini ve diğer kullanıcı meta verilerini alır.

İstek

Yetkilendirme başlığı: Authorization: Bearer <access_token>

Kullanıcı Bilgisi Alma İsteği Örneği
curl --location --request GET 'https://apis.roblox.com/oauth/v1/userinfo' \
--header 'Authorization: Bearer eyjlflabtfl...4gxqYBG'

Cevap

Kullanıcıyı benzersiz bir şekilde tanımlamak için sub değerini kullanabilirsiniz. Kullanıcılar Roblox kullanıcı adlarını ve görüntü adlarını değiştirebilir, bu nedenle bunları uygulamanızda kullanıcıları tanımlamak için benzersiz tanımlayıcılar olarak kullanmayın.

Beyan	Açıklama
sub	Roblox kullanıcı kimliği.
name	Roblox görüntü adı.
nickname	Roblox görüntü adı.
preferred_username	Roblox kullanıcı adı.
created_at	Roblox hesabının oluşturulma zamanı Unix zaman damgası olarak.
profile	Roblox hesap profil URL'si.
picture	Roblox avatar baş görünüm resmi. Avatar baş görünüm resmi henüz oluşturulmamışsa veya moderasyondan geçmemişse null olabilir.

Profil Kapsamı Olan Kullanıcı Örneği
{
  "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"
}

Profil Kapsamı Olmadan Kullanıcı Örneği
{
  "sub": "1516563360"
}

Keşif

OpenID Connect (OIDC) Keşif Belgesi, Open Cloud yapılandırma ayrıntıları hakkında meta verileri içeren JSON belgesidir; desteklenen kimlik ile ilgili kapsamların ve beyanların bir listesini içerir. Open Cloud OAuth 2.0 uç noktaları ve yapılandırmaları hakkında bilgi dinamik olarak keşfetmek için kullanabilirsiniz; örneğin yetkilendirme uç noktası, token uç noktası ve kamu anahtarı seti.

Keşif belgesini Keşif belgesi URI'inden alıp aldıktan sonra, yanıtta bilgileri doğrulamak için alanları manuel olarak inceleyebilir veya yanıt şemasındaki alanlarla eşlemek için kendi özel kütüphanenizi oluşturarak iş akışınızı otomatikleştirebilirsiniz.

GET .well-known/openid-configuration

Cevap

Tüm Keşif Belgesi yanıtları, aşağıdaki örnek yanıtla aynı şemayı takip eder.

Aşağıdaki kapsamların ve beyanların tamamı üçüncü taraf uygulama geliştiricilerine sunulmamıştır; bazıları yalnızca resmi Roblox uygulamaları tarafından kullanılabilir.

Keşif Belgesi Cevabı Örneği
{
  "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"
  ]
}