K-OAuth

A simple Java OAuth 2.0 library for Korean OAuth providers (Kakao, Naver)

Korean Version (한글 버전 README)

Table of Contents

1. Installation
2. Documentation
3. General Usage
   • Kakao Client
   • Naver Client
4. Advanced Features
5. Error Handling
6. Inspiration
7. Contributing

Installation

Gradle

Add the following to your build.gradle file:

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.higukang:k-oauth:1.0.1'
}

IDE Integration (Optional)

If you cannot see the library's source code or Javadoc in your IDE:

• IntelliJ: Click "Download Sources" in the notification bar or use the Gradle tab to refresh with sources enabled.
• VS Code: Ensure the "Java Language Support" extension is installed; it typically handles sources automatically.

Documentation

See this project's Javadoc

General Usage

Kakao Client

1. Exchange Code for Access Token

KakaoClient kakaoClient = KakaoClient.create();

try {
    KakaoTokenResponse response = kakaoClient.getToken()
        .clientId("YOUR_REST_API_KEY")
        .redirectUri("YOUR_REDIRECT_URI")
        .code("AUTHORIZATION_CODE")
        .clientSecret("YOUR_CLIENT_SECRET") // Optional (null is ignored)
        .build()
        .execute();

    System.out.println("Access Token: " + response.accessToken());
} catch (OAuthException e) {
    e.printStackTrace();
}

2. Get User Profile

KakaoClient kakaoClient = KakaoClient.create();

try {
    KakaoUserResponse user = kakaoClient.getUserInfo()
            .accessToken("ACCESS_TOKEN")
            .secureResource(false)
            .propertyKeys(KakaoPropertyKey.EMAIL)
            .build()
            .execute();

    System.out.println("Nickname: " + user.kakaoAccount().profile().nickname());
} catch (OAuthException e) {
    e.printStackTrace();
}

Naver Client

1. Exchange Code for Access Token

NaverClient naverClient = NaverClient.create();

try {
    NaverTokenResponse response = naverClient.getToken()
            .clientId("CLIENT_ID")
            .clientSecret("SECRET")
            .code("CODE")
            .state("STATE")
            .build()
            .execute();

    System.out.println("Access Token: " + response.accessToken());
} catch (OAuthException e) {
    e.printStackTrace();
}

2. Get User Profile

NaverClient naverClient = NaverClient.create();

try {
    NaverUserResponse response = naverClient.getUserInfo()
            .accessToken("ACCESS_TOKEN")
            .build()
            .execute();
    
    System.out.println("Nickname: " + response.response().nickname());
} catch (OAuthException e) {
    e.printStackTrace();
}

Advanced Features

Selective Property Retrieval (Kakao Only)

You can request specific user properties to optimize the response size.

KakaoUserResponse user = kakaoClient.getUserInfo()
        .accessToken("ACCESS_TOKEN")
        .propertyKeys(KakaoPropertyKey.EMAIL, KakaoPropertyKey.NICKNAME)
        .secureResource(true) // Return HTTPS URLs
        .build()
        .execute();

Error Handling

K-OAuth provides a detailed exception hierarchy to help you handle various failure scenarios.

• OAuthValidationException: Thrown when mandatory parameters are missing before the request.

• OAuthResponseException: Thrown when the OAuth provider returns a non-2xx response or a logical error (Naver's 200 OK error).

• OAuthNetworkException: Thrown when network issues occur (timeouts, DNS failures).

• OAuthParsingException: Thrown when a provider response cannot be parsed as expected JSON.

Validation and optional parameter notes:

• Required values are validated at build() time and throw OAuthValidationException.
• Optional parameters with null values are safely ignored.

try {
    // execute request...
} catch (OAuthResponseException e) {
    System.out.println("Status Code: " + e.getStatusCode());
    System.out.println("Error Code: " + e.getErrorCode());
    System.out.println("Message: " + e.getMessage());
} catch (OAuthException e) {
    // Handle other exceptions
}

Inspiration

Inspiration
Inspired by spotify-web-api-java.

Contributing

• Issues and Pull Requests are always welcome.
• Feel free to contribute, from small typo fixes to feature suggestions.

License

This project is licensed under the MIT License - see the LICENSE file for details.