Xsolla-logo

개요

이 섹션에서는 로그인 작업을 위한 API 호출에 대해 설명합니다. 요청을 전송하기 전에 관리자 페이지에서 로그인 프로젝트를 설정해야 합니다.

API 정의 다운로드

API 정의는 다음 두 가지 형식으로 다운로드할 수 있습니다.

용어집

관리자 페이지에서 다음 로그인 프로젝트 유형에 액세스할 수 있습니다.

  • 표준 로그인 프로젝트
  • 섀도우 로그인 프로젝트

이에 대한 자세한 정보는 크로스 플랫폼 계정 기능을 참조하세요.

표준 로그인 프로젝트

기본 계정을 저장하는 데 사용하는 로그인 프로젝트입니다.

섀도우 로그인 프로젝트

플랫폼 계정을 저장하는 데 사용하는 로그인 프로젝트입니다.

기본 계정

표준 로그인 프로젝트에서 생성하고 플랫폼 계정에 연결한 계정 유형입니다. 기본 계정은 다른 플랫폼에서 플레이어를 식별하는 데 사용됩니다.

플랫폼 계정

섀도우 로그인 프로젝트에서 생성하고 명확한 퍼블리싱 플랫폼에 연결한 계정 유형입니다. 플랫폼 계정은 다른 플랫폼 계정에 연결할 수 없습니다. 또한 기본 계정에서 계정 연결을 해제할 수 없습니다.

퍼블리싱 플랫폼

게임 배포에 사용하는 게임 플랫폼입니다(예: Steam, PlayStation, Xbox 등).

인증

로그인 API는 다음 토큰 유형을 지원합니다.

사용자 토큰 가져오기

토큰을 가져오려면 다음 요청 중 하나를 전송합니다.

JWT 인증 후 사용자는 <Callback URL>?token=<User token (JWT)> 쿼리 매개 변수로 된 토큰이 있는 콜백 URL로 리디렉션됩니다.

OAuth 2.0 프로토콜 기반 인증 후 JWT 생성 요청을 엑솔라 로그인 서버로 전송하여 수신한 code 매개 변수를 사용자 토큰(access_token)으로 교환합니다.

서버 토큰 가져오기

서버 토큰을 가져오는 방법:

  1. 서버 OAuth 2.0 클라이언트 설정
  2. 서버 JWT 생성

서버 OAuth 2.0 클라이언트 설정

  1. 관리자 페이지에서 프로젝트를 열고 로그인 섹션으로 이동합니다.
  2. 로그인 프로젝트 패널에서 구성을 클릭합니다.
  3. 보안 블록으로 이동하여 OAuth 2.0 섹션을 선택합니다.
  4. OAuth 2.0 추가를 클릭합니다.
  5. OAuth 2.0 리디렉션 URI를 지정합니다.
  6. 서버(서버 간 연결) 상자를 선택합니다.
  7. 토큰 수명을 지정합니다.
  8. 연결을 클릭합니다.
  9. 클라이언트 ID와 비밀 키를 복사하여 저장합니다.

서버 JWT 생성

애플리케이션의 백엔드에서 Generate JWT API 호출을 사용하여 서버 JWT를 가져오는 메서드를 구현합니다. 요청에는 다음 매개 변수가 포함되어야 합니다.

JWT 구조

모든 토큰은 JWT 형식을 가지며 페이로드에 명확한 정보를 포함합니다.

사용자 JWT

사용자 JWT는 인증 또는 등록의 결과로 수신한 토큰입니다. 토큰 페이로드에는 사용자 및 인증 호출에 대한 정보가 포함됩니다.

OAuth 2.0 프로토콜을 통해 사용자 토큰을 가져오려면 OAuth 2.0 클라이언트가 필요합니다. 사용자 토큰은 Authorization: Bearer <JWT> 헤더에서 전달됩니다.

기본 클레임

