보안 이벤트 구독

이 문서는 카카오 로그인이 적용된 서비스 사용자 계정의 상태가 변경되었을 때, 해당 정보를 서비스에 공유해 주는 보안 이벤트 구독에 대해 설명합니다.

기능 소개

보안 이벤트 구독은 사용자의 앱 연결 및 해제, 비밀번호 변경, 사용자 계정 비활성화와 같이 계정 상태에 중요한 변화가 생겼을 때, 그 내용을 사전에 등록된 콜백 URL로 전달하는 기능입니다. 서비스는 변경 알림을 통해 세션 종료, 사용자 재인증 요구 등 필요한 조치를 취해 보안을 강화할 수 있습니다.

이벤트는 OpenID 재단에서 개발 및 제공하는 Shared Signals and Events Framework(이하 'SSF') 규격을 바탕으로 설계됐으며, 일부 이벤트는 카카오에서 직접 정의하여 제공합니다.

용어

사용 방법

1. 이벤트 타입을 검토해 제공받을 정보 선택
2. 앱 설정
   • 보안 이벤트 구독 설정(필수): 콜백 URL, 이벤트 타입 설정
   • 동의항목 설정(CAEP, RISC 카테고리 사용 시에만 필수)
3. 메타데이터 조회를 통해 보안 이벤트 구독 시스템 규격 확인
4. 콜백 URL을 통해 전달받은 SET을 검증하고 처리하는 기능 구현 (참고: 보안 이벤트 수신하기)
5. 설정 및 기능 구현이 올바른지 테스트

동의항목 설정

CAEP, RISC 카테고리의 보안 이벤트는 민감 정보를 포함합니다. 따라서 [보안 이벤트 정보 제공] 동의항목 설정 및 사용자 동의가 필요합니다.

필요 시 아래 절차를 진행합니다.

1. 데브톡으로 [보안 이벤트 정보 제공] 동의항목의 설정 권한 요청
2. 권한 부여 후, [내 애플리케이션] > [카카오 로그인] > [동의항목]에서 [보안 이벤트 정보 제공]을 [선택 동의] 동의 단계로 설정 (참고: 설정하기)

지원하는 이벤트 타입

지원하는 카테고리별 이벤트는 아래와 같습니다. 카테고리 이름 선택 시 해당 카테고리 하위에 속한 이벤트를 자세히 확인할 수 있습니다.

OAUTH

OAuth 카테고리는 OAuth 2.0 프로토콜과 관련한 보안 이벤트 타입을 포함합니다.

RISC

RISC 카테고리는 사용자 계정의 비정상적인 활동을 알리는 보안 이벤트를 포함합니다. 동의항목 설정 및 사용자 동의가 필요합니다.

CAEP

CAEP 카테고리는 사용자 계정의 자격 증명과 관련한 보안 이벤트를 포함합니다. 동의항목 설정 및 사용자 동의가 필요합니다.

KAKAO

KAKAO 카테고리는 카카오가 정의하여 제공하는 이벤트 타입을 포함합니다.

메타데이터 조회하기

기본 정보

보안 이벤트 구독 시스템의 규격을 확인합니다.

응답

예제

요청 예제

curl -X GET https://kauth.kakao.com/.well-known/sse-configuration

응답 예제

HTTP/1.1 200 OK
{
    "issuer": "https://kauth.kakao.com",
    "jwks_uri": "https://kauth.kakao.com/.well-known/jwks.json",
    "delivery_methods_supported": "http://schemas.openid.net/secevent/risc/delivery-method/push"
}

보안 이벤트 수신하기

콜백 정보

사용자의 보안 이벤트 발생 시, 보안 이벤트 정보를 서비스의 콜백 URL에 HTTP POST 요청으로 전달합니다. 콜백 요청의 헤더(Header) Content-Type은 application/secevent+jwt, 본문은 보안 이벤트 정보가 담긴 SET 값입니다.

아래는 콜백 URL로 전달되는 요청 예시입니다.

POST /kakao/events HTTP/1.1
Host: callback.example.com
Content-Type: application/secevent+jwt
Accept: application/json

eyJraWQiOiI2NjVhYmVlYzExOGRkZmMyZDNiZjNlMmFkYWU3OT...

서비스는 콜백 URL에 전달된 콜백에 대해 SET 검증 후 성공 또는 실패로 응답해야 합니다.

SET 정보

서비스는 카카오계정의 보안 이벤트 정보가 담긴 SET을 POST 메서드로 전달받습니다. SET은 JWT(JSON Web Token) 형식의 토큰으로, 아래 세 가지 영역으로 구성돼 있습니다.

SET 구성

아래는 헤더, 페이로드 영역에 포함되는 필드의 상세 정보입니다.

헤더

페이로드

Event

보안 이벤트 상세 정보

Subject

