페이지 이동경로
  • Docs>
  • Kakao Login>
  • Concepts

Kakao Login

Concepts

This document introduces Kakao Login APIs and their features.

Overview

The Kakao Login API enables users to log in to your app with their Kakao Accounts in a fast, simple, and secure way, which helps to retain users on your app and maximize the number of people using your app.

You can integrate Kakao Login into your service in the following cases. Note that the functions of creating and deleting users' accounts are not provided by Kakao. Thus, You must implement the functions in your service internally since Kakao does not access or modify service data, such as saving or deleting user information.

Kakao Login use cases

Kakao Login

Here are the functions required for Kakao Login:

Name Description
Login Identifies users through their Kakao Accounts and gets permission to call Kakao APIs with the user information. You can collect user data, instead of requiring users to input their service IDs and passwords for identification. Through the Kakao Login API, a user can link to your app, and tokens are issued. The tokens are used to identify a user and make an API call with the user information on the Kakao platform.
Link Links an app with a Kakao Account so that you can call the Kakao APIs from the app.
Logout Expires the access and refresh token issued through the login process to have a user log out. When a user requests to log out or a service requests to make a specific user log out, the Logout API is invoked, and then the tokens expire.
Even after the logout, a user can log in and link to your app again using the same Kakao Account. However, make sure that the previous user information stored on the app cannot be recovered.
Unlink Unlinks your app with a user's Kakao Account. After a user unlinks from your app, you cannot make user-related API calls with the user's information in your app anymore, and all of the user data is completely deleted from the Kakao platform.
Even after the unlink, a user can log in and link to an app again using the same Kakao Account. However, make sure that the previous user information stored on the app cannot be recovered.
Token Verifies if you are authorized to make API calls by using the access token that is issued during the Login process.

Kakao Sync

Kakao Login enables users to sign up or log in more conveniently by linking their accounts to your service. If you want to increase the membership rate in your service or perform sophisticated target marketing according to users' demographic information, consider integrating Kakao Sync, an extended version of Kakao Login.

Kakao Sync provides the following two key features:

  • Simple Signup: allows users to consent to all of the Terms of Service, provision of personal information to third-party, and channel additions in the Consent screen without inputting information.
  • Kakao Account information: allows you to leverage business solutions such as Kakao Talk Channel more effectively.
Function Kakao Login Kakao Sync
Allow your service's app to access the user information saved in Kakao Account as long as the user consents.
Allow users to log into your service automatically on the device where Kakao Talk is installed.
See Auto-login from Kakao Talk.
Ask users for consent to provide their personal information on the Consent screen.
Ask users for consent to add a Kakao Talk Channel on the Consent screen,
which makes more users add your service's Kakao Talk Channel.
See Business channel.
Ask consent to your service's Terms of Service on the Consent screen,
which allows users to sign up for your service more conveniently in one click.
See Kakao Sync Simple Signup.
Increase more users by allowing those who visit an offlinestore to sign up via QR code.
Send targeted messages according to users' age range, purchase history, visit frequency, and so on.
Place a targeted Display ad according to users' demographic information.
Check the terms that a user has agreed to, and ask consent to the terms that a user has not agreed to.
See Design terms and policies.
Prompt a half-view asking consent to terms of services and personal data for a sign-up or link while chatting with a chatbot of your Business channel without moving to a separate page.
Prompt a half-view asking consent to provide user's personal data required for your service while chatting with a chatbot of your Business channel without moving to a separate page.
See 프로필이용 플러그인(Usage of profile plugin), provided in Korean only.

Login

When a user logins with Kakao, Kakao authorizes a third-party application (hereinafter referred to as 'app')A project associated with your service. An app is used to register your service information on the Kakao platform and get permission for the use of Kakao APIs. to access limited information. The authorization process with Kakao Login complies with Open Authorization (OAuth) 2.0, a standard authorization framework. For detailed specifications, refer to OAuth 2.0 Authorization Framework (RFC6749). If you want to implement Kakao Login for both authorization and authentication, you can use OpenID Connect (OIDC) protocol.

Login flow

Here is the login process based on OAuth authorization.

Login process Step 1. Kakao Login
  1. Once a user requests to log in with Kakao, Kakao requests user's credential and asks users' consent according to a user environment or choice. See Authorization methods according to user environments for more details.
    - Login with Kakao Talk: As Kakao Talk is launched, the user is logged in with the Kakao Account information linked to Kakao Talk.
    - Login with Kakao Account: In a web environment or on a device where Kakao Talk is not installed, the user is asked to log in with the user’s Kakao Account ID and password.
  2. Once the user logs in and gives permission for your app to access the user's data, the Kakao authorization server validates the user’s credentials and issues an authorization code. The user is redirected back to your app with the authorization code via redirect_uri.
  3. Your app requests to exchange the issued authorization code for an access token and a refresh token.
  4. The Kakao authorization server issues an access token and a refresh token based on the authorization code, and provides authentication. See Token information to learn more about the access and refresh token.

If a user's Kakao Account has successfully been linked with your app, the tokens are issued. Then, you can retrieve information of the user who is currently logged in through the Retrieving user information API to use the user data for your service.