토큰은 인증 또는 이메일 주소 확인 후 기본 클레임을 포함하게 됩니다. 이러한 클레임의 존재는 사용자 데이터베이스 및 인증 호출에 의존하지 않습니다.

 
클레임 유형 필수 설명
exp Unix 타임스탬프 토큰 만료 날짜 및 시간입니다. 기본 만료 시간은 24시간입니다. 모든 로그인 프로젝트의 만료 시간을 변경할 수 있습니다.
iss string 토큰에 서명한 서비스: https://login.xsolla.com.
iat Unix 타임스탬프 토큰을 제공하는 날짜 및 시간입니다.
sub string(UUID) 엑솔라 로그인 서버 측에 기록된 사용자 ID.
groups array

사용자가 속한 그룹 목록입니다. 모든 그룹은 다음 형식으로 작성됩니다.

  • id — 그룹 ID
  • name — 그룹 이름
  • is_default — 그룹의 기본값 여부를 표시(true 또는 false 값).

하나의 기본 그룹만 있을 수 있습니다. 이 그룹은 초기에 다른 그룹으로 배포되기 전의 모든 사용자를 포함합니다.

xsolla_login_project_id string(UUID) 로그인 프로젝트 ID입니다.
type string

인증 옵션:

  • xsolla_login - 사용자 이름/이메일 및 암호를 통한 로그인
  • social - 소셜 로그인
  • email - 이메일로 받은 일회성 코드를 통한 암호 없는 로그인
  • phone - SMS로 수신한 일회용 코드를 통한 암호 없는 로그인
  • firebase - 사용자 데이터 저장소가 Firebase인 경우 사용자 이름/이메일 및 암호를 통한 로그인
  • playfab - 사용자 데이터 저장소가 PlayFab인 경우 사용자 이름/이메일 및 암호를 통한 로그인
  • proxy - 사용자 데이터 저장소가 사용자 정의인 경우 사용자 이름/이메일 및 암호를 통한 로그인
  • device - 장치 ID로 로그인
  • server_custom_id - 사용자 정의 ID로 로그인

하나의 기본 그룹만 있을 수 있습니다. 이 그룹은 초기에 다른 그룹으로 배포되기 전의 모든 사용자를 포함합니다.

avatar string 사용자 아바타 URL입니다.
username string 사용자 이름입니다.
publisher_id integer 로그인 프로젝트를 소유한 판매자의 ID입니다.
email string 사용자 이메일 주소입니다.
payload string 인증을 진행하는 동안 페이로드 매개 변수에서 전달되는 추가 정보입니다.
promo_email_agreement boolean

다음 값 중 하나일 수 있습니다.

  • true 사용자가 뉴스레터 수신에 동의하는 경우.
  • false 그렇지 않은 경우.
기본적으로 true 값을 가짐.

로그인 위젯의 등록 양식에 기능을 추가하는 방법:

  • Widget 2.0을 사용하는 경우 계정 관리자에게 문의.
  • 이전 버전의 위젯을 사용하는 경우 초기화 코드promo_email_agreement 값을 사용하는 fields 매개 변수를 추가.

connection_information string 사용자가 생년월일을 확인했는지 여부를 표시합니다. 확인은 okname 서비스를 통해 진행합니다.

PlayFab 저장소

PlayFab 저장소를 사용하는 경우 인증 후 토큰에 포함된 클레임입니다.

클레임 유형 필수 설명
external_account_id string 사용자 PlayFab ID입니다.
session_ticket string

인증 요청 또는 PlayFab API에 대한 요청을 진행하는 동안 수신한 SessionTicket 매개 변수입니다.

OAuth 2.0 프로토콜을 통해 사용자를 인증하고 playfab 값을 scope 매개변수로 전달한 경우 토큰에 클레임이 포함됩니다.

entity_token string EntityToken.EntityToken 매개 변수입니다.
entity_type string EntityToken.Entity.Type 매개 변수입니다. title_player_account 값만 가질 수 있습니다.
entity_id string EntityToken.Entity.Id 매개 변수입니다.

