Open Cloud, istemcilerinizin gizli veya kamu olmasına bağlı olarak, PKCE ile veya onsuz OAuth 2.0 yetkilendirme akışını destekler.
- Gizli istemciler, kimlik bilgilerini gizli tutabilen uygulamalardır; örneğin arka uçta gizli verileri güvenli bir şekilde depolayabilen bir web sitesi.
- Kamu istemcileri, sırları saklayamayan uygulamalardır; örneğin mobil ve web tarayıcı uygulamaları.
Tüm istemciler için OAuth 2.0 yetkilendirme kodu akışını PKCE ile kullanmanızı öneriyoruz ve kamu istemcileri için bunu zorunlu kılıyoruz.
İstemci gizli anahtarını güvenli bir yerde saklayın ve asla kamuya açık hale getirmeyin. Kötü niyetli kişiler bunu uygulamanızı taklit etmek için kullanabilir.
Yetkilendirme kodu akışını uygulamak için uygulamanız aşağıdaki adımları gerçekleştirir:
- (PKCE için) Bir kod doğrulayıcı ve kod zorluğu oluşturun. Bu, istemci gizli anahtarını kullanmak yerine isteklerinize bir zorluk eklemenizi sağlar; bu da güvenliği artırır.
- Uygun parametrelerle yetkilendirme uç noktasına bir GET isteği gönderin.
- Yetkilendirme geri dönüşünü işleyin. Yetkilendirme aldıktan sonra, Roblox'dan alınan yetkilendirme kodunu uygulama oluşturma sırasında belirttiğiniz URL'ye yönlendirme isteği ile kullanın. Daha sonra kullanılmak üzere yetkilendirme kodunu ayrıştırın.
- Yetkilendirme kodu ile birlikte token uç noktasına bir POST isteği gönderin. Başarılı olursa, API çağrıları yapmak için kullanacağınız erişim ve yenileme jetonları alırsınız.
- Erişmek istediğiniz kaynaklar için referans belgelerine dayalı olarak OAuth 2.0 kimlik doğrulamasını destekleyen herhangi bir Open Cloud API'yi çağırın.
Aşağıdaki bölümler her adımı daha ayrıntılı bir şekilde açıklamaktadır.
Bir kod zorluğu oluşturun (sadece PKCE için)
Yetkilendirme sürecini başlatmadan önce, bir kod doğrulayıcıdan bir kod zorluğu oluşturmanız gerekir. Kod doğrulayıcı oluşturmak, hash hesaplamak ve kod zorluğunu oluşturmak için seçtiğiniz programlama dilindeki kütüphaneleri veya yerleşik işlevleri kullanabilirsiniz.
Kod doğrulayıcıyı oluştururken, yalnızca rezerve edilmemiş karakterler kullanın; büyük harf ve küçük harfler (A-Z, a-z), ondalık rakamlar (0-9), tire (-), nokta (.), alt çizgi (_) ve tilde (~) ile birlikte, minimum 43 karakter ve maksimum 128 karakter uzunluğunda olmalıdır.
Aşağıdaki örnek, Javascript kullanarak bir kod doğrulayıcı oluşturmayı ve SHA-256 hash algoritmasını kullanarak kod zorluğu üretmeyi göstermektedir:
Kodu Zorluk Oluştur
const crypto = require('crypto');
// doğrulayıcı ve zorluğu base64URL kodlayın
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// kod doğrulayıcıdan sha256 hash oluşturun
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
}
// rastgele bir kod doğrulayıcı oluşturun
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// kod doğrulayıcıdan bir zorluk oluşturun
var code_challenge = base64URLEncode(sha256(code_verifier));
PKCE için, daha sonraki adımlarda hem kod doğrulayıcı hem de zorluk değerlerine ihtiyacınız vardır.
Yetkilendirme URL'sini oluşturun
Yetkilendirme URL'sini nasıl oluşturacağınız hakkında eksiksiz bilgi için yetkilendirme uç noktası referans belgesine bakın.
Kullanıcı yetkilendirme sürecini başlatmak için gerekli parametrelerle bir yetkilendirme URL'si oluşturun:
- client_id: Uygulamanızın kaydetme işlemi sonrasında elde edilen istemci kimliği.
- redirect_uri: Uygulamanızın yönlendirme URI'si, uygulamanızın yeniden giriş noktası.
- scope: Uygulamanızın ihtiyaç duyduğu erişim izinlerini tanımlayan, boşlukla ayrılmış istenen kapsamların listesi.
- response_type: Yetkilendirme kodu akışını belirtmek için code olarak ayarlayın.
Sadece PKCE için gereklidir
- code_challenge: Bir kod doğrulayıcıdan oluşturulan kod zorluğu.
- code_challenge_method: Bu parametre değerini S256 olarak ayarlayın, bu kod zorluğunun SHA-256 algoritması kullanılarak dönüştürüldüğünü belirtmek için; en yaygın desteklenen ve güvenli kod zorluğu yöntemidir.
- state: İstek ve geri dönüş arasındaki durumu korumak için opak, güvenli rastgele bir değer.
Sadece PKCE dışındakiler için gereklidir
- client_secret: Uygulamanızı kaydetme işlemi sonrasında elde edilen uygulamanızın gizli anahtarı. PKCE ile kimlik doğrulama kullanıyorsanız, bu parametreyi atlayın. Yetkilendirme isteği URL'niz, aşağıdaki örnekte olduğu gibi iyi biçimlendirilmiş olmalıdır:
Örnek PKCE Yetkilendirme URL'si
Kullanıcılar URL'yi ziyaret ettiklerinde, yetkilendirme akışından geçeceklerdir. Başarılı olursa, Roblox kullanıcıyı belirtilen redirect_uri'ye yönlendirir.
Yetkilendirme geri dönüşlerini işleyin
Yetkilendirme akışı başarılı olduğunda, uygulamanız belirtilen redirect_uri üzerinde Roblox yetkilendirme sunucusundan bir GET isteği alır. İstekle birlikte code (yetkilendirme kodu) ve (önceden bir değer sağladıysanız) state parametrelerini alırsınız.
code parametresi, uygulamanın yetkilendirme sunucusundan bir erişim jetonu almak için değiştirebileceği yetkilendirme kodunu içerir. Çoğu arka uç sunucu dili, sorgu parametrelerine ayrıştırılmış nesneler olarak erişmenin standart yollarına sahiptir. code parametresini almanız ve erişim jetonları almak için kullanmanız gerekir.
state parametresi, yetkilendirme isteğinde başlangıçta sağladığınız bir opak değerdir. Bu parametreyi, yetkilendirme sürecinin durumunu veya bağlamını korumak için kullanabilirsiniz.
Örneğin, yönlendirme URI'nizi https://example.com/redirect olarak belirlerseniz, şu URL ile bir GET isteği alabilirsiniz:
Örnek Yönlendirme URL'si
Yetkilendirme başarısız olursa, uygulamanız belirtilen yönlendirme URL'sine error, error_description ve (uygun olduğunda) state parametreleri ile bir GET isteği alır.
- error parametresi, yetkilendirme sürecinde meydana gelen belirli bir OAuth 2.0 hatasını gösterir.
- error_description parametresi, hatanın ek ayrıntılarını sağlar.
- state parametresi, bir hata durumunda uygulamanızın durumu korumasına yardımcı olur.
Yetkilendirme kodunu erişim jetonları ile değiştirin
Yetkilendirme code'unu ayrıştırdıktan sonra, bunu Roblox kaynaklarına erişmek için jetonlarla değiştirin:
jeton alışverişi uç noktasına bir POST isteği göndererek bir erişim jetonu ve yenileme jetonu talep edin. İstek, yetkilendirme kodunu, istemci kimliğini ve kod doğrulayıcı değerini (PKCE) veya istemci gizli anahtarını (PKCE dışı) x-www-form-urlencoded formatında içermelidir.
Alınan yanıttan geçerli jetonları ayrıştırın. Erişim jetonu 15 dakika geçerlidir. Yenileme jetonunu güvenli bir şekilde, tipik olarak sunucu tarafında depolayın, böylece gelecekte yeni jetonlar almak için kullanabilirsiniz.
Örnek Jeton Uç Noktası Yanıtı{"access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IlBOeHhpb2JFNE8zbGhQUUlUZG9QQ3FCTE81amh3aXZFS1pHOWhfTGJNOWMiLCJ0eXAiOiJKV11234.eyJzdWIiOiIyMDY3MjQzOTU5IiwiYWlkIjoiM2Q2MWU3NDctM2ExNS00NTE4LWJiNDEtMWU3M2VhNDUyZWIwIiwic2NvcGUiOiJvcGVuaWQ6cmVhZCBwcm9maWxlOnJlYWQiLCJqdGkiOiJBVC5QbmFWVHpJU3k2YkI5TG5QYnZpTCIsIm5iZiI6MTY5MTYzOTY5OCwiZXhwIjoxNjkxNjQwNTk4LCJpYXQiOjE2OTE2Mzk2OTgsImlzcyI6Imh0dHBzOi8vYXBpcy5yb2Jsb3guY29tL29hdXRoLyIsImF1ZCI6IjcyOTA2MTAzOTc5ODc5MzQ5Nj1234.BjwMkC8Q5a_iP1Q5Th8FrS7ntioAollv_zW9mprF1ats9CD2axCvupZydVzYphzQ8TawunnYXp0Xe8k0t8ithg","refresh_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwia2lkIjoidGpHd1BHaURDWkprZEZkREg1dFZ5emVzRWQyQ0o1NDgtUi1Ya1J1TTBBRSIsInR5cCI6IkpXVCJ9..nKYZvjvXH6msDG8Udluuuw.PwP-_HJIjrgYdY-gMR0Q3cabNwIbmItcMEQHx5r7qStVVa5l4CbrKwJvjY-w9xZ9VFb6P70WmXndNifnio5BPZmivW5QkJgv5_sxLoCwsqB1bmEkz2nFF4ANLzQLCQMvQwgXHPMfCK-lclpVEwnHk4kemrCFOvfuH4qJ1V0Q0j0WjsSU026M67zMaFrrhSKwQh-SzhmXejhKJOjhNfY9hAmeS-LsLLdszAq_JyN7fIvZl1fWDnER_CeDAbQDj5K5ECNOHAQ3RemQ2dADVlc07VEt2KpSqUlHlq3rcaIcNRHCue4GfbCc1lZwQsALbM1aSIzF68klXs1Cj_ZmXxOSOyHxwmbQCHwY7aa16f3VEJzCYa6m0m5U_oHy84iQzsC-_JvBaeFCachrLWmFY818S-nH5fCIORdYgc4s7Fj5HdULnnVwiKeQLKSaYsfneHtqwOc_ux2QYv6Cv6Xn04tkB2TEsuZ7dFwPI-Hw2O30vCzLTcZ-Fl08ER0J0hhq4ep7B641IOnPpMZ1m0gpJJRPbHX_ooqHol9zHZ0gcLKMdYy1wUgsmn_nK_THK3m0RmENXNtepyLw_tSd5vqqIWZ5NFglKSqVnbomEkxneEJRgoFhBGMZiR-3FXMaVryUjq-N.Q_t4NGxTUSMsLVEppkTu0Q6rwt2rKJfFGuvy3s12345","token_type": "Bearer","expires_in": 899,"id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IkNWWDU1Mi1zeWh4Y1VGdW5vNktScmtReFB1eW15YTRQVllodWdsd3hnNzgiLCJ0eXAiOiJKV11234.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pZ2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwibm9uY2UiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.kZgCMJQGsariwCi8HqsUadUBMM8ZOmf_IPDoWyQY9gVX4Kx3PubDz-Q6MvZ9eU5spNFz0-PEH-G2WSvq2ljDyg","scope": "openid profile"}
Bir kaynak yöntemine çağrı yapın
Artık gerekli erişim jetonuna sahip olduğunuza göre, kimlik doğrulama yapılmış çağrılar yapmak için bunu kullanabilirsiniz. Erişim jetonunu, tüm API isteklerinin başlığına dahil edin.
Örneğin, uygulamanızın doğru çalışıp çalışmadığını test edebilirsiniz; tüm yetkilendirme akışından geçtikten sonra, bir erişim jetonuyla kullanıcı bilgi uç noktasına bir GET isteği gönderin. Bu uç noktayı çağırmadan önce openid veya hem openid hem de profile kapsamlarına sahip olduğunuzdan emin olun. Başarılı olursa, o uç noktadan gelen yanıt şöyle görünür:
Örnek Kullanıcı Bilgileri Yanıtı
{
"sub": "12345678",
"name": "Jane Doe",
"nickname": "robloxjanedoe",
"preferred_username": "robloxjanedoe",
"created_at": 1607354232,
"profile": "https://www.roblox.com/users/12345678/profile"
}