이 문서는 식별자 공유(Shared identity) 기능을 설명합니다.

식별자 공유는 서로 다른 두 개 이상의 서비스에서 동일한 사용자를 식별하기 위해 발급되는 공유 회원번호를 함께 사용하는 기능입니다.

예를 들어, 여러 개의 서비스(예: A 백화점, A 베이커리, A 카페 등)가 통합 회원체계(예: A 멤버스)를 이용하는 경우, 통합 멤버십 서비스에서 동일한 사용자를 식별할 때 활용할 수 있습니다. 또는 회원체계를 공유하진 않지만, 프로모션 또는 계약 관계에 따라 동일 사용자에 대한 식별이 필요한 경우에도 활용할 수 있습니다.

1. 데브톡에 아래 정보와 함께 식별자 공유 그룹 생성을 요청합니다. (참고: 식별자 공유 그룹)
   • 대표 앱 ID: 서비스 및 가입 정책의 기준이 되는 앱
   • 멤버 앱 ID 목록: 대표 앱의 정책이나 상태의 영향을 받는 앱
   • 목적: 공유 회원번호가 필요한 이유 및 목적
   • 사용 시나리오: 공유 회원번호가 필요한 시나리오 및 사용 방법
2. 카카오 담당자가 식별자 공유 그룹을 생성하면, [식별자 공유 그룹]에서 식별자 공유 그룹 정보를 확인할 수 있습니다.
3. 동의항목을 설정합니다.
4. 멤버 앱 사용자에게 동의를 요청해 공유 회원번호를 발급받습니다. (참고: 공유 회원번호 발급 과정)
5. 멤버 앱과 대표 앱에서 공유 회원번호를 사용하여 동일한 사용자를 식별합니다.

앱 관리 페이지의 [카카오 로그인] > [동의항목] > [공유 식별자]에서 식별자 공유 그룹 ID를 확인하거나 동의항목을 설정할 수 있습니다.

공유 회원번호 동의항목 설정

[A] 식별자 공유 그룹: 그룹에 속한 앱 정보를 확인할 수 있는 페이지로 이동

[B] 동의항목 ID: 식별자 공유 그룹 ID를 포함한 동의항목 ID

[C] 설정: 동의항목 설정창에서 아래 [동의 단계] 중 하나 선택

• 필수 동의: 사용자가 카카오 로그인 시 필수 항목으로 노출, 인가 코드 요청 API 호출 시 scope로 정의하지 않아도 동의화면에 노출
• 이용 중 동의: 사용자가 서비스 이용 중 동의가 필요한 시점에 동의화면 노출, 동의항목 추가 동의 요청 API 호출 시 scope 정의 필수 (참고: 동의 요청)
• 사용 안 함: 동의화면에 미노출, 이 경우 공유 회원번호를 발급 받을 수 없음

앱 관리 페이지의 [카카오 로그인] > [식별자 공유 그룹] > [그룹에 속한 앱]에서 그룹에 속한 앱 정보를 확인할 수 있습니다.

식별자 공유 그룹 확인

[A] 그룹 정보: 식별자 공유 그룹 이름, ID, 설명

[B] 그룹에 속한 앱: 그룹에 포함된 앱 정보

• 대표 앱: 그룹의 대표 앱 정보
• 멤버 앱: 그룹의 멤버 앱 정보, 대표 앱인 경우에만 노출, 대표 앱은 식별자 공유 그룹에 속한 모든 멤버 앱 목록 확인 가능

공유 회원번호 발급 과정에 대해 안내합니다. 멤버 앱에서 동의항목을 설정해야 공유 회원번호를 발급할 수 있습니다.

1. 동의항목 설정에 따라 멤버 앱 사용자에게 동의를 요청하는 동의화면이 노출됩니다.
2. 사용자가 [공유 회원번호(shared_id:{group_id})] 사용에 동의합니다.
3. 계정 상태 변경 웹훅을 이용하는 경우, 사용자 동의가 완료되면 웹훅이 전달됩니다.
   • 사용자 동의 완료 시, 해당 사용자가 대표 앱도 가입한 상태라면, 대표 앱과 멤버 앱에게 계정 상태 변경 웹훅 전달
   • 사용자가 대표 앱을 가입하지 않았다면 멤버 앱으로만 웹훅 전달
4. 멤버 앱은 공유 회원번호 조회 API로 공유 회원번호를 확인할 수 있습니다.

동의항목 설정에서 [이용 중 동의]를 선택하면 동의항목 추가 동의 요청 API 호출 시 scope 파라미터에 식별자 공유 그룹 ID를 shared_id:{SHARED_GROUP_ID} 형식으로 전달해야 합니다.

[필수 동의]을 선택한 경우, scope로 그룹 ID를 정의하지 않아도 동의화면에 노출됩니다.

curl -v -X GET "https://kauth.kakao.com/oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=shared_id:12345"

공유 회원번호 제공 동의를 철회하려면 동의항목 동의 철회 API 호출 시, scopes 파라미터에 shared_id:{SHARED_GROUP_ID} 형식으로 전달합니다.

curl -v -X POST "https://kapi.kakao.com/v2/user/revoke/scopes" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode 'scopes=["shared_id:12345"]'

사용자의 회원 번호로 공유 회원번호를 조회하거나, 공유 회원번호로 회원번호를 조회할 수 있습니다.

공유 회원번호 제공 조건을 참고합니다.

target_user_id와 shared_group_id 조합 또는 shared_user_id는 둘 중 하나만 전달해야 하며, 세 파라미터를 한 요청에 섞어 전달할 수 없습니다.

curl -v -G "https://kapi.kakao.com/v1/user/shared_user_id_info" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -d "target_user_id=${USER_ID}" \
  -d "shared_group_id=${SHARED_GROUP_ID}"

curl -v -G "https://kapi.kakao.com/v1/user/shared_user_id_info" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -d "shared_user_id=${SHARED_USER_ID}"

// HTTP/1.1 200 OK
{
  "user_id": 123456789,
  "shared_group_id": 68,
  "shared_user_id": 987654321
}

계정 상태 변경 웹훅 기능을 사용하면 아래 이벤트 발생 시, 대표 앱과 멤버 앱은 공유 회원번호와 관련된 알림을 받을 수 있습니다.

웹훅 기능을 이용하려면 웹훅 구현 절차를 참고합니다.

• 발생 시점: 멤버 앱에서 공유 회원번호 제공에 동의할 때
• 이벤트 타입: User Scope Consent
• 스키마: https://schemas.openid.net/secevent/oauth/event-type/user-scope-consent
• 카테고리: OAUTH
• 이벤트 페이로드:
  • scopes: 동의 화면에서 함께 동의한 동의항목
  • shared_id:{SHARED_GROUP_ID}: 공유 회원번호 동의항목
  • (예: account_email birthday age_range shared_id:1234)

• 발생 시점: 멤버 앱에서 공유 회원번호 제공에 동의 철회할 때
• 이벤트 타입: User Scope Withdraw
• 스키마: https://schemas.openid.net/secevent/oauth/event-type/user-scope-withdraw
• 카테고리: OAUTH
• 이벤트 페이로드:
  • scopes: 동의 화면에서 함께 철회한 동의항목
  • shared_id:{SHARED_GROUP_ID}: 공유 회원번호 동의항목
  • (예: account_email birthday age_range shared_id:1234)

• 발생 시점: 사용자가 멤버 앱에서 [공유 회원번호] 항목에 동의해 앱과 연결 시
  • 사용자가 카카오 로그인을 통해 대표 앱과 연결되어 있는 경우, 대표 앱에게도 이벤트 전달
• 이벤트 타입: Shared Identity Linked
• 스키마: https://schemas.kakao.com/platevent/kakao/event-type/user-shared-identity-linked
• 카테고리: KAKAO
• 이벤트 페이로드:
  • shared_group_id: 식별자 공유 그룹 ID
  • shared_user_id: 공유 회원번호

• 발생 시점: 사용자가 멤버 앱에서 동의를 철회했거나 연결 해제 시
  • 사용자가 카카오 로그인을 통해 대표 앱과 연결되어 있는 경우, 대표 앱에게도 이벤트 전달
• 이벤트 타입: Shared Identity Unlinked
• 스키마: https://schemas.kakao.com/platevent/kakao/event-type/user-shared-identity-unlinked
• 카테고리: KAKAO
• 이벤트 페이로드:
  • shared_group_id: 식별자 공유 그룹 ID
  • shared_user_id: 공유 회원번호

{
  "aud": "46e658413bbac2346e2b5d58afdfa343",
  "sub": "1376016924431190203",
  "iss": "https://kauth.kakao.com",
  "txm": "d8dfd85e-2690-4306-8898-f93557afaae8",
  "toe": 1774402955,
  "iat": 1774402955,
  "jti": "d7e9f084-53bf-4b39-abcd-d47df4af88b3",
  "events": {
    "https://schemas.kakao.com/platevent/kakao/event-type/user-shared-identity-unlinked": {
      "subject": {
        "sub": "1376016924431190203",
        "subject_type": "iss-sub",
        "iss": "https://kauth.kakao.com"
      },
      "shared_group_id": "111",
      "shared_user_id": "1111"
    }
  }
}

이 문서는 이해를 돕기 위하여 아래와 같은 용어를 사용합니다.

• 식별자 공유 그룹 내에서 동일한 사용자에게 발급되는 ID
• 각 서비스마다 부여되는 고유 회원번호(Service user ID)와는 별도로, 그룹별로 발급 및 관리되는 식별자
• 그룹에 속한 서비스들은 동일한 사용자에 대해 동일한 공유 회원번호를 갖게됨

• 앱이 유효한 공유 그룹에 속해 있어야 합니다.
• 사용자가 공유 그룹의 멤버 앱 중 최소 1개 이상에서 공유 회원번호 제공에 동의해야 합니다.
• 사용자는 카카오 로그인 기능으로 앱에 연결되어 있어야 합니다.
• 사용자는 활성 상태여야 합니다.

• 공유 회원번호를 함께 쓰는 서비스들을 묶는 그룹입니다.
• 그룹 별로 그룹 ID가 부여되며, 이 그룹 ID는 다음 API 호출 시 사용됩니다.
  • 공유 회원번호 조회
  • 동의 요청
  • 동의 철회
• 그룹에 속한 앱은 대표 앱과 멤버 앱으로 구분됩니다.
• 일반적으로 대표 앱은 기준이 되는 서비스로 지정합니다. 아래 예시를 참고합니다.
  • 멤버십 서비스인 경우, A 멤버십이 대표 앱, 하위 브랜드 앱들을 멤버 앱으로 지정
  • 계약 관계인 경우, 가입 기준이 되는 서비스가 대표 앱, 영향 받는 서비스를 멤버 앱으로 지정
  • A 서비스 가입을 위해 B 서비스 가입이 필수인 경우, B 앱을 대표 앱, A 앱을 멤버 앱으로 지정
• 대표 앱은 1개만 지정할 수 있고, 멤버 앱은 여러 개 지정할 수 있습니다.
• 그룹 생성 시 지정한 대표 앱은 변경할 수 없습니다.
• 하나의 앱은 하나의 그룹에만 소속될 수 있습니다. 즉, 어떤 앱이 대표 앱이나 멤버 앱으로 이미 그룹에 속해 있으면, 다른 그룹에는 소속할 수 없습니다.