Open Cloud는 클라이언트가 기밀인지 공개인지에 따라 PKCE와 함께 또는 없이 OAuth 2.0 승인 흐름을 지원합니다.
- _기밀 클라이언트_는 비밀번호와 같은 자격 증명을 기밀로 유지할 수 있는 앱으로, 비밀번호를 안전하게 저장하고 검색할 수 있는 웹사이트와 같습니다.
- _공개 클라이언트_는 비밀번호를 유지할 수 없는 앱으로, 모바일 및 웹 브라우저 앱과 같습니다.
모든 클라이언트에 대해 OAuth 2.0 승인 코드 흐름과 PKCE를 권장하며, 공개 클라이언트의 경우 필수로 요구합니다.
클라이언트 비밀번호를 안전한 곳에 저장하고 절대로 공개하지 마십시오. 악의적인 행위자는 이를 이용하여 귀하의 애플리케이션을 사칭할 수 있습니다.
승인 코드 흐름을 구현하기 위해 귀하의 앱은 다음 단계를 수행합니다:
- 코드 검증자와 코드 챌린지를 생성합니다 (PKCE 전용). 이를 통해 클라이언트 비밀번호 대신 요청에 챌린지를 포함할 수 있어 보안이 향상됩니다.
- 적절한 매개변수를 포함하여 승인 엔드포인트에 GET 요청을 전송합니다.
- 승인 콜백을 처리합니다. 승인 후, Roblox에서 받은 승인 코드를 앱 생성 시 지정한 URL로 리디렉션 요청합니다. 나중에 사용할 수 있도록 승인 코드를 파싱합니다.
- 승인 코드를 사용하여 토큰 엔드포인트에 POST 요청을 전송합니다. 성공하면 API 호출에 사용할 수 있는 액세스 및 갱신 토큰을 수신합니다.
- 접근하려는 리소스에 대한 참조 문서를 기반으로 OAuth 2.0 인증을 지원하는 Open Cloud API를 호출합니다.
다음 섹션에서는 각 단계를 더 깊이 설명합니다.
코드 챌린지 생성 (PKCE 전용)
승인 절차를 시작하기 전에 코드 검증자로부터 코드 챌린지를 생성해야 합니다. 선택한 프로그래밍 언어의 라이브러리나 내장 기능을 사용하여 코드 검증자를 생성하고 해시를 계산한 후 Base64 인코딩을 수행하여 코드 챌린지를 생성할 수 있습니다.
코드 검증자를 생성할 때는 예약되지 않은 문자만 사용하십시오. 대문자 및 소문자 문자(A-Z, a-z), 10진수 숫자(0-9), 하이픈(-), 마침표(.), 밑줄(_), 물결(~)을 포함하며 최소 길이는 43자, 최대 길이는 128자여야 합니다.
다음 예제는 자바스크립트를 사용하여 코드 검증자를 생성하고 SHA-256 해싱 알고리즘을 사용하여 코드 챌린지를 생성하는 방법을 보여줍니다:
코드 챌린지 생성
const crypto = require('crypto');
// 검증자와 챌린지를 base64URL 인코딩
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// 코드 검증자로부터 sha256 해시 생성
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
}
// 랜덤 코드 검증자 생성
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// 코드 검증자로부터 챌린지 생성
var code_challenge = base64URLEncode(sha256(code_verifier));
PKCE의 경우, 다음 단계에서 코드 검증자와 챌린지 값이 모두 필요합니다.
승인 URL 구성
승인 URL을 구성하는 방법에 대한 완전한 정보는 승인 엔드포인트 참조 문서를 참조하십시오.
사용자 승인 프로세스를 시작하려면 필요한 매개변수를 포함하여 승인 URL을 구성합니다:
- client_id: 애플리케이션 등록 후에 얻은 앱의 클라이언트 ID입니다.
- redirect_uri: 앱의 리디렉션 URI, 앱의 재진입 지점입니다.
- scope: 앱이 필요한 접근 권한을 정의하는 요청된 범위의 공백으로 구분된 목록입니다.
- response_type: 승인 코드 흐름을 나타내기 위해 code로 설정합니다.
PKCE 전용 필수 사항
- code_challenge: 코드 검증자로부터 생성된 코드 챌린지입니다.
- code_challenge_method: 이 매개변수 값을 S256으로 설정하여 코드 챌린지가 SHA-256 알고리즘을 사용하여 변환되었음을 나타냅니다. 이는 가장 널리 지원되며 안전한 코드 챌린지 방법입니다.
- state: 요청과 콜백 간의 상태를 유지하기 위한 불투명하고 안전한 랜덤 값입니다.
PKCE가 아닌 경우 필수 사항
- client_secret: 애플리케이션 등록 후에 얻은 앱의 클라이언트 비밀번호입니다. PKCE로 인증하는 경우 이 매개변수를 생략하십시오. 귀하의 승인 요청 URL은 다음 예제와 같이 잘 형식화되어야 합니다:
예제 PKCE 승인 URL
사용자가 URL을 방문하면 승인 흐름을 거치게 됩니다. 성공하면 Roblox는 사용자를 지정된 redirect_uri로 리디렉션합니다.
승인 콜백 처리
승인 흐름이 성공하면 귀하의 앱은 귀하가 지정한 redirect_uri에서 Roblox 승인 서버로부터 GET 요청을 받습니다. 요청에는 code (승인 코드)와 state(이전에 값을 제공한 경우) 매개변수가 포함됩니다.
code 매개변수에는 앱이 승인 서버에서 액세스 토큰으로 교환할 수 있는 승인 코드가 포함되어 있습니다. 대부분의 백엔드 서버 언어에서는 쿼리 매개변수에 접근하는 표준 방법이 있습니다. code 매개변수를 얻고 이를 사용하여 액세스 토큰으로 교환해야 합니다.
state 매개변수는 승인 요청에서 귀하가 처음 제공한 불투명한 값입니다. 이 매개변수를 사용하여 승인 프로세스의 상태 또는 컨텍스트를 유지할 수 있습니다.
예를 들어, 귀하가 리디렉션 URI로 https://example.com/redirect를 지정한 경우, 다음 URL로 GET 요청을 받을 수 있습니다.
예제 리디렉션 URL
승인이 실패하면 귀하의 앱은 지정된 리디렉션 URL로 error, error_description, 및 state (해당하는 경우) 매개변수를 포함한 GET 요청을 받습니다.
- error 매개변수는 승인 프로세스 동안 발생한 특정 OAuth 2.0 오류를 나타냅니다.
- error_description 매개변수는 오류에 대한 추가 세부 정보를 제공합니다.
- state 매개변수는 실패 시 귀하의 앱이 상태를 유지하는 데 도움이 됩니다.
승인 코드를 액세스 토큰으로 교환
승인 code를 파싱한 후, 이를 원하는 Roblox 리소스를 접근하기 위한 토큰으로 교환합니다:
토큰 교환 엔드포인트에 POST 요청을 전송하여 액세스 토큰 및 갱신 토큰을 요청합니다. 요청에는 승인 코드, 클라이언트 ID 및 코드 검증자 값 (PKCE) 또는 클라이언트 비밀번호 (비 PKCE)가 x-www-form-urlencoded 형식으로 포함되어야 합니다.
수신된 응답에서 적용 가능한 토큰을 파싱합니다. 액세스 토큰은 15분 동안 유효합니다. 갱신 토큰은 안전하게 저장하고, 일반적으로 서버 측에 두어 향후 새로운 토큰을 얻는 데 사용할 수 있습니다.
예제 토큰 엔드포인트 응답{"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"}
리소스 메서드 호출
이제 필요한 액세스 토큰이 있으므로 이를 사용하여 리소스 메서드에 대한 인증된 호출을 할 수 있습니다. 모든 API 요청의 헤더에 액세스 토큰을 포함하여 인증합니다.
예를 들어, 전체 승인 흐름을 거친 후 액세스 토큰과 함께 사용자 정보 엔드포인트에 GET 요청을 보내어 앱이 올바르게 작동하는지 테스트할 수 있습니다. 이 엔드포인트를 호출하기 전에 openid 또는 openid와 profile 두 가지 범위를 모두 포함하고 있는지 확인하십시오. 성공하면 해당 엔드포인트의 응답은 다음과 같습니다:
예제 사용자 정보 응답
{
"sub": "12345678",
"name": "Jane Doe",
"nickname": "robloxjanedoe",
"preferred_username": "robloxjanedoe",
"created_at": 1607354232,
"profile": "https://www.roblox.com/users/12345678/profile"
}