kpick-oauth 0.3.0

A simple OAuth client library for Google, Kakao, Naver, and GitHub.

kpick-oauth

A small Python OAuth helper library for Kakao, Naver, Google, and GitHub.

Installation

pip install kpick-oauth

Usage

from kpick_oauth import (
    OAuthClient,
    OAuthTokenError,
    OAuthUserInfoError,
    generate_state,
    verify_state,
)

client = OAuthClient(
    provider="github",
    client_id="your-client-id",
    client_secret="your-client-secret",
)

# Create a state value before redirecting the user.
# Bind it to the user's session/cookie so the callback can recover it.
state = generate_state()

# state is required. get_authorize_url() raises ValueError if it is empty.
authorize_url = client.get_authorize_url(
    redirect_uri="https://example.com/oauth/callback",
    state=state,
    scope="read:user user:email",
)

# Redirect the user's browser to authorize_url.

# In your callback route, compare the stored state with the returned state.
if not verify_state(stored_state, returned_state):
    raise ValueError("Invalid OAuth state")

try:
    token = client.fetch_token(
        code="authorization-code",
        redirect_uri="https://example.com/oauth/callback",
    )
    user = client.fetch_user(token["access_token"])
except OAuthTokenError:
    # Provider returned an error payload (e.g. invalid_grant) or no access_token.
    raise
except OAuthUserInfoError:
    # Provider returned an error payload from the userinfo endpoint.
    raise

# user is an OAuthUser, not your application's main user account.
# Use (user.provider, user.provider_id) as the OAuth account key.
# Only trust user.email when user.email_verified is True.
app_user = link_or_create_account_by_provider_id(user.provider, user.provider_id)

if user.email_verified is True and user.email:
    app_user.email = user.email

Security Notes

• Keep client_secret on your server. Do not put it in browser JavaScript.
• Do not put access tokens in URLs.
• Do not print or log tokens.
• Use generate_state() before redirecting to the provider.
• Use verify_state() in your callback before exchanging the code for a token.
• get_authorize_url() requires a non-empty state.
• Store provider login records by provider and provider_id.
• Do not use email as the OAuth account key.
• Kakao and Google emails are returned only when the provider marks them verified.
• Naver and GitHub emails are marked verified when returned by the provider.
• GitHub noreply emails are treated as unavailable and returned as None.
• Check user.email_verified before trusting an email for account recovery or linking.
• Do not log OAuthUser.raw; it can contain personal information.
• Token and userinfo provider error payloads raise OAuthTokenError / OAuthUserInfoError. This includes Kakao's negative code and Naver's non-"00" resultcode.

PKCE (Optional, Recommended Where Supported)

PKCE (RFC 7636) adds defense-in-depth against authorization code interception. This library accepts PKCE parameters as opt-in arguments. Providers whose official documentation does not list PKCE are rejected with ValueError so callers do not get a false sense of protection.

Provider	PKCE support
Google	yes
GitHub	yes
Kakao	no (per Kakao Developers docs)
Naver	no (per Naver Developers docs)

from kpick_oauth import OAuthClient, generate_pkce_pair, generate_state

client = OAuthClient("google", client_id, client_secret)

state = generate_state()
pkce = generate_pkce_pair()
# Store BOTH state and pkce.code_verifier in the user's session.

authorize_url = client.get_authorize_url(
    redirect_uri="https://example.com/oauth/callback",
    state=state,
    scope="openid email profile",
    code_challenge=pkce.code_challenge,
)

# ... in the callback, after verify_state(...) ...
token = client.fetch_token(
    code=callback_code,
    redirect_uri="https://example.com/oauth/callback",
    code_verifier=pkce.code_verifier,
)

Passing code_challenge to a Kakao or Naver client, or code_verifier to their fetch_token, raises ValueError. Omit PKCE for those providers.

Supported Providers

• Kakao
• Naver
• Google
• GitHub

Development

pip install -e ".[dev]"
pytest