1. Epic GamesDeveloper
  3. OIDC 토큰

OIDC 토큰

OIDC 토큰을 생성하고 ID 제공자를 통해 구성합니다.

OIDC 토큰

OIDC 토큰(OIDC Token)은 OIDC 호환 ID 제공자의 토큰을 노출하고 할당하고 액세스하고 새로 고치는 툴입니다. 이 툴은 클라우드 DDC처럼 언리얼 에디터와 함께 작동하는 다양한 클라우드 서비스를 구성할 때 유용합니다. 이 페이지에서는 OIDC 토큰 툴 환경설정 및 ID 제공자 구성에 대한 정보를 제공합니다.

환경설정

환경설정 파일은 Engine\Programs\OidcToken\oidc-configuration.json 또는 <Game>\Programs\OidcToken\oidc-configuration.json에 있습니다.

다음은 환경설정 파일의 내용을 보여주는 예시입니다.

C++
oidc-configuration.json 
{

	"OidcToken": {

		"Providers": {

			"MyOwnProvider": {

				"ServerUri": "https://<url-to-your-provider>",

ID 제공자 구성

이 섹션에서는 몇몇 일반 ID 제공자(Identity Providers, IdP)를 구성하는 방법을 설명합니다.

Okta

Okta를 IdP로 사용하려면 다음 항목을 구성해야 합니다.

  • 사용자의 인터랙티브 로그인을 위한 클라이언트(Client)(애플리케이션).

  • Okta가 클레임 및 범위를 매핑하는 방법과 액세스 제어를 관리하도록 사용자를 할당할 수 있는 일부 그룹을 제어하기 위한 커스텀 인증 서버(Custom Auth Server).

  • 인터랙티브 로그인이 불가능한 빌드 팜에서 실행하려는 경우, 로그인을 허용하도록 다른 클라이언트(애플리케이션)를 구성해야 합니다.

Okta는 커스텀 인증 서버 없이는 OIDC 로그인을 지원하지 않습니다. 커스텀 인증 서버 구성에 대해서는 Okta의 인증 서버에 대한 문서를 참조하세요.

Okta를 ID 제공자로 구성하는 단계는 다음과 같습니다.

  1. Okta 관리 대시보드를 엽니다.

  2. 애플리케이션(Applications) > 애플리케이션(Applications)을 클릭합니다.

  3. 인터랙티브 로그인을 위한 클라이언트를 생성하고 다음 허가 타입을 활성화합니다.

    • 새로고침 토큰(Refresh Tokens)

    • 인증 코드(Authorization Code)

  4. 다음 예시와 같이 localhost 아래에 여러 개의 로그인 URL을 지정하는 것이 좋습니다. 예를 들어 다음과 같이 할 수 있습니다.

    • http://localhost:8749/oidc-token

    • http://localhost:8750/oidc-token

    • http://localhost:8751/oidc-token

    • http://localhost:8752/oidc-token

    • http://localhost:8753/oidc-token

    • http://localhost:8754/oidc-token

    이렇게 하면 로그인 프로세스 동안 여러 로컬 포트에서 앱이 실행될 수 있으므로 포트 사용 중으로 인해 발생하는 문제를 방지할 수 있습니다.

    위에 나열된 포트는 임의로 든 예시입니다. 실제 상황에서는 필요에 맞는 포트를 선택하세요.

  5. 무인 로그인 클라이언트를 구성합니다. 이 클라이언트는 이전 단계에서 설정한 클라이언트와 비슷하지만, 다음과 같은 점이 다릅니다.

    • 클라이언트 크리덴셜(Client Credentials) 허가 타입을 대신 사용합니다.

    • 로그인 URL을 지정하지 않아도 됩니다.

    이렇게 하려면 클라이언트와 함께 프로파일 오브젝트를 사용해야 합니다. 생성된 프로파일을 업데이트하는 방법에 대한 예시는 Okta의 프로파일 어트리뷰트 업데이트에 대한 문서를 참조하세요.

  6. 무인 로그인에 사용하려는 클라이언트 크리덴셜을 생성한 후에는 다음 예시와 비슷하게 크리덴셜에 대한 페이로드를 제출합니다.

    C++ 
    "profile": {
		
             "clientCredentialsGroups": [
		
                 "app-ue-storage-project-your-project-name"
		
             ]
		
         }

  7. 다음 가이드라인을 따라 커스텀 인증 서버에서 그룹 클레임을 업데이트합니다.

    • 원하는 대로 사용자 그룹을 매핑할 수 있지만, 액세스 권한을 부여하려는 모든 사용자를 정확하게 포함하는 그룹을 하나 이상 생성해야 합니다. 에픽게임즈에서는 보통 프로젝트당 하나의 그룹을 생성합니다.

    • 또한, 일부 상급 액세스 권한이 있는 사용자를 위한 관리자 그룹도 생성해야 합니다.

    • 사용하려는 그룹을 쉽게 식별할 수 있는 명명 규칙을 사용합니다. 이렇게 하면 사용자가 속한 모든 그룹이 아닌 언리얼 엔진에만 적용되는 그룹만 토큰의 일부로 전송할 수 있습니다.

    • 그룹을 생성할 때는 각 그룹에 한 명 이상의 사용자를 할당해야 합니다.

  8. Okta 관리 페이지의 보안(Security) > API에서 커스텀 인증 서버를 환경설정합니다.

    커스텀 인증 서버는 Okta의 애드온으로, 직접 사용하지 못할 수도 있지만 Okta에서 OIDC 로그인을 처리하는 데 필요합니다.

    인증 서버를 생성하려면 인증 서버 생성(Create Authorization Server) 버튼을 클릭합니다. 이 인증 서버는 Cloud DDC에만 국한된 것이 아니라 원하는 모든 언리얼 엔진 서비스에 사용할 수 있습니다.

  9. 인증 서버를 편집하고 액세스 정책(Access Policies)을 구성합니다. 클라이언트당 하나의 정책을 생성하고 해당 클라이언트의 로그인을 허용하도록 설정합니다.

  10. 액세스 토큰 타입에 대한 클레임(Claims)을 연 다음, 그룹(Groups) 클레임을 구성하고 사용하려는 그룹을 필터링하고 clientCredentialsGroups를 포함하도록 설정합니다. 다음 커스텀 표현식을 사용합니다.

    C++ 
    (appuser != null) ? Arrays.flatten( Groups.startsWith("OKTA", "app-ue-", 100) == null ? {} : Groups.startsWith("OKTA", "app-ue-", 100) ) : app.profile.clientCredentialsGroup1s

    이 표현식은 app-ue로 시작하는 그룹을 필터로 걸러냅니다.

  11. 빌드 팜 로그인에 사용할 수 있는 cache_access 범위를 구성합니다.

위의 단계가 완료되면 Okta를 ID 제공자로 사용할 준비가 된 것입니다.

Okta를 ID 제공자로 테스트하는 방법

Okta를 테스트하는 단계는 다음과 같습니다.

  1. 인증 서버에서 토큰 프리뷰(Token Preview)로 이동합니다.

  2. 인증 코드(Authorization Code) 허가 타입의 인터랙티브 로그인(interactive login) 클라이언트를 선택합니다.

  3. 올바른 그룹에 할당된 사용자를 선택합니다.

이 토큰을 프리뷰할 때 표시되는 JSON에는 할당한 그룹 이름이 포함된 그룹 배열이 포함되어야 합니다.

Microsoft Entra(Azure AD)

Microsoft Entra를 ID 제공자로 구성하는 단계는 다음과 같습니다.

  1. Microsoft Azure Portal로 이동합니다.

  2. Microsoft Entra 서비스를 클릭합니다.

  3. 앱 등록(App registration)으로 이동한 다음 데스크톱 로그인을 위한 앱 등록을 새로 생성합니다. 다음과 같은 세팅이 있을 것입니다.

    • 단일 테넌트

    • 퍼블릭 클라이언트/네이티브 옵션을 사용하는 localhost 리디렉션 URI 세트가 포함되어 있습니다. 다음은 리디렉션 URI의 형태에 대한 몇 가지 예시입니다.

      • http://localhost:8749/oidc-token

      • http://localhost:8750/oidc-token

      • http://localhost:8751/oidc-token

      • http://localhost:8752/oidc-token

      • http://localhost:8753/oidc-token

      • http://localhost:8754/oidc-token

    이 앱의 client id를 적어둡니다.

  4. 토큰 환경설정(Token Configuration)으로 이동한 다음 애플리케이션에 할당된 그룹(Groups assigned to the application)을 사용하도록 그룹(groups) 클레임 세팅을 추가합니다.

  5. 프로젝트 사용자(project user) 역할에 대한 새 보안 그룹(security group)을 생성합니다. 생성한 보안 그룹을 역할에 할당한 다음, 원하는 모든 사용자를 보안 그룹에 추가합니다.

  6. 다음 앱 역할(app roles)을 생성합니다.

    • 프로젝트 사용자(Project User)(보통 프로젝트당 한 명)

    • 관리자(Admin)

    프로젝트 사용자 역할은 사용자와 그룹, 애플리케이션에 할당할 수 있어야 하지만, 관리자 역할은 사용자 전용입니다.

  7. 앱 등록(App registration)으로 돌아가 백엔드 서비스(예: '언리얼 클라우드 DDC')를 위한 앱을 생성합니다.

  8. 새 앱에 API 범위를 추가하고 이름을 user.access로 지정합니다. 이 API에 데스크톱 앱 액세스의 client id를 할당합니다.

  9. 쿠킹 앱에 대한 새로운 별도의 앱 등록을 생성하고 무인으로 로그인할 수 있도록 클라이언트 암호를 추가합니다. 또는 원하는 경우 관리 ID 등을 사용합니다. 이 앱에는 프로젝트 사용자 역할도 할당해야 합니다.

  10. oidc-configuration.json 파일을 생성할 때 앱 등록에 사용할 서버 URI를 엔드포인트(Endpoints) 버튼 아래에서 찾을 수 있습니다. 이 URI는 보통 [https://login.microsoftonline.com/](https://login.microsoftonline.com/)<directory-tenant-id>/v2.0과 같은 형태입니다.

  11. 클라이언트 ID의 경우 생성한 데스크톱 앱의 client id를 사용합니다. 이 범위에는 백엔드 서비스에서 생성한 API 범위가 포함되어야 하므로, 보통 다음과 같은 형태입니다. offline_access profile openid api://<api scope guid>/user.access

위의 단계가 완료되면 Microsoft Azure를 ID 제공자로 사용할 준비가 된 것입니다.

Ask questions and help your peers Developer Forums

Write your own tutorials or read those from others Learning Library

On this page