온라인 서비스 인증 인터페이스(Online Services Auth Interface) 는 온라인 서비스로 로컬 사용자를 인증하고 검증하는 API를 제공합니다. 로컬 사용자가 인증되면 프로젝트에서 많은 다른 온라인 서비스 기능과 상호작용하는 데 사용할 수 있는 계정 ID를 반환합니다.
API 개요
함수
다음 테이블에서는 인증 인터페이스에 포함된 함수에 대한 개괄적 설명을 확인할 수 있습니다.
| 함수 | 설명 |
|---|---|
Login |
로컬 사용자를 인증합니다. |
Logout |
로컬 사용자의 인증 세션을 종료합니다. |
ModifyAccountAttributes |
인증된 계정과 연관된 어트리뷰트를 수정합니다. |
QueryExternalServerAuthTicket |
로그인한 사용자 대신 서버 간 호출을 수행하기 위해 티켓을 쿼리합니다. 티켓은 일회용입니다. 사용자는 티켓이 필요한 호출을 반복할 때 새 티켓을 얻기 위해 다시 API를 호출해야 합니다. |
QueryExternalAuthToken |
서비스 계정을 다른 서비스 타입의 서비스 계정과 연동하기 위해 토큰을 가져옵니다. |
QueryVerifiedAuthTicket |
원격 클라이언트에 검증된 인증 세션을 생성하기 위해 티켓을 가져옵니다. |
CancelVerifiedAuthTicket |
검증된 인증 세션과 연관된 티켓을 취소하고 해당 티켓과 연관된 모든 리소스를 클린업합니다. |
| 세션 | |
BeginVerifiedAuthSession |
원격 사용자를 위한 검증된 인증 세션을 시작합니다. |
EndVerifiedAuthSession |
원격 검증된 인증 세션과 모든 연관된 리소스를 클린업합니다. |
| 사용자 얻기 | |
GetLocalOnlineUserByOnlineAccountId |
온라인 계정 ID를 사용하여 로그인한 사용자 계정을 가져옵니다. |
GetLocalOnlineUserByPlatformUserId |
플랫폼 사용자 ID를 사용하여 로그인한 사용자 계정을 가져옵니다. |
GetAllLocalOnlineUsers |
모든 로그인한 사용자 계정을 가져옵니다. |
| 이벤트 리스닝 | |
OnLoginStatusChanged |
사용자 로그인 상태가 변경되면 이벤트가 트리거됩니다. |
OnPendingAuthExpiration |
인증 토큰이 곧 만료되면 이벤트가 트리거됩니다. |
OnAccountAttributesChanged |
인증된 계정과 연관된 추가 어트리뷰트가 변경되면 이벤트가 트리거됩니다. |
| 헬퍼 | |
IsLoggedIn |
로컬 사용자의 로그인 상태를 쿼리합니다. |
열거형 클래스
인증 인터페이스는 사용자의 로그인 상태와 인증 티켓 대상자, 인증 토큰 메서드를 나타내는 세 개의 열거형 클래스를 정의합니다.
ELoginStatus
| 열거자 | 설명 |
|---|---|
NotLoggedIn |
플레이어가 로그인하지 않았거나 로컬 프로필을 선택했습니다. |
UsingLocalProfile |
플레이어가 로컬 프로필을 사용하고 있지만, 로그인하지는 않았습니다. |
LoggedInReducedFunctionality |
플레이어가 로그인했지만, 온라인 서비스로 함수 기능이 감소했을 수 있습니다. |
LoggedIn |
플레이어가 로그인했고 플랫폼 전용 인증 서비스로 검증되었습니다. |
ERemoteAuthTicketAudience
| 열거자 | 설명 |
|---|---|
Peer |
피어 검증에 적합한 티켓을 생성합니다. |
DedicatedServer |
데디케이티드 서버 검증에 적합한 티켓을 생성합니다. |
EExternalAuthTokenMethod
| 열거자 | 설명 |
|---|---|
Primary |
인증 인터페이스에서 제공하는 주 메서드를 사용하여 외부 인증 토큰을 획득합니다. |
Primary |
인증 인터페이스에서 제공하는 보조 메서드를 사용하여 외부 인증 토큰을 획득합니다. |
프라이머리 구조체
FAccountInfo
| 멤버 | 타입 | 설명 |
|---|---|---|
AccountId |
FAccountId |
이 사용자의 계정 ID입니다. 사용자의 온라인 플랫폼 계정을 나타냅니다. |
PlatformUserId |
FPlatformUserId |
이 온라인 사용자와 연관된 플랫폼 사용자 ID입니다. |
LoginStatus |
ELoginStatus |
이 현재 사용자의 로그인 상태입니다. |
Attributes |
TMap<FSchemaAttributeId, FSchemaVariant> |
추가 계정 어트리뷰트입니다. |
프로세스 흐름
로그인하기
Login 은 선택한 온라인 서비스로 로컬 사용자를 인증합니다. 성공 시, Login 은 FAccountInfo 구조체를 반환합니다. FAccountInfo 구조체에는 인증 인터페이스에 포함된 다른 많은 함수를 사용하는 데 필요한 FAccountId 가 포함되어 있습니다. 로그인에 성공하면 사용자의 LoginStatus 도 ELoginStatus::LoggedIn 으로 설정됩니다. 사용자가 자신의 계정으로 로그인한 후에는 다른 조건에 따라 상태가 ELoginStatus::UsingLocalProfile 또는 ELoginStatus::LoggedInReducedFunctionality 로 변경될 수 있습니다.
로그인이 필요한 로컬 사용자가 여러 명인 경우, 각 사용자는 개별적으로 로그인해야 합니다. 또한, 명시적인 로그인이 필요 없는 플랫폼 서비스도 있습니다. 이러한 서비스에서 사용자나 사용자들은 애플리케이션 시작 시 암시적으로 로그인됩니다. 자세한 내용은 구체적인 플랫폼 서비스 문서를 참조하세요.
외부 서버로 인증하기
게임에는 게임 전용 함수 기능을 제공하는 커스텀 웹 서비스가 있는 경우가 종종 있습니다. 이러한 서비스는 액세스를 제공하기 전에 호출자의 ID를 검증해야 합니다. QueryExternalServerAuthTicket 은 외부 서버로 사용자를 인증하기 위한 일회용 티켓을 얻습니다.
인증된 사용자와 다른 온라인 서비스 연결하기
둘 이상의 온라인 서비스를 사용해야 하는 게임이 많이 있습니다. 일반적인 예로는 첫 번째 함수 기능을 확장하는 또 다른 서비스와 결합된 플랫폼 서비스 등이 있습니다. QueryExternalAuthToken 은 사용자가 보조 서비스를 위한 별도의 로그인 크리덴셜을 제공할 필요가 없도록 다른 온라인 서비스로 인증하는 데 적합한 토큰을 반환합니다.
대부분의 플랫폼에서 이 토큰은 사용자 ID를 보장하는 OpenId 토큰입니다. 그런 다음 CredentialsType 이 ExternalAuth 로 설정되고 이 토큰이 CredentialsToken 으로 전달되면서 보조 서비스의 로그인 메서드에 이 토큰이 제공됩니다.
P2P 또는 데디케이티드 서버로 사용자 ID 검증하기
사용자는 게임 서버 또는 P2P 네트워크에 연결할 때 자신이 ID를 증명하고 인증 세션 트래킹을 허용해야 합니다. 클라이언트 측에서는 QueryVerifiedAuthTicket 이 게임 서버로 전송할 일회용 티켓을 얻어 사용자 ID를 증명합니다. CancelVerifiedAuthTicket 은 게임 서버의 플레이 세션이 종료되면 이 티켓을 취소합니다.
QueryVerifiedAuthTicket 을 호출하여 획득한 티켓은 일회용이므로 사용자가 새로 검증된 인증 세션을 시작할 때마다 QueryVerifiedAuthTicket 을 호출해야 합니다. CancelVerifiedAuthTicket 에도 같은 로직이 적용됩니다. 사용자가 생성한 모든 티켓에 대해 CancelVerifiedAuthTicket 을 호출해야 합니다.
클라이언트가 연결되면 게임 서버는 클라이언트가 제공한 티켓으로 BeginVerifiedAuthSession 을 호출합니다. 호출이 성공적으로 완료되면 제공된 티켓과 연관된 사용자의 검증된 인증 세션이 시작됩니다. 게임이 종료되면 EndVerifiedAuthSession 이 연관된 리소스를 정리합니다.
원격 게임 서버에 연결하는 사용자 클라이언트에 대한 이 프로세스는 다음과 같이 요약됩니다.
- 클라이언트가
QueryVerifiedAuthTicket을 호출하여 세션 인증 티켓을 획득합니다. - 클라이언트가 세션 인증 티켓과 해당 티켓 ID, 해당 계정 ID를 서버에 전송합니다.
- 서버에서 이 정보를 수신하고 이 정보로
BeginVerifiedAuthSession을 호출하여 검증된 인증 세션을 시작합니다. - 세션 종료 시, 클라이언트는
CancelVerifiedAuthTicket으로 인증 티켓을 취소하고 서버는EndVerifiedAuthSession으로 인증 세션을 종료합니다.
P2P 모델에서는 위의 프로세스가 다릅니다. 각 사용자 클라이언트는 연결 중인 각 원격 클라이언트에 대해 새 인증 티켓을 생성합니다. 그런 다음, 게임 서버로 인증하기 위한 단계가 각 원격 피어에 적용됩니다.
- 각각의 새 원격 피어는
QueryVerifiedAuthTicket을 호출하고 모든 다른 기존 피어로 인증하기 위해 일회용 티켓을 얻습니다. - 모든 기존 피어는
BeginVerifiedAuthSession을 호출하여 새 원격 피어에 대한 검증된 인증 세션을 시작합니다.
모든 인터페이스 구현이 P2P를 지원하는 것은 아닙니다. 자세한 내용은 해당 플랫폼 서비스 문서를 참조하세요.
계정 어트리뷰트 수정하기
게임 코드는 필요에 따라 ModifyAccountAttributes 를 호출하여 FAccountInfo 구조체에 추가 커스텀 어트리뷰트를 저장할 수도 있습니다.
수정된 어트리뷰트는 Logout 이 호출될 때까지 사용자의 데이터에 계속 존재합니다. 이러한 어트리뷰트는 인증 세션이 종료된 뒤에는 존속되지 않습니다. Logout 은 이러한 어트리뷰트가 포함된 사용자의 FAccountInfo 구조체를 소멸합니다.
로그아웃하기
Logout 은 로컬 사용자의 현재 인증 세션을 종료하고 연관된 리소스와 구조를 정리합니다.
예시
플랫폼 서비스로 로그인하기
UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
UE::Online::IAuthPtr AuthInterface = OnlineServices->GetAuthInterface();
UE::Online::FAuthLogin::Params Params;
Params.PlatformUserId = PlatformUserId;
Params.CredentialsType = LoginCredentialsType::ExchangeCode;
Params.CredentialsToken = TEXT("1234567890"); // Exchange code from command-line
AuthInterface->Login(MoveTemp(Params)).OnComplete([](const UE::Online::TOnlineResult<UE::Online::FAuthLogin>& Result)
{
if(Result.IsOk())
{
const TSharedRef<UE::Online::FAccountInfo> AccountInfo = Result.GetOkValue().AccountInfo;
// 이제 AccountInfo 오브젝트에 액세스할 수 있습니다.
}
else
{
FOnlineError Error = Result.GetErrorValue();
// 이제 오류를 처리할 수 있습니다.
}
});
연습
-
파라미터 없이
GetServices를 호출하여 기본 온라인 서비스를 가져온 다음, 인증 인터페이스에 액세스합니다.UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::IAuthPtr AuthInterface = OnlineServices->GetAuthInterface(); -
사용자 로그인에 필요한 파라미터를 인스턴스화합니다.
UE::Online::FAuthLogin::Params Params; Params.PlatformUserId = PlatformUserId; Params.CredentialsType = LoginCredentialsType::ExchangeCode; Params.CredentialsToken = TEXT("1234567890"); // Exchange code from command-line -
로그인 성공 시 계정 정보를 등록하거나 결과 오류를 처리하여
Login.OnComplete콜백을 처리합니다.AuthInterface->Login(MoveTemp(Params)).OnComplete([](const UE::Online::TOnlineResult<UE::Online::FAuthLogin>& Result) { if(Result.IsOk()) { const TSharedRef<UE::Online::FAccountInfo> AccountInfo = Result.GetOkValue().AccountInfo; // 이제 계정 정보 오브젝트에 액세스할 수 있습니다. } else { FOnlineError Error = Result.GetErrorValue(); // 이제 오류를 처리할 수 있습니다. } });
온라인 서브시스템에서 코드 변환하기
온라인 서비스 인증 인터페이스는 온라인 서브시스템 ID 인터페이스가 소유한 모든 코드를 담당합니다.
추가 정보
헤더 파일
필요에 따라 Auth.h 헤더 파일에서 직접 추가 정보를 참조하세요. Auth.h 인증 인터페이스 헤더 파일은 다음 디렉터리에 있습니다.
UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE 소스 코드를 획득하는 방법에 대한 지침은 언리얼 엔진 소스 코드 내려받기 문서를 참조하세요.
함수 파라미터 및 반환 타입
파라미터 전달 방법 및 / 함수 반환 시 결과 처리 방법을 포함한 함수 파라미터 및 반환 타입에 대한 설명은 온라인 서비스 개요 페이지의 함수 섹션을 참조하세요.
