Realizacja interfejsu OAuth 2.0 | Dokumentacja

Open Cloud wspiera autoryzację przepływu OAuth 2.0 z użyciem PKCE lub bez niego, w zależności od tego, czy twoi klienci są poufni lub publiczne.

Zaszyfrowane klienty to aplikacje, które są w stanie utrzymać hasła poufne, takie jak strona internetowa, która może bezpiecznie przechowywać i odzyskać sekrety na swoim boku.
Klienty publiczni to aplikacje, które nie mogą utrzymywać tajemnic, takie jak aplikacje mobilne i przeglądarki internetowe.

Zalecamy przepływ kodu autoryzacji OAuth 2.0 z PKCE dla wszystkich klientów i wymagamy go dla klientów publicznych.

Przechowywanie sekretu klienta w bezpiecznym miejscu i nigdy go nie ujawnianie na publiczne. Złe aktorzy mogą użyć go, aby oszukać swoją aplikację.

Aby zaimplementować kod upoważnienia, aplikacja wykonuje następujące kroki:

Generuj weryfikator kodu i wyzwanie kodowe (tylko dla PKCE). Dzięki temu możesz włączyć wyzwanie w swoich wnioskach, a nie w tajemnicy klienta, co poprawia bezpieczeństwo.
Wyślij prośbę GET do autoryzacji z odpowiednimi parami parametru.
Zarządzaj wezwanie do autoryzacji. Po uzyskaniu autoryzacji użyj kodu autoryzacji z Roblox w żądaniu przekierowania na URL, który określiłeś podczas dziełoaplikacji. Zeskanuj kod autoryzacji dla późniejszego użycia.
Wyślij prośbę POST do kryptowania tokenu z kodem autoryzacji. Jeśli się uda, otrzymasz dostęp i odświeżisz tokeny, z których można wykonać wezwania API.
Weź dowolną otwartą API, która wspiera uwierzytelnienie OAuth 2.0 oparte na dokumentacji referencyjnej zasobów, do których chcesz uzyskać dostęp.

Poniższe sekcje opisują każdy krok w większej głębi.

Generowanie wyzwania kodeksowego (tylko dla PKCE)

Zanim zainicjujesz proces autoryzacji, musisz generować wyzwanie kodowe od weryfikatora kodu. Możesz używać bibliotek lub zintegrowanych funkcji w języku programowania swojego wyboru, aby stworzyć weryfikator kodu, obliczyć hasz i wykonaj kodowanie Base64, aby generować wyzwanie kodowe.

Podczas tworzenia weryfikatora kodu używaj tylko nieskróconych znaków, w tym małe i duże litery (A-Z, a-z), dziesięciocyślowe liczby (0-9), kropki (-), kropki (.), naczynia górne _ i naczynia dolne _ z minimum 43 znaków i maksymalnie 128 znaków.

Poniższy przykład pokazuje, jak użyć Javascript, aby stworzyć weryfikator kodu i generować wyzwanie kodowe używając algorytmu haszowania SHA-256:

Generate Code Challenge
const crypto = require('crypto');

// base64URL encode the verifier and challenge
function base64URLEncode(str) {
  return str.toString('base64')
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=/g, '');
}

