Connect Interface

연결 인터페이스를 사용하면 플레이어가 지원되는 ID 제공자를 통해 게임에 로그인할 수 있습니다. ID 제공자 및 구성에 대한 자세한 내용은 ID 제공자 관리 문서를 참고하세요.

연결 인터페이스에서는 다음 서비스를 제공합니다.

• 에픽 온라인 서비스(EOS) 게임 서비스 액세스
• 크로스 플랫폼 서비스에 걸쳐 고유한 공통 사용자 ID 생성
• 에픽 서비스에 외부 ID 제공자 계정 연동

플레이어는 하나 이상의 외부 사용자 계정을 고유한 플레이어 ID인 제품 사용자 ID(PUID)와 연결할 수 있습니다. 이 제품 사용자 ID는 동일한 조직 내 각각의 제품에 대한 고유 ID입니다.

또한 인증 인터페이스를 사용하면 플레이어가 게임에서 직접 에픽게임즈 계정으로 로그인할 수 있습니다. 인증 인터페이스 사용에 관한 자세한 내용은 인증 인터페이스 문서를 참고하세요. 인증 인터페이스와 연결 인터페이스 간의 차이점은 아래 표에서 확인할 수 있습니다.

사용자는 외부 크리덴셜 세트를 사용하여 로그인합니다. 이 제품에 사용자가 이미 존재한다면, 일정 시간 동안 유지되는 액세스 토큰 이 부여됩니다. 현재 토큰의 지속시간은 1시간입니다. 토큰이 만료되기 전에 게임에 알려주며 이때 유효한 외부 크리덴셜이 있다면 기존 토큰을 갱신해야 합니다.

에픽 온라인 서비스 인터페이스는 외부 제공자의 액세스 권한을 제어할 수 없습니다. 따라서 연결 인터페이스 는

다음을 수행합니다.

• 외부 계정 제공자에서 사용자가 여전히 유효한지 검증
• 사용자가 에픽 서비스에 액세스할 수 있는 시간 연장

다음은 제공하지 않습니다.

• 묵시적으로 토큰 갱신
• 장기간 액세스 허가

외부 계정 제공자는 애플리케이션에 대한 권한 액세스가 주어지게 됩니다.

이 사용자 ID로 이용할 수 있는 서비스에 액세스하려면 EOS_ProductUserId 데이터 구조를 통한 외부 계정 식별이 필요합니다. 모든 인터페이스는 이 용법을 명확하게 나타내며, 타입 안전이 보장되어야 합니다. 이는 에픽 계정 서비스용으로 제공된 인증 인터페이스에 연결된 EOS_EpicAccountId 와는 별개입니다.

EOS 연결로 인증하려면 다음 단계를 따릅니다.

1. 지원되는 플랫폼으로부터 외부 크리덴셜이 포함된 EOS_Connect_LoginOptions 를 사용하여 EOS_Connect_Login 을 호출합니다. 지원되는 ID 제공자(예: Steam, Xbox 또는 Nintendo)로 로그인할 수 있습니다. 지원되는 ID 제공자 전체 목록은 ID 제공자 관리 문서를 참조하세요. 예를 들어 에픽게임즈 계정으로 인증하려면 로컬 에픽 사용자를 위한 ID 토큰을 EOS_Auth_CopyIdToken 에서 얻은 후 EOS_EExternalCredentialType 을 EOS_ECT_EPIC_ID_TOKEN 으로 설정합니다.

2. EOS_HConnect 핸들, EOS_Connect_LoginOptions 구조, 콜백 정보를 함수에 전달합니다.

인증 후에는 다음과 같은 추가 동작이 발생할 수 있습니다.

