OAuth with Kakao

Kakao is the South Korean technology company behind KakaoTalk, the default messaging app in South Korea. Kakao Login lets people sign in to other apps with the same Kakao account they use for KakaoTalk, which makes it the sign-in option users in South Korea expect to see.

How does the integration work?

You can use the Kakao OAuth adapter in Appwrite Auth to let users sign in with their Kakao account. Kakao asks users for the consent items you configure on your Kakao app, so Appwrite doesn't request any scopes by default. If you request a scope that isn't enabled as a consent item, Kakao rejects the sign-in with error KOE205.

Appwrite stores the user's nickname and profile image, and their email when the user grants the email consent item. It treats that email as verified only when Kakao reports it as both verified and valid.

How to implement

To implement the Kakao OAuth adapter in Appwrite Auth, there are several steps you must complete:

Step 1: Set up an app on Kakao Developers

In Kakao Developers, create an application or open an existing one, then complete Kakao Login's prerequisites:

• Find the REST API key. Under App > Platform Key > REST API key, copy the key. Kakao uses it as the client ID.
• Enable the client secret. Under the same REST API key, generate a Client secret, set it to enabled, and save the value for later use.
• Turn on Kakao Login. Under Kakao Login, set the state to ON. Requests fail with error KOE004 while it's off.
• Configure consent items. Under Kakao Login > Consent items, set the items you want to request, such as the nickname, profile image, and email address. Kakao gates some consent items behind additional feature permissions that require a business information review.

You'll register the redirect URI after you configure Appwrite in the next step.

Step 2: Add Kakao OAuth adapter to your Appwrite project

For this step, you must create an account on Appwrite Cloud or self-host Appwrite if you haven't already. In your Appwrite project, head over to the Auth page, open the Settings tab, and click Kakao under the OAuth2 Providers section.

Fill in the provider form:

• REST API key: your app's REST API key.
• Client Secret: the client secret you enabled.

Optionally, set Prompt to control Kakao's screens: login to ask users to sign in again, create to show the sign-up screen, select_account to let users pick an account, or none to skip the screens. Turn the provider on and click Update. Appwrite checks the REST API key and client secret with Kakao when you enable the provider and returns an error if Kakao rejects them.

Copy the Redirect URI shown in the form. On Appwrite Cloud it looks like https://<REGION>.cloud.appwrite.io/v1/account/sessions/oauth2/callback/kakao/<PROJECT_ID>, but always copy the exact value from the Console. In Kakao Developers, register it under App > Platform Key > REST API key > Redirect URI. An unregistered URI fails with error KOE006.

Step 3: Test the provider

Start a session from your app with the OAuthProvider.Kakao value. Only pass scopes for consent items you enabled on your Kakao app. With the Web SDK:

import { Client, Account, OAuthProvider } from 'appwrite';

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>');

const account = new Account(client);

account.createOAuth2Session({
    provider: OAuthProvider.Kakao,
    success: 'https://example.com/success',
    failure: 'https://example.com/failed',
});

Add your app's domain as a web platform in your Appwrite project so Appwrite accepts the success and failure URLs. Follow the OAuth 2 login flow for other platforms and for server-side sign-in.

Read more about Kakao and Appwrite Auth

If you would like to learn more about Kakao and Appwrite Auth, we have some resources that you should visit: