Skip to main content
PlayFab은 Admin, Server, 엔터티 API 호출을 위한 Microsoft Entra ID(이전 이름 Azure Active Directory) 인증을 지원합니다. Entra ID 인증을 사용하면 Microsoft ID로 로그인하고 개발자 시크릿 키 대신 위임된 액세스 토큰을 사용합니다. 애플리케이션은 PKCE가 포함된 권한 부여 코드, 장치 코드 또는 암시적 부여와 같은 표준 OAuth 2.0 공용 클라이언트 흐름을 사용하여 로그인 환경을 처리합니다.
Entra ID 인증은 Admin, Server 및 일부 엔터티 API 호출에 대해 개발자 시크릿 키의 대안입니다. 플레이어 대상 Client 및 엔터티 API는 플레이어 로그인을 통해 얻은 세션 티켓과 엔터티 토큰을 계속 사용합니다. title 엔터티 토큰으로 호출 가능한 엔터티 API만 Entra ID와 함께 사용할 수 있습니다. 시크릿 키에 대한 자세한 내용은 시크릿 키 관리를 참조하세요.

Entra ID 인증을 사용하는 이유

개발자 시크릿 키는 사용이 간단하지만, Entra ID 인증은 몇 가지 장점을 제공합니다.
  • 공유된 시크릿 없음 — 공용 클라이언트 흐름에는 클라이언트 시크릿이 필요하지 않습니다. 토큰은 수명이 짧고 로그인한 사용자로 범위가 지정됩니다.
  • 개별 책임 — 각 API 호출은 특정 사용자 ID에 연결되어 누가 무엇을 했는지 감사하기가 쉽습니다.
  • 조건부 액세스 — 조직은 IP 제한, 다단계 인증(MFA), 장치 규정 준수 확인과 같은 Entra ID 정책을 적용할 수 있습니다.

Entra ID 인증 작동 방식

Microsoft Entra ID를 사용한 적이 없다면, 이것은 Microsoft의 클라우드 ID 서비스입니다. Microsoft 365, XBOX 개발자 계정, Azure를 뒷받침하는 것과 동일한 ID 시스템입니다. PlayFab이 스튜디오에 수명이 긴 시크릿 키를 발급하는 대신, 도구가 Entra ID에게 개발자 로그인을 요청하고 수명이 짧은 액세스 토큰을 돌려받습니다. PlayFab은 스튜디오의 구성원인 사용자에 대해 Entra ID가 발급한 토큰을 신뢰합니다. 세 가지 당사자가 관련됩니다.
  • 개발자. Microsoft 계정(개인) 또는 직장 또는 학교 계정(Entra ID)으로 로그인한 사용자.
  • Entra ID의 앱 등록. 이는 PlayFab을 호출하는 도구(CLI, 빌드 스크립트, 내부 대시보드 등)를 나타냅니다. Entra ID에 “이 앱은 로그인한 사용자를 대신해 PlayFab 액세스 토큰을 요청할 수 있음”을 알립니다.
  • PlayFab 서비스. PlayFab은 Entra ID에서 애플리케이션 ID 448adbda-b8d8-4f33-a1b0-ac58cf44d4c1로 등록되어 있으며 plugin이라는 위임된 권한을 노출합니다. 코드가 448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin 범위를 요청하면 Entra ID는 PlayFab이 수락하는 토큰을 발급합니다.
일반적인 호출은 다음과 같습니다.
  1. 코드는 Microsoft Authentication Library(MSAL)를 사용하여 로그인을 시작합니다. 일반적으로 브라우저 팝업이나 장치 코드 프롬프트입니다.
  2. 사용자는 Microsoft ID로 로그인하고 앱이 자신을 대신해 PlayFab을 호출하는 것에 동의합니다.
  3. MSAL은 액세스 토큰(JWT)을 반환하고 향후 호출에서 프롬프트를 건너뛸 수 있도록 새로 고침 토큰을 캐시합니다.
  4. 코드는 각 PlayFab 요청의 Authorization: Bearer <token> 헤더로 토큰을 보냅니다.
  5. PlayFab은 토큰을 검증하고 일치하는 스튜디오 사용자에게 매핑하며 해당 사용자의 역할을 기반으로 호출을 승인합니다.