• EOS_HPlatform 핸들의 틱이 실행 중인 경우, 해당 작업이 끝난 후에 전달한 콜백이 실행됩니다.
• 성공적인 결과가 나온 후, 애플리케이션에서 인증이 필요한 추가적인 인터페이스에 계속 액세스할 수 있습니다.
• 사용자가 존재하지 않는 경우, 로그인 API는 EOS_ContinuanceToken 과 함께 EOS_InvalidUser 결과를 반환합니다. 해당 토큰은 로그인 시도에 대한 디테일을 제공하며, 로그인 플로의 이후 단계에서 필요합니다.

EOS_Connect_AddNotifyAuthExpiration 에 제공된 콜백 함수는 기존 액세스 토큰이 곧 만료될 때가 되면 실행됩니다. 이를 통해 애플리케이션에서 외부 액세스 토큰을 획득하고 EOS_Connect_Login 함수를 통해 SDK에 매번 토큰을 제공할 충분한 시간을 마련할 수 있습니다.

EOS_Connect_RemoveNotifyAuthExpiration 함수를 사용하면 이러한 알림 수신을 중지할 수 있습니다.

사용자의 인증 상태가 변할 때마다 애플리케이션에서 파악할 수 있도록 연결 인터페이스는 이런 알림에 대한 콜백을 제공합니다.

EOS_Connect_AddNotifyUserLoginStatusChanged 에 제공한 콜백 함수는 로컬 사용자의 인증 상태가 변할 때마다 실행됩니다. 이는 만료 알림이 무시되거나 외부 제공자 크리덴셜이 해당 액세스 토큰을 갱신할 수 없거나, 관리상의 이유로 백엔드 서비스에서 액세스를 명시적으로 해지한 경우에만 발생합니다. 이 콜백은 EOS 생태계의 다른 호출에서 이 인증 토큰이 무효하다는 것을 탐지한 경우에만 발생합니다. 그 이외의 경우에는 자동으로 발생하지 않습니다.

인증으로 인해 실패할 수도 있는 특정 호출의 모든 오류 메시지를 처리해야 합니다. 대개 EOS_Connect_Login 을 호출한 후 성공 시 원래 호출을 재시도하는 방법으로 복구할 수 있습니다.

EOS_Connect_RemoveNotifyUserLoginStatusChanged 함수를 사용하면 알림 수신을 중지할 수 있습니다.

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

로그인할 때 외부 크리덴셜을 사용한 경우 사용자를 생성하면 사용자를 위한 새로운 제품 사용자 ID 가 생성됩니다. 신규 사용자를 생성하기 전에 사용자에게 항상 메시지를 띄워 다른 로그인 방법이 있는지 확인해야 합니다. 그러면 혼란이 줄고 크로스 플랫폼 상황에서 사용자 게임 진행상황 병합 문제가 줄어듭니다.

애플리케이션에서 사용자의 새로운 제품 사용자 ID를 생성하려는 경우, 이전 호출 EOS_Connect_Login 의 EOS_ContinuanceToken 이 포함된 EOS_Connect_CreateUserOptions 를 사용하여 EOS_Connect_CreateUser 를 호출합니다.

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

애플리케이션 로그인 플로 중에 사용자가 보조 외부 크리덴셜 세트로 로그인할 수 있다고 판단되면, 첫 번째 로그인 호출의 EOS_ContinuanceToken 을 저장하고 EOS_Connect_Login 을 통해 로그인을 다시 시도하고, 로그인에 성공하면 즉시 EOS_Connect_LinkAccount 를 호출합니다. 이렇게 하면 외부 계정 2개가 제품 사용자 ID 1개와 연결됩니다. 당사 서비스 기능이 확대되면 둘 이상의 계정을 연결할 수도 있습니다.

애플리케이션의 목적이 새로운 외부 계정을 기존 제품 사용자 ID에 연결하는 것이라면, EOS_Connect_Login 을 호출하여 로그인된 사용자의 제품 사용자 ID 및 이전 호출 EOS_Connect_Login 의 EOS_ContinuanceToken 이 포함된 EOS_Connect_LinkAccountOptions 를 사용하여 EOS_Connect_LinkAccount 를 호출합니다.

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

외부 계정 ID 또는 개발자 포털 내의 계정 대시보드를 통한 제품 사용자 ID를 사용하여 EOS 연결 사용자를 검색할 수 있습니다. 플레이어의 연결된 외부 계정은 조직 수준에서 관리되므로 계정 대시보드는 조직 관리 메뉴 항목 옆에서 찾을 수 있습니다. 계정 대시보드를 통해 플레이어를 찾거나 플레이어의 요청에 따라 고객 지원에서 계정 연결 제거를 도울 수 있습니다. 이 대시보드를 사용하여 EOS 연결 사용자 또는 SDK 통합 테스팅 중에 연결된 모든 계정을 제거할 수 있습니다. 이와 함께 EOS 사용자 관리를 기존 내부 대시보드에 통합할 수 있는 개발자용 웹 REST API를 제공할 예정입니다.

최초 사용자 로그인 플로 도중 사용자가 다른 플랫폼 또는 다른 외부 계정 크리덴셜에서 플레이하던 기존 게임 진행상황을 재사용하는 대신, 의도치 않게 로그인된 계정(보통 로컬 플랫폼 계정)을 위한 새 제품 사용자 ID를 생성했을 수도 있습니다. 사용자는 게임의 크로스 플레이 기능을 모를 수도 있습니다.

이 경우 사용자는 초기 로그인 대화 박스를 건너뛰고 자신의 디폴트 플랫폼 계정 크리덴셜(로그인된 계정)로 진행하여 EOS_Connect_Login 및 EOS_Connect_CreateUser API의 플로를 통해 새 EOS_ProductUserId 를 생성합니다. 그 결과 게임 시작 시 EOS_Connect_Login 에서 사용하는 사용자의 로그인된 계정은 의도치 않은 제품 사용자 ID와 연결됩니다. 이 상태에서 회복하려면 사용자는 로그인된 계정을 새로 생성된 키체인과 연결 해제하여 최초 사용자 로그인 플로에 다시 들어가야 합니다.

로그인된 계정을 연결 해제하면 다른 기존 키체인과 연결된 다른 외부 계정 크리덴셜 세트를 사용하여 로그인할 수 있습니다. 이 방법이 성공하면 위 외부 계정 연결하기 섹션에서 설명한 플로를 사용하여 디폴트 로그인 계정을 원하는 기존 키체인과 연결할 수 있습니다.

또는 사용자가 로그인된 계정을 현재 키체인과 연결 해제하여 플랫폼 간의 게임 진행상황을 분리하거나 다른 키체인과 연결하기를 원할 수도 있습니다.

외부 계정과 현재 로그인된 제품 사용자 ID를 소유하는 키체인과의 연결을 해제하려면 EOS_Connect_UnlinkAccount 을 EOS_Connect_UnlinkAccountOptions 로 호출하고 LocalUserId 를 이전 EOS_Connect_Login 호출에 의해 반환된 EOS_ProductUserId 로 지정합니다. 작업이 성공적으로 완료되면 외부 계정과 모든 키체인 간의 연결이 제거됩니다. 따라서 다음번에 동일한 외부 계정과 연결된 크리덴셜을 사용하여 EOS_Connect_Login 으로 로그인을 시도하면 EOS_InvalidUser 결과가 EOS_ContinuanceToken 과 함께 반환됩니다.

계정 연결 생성 작업과 마찬가지로, 연결 해제 작업의 히스토리 또한 개발자 포털의 계정 대시보드에서 심사할 수 있습니다.

계정 탈취를 막기 위해 키체인에서의 계정 연결 해제는 오직 로컬 사용자가 현재 로그인한 계정에 대해서만 가능합니다. 이는 악성 액터가 연결된 계정 중 하나에 대한 액세스를 얻고 이를 사용하여 키체인에 연결된 다른 계정을 모두 제거하지 않도록 방지하기 위함입니다. 연결 해제 작업은 키체인 내 다른 연결된 계정 중 하나로 인증하지 않으면 모든 기존 인증 세션이 엔트리를 다시 연결하거나 덮어쓰지 못하게 제한해 악성 액터가 연결 해제된 계정을 동일한 플랫폼 내 자신의 해당 계정으로 대체하는 것을 방지하기도 합니다.

이러한 제한은 계정 탈취 시나리오와 관련하여 잠재적인 문제를 억제하기 위해 설정되었습니다.

애플리케이션에서 판단하기에 사용자가 아직 신규 계정을 생성하거나 기존 계정을 연결할 만큼 확고하지 않은 경우 애플리케이션에서 EOS 연결 디바이스 ID(EOS Connect Device ID) 기능을 사용하여 새 영구 가계정(pseudo-account)을 생성할 수 있습니다. 이 기능은 애플리케이션에서 외부 로그인 크리덴셜을 사용하지 않고 로컬 사용자의 영구적인 액세스 크리덴셜을 생성할 수 있게 해줍니다. 이를 통해 백엔드 서비스에서는 여러 게임 세션에 걸쳐 로컬 디바이스에서 현재 사용자를 기억할 수 있습니다. 디바이스 ID 기능은 특히 개인 모바일 디바이스에서 계정 크리덴셜을 묻지 않고 자동으로 사용자를 로그인시키고, 게임 진행상황 데이터를 유지하기 위해 사용자 로그인을 즉시 요구하지 않고도 바로 게임 플레이를 시작할 수 있게 해주는 데 사용됩니다.

하지만 디바이스 ID는 실제 사용자 계정과 연결되지 않으며 유일하게 로컬 디바이스 식별에만 사용 가능하기 때문에, 사용자의 진행상황이 어느 정도 게임 초반부를 넘어섰다면 크리덴셜과 계정을 잃는 일이 없도록 외부 인증 방법을 사용자의 디바이스 ID 계정과 연결하도록 요청하는 것이 좋습니다.

디바이스 ID 계정을 실제 사용자 ID와 연결하지 않으면 결국 디바이스 자체에 문제가 발생할 경우 모든 진행상황과 게임 데이터를 영구적으로 잃어버리게 됩니다. EOS SDK는 디바이스 ID 크리덴셜을 현재 로컬 디바이스에 로그인된 사용자의 키체인에 로컬로 저장합니다. 로컬 사용자 프로필이 리셋되거나 기타 이유로 프로필을 잃게 되면, 잃어버린 디바이스 ID는 더 이상 복구할 수 없습니다.

새로운 디바이스 ID를 생성하려면, 애플리케이션은 사용자의 DeviceModel이 포함된 유효한 EOS_Connect_CreateDeviceIdOptions 구조를 사용하여 EOS_Connect_CreateDeviceId 함수를 호출해야 합니다. 이 호출은 결국 EOS_Connect_OnCreateDeviceIdCallback 에 바인딩된 함수 콜백을 트리거합니다. 새로운 디바이스 ID가 생성되어 로컬 디바이스에 로그인된 사용자의 키체인에 저장된 경우, 콜백 파라미터에 있는 ResultCode 파라미터가 EOS_EResult::EOS_Success 로 설정됩니다. 기존 디바이스 ID가 존재하는 경우, EOS_EResult::EOS_DuplicateNotAllowed 가 반환됩니다. 그렇지 않으면 ResultCode 파라미터가 작업 실패 원인을 식별합니다.

고유 디바이스 ID로 로컬 사용자를 로그인시키려면 EOS_EExternalCredentialType::EOS_ECT_DEVICEID_ACCESS_TOKEN 외부 크리덴셜 유형으로 EOS_Connect_Login API를 호출합니다. 저장된 디바이스 ID 크리덴셜을 SDK에서 자동으로 관리하므로 입력 EOS_Connect_Credentials 구조체의 Token 파라미터는 NULL로 설정되어야 합니다. 하지만 디바이스 ID가 실제 사용자 ID와 연결되지 않으므로 EOS_Connect_UserLoginInfo 입력 구조체는 유효한 사용자 DisplayName과 함께 제공되어야 합니다.

