주요 콘텐츠로 건너뛰기

비밀번호 없는 권한 인증

이 가이드에서는 플레이어가 게임 앱을 통해 인증을 받도록 하여 사용자가 유저 ID를 수동으로 입력할 필요 없이 게임 허브에 원활하게 접근할 수 있도록 하는 방법을 설명합니다.

Webhook general flow image
Webhook general flow image

플로우를 시작하는 두 가지 방법

같은 Authorize User 엔드포인트로 두 가지 방식을 지원하며, 어느 방식을 쓰느냐에 따라 nonce가 필요한지가 결정됩니다:

  • 허브에서 시작(QR 코드 / 로그인 버튼). 플레이어가 게임 허브에 있습니다. 게임 허브는 QR 코드나 로그인 버튼을 표시하고 nonce를 생성한 뒤, 해당 nonce를 키로 하는 웹소켓을 통해 로그인을 기다립니다. 아래에서 단계별로 설명하는 플로우가 이 방식입니다.
  • 게임에서 시작("허브로" 버튼). 플레이어가 게임 앱에서 시작하고, 이미 인증된 상태로 허브에 들어갑니다. 같은 S2S 호출이지만 nonce를 생략하고, 반환된 authorization_url을 게임에서 직접 엽니다. 게임에서 시작하는 로그인을 참고하세요.

전제 조건

  • 요청 인증을 위한 활성화된 서버 간(S2S) API 키가 필요합니다.
  • Aghanim 대시보드의 Customization → Login에 설정된 Deep Link URL(아래 참고)이 필요합니다. 허브에서 시작하는 플로우에서만 필요합니다.

Deep Link URL은 플레이어가 로그인 버튼을 탭했을 때 게임 허브가 여는 주소입니다. Aghanim 대시보드의 Customization → Login → Deep Link URL에서 설정합니다.

이는 게임 → 허브 딥링크와 반대 방향입니다. 그쪽에서는 게임이 허브로 들어가는 링크(/go/login?player_id=…)를 열고, 여기서는 플레이어를 인증하기 위해 허브가 게임으로 들어가는 링크를 엽니다.

게임 허브는 이 URL에 after_auth와 nonce 쿼리 매개변수를 자동으로 추가합니다. 플레이스홀더를 직접 추가할 필요는 없습니다. 예를 들어 https://your-game-server.com/authorize-player로 설정하면, 허브가 열 때 https://your-game-server.com/authorize-player?after_auth=open_authorization_url&nonce=<value>가 됩니다. 설정한 URL에 포함한 고정 쿼리 매개변수는 그대로 유지됩니다.

커스텀 스킴보다 https App Link / Universal Link를 권장합니다

mygame://authorize-player 같은 커스텀 스킴 대신, 자체 도메인에서 처리하는 https:// Android App Link / iOS Universal Link(예: https://your-game-server.com/authorize-player)를 사용하세요.