If a user fails to log in, the first thing you need to do is checking out its response. The Kakao server sends the response code, including the reason for the failure. In this case, check its cause and fix the problem by referring to Troubleshooting.

Step 2. Check signup status
  1. The service server requests to retrieve user information with the issued access token.
  2. The Kakao API server validates the access token passed in the request. If the token is valid, respond to the request sent from the service server.
  3. The service server checks if the user has been signed up for the service by using the provided user information, and handles the user differently depending on the user's signup status.
    • For a user who has already signed up: Skip to Step 3. Log into service.
    • For a user who has not signed up: Store the user information provided by Kakao in the service database to complete signup.
Step 3. Log into service
  1. If the user has been signed up for the service, the service server creates a login session.
    NOTE: If you use OpenID Connect, you can use the issued ID token as a service session.
  2. The service client completes the login and shows the user to the service page in logged-in status.

Token information

Tokens are used to verify a user's identification, allowing you to keep using Kakao APIs without additional verification. The Kakao SDKs have a built-in token management feature. On the other hand, if you use a REST API, you need to request extra APIs to retrieve or refresh the tokens.

Here are three types of tokens you can get when you integrate Kakao Login. The validity periods of tokens differ depending on the platforms, as described in the below table.

Token Type Role Valid period
Access token Used to give your app permission to request data and to authenticate API calls. Android, iOS: 12 hours
JavaScript: 2 hours
REST API: 6 hours

NOTE: Has relatively short validity period due to security reasons.
Refresh token Used to gain a new access token and refresh token without an additional verification process for a certain period. 2 months

NOTE: Possible to refresh the tokens only a month before the access token expires.
ID token Used to authenticate users. See ID Token.

IMPORTANT: Only returned if you integrate OpenID Connect, and required to verify in the client-side.
Android, iOS: 12 hours
JavaScript: 2 hours
REST API: 6 hours

NOTE: Has same validity period as the access token.

Authorization methods according to user environments

The Kakao Login API proceeds the authorization process differently according to platforms, user environments, or login flows as follows.

Type Environment Description
Android SDK Android mobile device The Kakao Account information linked with Kakao Talk is used.
If Kakao Talk has not been installed on a user's device, the user needs to input Kakao Account information on a web page.
iOS SDK iOS mobile device The Kakao Account information linked with Kakao Talk is used.
If Kakao Talk has not been installed on a user's device, the user needs to input Kakao Account information on a web page.
JavaScript SDK PC or mobile web browser On mobile: The Kakao Account information linked with Kakao Talk is used.
On PC: Users need to input Kakao Account information on a web page.
REST API PC or mobile web browser On mobile: Users need to input Kakao Account information on a web page. When a user selects [Login with Kakao Talk] on a web page, the Kakao Account information linked to Kakao Talk is used.*
On PC: Users need to input Kakao Account information on a web page.

* 'Login with Kakao Talk' is only supported on the most commonly used web browsers such as Chrome or Safari.

* 'Login with Kakao Talk' is not supported on a mobile app using a REST API.

Process of Login with Kakao Talk Process of Login with Kakao Account
Basic verification method of Kakao Login

The Kakao SDK provides the easiest verification method for users as a default, but also allows you to select a different verification method. Refer to each development guide according to the platform that you are developing with.

Auto-login from Kakao Talk

The Auto-login from Kakao Talk (Auto-login, for short) is an extended feature of Kakao Login, which allows users to log in automatically from Kakao Talk in-app browser, and shows a different page depending on the user's login status. This feature allows for a more efficient and convenient service for users according to their signup status when accessing your service page in the Kakao Talk in-app browser.

Example that shows the Auto-login feature

The Auto-login process is broken down into three steps.

Step 1. Check for which browser the service page is being accessed on

This feature only works through the Kakao Talk in-app browser. To check if the user access the page through the Kakao Talk in-app browser, check if KAKAOTALK is included in UserAgent.

UserAgent
Browser Rule Description
Kakao Talk in-app browser KAKAOTALK Mozilla/5.0 (Android; Mobile; rv:13.0) Gecko/13.0 Firefox/13.0 KAKAOTALK
Step 2. Request authorization code for auto-login

After checking that the user browser is the Kakao Talk in-app browser, add the prompt parameter to the request of Getting authorization code API and set it to none.

Refer to the following developement guides to see how to request in detail:

Step 3. Present different pages according to the response

If the request is successful, check its response to figure out whether the user has signed up or not. Then, present different pages according to the user's signup status.

For users who have signed up

If a user has signed up, an authorization code is issued. Thus, the user does not go through the login process of inputting the user's ID and password. In this case, request tokens using the issued authorization code to complete the login process, and then present your service page to a user in a logged-in state.

For users who have not signed up

If a user has not signed up, the user cannot complete the login. In this case, the error response is returned with consent_required, indicating that the user's consent is required to use a service. Thus, you must present a service page to the user in a logged-out status.

Here is a sequence diagram showing the Auto-login process.

Auto-login flow

