Microsoft Entra ID

OAuth 2.0 provider for Microsoft Entra ID.

Also see the OAuth 2.0 guide.

Initialization

See Endpoints for more on the tenant parameter.

import { MicrosoftEntraId } from "arctic";

const entraId = new MicrosoftEntraId(tenant, clientId, clientSecret, redirectURI);

Create authorization URL

import { generateState, generateCodeVerifier } from "arctic";

const state = generateState();
const codeVerifier = generateCodeVerifier();
const scopes = ["openid", "profile"];
const url = entraId.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). Entra ID returns an access token, the access token expiration, and a refresh token.

import { OAuth2RequestError, ArcticFetchError } from "arctic";

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

Refresh access tokens

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

import { OAuth2RequestError, ArcticFetchError } from "arctic";

try {
	const tokens = await entraId.refreshAccessToken(accessToken);
	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
}

OpenID Connect

Use OpenID Connect with the openid scope to get the user's profile with an ID token or the userinfo endpoint. The nonce parameter is required by Entra ID to use OpenID. Arctic provides decodeIdToken() for decoding the token's payload.

const scopes = ["openid"];
const url = entraId.createAuthorizationURL(state, codeVerifier, scopes);
// The nonce should be unique to each request similar to state.
// However, nonce can just be "_" here since it isn't useful for server-based OAuth.
url.searchParams.set("nonce", nonce);

import { decodeIdToken } from "arctic";

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

const response = await fetch("https://graph.microsoft.com/oidc/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 = entraId.createAuthorizationURL(state, codeVerifier, scopes);