Security event subscription

This document explains how to use the security event subscription feature in Kakao Login.

Overview

Security event subscription is a feature that delivers users' security event information to services using Kakao Login. It is designed based on the OpenID Foundation's SSE (Shared Signals and Events) specification. It enables the service to take more active security actions. For example, you can receive information about a user's security events, such as linking and unlinking apps, changing passwords, and disabling accounts.

Security event information is passed to the service as a SET (Security Event Token). The service must process the SET passed through the callback URL as instructed in Receiving security events.

NOTE: SET delivery process of security event subscription system

1. Receiving the users' security event information.
2. Issuing a SET with the specified security event information.
3. Pushing the SET to the service's callback URL.

Before you begin

How to use

To use the security event subscription feature, follow these steps to configure your app and implement the feature.

1. Review Security event types and determine the required types for the service.
2. Change the app settings.
   • Set Security event subscription: Set callback URL and event type.
   • Set Consent items: Required when using CAEP and RISC categories.
3. Request Get metadata to check the security event subscription specification of Kakao Login.
4. Implement a feature to validate and process SETs delivered via callback URL. For more information, refer to Receiving security event.
5. Test whether the settings and feature implementation are correct.

Set Security event subscription

You need to set the callback URL to receive security event information and the event type to subscribe to in [My Application] > [Kakao Login] > [Security Event]. For more information, refer to Prerequisites.

Set Consent items

Some categories require setting consent items and getting the users' consent to provide security event information. For more information, refer to User consent.

Get metadata

To check the security event subscription specification, request as below.

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

Below are response details and examples.

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"
}

Security event types

The security event subscription system delivers the following security event information to the service.

* Not provided by default. Refer to Set Consent items.

The following is a list of Security event types by category.

Receiving security events

Callback information

When a user's security event occurs, the security event information is delivered as an HTTP POST request to the service's callback URL. Content-Type of the callback request header is application/secevent+jwt, and the body is a SET value containing the security event information.

Below is an example of the request that is delivered to the callback URL.

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

eyJraWQiOiI2NjVhYmVlYzExOGRkZmMyZDNiZjNlMmFkYWU3OT...

The service must respond with success or failure after SET validation for the callback delivered to the callback URL.

SET information

The service receives a SET containing security event information of the Kakao Account through the POST method. SET is a JWT (JSON Web Token) type token and consists of the following three areas.

SET configuration

Below are the details of the fields in the Header and Payload.

Header

Payload

Event

Security event details

Subject

The SET is generated as a single string of three parts that are Base64-encoded and concatenated with the period (.). The contents can be verified by Base64-decoding after separating each part based on the period. After SET validation, the service can verify the payload contents to perform any necessary user account protection actions. Below is an example of a decoded SET header and payload.

{
    "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 validation

The service must check and validate the contents of the SET before performing user account protection actions based on security event information. You can check and verify the SET contents in the following order:

1. Separate the header, payload, and signature based on the period (.).
2. Decode the payload in Base64.
3. Verify that the iss value in the payload matches https://kauth.kakao.com.
4. Verify that the aud value in the payload matches the service app's REST API key.
5. Verify the signature

Signature verification proceeds in the following order.

1. Decode the header in Base64.
2. Request OIDC: Get public key to get the list of public keys used by the Kakao authentication server for signing.
3. Check the public key value corresponding to the kid of the header in the public key list.
   • Caching the public key for a certain period is recommended, and note that requests may be blocked if they are too frequent.
4. Verify the signature with the public key using a library that supports JWT signature verification.
   • NOTE: OpenID Foundation, jwt.io
   • When implementing signature verification directly without using a library, the signature verification process can be performed according to the RFC7515 specification.

Success response

If the SET receiving server receives a callback request via the callback URL and the SET validation is successful, you should respond with the HTTP response code 202 Accepted with no response body. See the example below.

HTTP/1.1 202 Accepted

Failure response

If the SET receiving server received a callback request via the callback URL but failed the SET validation, you should respond with HTTP response code 400 Bad Request. The Content-Type of the response header should be application/json, and the body should contain the error code (err) and the reason (description) in JSON format according to RFC8935. See the example below.

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

Failure response error codes

Test

You can send a security event for the test in [Tools] > [Security Event Test]. You can use this feature to check whether the security event receiving is implemented correctly.

🅐 App: Select the app to test. 🅑 Callback URL: If you have finished setting up the Security event, output the set callback URL. 🅒 Category: Select a security event category. All categories can be selected for testing. 🅓 Event type: Select a security event type to send. All types can be selected for testing.

After selecting [Send], the test information appears at the bottom of the page, as shown below.

🅐 Security event request: Full text of the test request. Host and URL are excluded in the output when the callback URL is not set. 🅑 SET: The decoded value of the SET contained in the request is in 🅐. The header and payload are output respectively. Refer to this when debugging.