사용자 정의 저장소

사용자 정의 저장소를 사용하는 경우 인증 후 토큰에 포함된 클레임입니다.

클레임 유형 필수 설명
provider string 인증에 사용되는 소셜 네트워크의 이름입니다. 사용자가 사용자 이름과 암호를 통해 인증하는 경우 클레임은 xsolla 값을 갖습니다.
external_account_id string 서버 측의 사용자 ID입니다.
partner_data 인증을 진행하는 동안 서버가 응답 본문에서 반환하는 모든 유형의 데이터입니다.

소셜 인증

소셜 네트워크를 통한 인증 후에 토큰에 포함된 클레임입니다. 이러한 클레임의 존재는 사용자 데이터베이스에 의존하지 않습니다.

클레임 유형 필수 설명
provider string 인증에 사용된 SNS 이름.
id string 소셜 네트워크의 사용자 ID입니다.
is_cross_auth boolean 암묵 인증 요청이 진행 중임을 표시합니다.
social_access_token string 인증에 사용하는 소셜 네트워크 계정 access_token 매개 변수입니다. 이 기능을 설정하려면 계정 관리자에게 문의해야 합니다.
picture string(URL) 소셜 네트워크의 사용자 프로필 사진에 연결합니다.
birthday date(RFC3339) 소셜 네트워크의 사용자 생년월일입니다.
gender string 소셜 네트워크의 사용자 성별입니다.
name string 소셜 네트워크의 사용자 별명입니다.

OAuth 2.0 프로토콜을 통한 인증

OAuth 2.0 인증 후 토큰에 포함된 클레임입니다.

클레임 유형 필수 설명
jti string 고유 토큰 ID입니다.

전화번호를 통한 인증

전화번호를 통한 인증 후 토큰에 포함된 클레임입니다.

클레임 유형 필수 설명
phone_number string 인증에 사용되는 사용자의 전화번호입니다. 구분선 없이 국가 코드, 지역 번호 및 줄 번호를 기반으로 하는 전화번호 형식입니다.

서버 JWT

서버 토큰은 X-SERVER-AUTHORIZATION 헤더에서 전달됩니다.

토큰 페이로드에는 OAuth 2.0 클라이언트가 소유한 리소스에 대한 정보가 포함되어 있습니다. 토큰은 이러한 리소스에 대한 서버 기반 인증을 사용하여 호출에 액세스할 수 있습니다.

클레임 유형 필수 설명
xsolla_login_project_id string(UUID) OAuth 2.0 클라이언트를 소유한 로그인 프로젝트의 ID입니다.
resources array

OAuth 2.0 클라이언트가 소유한 리소스의 목록입니다. 가능한 리소스 유형:

  • publisher_id — 로그인 프로젝트를 소유한 판매자의 리소스
  • publisher_project_id관리자 페이지의 프로젝트 리소스

모든 그룹은 다음 형식으로 작성됩니다.

  • name — 리소스 유형
  • value — 리소스 ID

jti string 고유 토큰 ID입니다.

JWT 유효성 검사

인증에 성공하면 모든 사용자는 자신에게 생성된 JWT를 갖습니다. 생성된 JWT는 비밀 키로 서명됩니다. JWT가 관련성이 있고 로그인 프로젝트의 사용자에게 속해 있는지 확인하려면 해당 값의 유효성을 검사해야 합니다.

JWT의 유효성을 검사하는 방법:

  1. 관리자 페이지에서 프로젝트를 열고 로그인 섹션으로 이동합니다.
  2. 로그인 옵션의 패널에서 구성을 클릭합니다.
  3. 탐색 페이지에서 보안 블록으로 이동하여 JWT 서명 섹션을 선택합니다.
  4. 암호화 방식을 선택하고 선택한 방식에 따라 비밀 키 또는 새 공개 JSON 웹 키 필드의 값을 복사합니다.
  5. 라이브러리를 선택하고 응용 프로그램의 서버 측에서 연결합니다.
  6. 4단계에서 복사한 값을 유효성 검사 함수 항목에 전달합니다.

