Google

OAuth 2.0 authorization code provider for Google. Only supports confidential clients.

Also see OAuth 2.0 with PKCE.

Initialization

import { Google } from "arctic";

const google = new Google(clientId, clientSecret, redirectURI);

Create authorization URL

import { generateState, generateCodeVerifier } from "arctic";

const state = generateState();
const codeVerifier = generateCodeVerifier();
const scopes = ["openid", "profile"];
const url = google.createAuthorizationURL(state, codeVerifier, scopes);

Validate authorization code

validateAuthorizationCode() will either return an OAuth2Tokens, or throw one of OAuth2RequestError, ArcticFetchError, or a standard Error (parse errors). Google will return an access token with an expiration.

import { OAuth2RequestError, ArcticFetchError } from "arctic";

try {
	const tokens = await google.validateAuthorizationCode(code, codeVerifier);
	const accessToken = tokens.accessToken();
	const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
} catch (e) {
	if (e instanceof OAuth2RequestError) {
		// Invalid authorization code, credentials, or redirect URI
		const code = e.code;
		// ...
	}
	if (e instanceof ArcticFetchError) {
		// Failed to call `fetch()`
		const cause = e.cause;
		// ...
	}
	// Parse error
}

The refresh token expiration is returned as refresh_token_expires_in.

const tokens = await google.validateAuthorizationCode(code);
if (
	"refresh_token_expires_in" in tokens.data &&
	typeof tokens.data.refresh_token_expires_in === "number"
) {
	const refreshTokenExpiresIn = tokens.data.refresh_token_expires_in;
}

OpenID Connect

Use OpenID Connect with the openid scope to get the user's profile with an ID token or the userinfo endpoint. Arctic provides decodeIdToken() for decoding the token's payload.

Also see ID token claims.

const scopes = ["openid"];
const url = google.createAuthorizationURL(state, codeVerifier, scopes);

import { decodeIdToken } from "arctic";

const tokens = await google.validateAuthorizationCode(code, codeVerifier);
const idToken = tokens.idToken();
const claims = decodeIdToken(idToken);

const response = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
	headers: {
		Authorization: `Bearer ${accessToken}`
	}
});
const user = await response.json();

Get user profile

Make sure to add the profile scope to get the user profile and the email scope to get the user email.

const scopes = ["openid", "profile", "email"];
const url = google.createAuthorizationURL(state, codeVerifier, scopes);

Refresh tokens

Set the access_type parameter to offline to get refresh tokens. You will only get the refresh token on the user's first authentication.

const url = google.createAuthorizationURL(state, codeVerifier, scopes);
url.searchParams.set("access_type", "offline");

const tokens = await google.validateAuthorizationCode(code, codeVerifier);
const accessToken = tokens.accessToken();
const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
if (tokens.hasRefreshToken()) {
	const refreshToken = tokens.refreshToken();
}

Use refreshAccessToken() to get a new access token using a refresh token. This method's behavior is identical to validateAuthorizationCode(). Google will not provide a new refresh token after a token refresh.

import { OAuth2RequestError, ArcticFetchError } from "arctic";

try {
	const tokens = await google.refreshAccessToken(refreshToken);
	const accessToken = tokens.accessToken();
	const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
} catch (e) {
	if (e instanceof OAuth2RequestError) {
		// Invalid authorization code, credentials, or redirect URI
	}
	if (e instanceof ArcticFetchError) {
		// Failed to call `fetch()`
	}
	// Parse error
}

Revoke tokens

Revoke tokens with revokeToken(). This can throw the same errors as validateAuthorizationCode().

try {
	await google.revokeToken(token);
} catch (e) {
	if (e instanceof OAuth2RequestError) {
		// Invalid authorization code, credentials, or redirect URI
	}
	if (e instanceof ArcticFetchError) {
		// Failed to call `fetch()`
	}
	// Parse error
}