SET은 세 영역의 값을 Base64 인코딩(Encoding) 한 후 온점(.)으로 이어 붙인 하나의 문자열로 생성됩니다. 따라서 온점을 기준으로 각 영역을 분리하고, Base64 디코딩(Decoding)하여 내용을 확인할 수 있습니다. 서비스는 SET 검증 후 페이로드 내용을 확인하여 필요한 사용자 계정 보호 조치를 수행할 수 있습니다. 아래는 디코딩된 SET 헤더와 페이로드 예제입니다.

{
    "kid": "665abeec118ddfc2d3bf3e2adae799",
    "typ": "secevent+jwt",
    "alg": "RS256"
}

{
    "iss": "https://kauth.kakao.com",
    "aud": "${REST_API_KEY}",
    "sub": "${USER_ID}",
    "txm": "92a79799-3ae3-4112-8fe2-921c710daa38",
    "iat": 1674702636,
    "jti": "6a1a7a3e-b923-4eb8-886c-cbcbd1621fb0",
    "events": {
        "https://schemas.openid.net/secevent/oauth/event-type/user-linked": {
            "subject": {
                "sub": "1376016924429759243",
                "subject_type": "iss-sub",
                "iss": "https://kauth.kakao.com"
            }
        }
    }
}

SET 검증

서비스는 보안 이벤트 정보에 따른 사용자 계정 보호 조치를 수행하기 전 반드시 SET 내용을 확인하고 검증해야 합니다. 아래 순서로 SET 내용을 확인하고 검증할 수 있습니다.

1. 온점(.)을 기준으로 헤더, 페이로드, 서명을 분리
2. 페이로드를 Base64 방식으로 디코딩
3. 페이로드의 iss 값이 https://kauth.kakao.com와 일치하는지 확인
4. 페이로드의 aud 값이 서비스 앱의 REST API 키와 일치하는지 확인
5. 서명 검증

서명 검증은 아래 순서로 진행합니다.

1. 헤더를 Base64 방식으로 디코딩
2. OIDC: 공개키 목록 조회하기를 통해 카카오 인증 서버가 서명 시 사용하는 공개키 목록 조회
3. 공개키 목록에서 헤더의 kid에 해당하는 공개키 값 확인
   • 공개키는 일정 기간 캐싱(Caching)하여 사용할 것을 권장하며, 지나치게 빈번한 요청 시 요청이 차단될 수 있으므로 유의
4. JWT 서명 검증을 지원하는 라이브러리를 사용해 공개키로 서명 검증
   • 참고: OpenID Foundation, jwt.io
   • 라이브러리를 사용하지 않고 직접 서명 검증 구현 시, RFC7515 규격에 따라 서명 검증 과정 진행 가능

검증 성공 응답

SET 수신 서버가 콜백 수신 후 SET 검증에 성공한 경우, 본문 없이 HTTP 상태 코드 202 Accepted로 3초 내에 응답해야 합니다. 아래 예제를 참고합니다.

HTTP/1.1 202 Accepted

검증 실패 응답

SET 수신 서버가 콜백 수신 후 SET 검증에 실패한 경우, 아래 형식으로 3초 내에 응답해야 합니다.

• HTTP 상태 코드: 400 Bad Request
• 헤더의 Content-Type: application/json
• 본문: JSON 형식으로 RFC8935 규격에 따라 에러 코드(err)와 이유(description) 포함

아래 예제를 함께 참고합니다.

HTTP/1.1 400 Bad Request 
Content-Type: application/json
{
    "err": "invalid_key",
    "description": "Key ID 12345 has been revoked."
}

실패 응답 에러 코드

테스트

보안 이벤트 수신 처리가 올바르게 구현되었는지 [도구] > [보안 이벤트 테스트]에서 확인할 수 있습니다.

🅐 앱: 테스트 대상 앱 선택 🅑 콜백 URL: 보안 이벤트 설정 시 입력한 콜백 URL 표시 🅒 카테고리: 보안 이벤트 카테고리 선택, 테스트 시에는 모든 카테고리 선택 가능 🅓 이벤트 타입: 테스트 전송할 보안 이벤트 타입 선택, RISC와 CAEP 카테고리는 권한이 필요하나 테스트 시에는 이용 가능 🅔 카카오계정: 앱에 등록된 팀원 중 이벤트를 발송할 팀원 선택, 단, 선택한 계정은 해당 앱에 [연결]되어 있어야 이벤트를 발생시킬 수 있음 🅕 파라미터: 일부 카테고리의 경우 파라미터 입력 필요, 아래 참고

[발송]을 누르면 페이지 하단에 아래와 같은 테스트 정보가 나타납니다.

🅐 보안 이벤트 요청: 테스트 전송된 요청 전문, 콜백 URL 미설정 시 Host와 URL 미포함 예시 출력 🅑 보안 이벤트 토큰: 🅐의 요청에 포함된 SET을 디코딩한 값, header와 payload 각각 출력, 디버깅 시 참고