이 선택은 게임 앱이 설치되어 있지 않을 때 중요합니다. 예를 들어 플레이어가 모바일 브라우저에서 허브를 연 경우입니다:

  • 커스텀 스킴(mygame://…)에는 운영 체제 차원의 대체 동작이 없습니다. 기기에서 해당 스킴을 처리할 앱이 없으면 브라우저는 아무것도 하지 않고, 플레이어는 로딩 스피너에 머물게 됩니다. apple-app-site-association과 assetlinks.json 파일은 커스텀 스킴에 적용되지 않습니다.
  • https App Link / Universal Link는 자동으로 대체 동작합니다. 앱이 설치되어 있으면 OS가 앱을 열고, 그렇지 않으면 브라우저가 해당 https URL을 그대로 엽니다. 이 URL을 서버의 엔드포인트로 지정하고, 앱이 없을 때 플레이어가 도착할 곳(예: 웹 스토어)으로 리디렉션하면 플레이어가 막히지 않습니다.

App Links / Universal Links를 사용하려면 Deep Link URL에 쓰는 도메인에 assetlinks.json(Android)과 apple-app-site-association(iOS)을 호스팅하고, 앱에서 해당 경로를 등록하세요.

플레이어가 로그인 버튼을 클릭하면 게임 허브는 after_auth와 nonce를 추가한 Deep Link URL을 엽니다. URL 형식은 다음과 같습니다:

https://your-game-server.com/authorize-player?after_auth=open_authorization_url&nonce=<value>

여기서 <value>는 각 인증 요청마다 게임 허브에서 생성되는 고유한 문자열이고, after_auth는 4단계에서 게임 클라이언트가 무엇을 해야 하는지 알려줍니다.

게임 클라이언트(또는 앱이 설치되어 있지 않아 https App Link를 처리하지 못하는 경우에는 서버)는 딥링크를 가로채서 URL에서 nonce와 after_auth를 위치가 아닌 이름으로 읽어야 합니다. 이 nonce는 게임 백엔드에 대한 권한 부여 요청에 사용됩니다.

2단계: 게임 백엔드로 권한 부여 요청 전달

플레이어가 인증된 세션을 시작한 후, 게임 클라이언트는 게임 백엔드에 권한 요청을 전송해야 합니다.

3단계: Aghanim에게 권한 요청을 전송하기

게임 클라이언트로부터 요청을 받으면 게임 백엔드는 엔드포인트 Authorize User를 사용하여 Aghanim API에 POST 요청을 보내야 합니다. 요청에 다음 매개변수를 포함하세요:

매개변수설명필수 여부
player_id인증받을 플레이어의 고유 식별자.예
nonce게임 허브에서 제공하는 고유 문자열. 허브에서 시작하는 플로우에서는 필수이며, 게임에서 시작하는 로그인에서는 생략합니다.조건부
redirect_path플레이어를 리디렉션할 게임 허브 페이지.아니오
player_info최초 인증 시 설정할 선택적 플레이어 프로필. name, avatar_url, attributes, custom_attributes를 받습니다.아니오

nonce는 인증을 대기 중인 허브 세션과 연결합니다. 이를 통해 QR 코드 / 로그인 버튼을 표시하는 허브가 웹소켓으로 로그인됩니다. 게임에서 authorization_url을 직접 여는 경우에는 생략하세요(게임에서 시작하는 로그인 참고).

예시 요청

curl --request POST \
  --url https://api.aghanim.com/s2s/v1/users/authorize \
  --header 'Authorization: Bearer YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "player_id": "2D2R-OP3C",
    "nonce": "N2Q3Y2MGI6bQ",
    "player_info": {
      "name": "Han Solo",
      "avatar_url": "https://example.com/han.png",
      "attributes": { "hard_currency_amount": 500 },
      "custom_attributes": { "faction": "rebel" }
    }
  }'

예시 응답

{
  "authorization_url": "https://your-game-hub/go/login?token=dXNyX...FTV0xqTWg&nonce=N2Q3Y2MGI6bQ"
}

4단계: 플레이어를 인증 URL로 리디렉션

게임 백엔드는 Aghanim으로부터 authorization_url을 받으면, 이 URL을 다시 게임 클라이언트로 전달해야 합니다. 그런 다음 게임 클라이언트는 기본 브라우저를 실행하고 인증 URL을 열어야 합니다. 이 동작으로 플레이어의 게임 허브 인증이 완료됩니다.

게임 허브는 iOS 홈 화면에 설치된 게임 허브에서 로그인을 시작한 경우에만 after_auth=prompt_open_pwa를 보내고, 그 밖의 모든 로그인에는 open_authorization_url을 보냅니다. prompt_open_pwa인 경우 인증 URL을 열지 마세요. 대신 플레이어에게 게임 허브 앱으로 돌아가라는 메시지를 표시하세요. 로그인은 앱이 스스로 완료합니다.

