Auth Interface

참고: 인증 웹 API로 인증할 수도 있습니다. 자세한 내용은 EOS 웹 API 레퍼런스 인증 웹 API 문서를 참조하세요.

인증 인터페이스를 사용하면 플레이어가 게임에서 직접 에픽게임즈 계정에 로그인할 수 있습니다. 인터페이스를 사용하여 플레이어를 인증하고, 액세스 토큰을 받고, 에픽 온라인 서비스와의 기타 계정 관련 인터랙션을 처리하세요. 플레이어가 에픽게임즈 계정으로 로그인하면 플레이어에게 친구, 현재상태, 사용자 정보, Ecom 인터페이스 등 다른 에픽 계정 서비스에 대한 액세스를 제공할 수 있습니다.

또한 연결 인터페이스를 사용하면 플레이어가 지원되는 ID 제공자를 통해 게임에 로그인할 수 있습니다. 게임에서 연결 인터페이스를 사용하는 방법에 관한 자세한 내용은 연결 인터페이스 문서를 참고하세요. 인증 인터페이스와 연결 인터페이스 간의 차이점은 아래 표에서 확인할 수 있습니다.

인증 인터페이스를 사용하려면 게임(제품)의 에픽 계정 서비스(EAS) 가 활성 상태여야 하며, 기본 프로필(Basic Profile) 데이터에 액세스하기 위해 사용자 동의가 필요합니다. 개발자 포털에서 EAS를 활성화하거나 에픽 문서에서 자세한 내용을 확인할 수 있습니다. EAS와 사용자 동의가 없다면 EOS SDK와 인증 인터페이스를 초기화할 수는 있어도 백엔드 서비스에 보낸 모든 인증 인터페이스 함수 호출은 실패합니다.

인증 기능에 액세스하려면 EOS_HAuth 핸들이 필요합니다. 플랫폼 인터페이스 함수인 EOS_Platform_GetAuthInterface 를 호출하여 이 핸들을 획득할 수 있습니다. 사용자 정보에 액세스하려면 인증 인터페이스 함수에 이 핸들이 필요합니다.

EAS의 온라인 기능과 상호작용하려면 플레이어는 먼저 유효한 에픽 계정으로 로그인해야 합니다. 플레이어가 유효한 에픽 계정으로 로그인할 수 있도록 설정하려면 로컬 플레이어의 계정 크리덴셜이 포함된 EOS_Auth_LoginOptions 구조를 사용하여 EOS_Auth_Login 함수를 호출합니다. 로그인 시도의 성공 여부에 관계없이, 완료 시 EOS_Auth_OnLoginCallback 타입의 콜백 함수가 실행됩니다.

브랜드 리뷰는 에픽게임즈에서 개발사의 게임 브랜드를 검증하는 프로세스입니다. 검증이 끝나면 조직 외부의 플레이어가 게임의 에픽 계정 서비스 통합을 이용할 수 있습니다. 브랜드 리뷰가 완료되기 전에 플레이어가 외부 계정으로 게임 로그인을 시도하면 오류가 표시됩니다. 자세한 내용은 브랜드 리뷰 신청 프로세스 문서를 참고하세요.

EOS_Auth_LoginOptions 는 반드시 초기화해야 하는데, ApiVersion 변수는 EOS_AUTH_LOGIN_API_LATEST 로 설정하고 Credentials 변수(EOS_Auth_Credentials 타입)는 다음 정보를 포함한 상태로 초기화해야 합니다.

인증 인터페이스 핸들, EOS_Auth_LoginOptions 구조체, 콜백 정보를 함수에 전달합니다. EOS_HPlatform 핸들의 틱이 실행 중인 경우, 해당 작업이 끝난 후 아까 전달한 콜백이 실행됩니다.

SDK 1.5 버전부터 플랫폼별로 선호되는 로그인 타입은 다음과 같습니다.

게임에서는 로컬 사용자 계정의 플랫폼에서 액세스 토큰을 얻습니다. EOS_LCT_ExternalAuth 로그인 타입을 사용하여 플랫폼 사용자는 자신의 에픽 계정에 로그인합니다. 자세한 로그인 플로에 대해서는 외부 계정 인증을, 플랫폼 코드 통합에 대해서는 콘솔별 문서를 참고하세요.