이 문서 전반에서 사용되는 Entra ID 용어의 정의는 끝의 용어집을 참조하세요.

필수 구성 요소

  • Entra ID(직장 또는 학교 계정)로 뒷받침되는 Microsoft 계정 또는 개인 Microsoft 계정(MSA).
  • PlayFab 타이틀. 자세한 내용은 PlayFab 계정 만들기를 참조하세요.
  • Microsoft Entra ID 테넌트에서 애플리케이션을 등록할 권한.
  • 호출 사용자는 PlayFab 스튜디오에 추가되고 타이틀 관리자로 할당되어야 합니다. 역할에 대한 자세한 내용은 PlayFab 사용자 역할을 참조하세요.

Entra ID에 공용 클라이언트 애플리케이션 등록

코드가 로그인한 사용자를 대신하여 위임된 토큰을 요청할 수 있도록 Entra ID 테넌트에 애플리케이션을 등록해야 합니다. 공용 클라이언트 흐름(SPA, 장치 코드, 암시적)의 경우 클라이언트 시크릿이 필요하지 않습니다.
  1. Azure 포털에 로그인합니다.
  2. App registrations를 검색하고 선택한 다음 New registration을 선택합니다.
  3. 애플리케이션 이름을 입력합니다(예: PlayFab API Client).
  4. Supported account types에서 조직의 요구 사항과 일치하는 옵션을 선택합니다. 최대한의 유연성을 위해 Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts를 선택합니다. 이 옵션은 모든 Microsoft 계정이 인증할 수 있게 합니다.
  5. 애플리케이션 유형에 따라 Redirect URI를 구성합니다.
    • SPA(단일 페이지 애플리케이션)의 경우 **Single-page application (SPA)**를 선택하고 리디렉션 URI를 입력합니다(예: http://localhost:3000).
    • 장치 코드 흐름을 사용하는 네이티브 또는 콘솔 애플리케이션의 경우 **Public client/native (mobile & desktop)**를 선택하고 http://localhost를 입력합니다.
  6. Register를 선택합니다. 개요 페이지에서 Application (client) ID를 기록합니다. 토큰을 요청할 때 이 값이 필요합니다.
  7. 앱 등록에 PlayFab API 권한을 추가합니다.
    1. Azure 포털에서 앱 등록으로 이동하고 API permissions를 선택합니다.
    2. Add a permission > APIs my organization uses를 선택합니다.
    3. PlayFab 애플리케이션 ID 448adbda-b8d8-4f33-a1b0-ac58cf44d4c1을 검색하고 선택합니다.
    4. Delegated permissions를 선택하고 plugin 권한을 체크한 다음 Add permissions를 선택합니다.
시나리오에 기밀(웹 앱) 클라이언트가 필요한 경우 Certificates & secrets 아래에서 클라이언트 시크릿도 만들어야 합니다. 이 문서에서는 시크릿이 필요하지 않은 공용 클라이언트 흐름에 초점을 맞춥니다. 기밀 클라이언트 흐름에 대한 자세한 내용은 Microsoft ID 플랫폼 및 OAuth 2.0 권한 부여 코드 흐름을 참조하세요.

PlayFab 스튜디오 액세스 설정

PlayFab은 스튜디오 멤버십에 대해 Entra ID 토큰을 검증합니다. 호출 사용자는 PlayFab 스튜디오에 추가되고 적절한 역할이 부여되어야 합니다.
  1. 스튜디오 관리자가 Game Manager에 로그인합니다.
  2. 스튜디오의 Users 섹션으로 이동합니다.
  3. Add User를 선택하고 API 액세스가 필요한 개발자의 Microsoft 계정 이메일을 입력합니다.
  4. 인증 제공자로 Microsoft를 선택합니다.
  5. 사용자에게 Admin 또는 Server API 액세스를 포함하는 역할을 할당합니다. 최소한 사용자는 API를 호출해야 하는 타이틀에 대해 타이틀 관리자여야 합니다.
  6. Add user를 선택하여 초대를 보냅니다.
사용자 추가 및 역할 할당에 대한 자세한 내용은 PlayFab Game Manager 계정 인증을 참조하세요.

액세스 토큰 얻기

애플리케이션은 사용자를 로그인시키고 Entra ID에서 위임된 액세스 토큰을 얻는 역할을 담당합니다. 다음 예제는 일반적인 공용 클라이언트 흐름을 보여줍니다.

대화형 브라우저 흐름(데스크톱 및 콘솔 앱에 권장)

대화형 브라우저 흐름은 로그인을 위한 시스템 브라우저 창을 엽니다. 데스크톱 애플리케이션과 로컬 개발 도구에 권장되는 옵션입니다.

PKCE가 포함된 권한 부여 코드(SPA에 권장)

PKCE(Proof Key for Code Exchange)가 포함된 권한 부여 코드 흐름은 단일 페이지 애플리케이션에 권장되는 접근 방식입니다. 다음 JavaScript 예제는 Microsoft Authentication Library(MSAL)를 사용합니다.

액세스 토큰으로 PlayFab API 호출

X-SecretKey 헤더를 사용하는 대신 PlayFab API 요청의 Authorization 헤더에 Bearer 토큰으로 Entra ID 액세스 토큰을 포함합니다.

예제 요청

동일한 요청에서 X-SecretKeyAuthorization: Bearer를 함께 사용할 수 없습니다. 호출당 하나의 인증 방법을 사용하세요.

C# 예제

다음 예제는 Microsoft Authentication Library(MSAL)를 사용하여 토큰을 얻고 Server/GetTime API를 호출합니다. your-client-id를 앱 등록의 Application (client) ID로 바꿉니다.

Node.js 예제

다음 예제는 @azure/msal-node 라이브러리를 사용하여 토큰을 얻고 Server/GetTime API를 호출합니다. your-client-id를 앱 등록의 Application (client) ID로 바꿉니다.

토큰 새로 고침

Entra ID 액세스 토큰은 수명이 짧습니다(일반적으로 60~90분). MSAL을 사용하는 경우 각 요청 전에 AcquireTokenSilent(C#)를 호출하거나 토큰 캐시를 확인하세요. 캐시된 새로 고침 토큰이 있는 경우 MSAL이 자동으로 새로 고침을 처리합니다. 토큰을 수동으로 관리하는 경우 현재 토큰이 만료되기 전에 동일한 로그인 흐름을 사용하여 새 토큰을 요청합니다.
사용 중에 토큰이 만료되면 PlayFab은 401 Unauthorized 응답을 반환합니다. 애플리케이션은 새 토큰을 요청하고 호출을 재시도하여 이 오류를 처리해야 합니다.

문제 해결

예제 오류 응답

Bearer 토큰이 누락되었거나 형식이 잘못되었거나 만료되었을 때 PlayFab의 401 Unauthorized는 다음과 같습니다.
로그인한 사용자가 인증되었지만 타이틀에 대한 관리자 권한이 없을 때 PlayFab의 403 Forbidden은 다음과 같습니다.

제한 사항

PlayFab SDK는 현재 Entra ID 인증을 지원하지 않습니다. 오늘날 Entra ID 토큰으로 PlayFab API를 호출하려면 직접 HTTP 호출을 사용하고 C#Node.js 예제에 표시된 대로 Authorization: Bearer <token> 헤더를 직접 설정하세요. SDK 지원은 향후 릴리스에서 계획되어 있습니다.

용어집

참고 항목

마지막 수정일 2026년 8월 24일