게임에서 시작하는 로그인

플레이어가 게임 앱에서 시작하고, 허브가 앱을 여는 대신 이미 로그인된 상태로 허브에 들여보내고 싶을 때(예: "허브로" 버튼) 이 방식을 사용합니다. 같은 Authorize User 엔드포인트를 쓰지만 위 플로우와 두 가지가 다릅니다. 딥링크 가로채기(1~2단계)를 건너뛰고, nonce를 생략합니다.

  1. 플레이어가 게임 내 버튼을 탭합니다.
  2. 게임 백엔드가 player_id만(선택적으로 redirect_path도) 담아 POST /s2s/v1/users/authorize를 호출합니다. nonce는 넣지 않습니다.
  3. Aghanim이 https://your-game-hub/go/login?token=… 형식의 authorization_url을 반환합니다.
  4. 이 URL을 게임 클라이언트로 전달해 기기의 기본 브라우저에서 엽니다. URL의 token으로 플레이어가 허브에 로그인됩니다.

참고:

  • 이 방향에서는 Deep Link URL 설정이 필요 없으며, 어떤 웹 로그인 방식이 활성화되어 있든 동작합니다. 허브에서 "Login with Player Id" 방식을 활성화할 필요가 없습니다. 허브 자체의 로그인 화면은 한 가지 방식(예: QR 코드)으로 제한하면서도 게임에서 바로 플레이어를 로그인시킬 수 있는 편리한 방법입니다.
  • 웹소켓으로 대기 중인 허브 세션이 없으므로 nonce로 연결할 대상이 없고, nonce를 키로 하는 권한 거부 호출도 적용되지 않습니다. 플레이어를 로그인시키면 안 된다고 게임이 판단하면 authorization_url을 열지 마세요.

권한 부여 실패 처리

게임이 항상 플레이어를 인증할 수 있는 것은 아닙니다. 예를 들어 플레이어가 아직 게임 허브에 접근하는 데 필요한 레벨에 도달하지 않았거나, 계정이 제한된 경우입니다. 이런 경우 플레이어가 로딩 스피너에서 기다리지 않도록, 로그인을 진행할 수 없다는 것을 Aghanim에 알려주세요.

권한 요청 거부

게임 백엔드가 로그인을 진행할 수 없다고 판단하면 Reject Authorization 엔드포인트를 사용하여 Aghanim API에 POST 요청을 보냅니다. 권한 부여 딥링크에서 받은 것과 같은 nonce를 포함하세요:

매개변수설명필수 여부
nonce권한 부여 딥링크에서 가져온, 게임 허브가 제공한 고유 문자열.예
reason권한 부여를 진행할 수 없는 이유. not_eligible(플레이어가 허브 접근 조건을 충족하지 않음), banned, rejected(일반 거부) 중 하나입니다.예

예시 요청

curl --request POST \
  --url https://api.aghanim.com/s2s/v1/users/authorize/reject \
  --header 'Authorization: Bearer YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "nonce": "N2Q3Y2MGI6bQ",
    "reason": "not_eligible"
  }'

예시 응답

{
  "error_url": "https://your-game-hub/error?message_code=auth_via_game.not_eligible"
}

플레이어에게 오류 표시

실패를 어떻게 보여줄지는 게임이 결정합니다:

  • 게임 클라이언트에서. 게임 자체 UI에 오류를 표시한다면 추가 작업은 필요 없습니다. error_url은 무시해도 됩니다.
  • 게임 허브에서. 브라우저에서 오류를 보여주고 싶다면, 성공 시 authorization_url과 똑같이 error_url을 게임 클라이언트로 전달해 기본 브라우저에서 여세요. 그러면 게임 허브가 해당 오류 메시지를 플레이어에게 표시합니다.

도움이 필요하세요?
통합팀에 문의하십시오 integration@aghanim.com

On this page