PC와 모바일 디바이스에서는 보통 인증 백엔드에서 부여한 장기 실행 새로고침 토큰으로 활성화되는 디바이스 및 사용자 계정별 영구 로그인을 사용합니다. 이러한 플랫폼에서 SDK는 필요에 따라 해당 토큰을 자동으로 저장 및 검색하고 매번 로그인 후에 업데이트합니다. 영구 로그인에 대한 섹션을 참고하세요.

에픽게임즈 런처와 연결된 애플리케이션을 시작하면 런처에서 몇 가지 파라미터를 포함하는 명령줄을 제공하며 그 형식은 다음과 같습니다.

이 명령줄의 중요 필드는 다음과 같습니다.

애플리케이션은 이 정보를 파싱하여 EOS_Auth_Credentials 구조체를 통해 EOS_Auth_Login 으로 전달해야 합니다. EOS_Auth_Credentials 의 변수에는 Id, Token, Type 의 세 가지가 있습니다. 이 로그인 방법에서는 ID가 필요하지 않으므로 Id 를 비워 둘 수 있습니다. Token 에는 AUTH_PASSWORD 명령줄 파라미터의 교환 코드를 입력합니다. 마지막으로, Type 은 EOS_LCT_ExchangeCode 여야 합니다.

EOS SDK 버전 1.5부터 EOS_Auth_LoginOptions 에는 이름이 ScopeFlags 인 EOS_EAuthScopeFlags (API LINK) 타입의 새로운 필드가 포함됩니다. 범위는 애플리케이션이 올바르게 기능하는 데 필요한 권한 세트입니다. 예를 들어, 애플리케이션이 사용자의 친구 목록을 확인해야 할 경우 EOS_AS_FriendsList 범위를 요청해야 하며 사용자에게는 로그인 플로 도중에 여기에 동의하라는 메시지가 나타납니다. 사용자가 요청 범위 중 하나라도 동의하지 않으면 로그인이 실패합니다. 동의 요청 시, 요청은 개발자 포털의 제품에 구성된 범위와 정확히 일치해야 합니다.

에픽게임즈 런처와 연결된 애플리케이션을 시작하면 런처에서 몇 가지 파라미터를 포함하는 명령줄을 제공하며 그 형식은 다음과 같습니다.

이 명령줄의 중요 필드는 다음과 같습니다. 이 정보는 애플리케이션에 의해 파싱되고 EOS_Auth_Credentials 구조를 통해 EOS_Auth_Login 에 제공되어야 합니다. EOS_Auth_Credentials 의 변수에는 Id, Token, Type 의 세 가지가 있습니다. Type 의 경우 EOS_LCT_ExchangeCode 를 사용합니다.

Id 는 이 로그인 유형에 사용되지 않으므로 비워두세요. 마지막으로는 AUTH_PASSWORD 의 익스체인지 코드를 Token 으로 제공하세요.

PC 및 모바일 플랫폼에서 에픽게임즈 런처 외부의 영구 사용자 로그인을 지원하려면 EOS_LCT_AccountPortal 로그인 타입을 사용해야 합니다.

SDK는 사용자의 에픽 계정 로그인 성공 후 인증 백엔드에서 새로고침 토큰을 자동으로 받아 디바이스에서 로컬로 로그인한 사용자의 로컬 키체인에 새로고침 토큰을 저장합니다. 로컬 키체인의 경우 SDK는 디바이스의 운영 체제에서 제공하는 보안 크리덴셜 저장소를 사용합니다.

로컬 사용자 자동 로그인 시 게임에서는 항상 EOS_LCT_PersistentAuth 로그인 타입을 사용하여 EOS_Auth_Login 을 먼저 호출해야 합니다. SDK에서 장기 실행 액세스 크리덴셜을 관리하기 때문에 Id 및 Token 입력 필드는 NULL 로 설정되어야 합니다. SDK에서 로컬 사용자의 키체인에서 새로고침 토큰을 확인 후 토큰을 찾은 경우 자동으로 해당 토큰을 사용하여 사용자를 에픽 계정에 로그인시킵니다. 해당 플랫폼에서 로그인에 성공하면 SDK에서 로컬 키체인의 새로고침 토큰을 자동으로 업데이트합니다.