디바이스 ID를 실제 외부 사용자 계정과 연결하려면 먼저 디바이스 ID 크리덴셜 유형을 사용하여 게임에서 로컬 사용자를 정상적으로 로그인시키도록 합니다. 그런 다음, 사용자에게 실제 ID로 로그인하도록 요청하고 ContinuanceToken 과 함께 EOS_Connect_Login 을 다시 반환한 후, EOS_Connect_Link API로 외부 계정과 연결하여 로컬 디바이스를 사용자의 실제 계정과 연결합니다. 그러면 게임을 시작할 때마다 사용자가 자동으로 로그인됩니다. 이는 외부 사용자 계정 크리덴셜을 묻지 않고 여전히 디바이스 ID를 원래 목적대로 사용자를 자동 로그인하도록 사용할 수 있기 때문입니다.

EOS_Connect_DeleteDeviceId API를 호출하여 로컬 디바이스의 현재 사용자 프로필에서 디바이스 ID를 삭제할 수도 있습니다. 디바이스 ID 삭제 작업은 영구적이며 되돌릴 수 없는 작업입니다. 하지만 언제든지 새로운 디바이스 ID를 생성하고 이를 기존 외부 사용자 계정에 연결해 자동 로그인 기능을 복원할 수 있습니다.

Android 및 iOS 디바이스의 경우, 설치된 애플리케이션을 제거하면 해당 애플리케이션이 생성한 모든 로컬 디바이스 ID 크리덴셜이 자동으로 삭제됩니다.

그러나 데스크톱 플랫폼(Linux, macOS, Windows)의 경우, 디바이스 ID 크리덴셜이 자동으로 삭제되지 않습니다. 애플리케이션이 재설치되었다면 로컬 OS 사용자의 기존 디바이스 ID 크리덴셜을 재사용할 수 있습니다. 애플리케이션이 처음 실행되었다면 사용자가 확실히 초기 상태로 사용을 시작하도록 EOS_Connect_DeleteDeviceId API를 호출할 수 있습니다.

일반적인 방법으로 디바이스 ID 가계정과 실제 외부 사용자 계정을 연결할 수 없는 엣지 케이스가 있습니다. 이 경우 로그인된 실제 사용자 계정은 이미 동일한 EOS 조직하의 기존 키체인에 속해 있습니다. 이때 게임이 로컬 디바이스 ID 로그인 유형을 사용하여 사용자를 우선 자동으로 로그인하게 한 다음, 사용자가 실제 외부 사용자 계정 크리덴셜로 로그인하면 EOS_Connect_Login API가 EOS_ContinuanceToken 대신 기존 EOS_ProductUserId 를 반환합니다. 이런 시나리오를 처리하기 위해 EOS_Connect_TransferDeviceIdAccount API가 사용됩니다.

EOS_Connect_Link API가 EOS_ContinuanceToken 사용을 요구하기 때문에 디바이스 ID 가계정은 기존 키체인과 연결될 수 없습니다. 또한 이제 플레이어는 두 개의 분리된 EOS_ProductUserIds 를 가지게 되므로 두 EOS_ProductUserIds (즉 게임 프로파일) 중 하나를 구버전으로 간주하여 버리고 나머지 하나로 게임을 진행할 것인지 선택하게 됩니다. 만약 플레이어가 프로파일 하나를 버릴 경우 게임은 로컬 디바이스 ID 계정을 백엔드에서 지속되는 연결된 계정의 기존 키체인에 연결할 수 있습니다.

두 개의 EOS_ProductUserIds 가 있는 시나리오를 해결하려면 로컬 사용자가 게임에서 디바이스 ID 로그인 유형으로 로그인한 때와 동일한 게임 세션에서 외부 계정을 사용하여 로그인해 그에 대해 다른 EOS_ProductUserId 세션을 받는 때를 구분해야 합니다. 이렇게 되면 게임에서 EOS_ProductUserIds 중 하나가 백엔드에 의미 있는 게임 진행상황을 가졌는지 자동으로 확인을 시도합니다. 의미 있는 게임 진행상황이 없는 경우 게임은 이를 버리고 로컬 디바이스 ID 가계정을 실제 외부 사용자 계정의 기존 키체인과 연결합니다.

게임이 이 사소한 사례를 사용자 대신 자동화할 수 있다고 판단하지 못하는 경우 사용자에게 진행 방법을 선택하는 창을 표시해야 합니다. 이 선택 대화 박스에서 플레이어는 각 EOS_ProductUserId 를 비교하여 게임 진행상황을 검토하고 어느 쪽을 유지할지 선택할 수 있어야 합니다. 게임 진행상황이 영원히 사라지며 이후 복구가 불가능하다는 점을 사용자에게 아주 명확하게 고지해야 합니다. 게임에서 사용자에게 프로파일을 모두 유지하면서 현재 게임 세션에서 플레이를 계속할 프로파일을 선택하게 할 수도 있습니다.

만약 사용자가 게임 프로파일 하나를 버리고 다른 프로파일로 영구 전환할 경우 게임에서 EOS_Connect_TransferDeviceIdAccount API를 호출하여 로컬 디바이스 ID 가계정을 실제 외부 사용자 계정과 연결된 키체인으로 이전해야 합니다. 이 API에서 EOS_Connect_TransferDeviceIdAccountOptions 구조체를 입력하고 ProductUserIdToPreserve 파라미터가 디바이스 ID 이전 작업에서 보존할 알맞은 EOS_ProductUserId 값을 가리키도록 설정합니다.

다른 인터페이스는 원격 사용자나 외부 사용자(예: 같은 서버에 있는 플레이어나 친구 목록 등)를 위해 EOS_ProductUserId 를 예상합니다. 매핑 API를 통해 외부 사용자 계정 식별자를 EOS_ProductUserId 로 변환할 수 있습니다.

EOS_Connect_QueryExternalAccountMappings 는 외부 계정 ID를 SDK 표현으로 변환하는 비동기 호출입니다. 단순히 EOS_EExternalAccountType 을 설정하고 인접한 외부 계정 ID 목록을 문자열 형식으로 제공합니다.

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

콜백 반환에 성공하면 EOS_Connect_GetExternalAccountMapping 을 통해 매핑을 얻을 수 있습니다. 이 함수는 전과 마찬가지로 EOS_EExternalAccountType 을 가져오고, 외부 계정 ID를 문자열 형식으로 제공하는 호출마다 단일 EOS_ProductUserId 를 반환합니다.

외부 계정으로 제품 사용자 ID를 얻을 수 있는 것처럼, 제품 사용자 ID로 외부 계정을 얻을 수도 있습니다.

EOS_Connect_QueryProductUserIdMappings 는 비동기 호출로, 표시 이름과 마지막 로그인 시간을 포함하는 추가적인 계정 데이터와 함께 EOS_ProductUserIds 를 지정된 플랫폼의 외부 대응 항목으로 변환합니다. 인접한 제품 사용자 ID 목록을 제공하기만 하면 됩니다.

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

콜백 반환에 성공하면 EOS_Connect_GetProductUserIdMapping 을 통해

매핑을 가져올 수 있습니다. 이 함수는 EOS_EExternalAccountType , 입력 버퍼, 버퍼 길이를 가져와 외부 계정 ID로 채웁니다. 버퍼가 너무 작으면 적절한 크기의 버퍼가 반환됩니다.

제품 사용자의 연결된 외부 계정 수를 얻으려면 EOS_Connect_GetProductUserExternalAccountCount 를 사용합니다.

인덱스를 사용하여 제품 사용자와 연결된 외부 계정 정보를 가져오려면 EOS_Connect_CopyProductUserExternalAccountByIndex 를 사용합니다.

제품 사용자와 연결된 특정 유형의 외부 계정 정보를 가져오려면 EOS_Connect_CopyProductUserExternalAccountByAccountType 을 사용합니다.

계정 ID를 사용하여 제품 사용자와 연결된 외부 계정 정보를 가져오려면 EOS_Connect_CopyProductUserExternalAccountByAccountId 를 사용합니다.

가장 최근에 로그인한 외부 계정을 레퍼런스로 사용하여 제품 사용자에 대한 정보를 가져오려면 EOS_Connect_CopyProductUserInfo 를 사용합니다.

제품 사용자 ID가 지정된 외부 플랫폼에 매핑되지 않으면 위에 반환된 결과에 해당 데이터가 나타나지 않습니다. 즉, 사용자가 해당 외부 계정 유형을 자신의 제품 사용자 ID에 연결한 적이 없다는 뜻이 됩니다.

OpenID Connect 프로토콜의 일부인 ID 토큰(ID Token)은 서버 측의 사용자 ID를 검증하는 데 사용합니다. ID 토큰은 제품 사용자 ID처럼 인증된 사용자의 정보가 담긴 JSON 웹 토큰(JWT)입니다. ID 토큰을 사용하면 백엔드 서비스 및 게임 서버에서 클라이언트로부터 받은 사용자 식별자를 안전하게 검증할 수 있습니다.

게임 클라이언트는 로컬 사용자의 ID 토큰을 가져올 수 있습니다. 사용자가 EOS 연결로 로그인한 뒤 EOS_Connect_CopyIdToken SDK API를 호출하여 사용자의 EOS_ProductUserId 를 포함하는 EOS_Connect_CopyIdTokenOptions 구조를 전달하는 식입니다.

출력한 EOS_Connect_IdToken 구조에는 사용자의 EOS_ProductUserId 와 ID 토큰 데이터를 나타내는 JWT가 있습니다. 참고로 관련 작업이 끝난 뒤 ID 토큰 구조를 해제하려면 EOS_Connect_IdToken_Release 를 호출해야 합니다.

ID 토큰을 얻은 후에는 게임 클라이언트가 다른 파티의 ID 토큰도 제공할 수 있습니다. EOS_Connect_Login 호출에 성공할 때마다 새 ID 토큰이 제공됩니다.

이 ID 토큰은 로컬 사용자의 EOS 연결 인증 세션 수명 동안 유효합니다. 게임 클라이언트에서 인증 세션을 새로고침할 경우 이전에 사용한 ID 토큰은 곧 만료되며, 필요에 따라 새 ID 토큰을 사용합니다.

EOS 연결 ID 토큰에 사용할 JSON 웹 키 세트(JWKS)의 엔드포인트는 다음과 같습니다. https://api.epicgames.dev/auth/v1/oauth/jwks

게임 서버에서 ID 토큰의 유효성을 검사할 수 있습니다. EOS_Connect_VerifyIdToken SDK API를 호출한 뒤, EOS_Connect_IdToken 을 포함하는 EOS_Connect_VerifyIdTokenOptions 를 전달하는 식입니다. 참고로 게임 서버의 사용자 핸들은 클라이언트의 사용자 핸들에 따라 달라질 수 있으므로, 검증을 호출하기 전에 EOS_ProductUserId_FromString 을 사용해 EOS_Connect_IdToken 구조 중 EOS_ProductUserId 부분을 채워야 합니다.

공개적으로 사용 가능한 표준 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. 클라이언트 ID('aud')가 게임 클라이언트를 이용한 EOS SDK 초기화나 EOS 연결 서비스의 사용자 인증에 사용하는 클라이언트 ID와 일치하는지 검증합니다.

ID 토큰 검증에 성공한 경우, 제품 사용자 ID('sub') 값을 신뢰할 수 있습니다.

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

헤더

페이로드

각주

1. 연결된 외부 계정에 관해 자세히 알아보려면 인증 인터페이스 문서를 참고하세요. ↩

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

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

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

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

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

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

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