주요 콘텐츠로 건너뛰기

Game Hub에서 소셜 인증

Aghanim은 웹훅을 통한 플레이어 인증을 위해 여러 소셜 로그인 제공자(예: Apple, Discord, Facebook, Google) 및 일반 OIDC 준수 제공자를 지원합니다. 이 웹훅은 로그인 이벤트 시 백엔드에 알림을 보내며, OAuth2 권한 부여 코드의 유효성을 검사하여 Game Hub 접근을 허가하거나 거부해야 합니다.

요구 사항

소셜 로그인을 사용하여 Aghanim에서 플레이어 검증 이벤트를 처리하기 위해 서버는 다음을 수행해야 합니다:

  • HTTPS POST 엔드포인트 노출.
  • Aghanim이 서명한 웹훅 이벤트 수락.
  • 제공된 code(OAuth2 Authorization Code Grant flow에서 response_type=code를 사용하여 획득한 인증 코드)를 적절한 공급자의 액세스 토큰으로 교환합니다.
  • 성된 사용자 프로필을 검증한 후 귀사의 플레이어 데이터베이스와 일치 여부를 확인합니다.
  • 성공 또는 실패에 대해 200 상태 코드와 JSON 페이로드로 응답합니다.

지원하는 공급자

게임 애플리케이션 대시보드에서 각 소셜 공급자를 구성하고 OAuth2 흐름에 대한 적절한 Redirect URI 처리를 보장해야 합니다. 다음 공급자들이 현재 지원됩니다:

  • Apple
  • Discord
  • Google
  • Facebook
  • OIDC(모든 OpenID Connect 준수 제공자)
정보

위에 나열되지 않은 제공자의 경우, 일반 OIDC Login 플러그인을 사용하여 모든 OpenID Connect 준수 ID 제공자(예: Keycloak, Auth0, Okta, Azure AD)를 통합할 수 있습니다. 추가 도움이 필요하시면 문의하기로 연락해 주세요.

OAuth2 Redirect URI

각 공급자에 대해 다음 Redirect URI가 해당 개발자 콘솔에 추가되었는지 확인하세요:

https://<GAME_HUB_DOMAIN>/oauth2/<PROVIDER>/callback

<GAME_HUB_DOMAIN>을 Game Hub의 도메인으로 (예: demo.aghanim.com), <PROVIDER>를 facebook, google, apple, discord, 또는 oidc로 교체하세요.

제공자별 구성

정보

일반적인 OAuth2 흐름이 제공업체마다 일관적이지만, 설정 단계는 플랫폼마다 조금씩 다릅니다. 세부적인 설정 지침은 각 제공자의 개발자 문서에서 찾을 수 있습니다.

Apple

  1. Apple 개발자 포털로 이동합니다
  2. Identifiers에서 새로운 Sign In with Apple 서비스를 등록합니다
  3. Services ID와 Redirect URI를 구성합니다.
  4. OAuth2 토큰 교환을 위한 client secret JWT를 생성합니다

Discord

  1. Discord 개발자 포털에 방문합니다
  2. 애플리케이션을 생성하고 OAuth2를 활성화합니다
  3. Redirect URI를 설정하세요

Facebook

  1. Facebook 개발자로 이동합니다
  2. 새로운 앱 만들기(유형: Consumer)
  3. Facebook 로그인 제품 추가
  4. Facebook 로그인 → 설정에서 구성합니다:
    • 클라이언트 OAuth 로그인: 예
    • Redirect URI에 대한 엄격 모드 사용: 예
  5. Valid OAuth Redirect URIs에 Redirect URI를 설정합니다.

Google

  1. Google 클라우드 콘솔로 이동합니다
  2. APIs & Services → Credentials에서 OAuth2 자격 증명을 만드세요
  3. Redirect URI 구성합니다

OIDC

  1. OIDC 준수 ID 제공자(예: Keycloak, Auth0, Okta, Azure AD)에서 클라이언트 애플리케이션을 구성하세요
  2. Discovery URL, Authorization Endpoint, Client ID를 기록해 두세요
  3. Redirect URI를 설정하세요
  4. 자세한 설정 지침은 OIDC Login 가이드를 참고하세요

구성