어떤 이유로든 EOS_Auth_Login 이 실패한다면, 플랫폼의 디폴트 로그인 방법으로 진행합니다. EOS_Auth_Login 이 새로고침 토큰을 찾았지만 서버가 토큰을 거부해서 로그인에 실패한다면, 즉 토큰이 없다거나, 연결 또는 서비스 문제나 작업 취소 또는 재시도 대기 외의 다른 이유로 호출이 실패한다면, 토큰이 구버전이어서 모든 향후 세션에서 계속 실패를 야기할 것이므로 애플리케이션에서 토큰을 삭제해야 합니다. EOS_Auth_DeletePersistentAuth 를 호출하여 사용자의 로컬 키체인에 저장된 크리덴셜을 명시적으로 제거할 수 있습니다. 그러면 애플리케이션에서 플랫폼의 디폴트 로그인 플로를 진행합니다.

로그인한 사용자가 자동 로그인을 비활성화하기를 원하는 경우에는, EOS_Auth_Logout 을 호출하여 로그아웃하고 EOS_Auth_DeletePersistentAuth 를 호출하여 인증 백엔드에서 사용자의 장기 실행 로그온 세션을 철회합니다. 그러면 로컬 사용자의 키체인에서 장기 실행 새로고침 토큰도 삭제됩니다.

로그아웃하려면 EOS_Auth_LogoutOptions 데이터 구조체를 사용하여 EOS_Auth_Logout 함수를 호출합니다. 작업이 끝나면 EOS_Auth_OnLogoutCallback 타입의 콜백 함수가 실행됩니다. EOS_Auth_LogoutOptions 구조체를 다음과 같이 초기화합니다.

인증 인터페이스 핸들, EOS_Auth_LogoutOptions 구조체, 콜백 함수를 EOS_Auth_Logout 에 전달합니다. EOS_HPlatform 핸들의 틱이 실행 중인 경우, 해당 작업이 끝난 후 아까 전달한 콜백이 실행됩니다.

EOS_LCT_PersistentAuth 로그인 타입을 사용한 경우 EOS_Auth_DeletePersistentAuth 함수도 호출해서 인증 백엔드의 장기 실행 로그온 세션을 철회해야 합니다. 이렇게 하면 로컬 디바이스의 로컬 사용자 로그인도 영구 삭제됩니다.

EOS SDK는 로컬 사용자의 인증 상태를 애플리케이션이 작동하는 동안 주기적으로 검증합니다. 이를 통해 사용자가 다른 곳에서 로그인하지는 않았는지 아니면 애플리케이션 외부 요인으로 인해 액세스가 끊어지지 않았는지를 확인할 수 있습니다. 사용자의 인증 상태가 변경될 때마다 애플리케이션에서 파악할 수 있도록 인증 인터페이스는 로컬 플레이어에게 이러한 상태 변경이 생길 때마다 EOS_Auth_OnLoginStatusChangedCallback 타입 콜백을 호출합니다. EOS_Auth_AddNotifyLoginStatusChanged 함수로 이 프로세스에 자체적인 콜백 함수를 어태치할 수 있습니다.

애플리케이션이 작동하는 동안 연결이 끊어졌다고 해서 사용자가 로그아웃했다는 의미는 아닙니다. 로그아웃 이벤트가 발생하면 EOS 백엔드는 인증 인터페이스에 이를 명시적으로 알리며, 오직 이 경우에만 사용자가 공식적으로 오프라인 상태라는 것을 안전하게 추정할 수 있습니다. 서비스 정지, 로컬 하드웨어 장애 등의 사용자 연결 문제는 다양한 API 기능이 정상 작동하지 못하게 만들 수 있습니다. 만약 이런 상호작용 없이도 게임을 계속 진행할 수 있다면 사용자를 로그아웃시키지 않은 상태에서 연결이 복구될 것이라는 추정하에 플레이를 계속 진행하는 것이 좋습니다.

플레이어의 현재 상태를 필요할 때마다 확인하려면 EOS_Auth_GetLoginStatus 함수를 사용합니다. 이 함수는 온라인 서비스와의 최근 커뮤니케이션을 토대로 인증 상태를 결정합니다. 따라서 결과가 즉시 반환되며 아무런 콜백 함수도 사용되지 않습니다.

