RFC: OAuth helpers

[pilcrowonpaper]

Breaking changes

• Yes
• None

Summary

Add 4 new OAuth helpers to the OAuth integration (@lucia-auth/oauth):

• createOAuth2AuthorizationUrl()
• createOAuth2AuthorizationUrlWithPKCE()
• validateOAuth2AuthorizationCode()
• decodeIdToken()

These functions, in combination with existing API such as providerUserAuth(), will make implementing OAuth providers significantly easier

Motivation

Better and easier APIs for implementing custom OAuth providers has been heavily requested.

Goals

• Provide APIs to get the authorization url and validate authorization codes for OAuth 2.0 authorization code grant

Non-goals

• Provide a provider (e.g. provider()) that can be used to create an OAuth provider by providing some basic options
  • I did experiment with this but all the callbacks it required went against the design philosophy of Lucia, was more complex (to implement and for the user), and did not make things significantly easier
• Provide APIs for OAuth 1.0 and 1.0a
• Provide APIs for implicit and password grant types
• Provide APIs that support non-spec compliant OAuth 2.0 implementation

API design

createOAuth2AuthorizationUrl()

Creates a new authorization url for OAuth 2.0 authorization code grant with a state. This returns a promise to be consistent with createOAuth2AuthorizationUrlWithPKCE().

const createOAuth2AuthorizationUrl: (
	url: string | URL,
	options: {
		clientId: string;
		scope: string[];
		state?: string;
		redirectUri?: string;
		searchParams?: Record<string, string | undefined>;
	}
) => Promise<readonly [authorizationUrl: URL, state: string]>;

Parameters

name	type	description
url	string | URL	Authorization url base
options.clientId	string	client_id
options.scope	string[]	A list of values for scope
state	string	Custom state
redirectUri	string	redirect_uri
searchParams	Record<string, string | undefined>	Any additional search params to add to the url

Returns

name	type	description
authorizationUrl	URL	Authorization url
state	string	Generated or provided state

createOAuth2AuthorizationUrlWithPKCE()

Creates a new authorization url for OAuth 2.0 authorization code grant with a state and PKCE code challenge.

const createOAuth2AuthorizationUrlWithPKCE: (
	url: string | URL,
	options: {
		clientId: string;
		scope: string[];
		codeChallengeMethod: "S256";
		state?: string;
		redirectUri?: string;
		searchParams?: Record<string, string | undefined>;
	}
) => Promise<
	readonly [authorizationUrl: URL, state: string, codeVerifier: string]
>;

Parameters

name	type	description
url	string | URL	Authorization url base
options.clientId	string	client_id
options.scope	string[]	A list of values for scope
options.codeChallengeMethod	"S256"	Code challenge method
state	string	Custom state
redirectUri	string	redirect_uri
searchParams	Record<string, string | undefined>	Any additional search params to add to the url

Returns

name	type	description
authorizationUrl	URL	Authorization url
state	string	Generated or provided state
codeVerifier	string	Generated code verifier

validateOAuth2AuthorizationCode()

Validates OAuth 2.0 authorization code.

const validateOAuth2AuthorizationCode: <_ResponseBody extends {}>(
	authorizationCode: string,
	url: string | URL,
	options: {
		clientId: string;
		redirectUri?: string;
		codeVerifier?: string;
		clientPassword?: {
			clientSecret: string;
			authenticateWith: "client_secret" | "http_basic_auth";
		};
	}
) => Promise<_ResponseBody>;

Parameters

name	type	description
authorizationCode	string	Authorization code
url	URL | string	Access token endpoint
options.redirectUri	string	redirect_uri
options.codeVerifier	string	code_verifier
options.clientPassword
options.clientPassword.clientSecret	string	Client secret
options.clientPassword.authenticateWith	"client_secret" | "http_basic_auth"	See below

options.clientPassword.authenticateWith

value	description
"client_secret"	Send the client secret inside request body as client_secret
"http_basic_auth"	Send the client secret with the client id with HTTP Basic authentication scheme

Generics

name	extends	description
_ResponseBody	{}	Response body of the access token request

decodeIdToken()

Decodes the OpenID Connect id token and returns the claims. Does NOT validate the JWT. Throws Error if provided id token is invalid or malformed.

const decodeIdToken: <_Claims extends {}>(
	idToken: string
) => {
	iss: string;
	aud: string;
	exp: number;
} & _Claims;

Parameters

name	type
idToken	string

Generics

name	extends	description
_Claims	{}	JWT payload claims

Returns

JWT payload.

Example

import {
	createOAuth2AuthorizationUrl,
	providerUserAuth,
	validateOAuth2AuthorizationCode
} from "@lucia-auth/oauth";

import type { Auth } from "lucia";
import type { OAuthProvider } from "@lucia-auth/oauth";

const PROVIDER_ID = "github";

export const github = <_Auth extends Auth>(auth: _Auth, config: Config) => {
	const getGithubTokens = async (code: string): Promise<Tokens> => {
		type ResponseBody =
			| {
					access_token: string;
			  }
			| {
					access_token: string;
					refresh_token: string;
					expires_in: number;
					refresh_token_expires_in: number;
			  };

		const tokens = await validateOAuth2AuthorizationCode<ResponseBody>(
			code,
			"https://github.com/login/oauth/access_token",
			{
				clientId: config.clientId,
				clientPassword: {
					clientSecret: config.clientSecret,
					authenticateWith: "client_secret"
				}
			}
		);

		return {
			accessToken: tokens.access_token,
			accessTokenExpiresIn: null
		};
	};

	const getGithubUser = async (accessToken: string) => {
		const request = new Request("https://api.github.com/user", {
			headers: {
				Authorization: authorizationHeader("bearer", accessToken)
			}
		});
		const githubUser = await handleRequest<GithubUser>(request);
		return githubUser;
	};

	return {
		getAuthorizationUrl: async () => {
			return await createOAuth2AuthorizationUrl(
				"https://github.com/login/oauth/authorize",
				{
					clientId: config.clientId,
					scope: config.scope ?? [],
					redirectUri: config.redirectUri
				}
			);
		},
		validateCallback: async (code: string) => {
			const githubTokens = await getGithubTokens(code);
			const githubUser = await getGithubUser(githubTokens.accessToken);
			const providerUserId = githubUser.id.toString();
			const githubUserAuth = await providerUserAuth(
				auth,
				PROVIDER_ID,
				providerUserId
			);
			return {
				...githubUserAuth,
				githubUser,
				githubTokens
			};
		}
	} as const satisfies OAuthProvider;
};

type Config = {
    // ...
}
type Tokens = {
    // ...
}
type GithubUser = {
    // ..
}

Considerations

• API names
  • Especially options.clientPassword.authenticateWith params in validateOAuth2AuthorizationCode()

[luccasr73]

will these 4 new functions be part of the public api or just for internal use in creating providers? validateOAuth2AuthorizationCode and decodeIdToken can be very useful for dealing with oauth implicit login like expo-auth-session does https://docs.expo.dev/guides/authentication/#implicit-login

[pilcrowonpaper]

Oh, public api

[pilcrowonpaper]

We are moving forward with the RFC #899