Auth0

OAuth 2.0 provider for Auth0.

Also see the OAuth 2.0 guide for confidential clients and the OAuth 2.0 with PKCE guide for public clients.

Initialization

The domain should not include the protocol or path. Pass the client secret for confidential clien.ts

import * as arctic from "arctic";

const domain = "xxx.auth0.com";
const auth0 = new arctic.Auth0(domain, clientId, clientSecret, redirectURI);
const auth0 = new arctic.Auth0(domain, clientId, null, redirectURI);

Create authorization URL

For confidential clients, pass the state and scopes. PKCE is not supported for confidential clients.

import * as arctic from "arctic";

const state = arctic.generateState();
const scopes = ["openid", "profile"];
const url = auth0.createAuthorizationURL(state, null, scopes);

For public clients, pass the state, PKCE code verifier, and scopes.

import * as arctic from "arctic";

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

Validate authorization code

For confidential clients, pass the authorization code.

validateAuthorizationCode() will either return an OAuth2Tokens, or throw one of OAuth2RequestError, ArcticFetchError, UnexpectedResponseError, or UnexpectedErrorResponseBodyError. Auth0 returns an access token, the access token expiration, and a refresh token.

import * as arctic from "arctic";

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

For public clients, pass the authorization code and code verifier.

const tokens = await auth0.validateAuthorizationCode(code, codeVerifier);

Refresh access tokens

Use refreshAccessToken() to get a new access token using a refresh token. Auth0 returns the same values as during the authorization code validation. This method also returns OAuth2Tokens and throws the same errors as validateAuthorizationCode()

import * as arctic from "arctic";

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

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.

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

import * as arctic from "arctic";

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

const response = await fetch("https://xxx.auth.com/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 = auth0.createAuthorizationURL(state, codeVerifier, scopes);

Revoke tokens

Revoke tokens with revokeToken(). Currently, only refresh tokens can be revoked. It throws the same errors as validateAuthorizationCode().

try {
	await auth0.revokeToken(refreshToken);
} catch (e) {
	// Handle errors
}