// create sha256 hash from code verifier
function sha256(buffer) {
  return crypto.createHash('sha256').update(buffer).digest(`base64`);

// create a random code verifier
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// generate a challenge from the code verifier
var code_challenge = base64URLEncode(sha256(code_verifier));

Dla PKCE wymagane są zarówno weryfikator kodu, jak i wartości wyzwania w późniejszych krokach.

Konstrukcja URL Autoryzacji

Zobacz dokumentację autororyzacji końca dla kompletnej informacji o tym, jak zbudować URL autoryzacji.

Aby uruchomić proces autoryzacji użytkownika, zbuduj URL autoryzacji z wymaganymi parametrami:

client_id : ID klienta Twojego aplikacjauzyskane po rejestracji aplikacji.
redirect_uri : Twoja przekierowana URL, punkt ponownego wejścia do Twojego aplikacja.
scope : Wymagane zakresy, które określają dostępne uprawnienia aplikacji w oddzielnej liście.
response_type : Ustaw go na code, aby określić przepływ kodu autoryzacji. Wymagane tylko dla PKCE
code_challenge : Kodowe wyzwanie generowane przez weryfikator kodu.
code_challenge_method : Ustaw wartość tego parametru na S256, aby określić, że kod wyzwania został przekształcony przy użyciu algorytmu SHA-256, najpowszechniejszego i najbardziej bezpiecznego kodu wyzwania.
state : Opakowana, bezpieczna wartość losowa do utrzymania stanu między prośbą i wezwy. Wymagane tylko dla nie-PKCE
client_secret : Klient sekretny Twojego aplikacjauzyskany po rejestracji Twojego aplikacji . Jeśli używasz uwierzytelniania z PKCE, omituj ten parametr. Twoja wniosek o autoryzację musi być dobrze ustrukturyzowany, jak w następnym przykładzie:

Przykład URL autoryzacji PKCE
https://apis.roblox.com/oauth/v1/authorize?client_id=7290610391231237934964
    &code_challenge=PLEKKVCjdD1V_07wOKlAm7P02NC-LZ_1hQfdu5XSXEI
    &code_challenge_method=S256
    &redirect_uri=https://example.com/redirect
    &scope=openid%20profile
    &response_type=code
    &state=abc123

Gdy użytkownicy odwiedzają URL, są przekierowani poprzez proces uwierzytelniania. Jeśli udało się, Roblox przekieruje użytkownika na określony redirect_uri .

Wykorzystywanie danych autoryzacji

Gdyby płynący proces autoryzacji był udany, aplikacja otrzymuje GET prośbę od serwera autoryzacji Roblox w redirect_uri, który określiłeś. W prośbaotrzymujesz code (kod autoryzacji) i 2> state2> (jeśli wcześniej określiłeś wartość).

Parametr code zawiera kod autoryzacji, który aplikacja może wymienić na token dostępu z serwera autoryzacji. Większość języków serwera bazowego ma standardowe sposoby na uzyskanie parametrów zapytania jako obiekty dekompozycji. Będziesz musiał uzyskać parametr code i użyć go do wymiany na token dostępu.
Parametr state jest opacym wartością, którą pierwotnie dostarczyłeś w wniosku o autoryzację. Możesz użyć tego parametru do utrzymania stanu lub kontekstu procesu autoryzacji.

Na przykład, możesz otrzymać prośbę GET z następującym URL, jeśli określiłeś swoją przekierowaną URL, aby była https://example.com/redirect .

Przykład URL przekierowania
https://example.com/redirect?code=10c45PNuquKnFJ6pUcy5-fHkghEM6lSegm-7hj9mVEprub1dSDuStuKK_EAUXY7AHTD63xcnmvxSLthp-C8g3jzIGZVzuXSd20Y2dEYI9hx0LZmPg95ME4z2K03UheiZbroyXUjYyB3ReoMqobzDVPzyx6IS8kj2Uu-11Xq_0JiTYxtDatuqXRNIAmJT8gMJmbSyOLOP_vnDvbeMUiBsqCRrkTGVbWSwYSc8sTVVE-535kYdqQOgNjH1ffCoZLGl8YYxLnpb2CXJlRQPrcjkA&state=6789

Jeśli autoryzacja nie powiodła się, aplikacja otrzymuje GET prośbę o określonym URL z error , error_description i 2> state2> (jeśli mające zastosowanie) parametrów.

Parametr error wskazuje na specjalny błąd OAuth 2.0, który nastąpił podczas procesu autoryzacji.
Parametr error_description dostarcza dodatkowe szczegóły błędu.
Parametr state pomaga twojej aplikacji utrzymać stan w przypadku awarii.

Wymiana kodu autoryzacji za tokeny dostępu

Gdy masz przetworzonej autoryzacji code , wymień go na tokeny, aby uzyskać dostęp do pożądanych zasobów Roblox:

Żądaj token dostępu i token odświeżania, wysyłając POST prośbę do węzła wymiany tokenów . Prośba musi zawierać kod autoryzacji, ID klienta i wartość weryfikatora kodu (PKCE) lub klucz sekretny w x-www-form-urlencoded formie.

Zidentyfikuj odpowiednie tokeny z otrzymaną odpowiedzią. Token dostępu jest ważny przez 15 minut. Przechowywanie tokenu aktualizacji jest zwykle na stronie serwera, abyś mógł go użyć do uzyskania nowych tokenów w przyszłości.

Token Endpoint Odpowiedzi
{
  "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.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pY2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwibm9uY2UiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.kZgCMJQGsariwCi8HqsUadUBMM8ZOmf_IPDoWyQY9gVX4Kx3PubDz-Q6MvZ9eU5spNFz0-PEH-G2WSvq2ljDyg",
  "scope": "openid profile"
}

Zwischenie metody zasobu

Teraz, gdy masz wymaganą token dostępu, możesz go użyć do tworzenia uwierzytelnionych wezwania do metod zasobów. Włącz token dostępu w nagłówku wszystkich prośb API, aby go autoryzować.

Na przykład, możesz sprawdzić, czy twoja aplikacja funkcjonuje poprawnie, przechodząc przez cały płyn autorizacji i następnie wykonując GET prośbę o dane użytkownika do user information z użyciem tokenu dostępu. Upewnij się, że masz openid lub obie <

Odpowiedź na przykładowe informacje użytkownika
{
  "sub": "12345678",
  "name": "Jane Doe",
  "nickname": "robloxjanedoe",
  "preferred_username": "robloxjanedoe",
  "created_at": 1607354232,
  "profile": "https://www.roblox.com/users/12345678/profile"
}