외부 계정을 사용하여 EOS_Auth_Login 으로 로그인하려면 EOS_Auth_Credentials 의 Type 을 EOS_LCT_ExternalAuth 로 설정하고, ExternalType 을 외부 크리덴셜 타입으로 설정하며, Token 을 외부 인증 토큰으로 설정합니다. 사용 가능한 메서드의 전체 목록은 EOS_EExternalCredentialType 을 참고하세요. 예를 들어, Steam으로 로그인하려면 EOS_ECT_STEAM_SESSION_TICKET 을 ExternalType 으로 사용하고 Token 은 Steam 세션 티켓으로 설정합니다.

외부 계정이 연결되지 않아 외부 인증 로그인이 실패하면 EOS_InvalidUser 가 반환됩니다. EOS_ContinuanceToken 은 EOS_Auth_LoginCallbackInfo 데이터에서 설정됩니다. 외부 계정 로그인을 계속하고 외부 계정을 연결하려면 EOS_ContinuanceToken 및 LinkAccountFlags 를 EOS_LA_NoFlags 로 설정하여(대부분의 경우 계정 포털(Account Portal) 또는 PIN 부여(PIN Grant)를 통한 동의가 필요함) EOS_Auth_LinkAccount 를 호출해야 합니다. 그러면 외부 계정이 사용자의 에픽 계정에 연결됩니다.

외부 계정 인증을 사용하여 제공자를 연결하려면 개발자 포털에서 제품에 ID 제공자(Identity Providers) 를 구성해야 합니다. 자세한 내용은 ID 제공자 구성하기를 참고하세요.

게임에서 런처를 통해 추가 실행 옵션, 프로모션 또는 기타 뉴스를 포함하는 경우 런처에서 로그인 플로를 관리해야 합니다. 에픽게임즈 런처에서 생성된 교환 코드 는 유효 기간이 짧으므로 교환 코드가 만료되지 않도록 유의해야 합니다. 에픽게임즈 런처에서 게임 애플리케이션을 직접 실행하지 않는 경우 다음 패턴을 사용합니다.

1. 에픽게임즈 런처에서 서드 파티 런처를 시작하여 위의 에픽게임즈 런처와 연결하기 섹션에 설명된 대로 명령줄의 교환 코드를 전달합니다.
2. 서드 파티 런처에서 교환 코드를 사용하여 EOS_Auth_Login API를 통해 플레이어를 로그인시킵니다. EOS_Auth_ClientCredentials 구조의 Type 및 Token 필드를 각각 EOS_LCT_ExchangeCode 및 명령줄의 교환 코드로 설정하여 EOS_Auth_LoginOptions 를 초기화합니다.
3. 플레이어가 게임 실행을 선택하면, EOS_Auth_CopyUserAuthToken API를 사용하여 토큰 디테일의 사본을 얻습니다. EOS_Auth_Token 에서 RefreshToken 을 복사하고 EOS_Auth_Token_Release API를 호출하여 SDK에 의해 할당된 메모리를 해제합니다.
4. 시작 시 게임이 읽을 수 있는 환경 변수를 설정하여 새로고침 토큰을 게임 애플리케이션에 전달합니다. 새로고침 토큰이 무효화되므로 서드파티 런처 종료 시 서드 파티 런처에서 플레이어를 로그아웃시키지 마세요.
5. 게임 프로세스가 시작되면 게임에서 EOS_Auth_Login API를 사용하여 플레이어를 로그인시킬 수 있습니다. EOS_Auth_ClientCredentials 구조의 Type 및 Token 필드를 각각 EOS_LCT_RefreshToken 및 환경 변수의 새로고침 토큰으로 설정하여 EOS_Auth_LoginOptions 를 초기화합니다.

OpenID Connect 프로토콜의 일부인 ID 토큰(ID Token)은 서버 측의 사용자 ID를 검증하는 데 사용합니다. ID 토큰은 계정 ID 등 인증된 사용자에 대한 정보가 포함된 JSON 웹 토큰(JSON Web Token, JWT)입니다. 이를 통해 백엔드 서비스 및 게임 서버는 클라이언트로부터 받는 사용자 식별자를 안전하게 검증할 수 있습니다.

게임 클라이언트는 사용자가 로그인한 뒤 EOS_Auth_CopyIdToken SDK API를 호출하여 사용자의 EOS_EpicAccountId 가 포함된 EOS_Auth_CopyIdTokenOptions 구조를 전달함으로써 로컬 사용자의 ID 토큰을 획득할 수 있습니다.

출력된 EOS_Auth_IdToken 구조는 사용자의 EOS_EpicAccountId 와 ID 토큰 데이터를 나타내는 JWT를 포함합니다. 작업을 마친 뒤 ID 토큰 구조를 해제하려면 EOS_Auth_IdToken_Release 를 호출해야 한다는 점에 유의하세요.

ID 토큰을 얻은 후에는 게임 클라이언트가 다른 파티의 ID 토큰도 제공할 수 있습니다. ID 토큰은 로그인된 로컬 사용자가 항상 즉시 사용 가능합니다.

EOS 인증 ID 토큰의 JSON 웹 키 세트(JSON Web Key Set, JWKS) 엔드포인트는 다음과 같습니다. https://api.epicgames.dev/epic/oauth/v1/.well-known/jwks.json

게임 서버는 EOS_Auth_VerifyIdToken SDK API를 호출하고 EOS_Auth_IdToken 이 포함된 EOS_Auth_VerifyIdTokenOptions 를 전달하여 ID 토큰의 유효성을 검사할 수 있습니다. 게임 서버는 검증을 호출하기에 앞서 EOS_EpicAccountId_FromString 을 사용하여 EOS_Auth_IdToken 구조의 EOS_EpicAccountId 부분을 채워야 한다는 점에 유의하세요. 서버의 사용자 핸들은 클라이언트의 사용자 핸들과 다르기 때문입니다.

공개적으로 사용 가능한 표준 JWT 라이브러리를 이용하면 백엔드 서비스에서 ID 토큰의 유효성을 검증하고 토큰 클레임을 추출할 수 있습니다. https://jwt.io/에서 이 용도로 사용할 수 있는 라이브러리 목록을 확인하세요. 사용한 라이브러리는 최상의 퍼포먼스 및 네트워킹 오버헤드 감소를 위해 획득한 JWKS 정보의 자동 캐싱을 허용해야 합니다.

EOS SDK 및 기타 지원 라이브러리에서는 확보한 클레임에 대한 신뢰를 확보하기 전에 ID 토큰을 안전하게 검증하는 데 필요한 절차를 수행합니다. 수행 절차는 다음과 같습니다.

1. 토큰 시그니처 알고리즘('alg')이 존재하는지, '없음(none)'으로 설정되지는 않았는지 검증합니다.
2. 에픽 온라인 서비스에서 호스팅하는 JWKS 엔드포인트를 이용해 JWT 시그니처와 예상 공인인증서를 대조 검증합니다.
3. 토큰 발급자('iss')가 존재하는지, https://api.epicgames.dev의 기본 URL로 시작하는지 검증합니다.
4. 토큰 발급 시간('iat')이 과거인지 검증합니다.
5. 토큰 만료 시간('exp')이 미래인지 검증합니다.
6. 게임 클라이언트로 EOS SDK를 초기화하거나 에픽 계정 서비스로 사용자를 인증하는 데 사용할 클라이언트 ID와 클라이언트 ID('aud')가 일치하는지 검증합니다.

ID 토큰을 성공적으로 검증한 뒤에는 에픽 계정 ID('sub') 값을 신뢰할 수 있습니다.

ID 토큰에는 다음 JSON 구조가 포함됩니다.

헤더

페이로드

각주

1. 연결된 외부 계정에 관한 자세한 내용은 인증 인터페이스 문서를 참고하세요. ↩

2. ID 제공자에 관한 자세한 내용은 ID 제공자 관리 문서를 참고하세요. ↩

3. 친구 인터페이스 사용에 관한 자세한 내용은 친구 인터페이스 문서를 참고하세요. ↩

4. 현재상태 인터페이스 사용에 관한 자세한 내용은 현재상태 인터페이스 문서를 참고하세요. ↩

5. Ecom 인터페이스 사용에 관한 자세한 내용은 Ecom 인터페이스 문서를 참고하세요. ↩

6. EOS 소셜 오버레이에 관한 자세한 내용은 소셜 오버레이 개요 문서를 참고하세요. ↩

7. EOS_Platform_Tick 호출에 관한 자세한 내용은 API 레퍼런스 문서를 참고하세요. ↩

8. 만료 알림 이벤트에 관한 자세한 내용은 연결 인터페이스 문서를 참고하세요. ↩