엔드포인트를 등록하려면 다음을 실행하세요:

  • Aghanim 대시보드 → 게임 > 웹훅 > 새 웹훅, 플레이어 확인 이벤트 유형을 선택합니다.
  • 또는 Create Webhook API를 통해

요청 스키마

아래는 예시입니다 player.verify 웹훅 요청:

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "player.verify",
  "event_data": {
    "method": "google",
    "code": "4/0123abc...xyz"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.login",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

이벤트 스키마

Key유형설명
event_idstringAghanim에 의해 생성된 고유 이벤트 ID.
game_idstringAghanim 시스템에서의 귀하의 게임 ID.
event_typestring이벤트의 유형, player.verify 이럴 경우.
event_timenumber유닉스 에포크 시간으로 된 이벤트 날짜.
event_dataEventData이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
idempotency_keystring|null웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다. 일 수 있습니다 null 이벤트 유형에 따라 달라집니다.
request_idstring|null이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
sandboxboolean이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
triggerstring|nullThe trigger that caused the event to be sent.
transaction_idstringAghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
contextobject|null이벤트에 대한 컨텍스트 정보.

EventData 스키마

Key유형설명
methodstring인증에 사용되는 공급자입니다. apple, discord, facebook, google, oidc 중 하나입니다.
codestring공급자가 생성한 승인 코드입니다. 자세한 내용은 RFC 6749 섹션 4.1.2를 참조하세요.
redirect_uri`string\null`

웹훅 처리

백엔드는 다음을 수행해야 합니다:

  1. 요청 본문에서 method, code, redirect_uri를 추출합니다.
  2. 해당 공급자의 OAuth2 토큰 엔드포인트를 사용하여 code를 액세스 토큰으로 교환합니다. redirect_uri가 null이 아니면 토큰 교환 요청에 포함하세요.
  3. 액세스 토큰을 사용하여 사용자 프로필을 조회합니다.
  4. 데이터베이스에 있는 플레이어와 소셜 계정을 매치하세요.
  5. 적절한 웹훅 응답 스키마를 사용하여 로그인을 허용하거나 거부합니다.

성공적인 응답 스키마

예상되는 구조에 대해서는 player.verify 웹훅 응답 문서를 참조하세요.

실패 응답 스키마

검증에 실패하면 200 상태 코드와 다음 JSON 응답으로 반환합니다:

{
  "status": "error",
  "code": "not_found",
  "message": "Player not found"
}

가능한 오류 코드 목록:

  • not_found - 계정/플레이어를 찾을 수 없음.
  • invalid_signature - 서명이 유효하지 않았습니다.
  • validation_error - 요청 데이터가 유효하지 않았습니다.
  • banned - 계정/플레이어가 차단되었습니다.

FAQ

Do I need to share my OAuth credentials with Aghanim?

No. Aghanim은(는) OAuth 클라이언트 시크릿이나 API 키에 대한 접근이 전혀 필요하지 않습니다. 플레이어가 Game Hub에서 소셜 제공자를 통해 로그인하면 Aghanim은(는) 제공자로부터 인증 code를 받고 player.verify 웹훅을 통해 이를 백엔드로 전달합니다. 그런 다음 서버가 자체 자격 증명(게임이 이미 사용 중인 것과 동일한 자격 증명)을 사용하여 해당 코드를 액세스 토큰으로 교환합니다.

Do I need to create a separate OAuth app for Aghanim?

No. 게임이 이미 사용 중인 것과 동일한 OAuth 애플리케이션을 사용해야 합니다. 필요한 유일한 변경 사항은 제공자의 개발자 콘솔에서 기존 앱의 허용된 리디렉션 URI에 Aghanim Redirect URI를 추가하는 것입니다.

What about providers with app-scoped IDs (Meta, Apple)?

Meta (Facebook) 및 Apple과 같은 제공업체는 특정 OAuth 애플리케이션에 범위가 지정된 플레이어 ID를 발급합니다. Aghanim은 기존 OAuth 앱(별도의 앱이 아님)을 사용하므로, 토큰 교환 중에 반환되는 플레이어 ID는 게임에서 이미 알고 있는 동일한 ID입니다. ID 불일치가 없습니다.

도움이 필요하세요?
통합팀에 문의하십시오 [email protected]

On this page