Open Cloud wspiera proces autoryzacji OAuth 2.0 z i bez PKCE, w zależności od tego, czy twoje aplikacje są poufne, czy publiczne.
- Poufne aplikacje to aplikacje, które mogą przechowywać dane uwierzytelniające w tajemnicy, takie jak stron internetowych, które mogą bezpiecznie przechowywać i pobierać sekrety na swoim serwerze.
- Publiczne aplikacje to aplikacje, które nie mogą przechowywać sekretów, takie jak aplikacje mobilne i przeglądarki internetowe.
Zalecamy używanie procesu autoryzacji OAuth 2.0 z kodem autoryzacyjnym z PKCE dla wszystkich klientów i wymagamy go dla klientów publicznych.
Przechowuj sekret klienta w bezpiecznym miejscu i nigdy nie ujawniaj go publicznie. Złe osoby mogą użyć go, aby podszyć się pod twoją aplikację.
Aby wdrożyć proces autoryzacji z użyciem kodu autoryzacyjnego, twoja aplikacja wykonuje następujące kroki:
- Wygeneruj weryfikator kodu oraz wyzwanie kodowe (tylko PKCE). Umożliwia to dołączenie wyzwania w twoich żądaniach zamiast sekretu klienta, co poprawia bezpieczeństwo.
- Wyślij żądanie GET do punktu końcowego autoryzacji z odpowiednimi parametrami.
- Obsłuż callback autoryzacji. Po uzyskaniu autoryzacji, użyj kodu autoryzacyjnego z Roblox w żądaniu przekierowania do URL, który określiłeś podczas tworzenia aplikacji. Sparafrazuj kod autoryzacyjny do późniejszego użycia.
- Wyślij żądanie POST do punktu końcowego tokena z kodem autoryzacyjnym. Jeśli operacja się powiedzie, otrzymasz tokeny dostępu i odświeżania, które umożliwią wywoływanie API.
- Wywołaj dowolne API Open Cloud, które wspiera uwierzytelnianie OAuth 2.0, w oparciu o dokumentację odniesienia dla zasobów, do których chcesz uzyskać dostęp.
Poniższe sekcje opisują każdy krok bardziej szczegółowo.
Wygeneruj wyzwanie kodowe (tylko dla PKCE)
Przed rozpoczęciem procesu autoryzacji musisz wygenerować wyzwanie kodowe z weryfikatora kodu. Możesz użyć bibliotek lub wbudowanych funkcji w wybranym przez siebie języku programowania, aby utworzyć weryfikator kodu, obliczyć hash i wykonać kodowanie Base64, aby wygenerować wyzwanie kodowe.
Podczas tworzenia weryfikatora kodu używaj tylko znaków zarezerwowanych, w tym wielkich i małych liter (A-Z, a-z), cyfr dziesiętnych (0-9), myślników (-), kropek (.), podkreślników (_) i tyld (~), z minimalną długością 43 znaków i maksymalną długością 128 znaków.
Poniższy przykład pokazuje, jak użyć Javascript do stworzenia weryfikatora kodu i wygenerowania wyzwania kodowego za pomocą algorytmu haszującego SHA-256:
Generowanie wyzwania kodowego
const crypto = require('crypto');
// kodowanie base64URL weryfikatora i wyzwania
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// tworzenie hasha sha256 z weryfikatora kodu
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
}
// tworzenie losowego weryfikatora kodu
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// generowanie wyzwania z weryfikatora kodu
var code_challenge = base64URLEncode(sha256(code_verifier));
Dla PKCE potrzebujesz zarówno wartości weryfikatora kodu, jak i wyzwania w późniejszych krokach.
Skonstruuj URL autoryzacji
Zobacz dokumentację odniesienia punktu końcowego autoryzacji po pełne informacje o tym, jak skonstruować URL autoryzacji.
Aby rozpocząć proces autoryzacji użytkownika, skonstruuj URL autoryzacji z wymaganymi parametrami:
- client_id: ID klienta twojej aplikacji uzyskane po zarejestrowaniu twojej aplikacji.
- redirect_uri: URI przekierowania twojej aplikacji, punkt ponownego wejścia do twojej aplikacji.
- scope: Żądane zakresy, które definiują uprawnienia dostępu, których potrzebuje twoja aplikacja w formie listy oddzielonej spacjami.
- response_type: Ustaw je na code, aby wskazać proces autoryzacji z kodem.
Wymagany tylko dla PKCE
- code_challenge: Wyzwanie kodowe wygenerowane z weryfikatora kodu.
- code_challenge_method: Ustaw tę wartość parametru na S256, aby wskazać, że wyzwanie kodowe zostało przekształcone przy użyciu algorytmu SHA-256, najbardziej powszechnie wspieranego i bezpiecznego sposobu wyzwania kodowego.
- state: Nieprzejrzysta, bezpieczna wartość losowa, aby utrzymać stan między żądaniem a callbackiem.
Wymagany tylko dla non-PKCE
- client_secret: Sekret klienta twojej aplikacji uzyskany po zarejestrowaniu twojej aplikacji. Jeśli korzystasz z uwierzytelniania z PKCE, pomiń ten parametr. Twój URL żądania autoryzacyjnego musi być dobrze sformatowany, jak w poniższym przykładzie:
Przykład URL autoryzacji PKCE
Kiedy użytkownicy odwiedzają URL, są przeprowadzani przez proces autoryzacji. Jeśli wszystko przebiegnie pomyślnie, Roblox przekieruje użytkownika do określonego redirect_uri.
Obsłuż callback autoryzacji
Gdy proces autoryzacji powiedzie się, twoja aplikacja otrzymuje GET żądanie od serwera autoryzacji Roblox przy redirect_uri, który określiłeś. W żądaniu otrzymujesz parametry code (kod autoryzacyjny) oraz state (jeśli wcześniej podałeś wartość).
Parametr code zawiera kod autoryzacyjny, który aplikacja może wymienić na token dostępu z serwera autoryzacji. Większość języków serwerowych posiada standardowe sposoby uzyskiwania parametrów zapytania jako zdekodowanych obiektów. Musisz pobrać parametr code i użyć go do wymiany na tokeny dostępu.
Parametr state to nieprzejrzysta wartość, którą początkowo podałeś w żądaniu autoryzacyjnym. Możesz tego parametru użyć do utrzymania stanu lub kontekstu procesu autoryzacyjnego.
Na przykład, możesz otrzymać żądanie GET z następującym URL, jeśli określiłeś swoje URL przekierowania jako https://example.com/redirect.
Przykład URL przekierowania
Jeśli autoryzacja się nie powiedzie, twoja aplikacja otrzyma żądanie GET do określonego URL przekierowania z parametrami error, error_description oraz state (jeśli dotyczy).
- Parametr error wskazuje na konkretny błąd OAuth 2.0, który wystąpił podczas procesu autoryzacji.
- Parametr error_description dostarcza dodatkowych szczegółów na temat błędu.
- Parametr state pomaga twojej aplikacji utrzymać stan w przypadku awarii.
Wymień kod autoryzacyjny na tokeny dostępu
Kiedy już sparsujesz kod autoryzacyjny, wymień go na tokeny, aby uzyskać dostęp do pożądanych zasobów Roblox:
Poproś o token dostępu i token odświeżający, wysyłając żądanie POST do punktu końcowego wymiany tokenów. Żądanie musi zawierać kod autoryzacyjny, ID klienta oraz wartość weryfikatora kodu (PKCE) lub sekret klienta (non-PKCE) w formacie x-www-form-urlencoded.
Odczytaj odpowiednie tokeny z uzyskanej odpowiedzi. Token dostępu jest ważny przez 15 minut. Bezpiecznie przechowuj token odświeżający, zazwyczaj po stronie serwera, aby móc w przyszłości uzyskać nowe tokeny.
Przykład odpowiedzi z punktu końcowego tokenów{"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"}
Wykonaj wywołanie metody zasobów
Teraz, gdy masz wymagany token dostępu, możesz go użyć do wykonania autoryzowanych wywołań do metod zasobów. Dołącz token dostępu w nagłówku wszystkich żądań API, aby je autoryzować.
Na przykład, możesz przetestować, czy twoja aplikacja działa poprawnie, przechodząc przez cały proces autoryzacji, a następnie wykonując żądanie GET do punktu końcowego informacji o użytkowniku z tokenem dostępu. Upewnij się, że masz zakres openid lub oba zakresy openid i profile przed wywołaniem tego punktu końcowego. Jeśli wszystko pójdzie dobrze, odpowiedź z tego punktu końcowego wygląda następująco:
Przykład odpowiedzi z informacji o użytkowniku
{
"sub": "12345678",
"name": "Jane Doe",
"nickname": "robloxjanedoe",
"preferred_username": "robloxjanedoe",
"created_at": 1607354232,
"profile": "https://www.roblox.com/users/12345678/profile"
}