Here is one of the Auto-login scenarios. As an example, let's see a product page that is commonly shared through Kakao Talk.

  • See the browser information to check if the user accessed the page through the Kakao Talk in-app browser.
  • If the user has accessed the page through the Kakao Talk in-app browser, add prompt=none in the login request.
  • If the user has signed up through Kakao Sync, you will get an authorization code and show a product description page in a logged-in state. In this case, users do not need to log in to buy the product on the page.
  • If the user has not signed up, an error returns. In this case, show the user the product page in a logged-out state. If the user wants to log in to make a purchase, prompt the user to log in, not using the Auto-login feature.

Logout

To log a user out of your service, you can use the Logout API which invalidates the access token and the refresh token issued through the Kakao Login process.

The logout proceeds differently depending on how the Logout API is requested as follows:

What is used in request Used tool Request result Logout result
Access token Kakao SDK The requested access token expires, and the access token managed by SDK is also deleted. The user is logged out of the device where the corresponding access token is used.
Access token REST API The requested access token expires. The user is logged out of the device where the corresponding access token is used.
Admin key REST API All valid access tokens of the requested user expire. The user is logged out on all devices.

After a user is logged out, you cannot call any Kakao APIs by using the expired access token in the service. You need to implement the subsequent process after a user is logged out of your service, such as redirecting the user to the main page or changing the user status.

Ensure that the Logout API enables users to log out of service only without affecting the Kakao Account login session. If you need to make users log out of their Kakao Accounts as well as your service, use the Logout of service and Kakao Account functionality.

Logout of service and Kakao Account

If you want to log a user out of both Kakao Account and a service where the user requests to log out, you can use the add-on feature, 'Logout of service and Kakao Account'. The basic Logout API invalidates the access and refresh tokens but Kakao Account login session is still retaiend. On the other hand, if you use the 'Logout of service and Kakao Account' feature, both of the Kakao Account session and the service session expire.

When a user attempts to log out in a service that this feature is applied, the user is redirected to a bridge page where the user can select between [Log out of this service] and [Log out of the service and Kakao Account].

Screenshot of logout of service and Kakao Account

The logout proceeds differently depending on the Kakao Account's login status and which option a user selects.

  • If a user selects [Log out of this service], the user is redirected to the Logout Redirect URI set in [My Application] > [Kakao Login] > [Logout Redirect URI].
  • If a user selects, [Log out of the service and Kakao Account],
    • If the Kakao Accout session is not retained, the user is redirected to the set Logout Redirect URI.
    • If the Kakao Accout session is retained, Kakao ends the Kakao Account session and redirects the user to the set Logout Redirect URI.

To implement the 'Logout of service and Kakao Account' feature in your service,

  1. Register Logout Redirect URI which users are redirected to when the logout request is successful.
  2. Develop 'logout of service and Kakao Account' feature by referring to REST API. This API invalidates the access token and redirects a user to the registered Logout Redirect URI. If a user selects [Log out of the service and Kakao Account] and the user's Kakao Account session is retaiened, this API also expires Kakao Account session.
  3. Expire the user's service session in your server-side at the moment when the user is redirected to the Logout Redirect URI.

Link

The link indicates the connection status between a service and a user's Kakao Account.

When a user attempts to log into a service with the Kakao Account for the first time, the user is asked to agree to provide personal information to a third party and Terms of Service on the Consent screen. Once the user agrees to permit the service to access the user's personal data, the user's Kakao Account is linked with the service app.

Once the user is linked to a service,

  • The user can use the service without going through an extra signup process.
  • The third-party service can access user data or use Kakao services by calling the Kakao APIs with the tokens passed from Kakao.

Linking vs. Creating user account

Link Creating user account
Definition Process of registering the user in the Kakao Developers app. A third-party service can use the user data on the Kakao platform when a user permits to use the data.
Refer to User consent.
Process of registering a user as a member in the service server's database.
How to use Use Kakao Login API.
If using a REST API, you must call both the Getting authorization code API) and Getting tokens API.
Not provided by Kakao Platform.
Required to implement in your service internally.
For an easier implementation, consider Kakao Sync Simple Signup.
Post-processing The link does not affect the user database in the service server since Kakao cannot access the service data.
If a new user is linked to your service, you must register the user in your service server's database. Only after that a new account is created.
Required to register the user data in the service's user database.
Otherwise, the signup is not completed.
See Creating user account.

Unlink

As opposed to the concept of link, the unlink functions to disconnect the connection between a service app and a user's Kakao Account.

How to handle unlink request

Depending on how users are unlinked, you need to procced differently as follows:

Case Action
If a user deletes the user's Kakao Account. The Unlink API is called. Then, the user's Kakao Account is unlinked from your service app as the tokens issued through Kakao Login are deleted.

IMPORTANT: To get notified who are unlinked from your service and handle the unlinked users, we recommend using the unlink callback function.
If a user selects [Disconnect] on the Manage Connected Services page.
If a user requests to unlink through the Kakao Customer service
If a user has not completed a signup.
If a user deletes the user's service account. Handle the account deletion in your service by deleting the user data stored in the user database.
In addition, you must call the Unlink API to unlink the user's Kakao Account from your app.
See Deleting service account.

After unlink

After a user's account is unlinked from your app,

  • You cannot make API calls associated with the user information.
  • Users can re-link to your app by loging in with their Kakao Account.
    • After the re-link, the previous app usage history cannot be recovered.
    • After the re-link, the app issues the same service user ID for the user. If your service retains the user’s data under the service user ID, you can provide the same service for the user.
  • According to the Kakao Developer's Terms of Service and Privacy Policy, you should handle users' Kakao Account information that they have provided to use your service.
IMPORTANT: Unlink for users who have not completed a signup

Starting December 28, 2020, the users who have not completed a sign-up for third-party services will have their accounts set to Unlink. This will be processed every day. If users do not complete sign up and their accounts will be changed to the Unlink state. In this case, you can get an unlink callback. Refer to Notice for more details.

Unlink on Manage Connected Services

Users can unlink their Kakao Accounts from services in [General Settings] > [Privacy] > [Kakao Account] > [Manage Connected Services] on Kakao Talk application or [Use Your Account] > [Manage Connected Services] on the Kakao Account page.

How to unlink on Kakao Account page and Kakao Talk

Disconnect vs. Delete All Data

Depending on whether the Unlink callback function is implemented in your service, the buttons on the Manage Connected Services page are displayed differently.

Screenshot of Managed Connected Services page

If you do not use the Unlink callback function, the [Disconnect] and [Delete All Data] buttons are displayed on the Manage Connected Services page. In this case, users must request to unlink with [Disconnect] and request to delete user information with [Delete All Data] respectively.

If you use the Unlink callback function, [Delete All Data] is displayed only since the Kakao platform notifies your service of a user's request to unlink and delete user information when the user selects this button.

Each button functions as follows:

Button name Disconnect Delete All Data
Function Unlinks a user's Kakao Account from the service app. Unlinks a user's Kakao Account from the service app,
and requests to delete the user data from the service server's database to handle the account deletion.

IMPORTANT: This button is displayed only when the unlink callback function is enabled.
IMPORTANT

If your service provides iOS apps, you must provide account deletion within your app along with account creation according to the App Store Review Guidelines. Likewise, if you integrate Kakao Login into your service, you must also provide a function to unlink from your app since users are linked to your app when they log in with Kakao. This applies to all apps submitted after January 31, 2022.

Managing service accounts

Creating service account

While the link between your app and Kakao Account is processed on the Kakao platform, the signup process to register as a new member with Kakao Account should be processed in the service database. Be sure that Kakao API just passes the result in response to your request or processes the information, not access your service data.

Process of signup with Kakao Account

When a user agrees to provide the user data on the Consent screen, find a match for the user with the provided user data.

  • For the existing users, link the user's account with your service.
  • If a user is new to your service, you need to register the user data in your service database to create a new account.

In the signup process,

  1. Decide what types of user data your service requires to use your service.
  2. Check which data your service needs and which data Kakao provides. If Kakao does not retain specific data, collect it when a user signs up. However, this might cause a user to quit the signup process for the inconvenience, so collect the user data only when your service needs or a user attempts to use the related service if necessary.
Process of Simple signup

Deleting service account

If a user requests to delete the service account,

  1. Call the Unlink API to unlink the user's Kakao Account from your service app.
  2. Delete the user information in the service database to terminate the user's service account.

If a user's service account is deleted, the user's Kakao Account also must be unlinked from the service. Otherwise, the Kakao platform considers the user is still using the service.

Concept of unlink

Handling Kakao Login users

If your service implements a sign-up process, you also need to implement a process to handle users who attempt to log in or sign up with Kakao Account.

For user's convenience, we recommend allowing users to log in with the existing user data through Kakao Login.

Here is a flow that shows how to classify users when linking the users with the existing user data stored in the service. Basically, all policies and processes related to managing users are determined by the service, but this flowchart would be helpful to provide users with a seamless and convenient signup process and use of the service.

Flowchart of Kakao Sync

Identify registered users

At the moment when a user attempts to link with your service, you can figure out whether the user has already been signed up.

You can check if Kakao retains the data of the new users by using some unique data such as Connecting Information (CI), phone number, or email. Then, map users by referring to Handle service members.

To check if a user is registered in a service that adopts Kakao Sync, the value of Connecting Information (CI) saved in Kakao Account is generally used. However, if your service does not collect CI, you can also refer to phone number, email, or birthday.

IMPORTANT

Email and phone number are subject to change. Except for a service user ID, CI, and legal name, users may change other Kakao Account information at any time. If you use changeable user data such as email as a service user ID or a user identifier, problems may occur when the user data is changed.

Handle service members

Depending on whether users' data is stored in the service database, you can handle the users differently as follows:

Cautions when linking the existing user data to Kakao Account information
  • Even though user data completely matches the existing user data, ask the user if the account information is the user's and proceeds to link the account. Some users may not want to link their accounts with Kakao Accounts, or user data may not belong to the user.
  • Consider that the personal information provided by Kakao can be changed when designing and developing your service. Users may change their personal information such as birthday and gender in the account at any time and delete the Connecting Information (CI) value in Kakao Account if necessary. Or new information that is not passed when signing up may be passed additionally when a user logs in.
If all user data matches

If there is user data that matches Kakao Account information, notify a user of the registered status and ask the user to log in with Kakao using the existing account.

  • If a user agrees to link with the existing account, add the Kakao Account information to the existing user data and allow the user to log in with Kakao using the existing account.
  • If a user does not agree to link with the existing account, add the user's account in the service server's database as a new member.
Scenario if user data matches
If only some user data matches

If only some user data matches with Kakao Account information, it is recommended to link the user to the user's Kakao Account rather than registering as a new member.

Notify a user of the account that is assumed as the user account and link the user to the user's Kakao Account by asking the user to input the password.

Here is a representative example of one of the methods that link to existing user data.

Scenario if only some user data matches
If no user data matches

If user data that matches a new user account does not exist in your service database, create a new account for the user. However, the user may have been signed up previously for the service. For this case, you can request the user to input the existing account information to link with the existing account.

Scenario if no user data is matched

Provide 'Linking with my account' option

Some users who actively use your service may want to link the service accounts to their Kakao Accounts. Other users who use the service with other social media accounts may wish to link the accounts to the Kakao Account. For these cases, you can provide the '소셜 계정 연동 기능(Linking a social media account)' option in your service to link their service accounts to their Kakao Accounts through Kakao Login or Kakao Sync Simple Signup.

Link with Kakao Account on Kakao Talk

User consent

Kakao requests consent to the required user information when a user logs in with Kakao for the first time. After a user logs in Kakao, the user information stored on the Kakao platform can be provided to each service through Kakao APIs. Ensure that the user information is only available when users agree to provide their personal information to third-parties. If users do not agree, Kakao cannot provide the information when your app requests even though the user information is saved in Kakao Account.

Consent screen

When you request the Getting authorization code API or Login APIs through the Kakao SDKs, the Consent screen configured in [My Application] > [Kakao Login] > [Consent Items] is prompted to users as follows.

Configured consent screen

The scope set as 'Consent during use' is not displayed on the Consent screen prompted when a user attempts to log in. If you request additional consent for the scope, the consent screen with the scope added as a [Required consent] is prompted at the moment when the user information is required.

Scope

Scope refers to the data that your app can access through Kakao APIs. A scope is also referred to as 'consent item' on the Consent screen or user interface shown to end-users.

How to check scope ID

You can configure consent items needed for your service under 'Personal Information' and 'Permission'. Go to [My Application] > [Kakao Login] > [Consent items] page. You can check the 'Scope ID' column for each scope. You can also refer to Manage consent items > Personal Information and Permission.

When to use scopes

You can set the scopes when you want to specify the scopes to obtain consent by passing the scope parameter when you call the Login API or Requesting additional consent API. Refer to Scope parameter.

How to check which scope required consent

When you request the Retrieving user information API, the response includes ${FIELD_NAME}_needs_agreement with a boolean type provided along with each user information. The key is provided to inform that the scope requires consent for your app to access the data and only provided when the scope is enabled on the Consent Items page.

Here is a scenario according to the presence of the user information.

  • If the user information is stored in Kakao Account, you can retrieve the information as far as the user has consented.
    • true returns: You can obtain consent to use the stored user information by Requesting additional consent.
    • false returns: The user information has already been providing so requesting consent is not necessary.
  • If the user information is NOT stored in Kakao Account,
    • true returns: You can obtain consent through Provision after collecting information feature.
    • false returns: it is recommended not to use the user information. If required, you can collect it internally.
How to revoke consent to a scope

You can revoke the user's consent by calling the Revoking consent API.

This API is also called when a user withdraws the Optional consent items in [General Settings] > [Privacy] > [Kakao Account] > [Manage Connected Services] on the Kakao Talk application or in [Use Your Account] > [Manage Connected Services] on the Kakao Account page.

Consent screen

Request additional consent

The Requesting additional consent API is used to request permission from the users to provide their user information or to use some functions which are provided by the Kakao platform.

It is recommended to request consent to scopes at the moment when your service needs, rather than collecting all information when a user logs in.

IMPORTANT: What to collect internally

If a user refuses to provide their user information, Kakao cannot collect and provide it regardless of using the Requesting additional consent API. In this case, the user information needs to be collected internally. Terms of Service is not applicable for this API. If it is required to add a Terms of Service in the middle of operating your service, you need to obtain additional consent through an internal page.

Scope parameter

To request additional consent, adding the scope parameter when you request the Login API (or Getting authorization code API if using a REST API).

Whether to use the scope parameter and the user's linked status affect which API is invoked and which scopes are included on the Consent screen as follows:

Whether user is linked to app Whether to pass scope in request How API works User experience
X X Login API is invoked. Consent screen asking permission for the scopes specified in [My Application] > [Consent Items] is prompted when a user attempts to log in.
X O* Login API is invoked. Consent screen asking permission for the scopes as specified through the scope parameter in the request when a user attempts to log in.
O X Login API is invoked. Consent screen does not appear.
Tokens are issued for the scopes specified in [My Application] > [Consent Items].
O O* Requesting additional consent API is invoked for the scope passed through the scope parameter in the request. Consent screen asking for additional consent to the specified through scope is presented when a user performs an action that requires the scope.

If OpenID Connect is enabled, you must add 'openid' to 'scope' along with the scope values you want to obtain consent. If not, you cannot get an ID token even though OIDC is enabled since the OAuth protocol is applied.

Best practice
Step 1. Check required consent item

There are two main cases when your service requires additional user consent during use of the service:

  • When your service requires additional user information to allow users to use your service.
  • When your service requires consent for a specific scope to call a Kakao API.

If you need to obtain user consent for additional user information, you can call the Retrieving consent details API first to check what scopes a user has already consented.

You can also check it by calling the Retrieving user information API. When you request this API, only the scopes that a user has consented are returned. In this case, you can check the value of ${FIELD_NAME}_needs_agreement to figure out if the scope requires consent. If the user consents to the scope and the user information of the scope is available to provide, the value of scope is returned to true. For more information, refer to needs_agreement.

The following sample snippet is the response of the Retrieving user information API when the user has not agreed to provide Email.

Sample: If user has not agreed to provide Email

{
  "id": 1633204891,
  "connected_at": "2021-02-18T06:13:55Z",
  "properties": {
    "nickname": "춘식이",
    "profile_image": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_640x640.jpg",
    "thumbnail_image": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_110x110.jpg"
  },
  "kakao_account": {
    "profile_needs_agreement": false,
    "profile": {
      "nickname": "춘식이",
      "thumbnail_image_url": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_110x110.jpg",
      "profile_image_url": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_640x640.jpg",
      "is_default_image": false
    },
    "email_needs_agreement": true       // Requires consent to Email
  }
}

The response above does not include Email information since the user has not agreed to the Email scope. However, if the value of email_needs_agreement is true, you can get email information if the user agrees. To use the user's Email information in your service, you must request additional consent to Email.

If the Kakao API request fails due to insufficient scopes, you can figure out which API (api_type) requires consent to which scopes (required_scope) by checking the error response. You can also see allowed_scopes to check the scopes that the user has already agreed to. Only after you obtain consent by requesting additional consent to the scope of required_scope, you can use the corresponding API.

Name Description
required_scopes Scopes that a user needs to consent to use the API
allowed_scopes Scopes that a user has consented

The following sample snippet is the response of the Kakao Talk messaging API when the user has not agreed to the required consent item.

Sample: Fail due to no permission to send Kakao Talk message
HTTP/1.1 403 Forbidden
{
  "msg": "insufficient scopes.",
  "code": -402,
  "api_type": "TALK_MEMO_DEFAULT_SEND",
  "required_scopes": [
    "talk_message"
  ],
  "allowed_scopes": [
    "profile",
    "account_email"
  ]
}

required_scopes in the response above indicates that you need to obtain consent to talk_message from the user. Only after requesting additional consent to talk_message, you can call the API.

Step 2. Request additional consent

Request additional consent to the required scope for the corresponding API. For the scope key, check 'Scope ID' in the [My Applications]> [Kakao Login] > [Consent items] or see Manage consent item.

To see how to implement, refer to the following development documentation:

Step 3. Reissue token and check result

When you request additional consent, the user may not accept your request by clicking [Cancel]. For this case, you need to check if the user has granted the consent request.

If the user agrees to the required consent item, the response of the Requesting additional consent API is the same as the Getting authorization code API. In this case, you need to get new tokens using the newly issued authorization token by requesting the Getting tokens API.

After that, check the response of the Getting tokens API, and see if the scope you requested additionally is included in scope. If included, you can get the user information of the scope by requesting the Retrieving user information API.

Sample: Response of the Getting tokens API
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "token_type":"bearer",
    "access_token":"${ACCESS_TOKEN}",
    "expires_in":43199,
    "refresh_token":"${REFRESH_TOKEN}",
    "refresh_token_expires_in":25184000,
    "scope":"account_email profile"     // Scope user has agreed to
}

You can figure out which scopes are required to obtain consent additionally to use a specific API through scope in the response of the Getting tokens API. You can also check if the API request is succeeded. If the user has disagreed or an error occurs, request additional consent or disable the service's function for the user. Allow a user to use your service only when the user has agreed to the required scope.

User information

After a user logs in, you can request user information through the Kakao APIs, including the Retrieving user information API. Kakao provides user information as far as users agree to provide.

Here are the kinds of user information retrieved through the respective Kakao APIs:

IMPORTANT

The contents of the API response can be added or deprecated. For the case that properties are added, you need to implement exception handling. For change properties, we will notify you through DevTalk so that you can take action.

Data passed through the Retrieving user information API

You can retrieve the following user information through the Retrieving user information API. You can use the retrieved user information as member information in your service when the user logs in with Kakao Login or signs up through Kakao Sync Simple Signup. For the information that Kakao does not manage such as passport number, you must collect it separately in your service.

For detailed information including data types and formats, refer to REST API.

Name Description
id Service user ID.
kakao_account Kakao Account information.
connected_at The time when the user is linked with a service.
synched_at The time when the user is logged in through Kakao Sync Simple Signup.


Providing conditions: Only passed for Kakao Sync service users. In this case, its value is the same as connected_at.
properties Additional user information saved on the Kakao platform to use it later.
Refer to Prerequisites > Manage user properties.

Data included in Kakao Account

Each user information of the Kakao Account includes a field whose name ends with needs_agreement, indicating whether user consent is required to provide the information. For more details, refer to needs_agreement.

Permission: Indicates the consent items that require permission to set as 'Required consent' or 'Optional consent'. Refer to Manage consent items to see how to obtain permission.

User information Description Required user consent
Profile Profile information of Kakao Account.

Include:
- Nickname
- Profile image URL
- Thumbnail image URL
- Whether the default image is used for profile image
- Whether consent to profile is required
NOTE: From June 25, 2021, you can request consent to the nickname and the profile image of the profile information separately. Refer to Notice for more details.
Profile Info(nickname/profile image)
or
Nickname
Profile image
Email Representative email of Kakao Account.
Email may not be collected in a user's Kakao Account. In this case, use the Provision after collecting information option or collect it in your service internally.
A user's Kakao Account email may not be verified. If your service needs to use only verified emails, proceed the verification process for the users who do not have unverified emails.

Include:
- Representative email of Kakao Account
- Verification status of email
- Validation status of email
- Whether consent to email is required
NOTE: Cautions when using email
Email
Permission
Name Name of Kakao Account.
If a name is not registered in a Kakao Account, use the Provision after collecting information option.
Name
Permission
Age Range Age range of Kakao Account based on Korean age.

Include:
- Age range
- Whether consent to age range is required
Age range
Permission
Birthday Birthday of Kakao Account.

Include:
- Birthday
- Birthday type
- Whether consent to birthday is required
Birthday registered in Kakao Account.
Permission
Birth year Birth year of Kakao Account.

Include:
- Birth year
- Whether consent to birth year is required
Birth Year registered in Kakao Account.
Permission
Gender Gender of Kakao Account.

Include:
- Gender
- Whether consent to gender is required
Gender
Permission
Phone number Phone number of Kakao Account.

Include:
- Phone number
- Whether consent to phone number is required
IMPORTANT: The Provision after collecting information is not applicable for Phone number.
Phone number
Permission
CI(Connecting Information) Cryptographic user identification value.
CI can be used only to check if the same user has already been registered in the membership database.

Include:
- Connecting InformationThe time when Certificate Authority issues CI
- Whether consent to CI for a reference is required
IMPORTANT: Use CI provided by Kakao only to compare with CI collected by a service. You cannot use CI for user authentication because Kakao does not have a role as Certificate Authority.
CI(Connecting Information)
Permission
Cautions when using email
  • If your service uses email provided by Kakao, you must check if users' email is valid through the is_email_valid field, which is provided along with email when a user consents to the Email scope.
    • If a user's email has expired, the user's email is masked with asterisks (*). (Example: ka***@kakao.com)
  • If your service sends emails to the email addresses provided by users, you must check both the is_email_valid and is_email_verified fields.
  • User's email saved in Kakao Account can be changed if a user wants. For this reason, we recommend not to use users' emails as an ID or not to identify users by email.
Checklist: Things to do if user information is not passed

If you cannot get a specific user information such as email that you need through the Retrieving user information API, proceed the followings:

1. Check if you enable the consent item for the user information in Consent Items. You must set it to either 'Required consent' or 'Optional consent' to get the user information. If you must obtain consent to a specific user information, use the Provision after collecting information option. 2. Check the {FIELD_NAME}_needs_agreement key, such as email_needs_agreement. If the key value is 'true', request additional consent to obtain consent by prompting the Consent screen.

Data passed through other APIs

Permission: Indicates the consent items that require permission to set as 'Required consent' or 'Optional consent'. Refer to Manage consent items to see how to obtain permission.

User information Description Required user consent
Shipping information Shipping information of Kakao Account. Shipping information
Permission
Kakao Talk profile Profile of Kakao Talk.
This profile is different from Kakao Account profile.

Include:
- Nickname
- Profile image URL
- Thumbnail image URL
Profile Info(nickname/profile image)
Kakao Talk friend information Friend information of Kakao Talk.

IMPORTANT: After permission for the Retrieving list of friends API is granted, you can get a list of friends who meet the condition.
Friends List in Kakao Service(Including profile image, nickname, and favorites)
Permission
Kakao Talk Channel addition status and details Relationship between a Kakao Talk Channel and a user.
If you connect your Biz app to one or more than Kakao Talk Channels in Kakao Business, you can set the required consent item to 'Optional consent' item.
Kakao Talk Channel addition status and details
Kakao Story profile Profile of Kakao Story.
This profile is different from Kakao Account profile.

Include:
- Nickname
- Profile image URL
- Thumbnail image URL
- Background image
Profile Info(nickname/profile image)
Kakao Story Birthday Birthday registered in Kakao Story.

Include:
- Birthday
- Birthday type
Birthday
KakaoStory Profile URL Kakao Story profile URL. KakaoStory profile URL

OpenID Connect

OpenID Connect (OIDC) is an authentication layer built on top of the authorization protocol, the OAuth 2.0. For detailed specifications, refer to OpenID Connect Core 1.0.

You can decide which protocol to apply when integrating Kakao Login in your service, considering the differences between OAuth and OpenID Connect.

OAtuh 2.0 OpenID Connect
Definition Web authorization protocol Authentication layer on top of OAuth 2.0
Purpose To verify what resource a user has access to,
To grant access or usage permission from users
To verify who a user is
Token Access token, Refresh token Access token, Refresh token,
ID Token
Use case API authorization Maintaining session
Single Sign-On (SSO) functionality

OIDC authentication flow