주의

비밀 키를 누구에게도 알려주어선 안 됩니다. 손상된 경우 업데이트해야 합니다.

오류

오류 응답이 있는 경우 엑솔라 로그인 서버는 다음 필드가 있는 JSON 개체를 반환합니다.

필드 유형 설명
code string 엑솔라 로그인 서버 오류 코드입니다.
description string 오류 설명입니다. 텍스트는 항상 영어로 되어 있습니다. 오류가 발생할 경우 나중에 값이 변경될 수 있으므로 이 텍스트를 사용해선 안 됩니다.
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

400 Bad Request

코드 설명
0 요청에 잘못된 매개 변수가 있습니다.
010-019 클라이언트 인증에 실패했습니다(예: 알 수 없는 클라이언트, 클라이언트 인증이 포함되지 않음 또는 지원되지 않는 인증 방식).
010-022 매개 변수 상태가 누락되었거나 8자 미만이므로 너무 약합니다.
010-023 인증 권한 부여 또는 새로 고침 토큰이 잘못되었거나, 만료되었거나, 해지되었거나, 인증 요청에서 사용한 리디렉션 URI와 일치하지 않거나, 다른 클라이언트에 대해 발급되었습니다.

401 Unauthorized

코드 설명
002-016 잘못된 토큰입니다.
002-040 금지된 사용자는 인증할 수 없습니다.
003-001 사용자 이름 또는 암호가 잘못되었습니다.
003-007 확인되지 않은 사용자 계정입니다.
003-025 OAuth 2.0 액세스 토큰을 가져오는 동안 오류가 발생했습니다.
003-040 권한이 없는 사용자입니다.
010-026 엑솔라 로그인 서버 또는 리소스 소유자가 요청을 거부했습니다.

403 Forbidden

코드 설명
1901-0001 잘못된 토큰입니다.

404 Not Found

코드 설명
003-002 사용자를 찾을 수 없습니다.
003-019 프로젝트를 찾을 수 없습니다.
003-061 개체를 찾을 수 없습니다.

418 I’m a teapot

코드 설명
004-001 문제가 발생했습니다.

422 Unprocessable Entity

코드 설명
0 쿼리에서 별명을 누락했습니다.
002-050 사용자의 이중 인증 설정이 변경되지 않았습니다.
003-003 지정한 사용자 이름을 가진 사용자가 이미 있습니다.
003-020 이 로그인 프로젝트에 사용할 수 없는 호출입니다.
003-022 이 로그인 프로젝트는 잘못 구성되어 있습니다. 엑솔라 관리자 페이지에서 이 로그인 프로젝트 설정을 변경하거나 계정 관리자에게 문의해야 합니다.
003-033 프로젝트 유형이 일치하지 않습니다.
006-003 client_credentials 권한 부여 유형의 OAuth 2.0 클라이언트만 액세스 목록을 가질 수 있습니다.
010-015 소셜 네트워크 인증 실패: SERVICE_NAME.
010-016 이 소셜 계정은 이미 다른 사용자와 연결되어 있습니다.
010-032 이 소셜 네트워크를 통한 인증은 이 로그인 프로젝트에서 활성화되지 않았습니다. 엑솔라 관리자 페이지 > 로그인 프로젝트 > 내 로그인 프로젝트 > 소셜 연결에서 활성화해야 합니다.
030-024 이 로그인 프로젝트에서는 암호 재설정이 비활성화되어 있습니다.
2002-0001 중복된 특성입니다.

429 Too Many Requests

코드 설명
002-054 허용된 검색 시도 횟수를 초과했습니다. 다음 요청 전에 잠시 기다려야 합니다.
010-005 허용된 요청 횟수를 초과했습니다.
1900-0001 허용된 요청 횟수를 초과했습니다.