Amazon Cognito

OAuth 2.0 authorization code provider for Amazon Cognito.

Also see OAuth 2.0 with PKCE.

Initialization

The domain should not include the protocol or path. Pass a client secret for confidential clients.

import * as arctic from "arctic";

const domain = "<POOL-DOMAIN>.auth.<REGION>.amazoncognito.com";
const cognito = new arctic.AmazonCognito(domain, clientId, clientSecret, redirectURI);
const cognito = new arctic.AmazonCognito(domain, clientId, null, redirectURI);

Create authorization URL

import * as arctic from "arctic";

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

Validate authorization code

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

import * as arctic from "arctic";

try {
	const tokens = await cognito.validateAuthorizationCode(code, codeVerifier);
	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
}

Refresh access tokens

Use refreshAccessToken() to get a new access token using a refresh token. This method's behavior is identical to validateAuthorizationCode(). Cognito will only return a new access token.

import * as arctic from "arctic";

try {
	// Pass an empty `scopes` array to keep using the same scopes.
	const tokens = await cognito.refreshAccessToken(refreshToken, scopes);
	const accessToken = tokens.accessToken();
	const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
} 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 = cognito.createAuthorizationURL(state, codeVerifier, scopes);

import * as arctic from "arctic";

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

const response = await fetch(userPool + "/oauth/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 = cognito.createAuthorizationURL(state, codeVerifier, scopes);

Revoke refresh tokens

Pass a refresh token to revokeToken() to revoke all tokens associated with the authorization. This can throw the same errors as validateAuthorizationCode().

try {
	await cognito.revokeToken(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
}

Token revocation must be enabled in the settings.