Since OIDC is on top of OAuth, the login process with OIDC protocol is the same as the OAuth authorization process.

Here is the sequence diagram of the OIDC process. If you request tokens with OIDC enabled, you will get an ID Token along with an access token and a refresh token when you request tokens.

Process of OIDC authentication

ID Token

The ID token is a security token in JSON Web Token (JWT) format encrypted with the RS256 algorithm. The ID token contains the claims consisting of Header, Payload, and Signature separated by period(.) and is encoded using Base64 algorithm. Since the ID token contains identity information for a user, you can use the issued ID token to retain a session in your service. You can also implement the Single Sign-On (SSO) functionality in your service. For detailed specifications, refer to JSON Web Token (RFC7519).

Segment Description
Header Encryption information that contains the followings:
- alg: Encryption algorithm applied to ID token. Fixed as RS256.
- typ: Type of ID token. Fixed as JWT (JSON Web Token).
- kid: Cryptographic key ID.
Payload User authentication information that contains the followings:
- iss: Issuer Identifier. Fixed as https://kauth.kakao.com.
- aud: App key of the app which the ID token is issued for.
- sub: Service user ID.
- iat: Time when the JWT was issued.
- auth_time: Time when a user was authenticated.
- exp: Validity period of ID token in seconds, which is the same as that of access token.
- nonce: Random string passed in the request of the Getting authorization code API.
- nickname: User nickname saved in Kakao Account.
- picture: URL of user profile thumbnail image saved in Kakao Account.
- email: User's valid email saved in Kakao Account.

Refer to the response of Getting ID token information API.
Signature Signed value with a public key provided by the Kakao authorization server.

You can also decode the ID token by calling the Getting ID token information API, which is allowed to use only for debugging.

How to integrate OIDC

The way to integrate OIDC is basically the same as OAuth, except for OIDC activation and using the scope parameter.

Step 1. Enable OIDC function

Go to [My Application] > [Kakao Login], and then activate the OpenID Connect.

Step 2. Check Discovery document

When you send a request to /.well-known endpoint/openid-configuration, you can access the Discovery document and retrieve the metadata that you may need while implementing OIDC.

With the discovery document, you can retrieve:

  • URLs of the endpoints for authorization, tokens, user information and JSON web key.
  • Configuration of Kakao authorization server for OIDC.

To see the response fields included in the Discovery document, see REST API > Retrieve Discovery document.

Step 3. Implement Kakao Login

Implement Kakao Login by referring to the development guide. When you call the Login API, you will get an ID token. For a REST API, refer to Advanced: Login with Open ID Connect.

IMPORTANT

If you call the Requesting additional consent API, you must add 'openid' to 'scope', the required parameter. If not, OAuth is applied even though OIDC is enabled, which means that you cannot get an ID token. If you don't pass the 'scope' parameter when requesting additional consent, the Login API is called with the scopes as specified in [My Application] > [Consent Items].

Step 4. Verify ID token

When your service obtains an ID token from Kakao, you need to check the integrity on your service server by verifying the issued ID token as follows:

  1. Separate the ID token into Header, Payload, and Signature by period(.).
  2. Decode the payload from Base64 format.
  3. To verify that the ID token is issued from Kakao authorization server (kauth), check if the value of iss in the JWT payload is https://kauth.kakao.com.
  4. Check if the value of aud in the JWT payload is your app key. The app key type may differ depending on the platform you use.
  5. To verify that the ID token's expiration time has not passed, check if the value of exp is greater than UNIX timestamp of the current time.
  6. Optional: If you pass nonce in your request to prevent replay attacks, check if the value of nonce in the JWT payload matches the nonce value passed in your request.
  7. Check if the issuer has properly signed the ID token with the public key by verifying cryptographic signature.
Verifying Cryptographic signature

The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by the authorization server and signed using the RS256 signing algorithm.

  1. To find out a public key, call the Getting public key.
  2. Check kid passed in the response.
    IMPORTANT: Ensure that the public key may change periodically or when some issues occur. Thus, you must make use the public keys by caching them in your service periodically.
  3. Verify ID token with kid by using the official libraries:
    - OpenID Foundation
    - jwt.io

Since the cryptographic signature checking process is complicated, we strongly recommend using the official libraries above. However, if you want to decrypt and verify the ID token internally in your service instead of using libraries, refer to 5.2. Message Decryption in JSON Web Encryption (RFC 7516).

Step 5. Retrieve User information

If your service needs to retrieve user information about the user authenticated through OIDC and use the claims for data mapping, call the Retrieving user information for OIDC. This API complies with the Standard Claims, and only provides the basic user information unlike the Retrieving user information.

Scope of support

API Android SDK iOS SDK JavaScript SDK Flutter SDK REST API
Login
Logout
Link
Unlink
Retrieving token information
Getting tokens
Refreshing tokens
Auto-login from Kakao Talk
Retrieving user information
Retrieving shipping address
Storing user information
Retrieving user list
Retrieving multiple user information
Requesting additional consent
Retrieving consent details
Revoking consent
Checking user agreed terms
Getting consent to desired terms
Login with OpenID Connect
Manual signup

To implement Kakao Login using a REST API, the Getting authorization codeand the Getting tokens APIs are required.