/**
* Implementation of [Client Initiated Account Linking](https://auth0.com/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation)
* in an Auth0 Action. This action facilitates OIDC Applications to be able to
* request account linking from the Authorization Server instead of having to perform
* this in-app.
*
* This Action is intended to allow adding additional services, such as Google, Facebook
* Microsoft, Github etc, to an end user's primary user-account.
*
* This Action operates with the model of a primary account, the account the user is currently
* logged-in as, and a secondary account. An account which will be linked to the primary account.
* Upon successful linking, the secondary account will be a part of the primary. This is a destructive
* action.
*
*
* To request account linking the application must send the following parameters
* - `scope=link_account`, used to determine account linking is required
* - `id_token_hint`, A valid `id_token` obtained for the client, that belongs to the user on
* whose behalf the client initiated account linking is being requested
* - `requested_connection`, the provider which is requested.
* - `requested_connection_scope`, OPTIONAL list of scopes that are requested by the provider,
* if not present it will leverage the configured scopes in the Dashboard.
*
* If you intend to perform custom MFA we recommend using another action prior to this to centralize and
* enforce those policies. This Action should be treated as a client.
*
* Author: Auth0 Product Architecture
* Date: 2025-03-21
* License: MIT (https://github.com/auth0/client-initiated-account-linking/blob/main/LICENSE)
*
* ## Required Secrets
*
* - `AUTH0_CLIENT_ID` Client ID for Regular Web Applicaton, this action is registered to
* - `AUTH0_CLIENT_SECRET` Client Secret for Regular Web Application, this action is registered to
* - `ACTION_SECRET` A secret that is unique to this application you can use `uuidgen` or a secure random string
*
* ## Optional Secrets and Configuration
*
* - `ALLOWED_CLIENT_IDS` Comma Separated List of all client ids, by default all clients may request when using OIDC
* - `DEBUG` `debug` compatible string, this action uses `account-linking:{info,error,verbose}` to differentiate between logs
* - `ENFORCE_MFA` - if set to "yes" will require MFA to have been performed on the current session, it will also enforce MFA in the nested
* if MFA is not performed but is enrolled on the end-user. Default: "no"
* - `ENFORCE_EMAIL_VERIFICATION` - if set to "yes" will require the `primary` account's email is verified. Default: "no"
* - `PIN_IP_ADDRESS` - If set to "yes" will require the transaction complete on same IP Address, this can be finnicky for some customers. Default: "no"
*/
// Required Modules
const { ManagementClient, PostIdentitiesRequestProviderEnum } = require('auth0');
const client = require('openid-client');
const jose = require('jose');
const { createHash } = require('node:crypto');
const { URLSearchParams } = require('node:url');
const debug = require('debug');
const { hkdf } = require('@panva/hkdf');
const logger = {
error: debug('account-linking:error'),
info: debug('account-linking:info'),
verbose: debug('account-linking:verbose'),
};
// Global constants
const SCOPES = {
LINK: 'link_account',
};
const JWKS_CACHE_KEY = 'jwks-cache';
const MGMT_TOKEN_CACHE_KEY = 'management-token';
/**
* This action should only run for OIDC/OAuth 2 Flows
* @type {Protocol[]}
*/
const ALLOWED_PROTOCOLS = [
'oidc-basic-profile',
'oidc-implicit-profile',
'oauth2-device-code',
'oidc-hybrid-profile',
];
// End Global Constants
/**
* Initial Handler
*
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
* @returns
*/
exports.onExecutePostLogin = async (event, api) => {
normalizeEventConfiguration(event);
debug.enable(event.configuration.DEBUG || 'account-linking:*');
try {
if (isLinkingRequest(event)) {
const jwksCache = extractCachedJWKS(event, api);
const response = await validateIdTokenHint(event, api, jwksCache);
if (response === 'invalid') {
logger.error('Denying linking request ID_TOKEN_HINT provided was invalid');
api.access.deny(
'ID_TOKEN_HINT Invalid: The `id_token_hint` does not conform to the authorization policy',
);
return;
}
if (event.configuration.ENFORCE_MFA === 'yes') {
if (
Array.isArray(event.user.enrolledFactors) &&
event.user.enrolledFactors.length > 0
) {
if (!event.authentication?.methods?.some((method) => method.name === 'mfa')) {
logger.info(
'Denying linking request for %s mfa was not performed in this transaction, a previous action must use .challengeWith, .challengeWithAny',
event.user.user_id,
);
api.access.deny('You must perform MFA for account linking');
return;
}
}
}
if (
event.configuration.ENFORCE_EMAIL_VERIFICATION === 'yes' &&
event.user.email_verified === false
) {
logger.info(
'Denying linking request for %s email is not verified',
event.user.user_id,
);
api.access.deny('Email Verification is required for account linking');
return;
}
return handleLinkingRequest(event, api);
}
if (isNestedTransaction(event)) {
if (event.configuration.ENFORCE_MFA === 'yes') {
forceMFAForNestedTransaction(event, api);
}
}
} catch (err) {
logger.error('Unexpected Error, %s', err.toString());
api.access.deny('Unexpected Error trying to start account linking');
}
};
/**
* Callback handler
*
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
* @returns
*/
exports.onContinuePostLogin = async (event, api) => {
normalizeEventConfiguration(event);
if (isLinkingRequest(event)) {
return handleLinkingCallback(event, api);
}
};
/**
* Check's if this an Account Linking Request
*
* @param {PostLoginEvent} event
*/
function normalizeEventConfiguration(event) {
event.configuration = event.configuration || {};
// prefer configuration
event.configuration.DEBUG =
event.configuration?.DEBUG || event.secrets?.DEBUG || 'account-linking:error';
event.configuration.ENFORCE_MFA =
event.configuration?.ENFORCE_MFA || event.secrets?.ENFORCE_MFA || 'no';
event.configuration.ENFORCE_EMAIL_VERIFICATION =
event.configuration?.ENFORCE_EMAIL_VERIFICATION ||
event.secrets?.ENFORCE_EMAIL_VERIFICATION ||
'no';
event.configuration.PIN_IP_ADDRESS =
event.configuration?.PIN_IP_ADDRESS || event.secrets?.PIN_IP_ADDRESS || 'no';
}
// Helper Utilities
/**
* Function that detects if we are running within a nested transaction
* @param {PostLoginEvent} event
*/
function isNestedTransaction(event) {
const { AUTH0_CLIENT_ID: clientId } = event.secrets;
if (event.client.client_id === clientId) {
return true;
}
}
/**
* Forces MFA for the nested transaction
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
*/
function forceMFAForNestedTransaction(event, api) {
if (Array.isArray(event.user.enrolledFactors) && event.user.enrolledFactors.length > 0) {
api.authentication.challengeWithAny(
event.user.enrolledFactors.map((factor) =>
factor.method === 'sms'
? {
type: 'phone',
options: { preferredMethod: 'sms' },
}
: { type: factor.method },
),
);
}
}
/**
* Check's if this an Account Linking Request
*
* @param {PostLoginEvent} event
*/
function isLinkingRequest(event) {
if (!event.transaction || !event.transaction.protocol) {
logger.verbose('Skipping because no transaction');
return false;
}
if (ALLOWED_PROTOCOLS.includes(event.transaction.protocol) === false) {
logger.verbose('Skipping because protocol not allowed');
return false;
}
const { requested_scopes } = event.transaction;
if (!Array.isArray(requested_scopes)) {
logger.verbose('Skipping because requested_scopes not found');
return false;
}
if (!requested_scopes.includes(SCOPES.LINK)) {
logger.verbose('Skipping because requested_scopes does not contain link_account');
return false;
}
const { ALLOWED_CLIENT_IDS } = event.secrets;
if (ALLOWED_CLIENT_IDS !== undefined) {
const allowedClientIds = ALLOWED_CLIENT_IDS.split(',');
if (allowedClientIds.includes(event.client.client_id) === false) {
logger.error('Account Linking is not allowed for %s', event.client.client_id);
return false;
}
}
return true;
}
/**
*
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
*/
async function handleLinkingRequest(event, api) {
const issuer = getAuth0Issuer(event);
const {
requested_connection: requestedConnection,
requested_connection_scope: requestedConnectionScope,
} = event.request.query;
const codeVerifier = await getUniqueTransaction(event);
const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier);
const jwksCache = extractCachedJWKS(event, api);
const config = await getOpenIDClientConfig(event, api, jwksCache);
logger.info(
'Generating authorization request for %s provider %s',
event.user.user_id,
requestedConnection,
);
/**
* @type {Record<string, string>}
*/
const authorizationParameters = {
redirect_uri: new URL('/continue', issuer).toString(),
code_challenge: codeChallenge,
code_challenge_method: 'S256',
connection: requestedConnection,
scope: 'openid profile email', // this scope is for the auth0 transaction
max_age: '0',
};
if (requestedConnectionScope) {
// This scope is for the transaction
authorizationParameters['connection_scope'] = requestedConnectionScope;
}
logger.info('Requesting authorization with provider %s', requestedConnection);
const authorizeUrl = client.buildAuthorizationUrl(config, authorizationParameters);
api.redirect.sendUserTo(authorizeUrl.toString());
}
/**
*
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
*/
async function handleLinkingCallback(event, api) {
const callbackUrl = getCallbackUrl(event);
const jwksCacheInput = extractCachedJWKS(event, api);
const config = await getOpenIDClientConfig(event, api, jwksCacheInput);
const codeVerifier = await getUniqueTransaction(event);
let subject;
try {
logger.info('Attempting callback verification for %s', event.user.user_id);
const tokens = await client.authorizationCodeGrant(config, callbackUrl, {
expectedState: client.skipStateCheck,
idTokenExpected: true,
maxAge: 60,
pkceCodeVerifier: codeVerifier,
});
const jwksCacheExport = client.getJwksCache(config);
// Store cached JWTs
if (jwksCacheExport && jwksCacheExport.uat !== jwksCacheInput?.uat) {
storeCachedJWKS(event, api, jwksCacheExport);
}
const claims = tokens.claims();
if (!claims) {
console.warn('Failed: No claims');
return;
}
subject = claims['sub'];
logger.info('Callback success for %s', event.user.user_id);
} catch (err) {
logger.error(
'Failed to complete account linking for %s: %s',
event.user.user_id,
err.toString(),
);
api.access.deny('Failed to complete account linking');
return;
}
return linkAndMakePrimary(event, api, subject);
}
/**
* Will obtain a cached JWKS from Actions Cache
*
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
*
* @returns {jose.ExportedJWKSCache | undefined} either a cached jwks or null. If this fails it'll fail gracefully
*/
function extractCachedJWKS(event, api) {
try {
const cachedJWKCache = api.cache.get(JWKS_CACHE_KEY);
if (!cachedJWKCache) {
return undefined;
}
/**
* @type {jose.ExportedJWKSCache}
*/
const value = JSON.parse(cachedJWKCache.value);
return value;
} catch (err) {
// We should default to return here
// we can always fetch as fallback
}
return undefined;
}
/**
* Will obtain a cached JWKS from Actions Cache
*
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
* @param {jose.ExportedJWKSCache} updated Exported JWKS cache
*/
function storeCachedJWKS(event, api, updated) {
api.cache.set(JWKS_CACHE_KEY, JSON.stringify(updated));
}
/**
* Helper function to return a client from openid-client. This is used
* for all the requests.
*
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
* @param {jose.ExportedJWKSCache | undefined} jwksCacheInput
*
* @returns {Promise<client.Configuration>}
*/
async function getOpenIDClientConfig(event, api, jwksCacheInput) {
const issuer = getAuth0Issuer(event);
const { AUTH0_CLIENT_ID: clientId, AUTH0_CLIENT_SECRET: clientSecret } = event.secrets;
const config = await client.discovery(
issuer,
clientId,
{},
client.ClientSecretPost(clientSecret),
{
algorithm: 'oidc',
},
);
if (jwksCacheInput !== undefined) {
client.setJwksCache(config, jwksCacheInput);
}
return config;
}
/**
* returns the callback url
*
* @param {PostLoginEvent} event
* @returns {URL}
*/
function getCallbackUrl(event) {
const callbackUrl = new URL('/continue', getAuth0Issuer(event));
callbackUrl.search = new URLSearchParams(event.request.query).toString();
return callbackUrl;
}
/**
* This method implements the following logic
*
* - Ensure the `id_token_hint` is a valid `id_token`.
* - Ensure the `client_id` in `id_token` matches the `client_id` of `event`.
* - Ensure the `id_token` was issued to one of the event.secrets.ALLOWED_CLIENTs
* - Ensure the `user_id` of the current `event.user` is the same as current user
*
*
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
* @param {jose.ExportedJWKSCache | undefined} jwksCache
* @returns {Promise<"invalid"|"valid">} `valid` if all constraints match, `invalid` if any constraint fail,
*/
async function validateIdTokenHint(event, api, jwksCache) {
const { id_token_hint: idTokenHint } = event.request.query;
const issuer = getAuth0Issuer(event);
if (!idTokenHint || typeof idTokenHint !== 'string') {
return 'invalid';
}
const { client_id: clientId } = event.client;
const { user_id: userId } = event.user;
const jwksUrl = new URL('/.well-known/jwks.json', issuer);
const JWKS = jose.createRemoteJWKSet(jwksUrl, {
[jose.jwksCache]: jwksCache,
});
try {
const payload = await jose.jwtVerify(idTokenHint, JWKS, {
algorithms: ['RS256'],
audience: clientId,
subject: userId,
issuer: issuer.toString(),
maxTokenAge: '10m',
});
return 'valid';
} catch (err) {
//
logger.error('ID_TOKEN_HINT validation failure %s', err.toString());
}
return 'invalid';
}
/**
* Helper function to get a cached management token and client.
*
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
* @returns
*/
async function getManagementClient(event, api) {
let { value: token } = api.cache.get(MGMT_TOKEN_CACHE_KEY) || {};
if (!token) {
logger.verbose('Attempting to obtain token for management api');
// we don't need the JWKS here.
const config = await getOpenIDClientConfig(event, api, undefined);
try {
const tokenset = await client.clientCredentialsGrant(config, {
audience: new URL('/api/v2/', `https://${event.secrets.AUTH0_DOMAIN}`).toString(),
});
const { access_token: accessToken } = tokenset;
token = accessToken;
if (!token) {
logger.error('No access token was returned by the server for Management API');
return null;
}
const result = api.cache.set(MGMT_TOKEN_CACHE_KEY, token, {
ttl: (tokenset.expires_in - 60) * 1000,
});
if (result?.type === 'error') {
logger.error(
'failed to set the token in the cache with error code: %s',
result.code,
);
}
} catch (err) {
logger.error('failed calling cc grant %s', err.toString());
return null;
}
}
logger.info('Created a management api client');
return new ManagementClient({
domain: getAuth0Issuer(event).hostname,
token,
});
}
/**
*
* @param {string} sub
* @returns {{provider: PostIdentitiesRequestProviderEnum, user_id: string}}
*/
function splitSubClaim(sub) {
const firstPipeIndex = sub.indexOf('|');
const provider = /** @type {PostIdentitiesRequestProviderEnum} */ (
sub.slice(0, firstPipeIndex)
);
return {
provider,
user_id: sub.slice(firstPipeIndex + 1),
};
}
/**
* Returns the current domain for the tenant
*
* @param {PostLoginEvent} event
*/
function getAuth0Issuer(event) {
return new URL(`https://${event.request.hostname}/`);
}
/**
* In order to determine this transaction can be executed only between the initial
* and the continue handler. We need to derive a unique string
*
* @todo: Once `transaction.id` is stable, us that to derive PKCE
*
* @param {PostLoginEvent} event
*/
async function getUniqueTransaction(event) {
const { ACTION_SECRET: appSecret } = event.secrets;
const { PIN_IP_ADDRESS: pinIp } = event.configuration;
// eslint-disable-next-line no-unused-vars
const { protocol, requested_scopes, response_type, redirect_uri, state, locale } =
/**{@type {Transaction}} */ event.transaction;
const { id: sessionId } = event.session || {};
const stableTransaction = [
event.user.user_id,
protocol,
requested_scopes,
response_type,
redirect_uri,
state,
locale,
sessionId,
];
if (pinIp) {
stableTransaction.push(event.request.ip);
}
const transactionInfo = JSON.stringify(stableTransaction);
const transactionHotfix = sha256(transactionInfo);
const derivedKey = await hkdf(
'sha256',
transactionHotfix, // ikm
appSecret, // salt
transactionInfo, // info
64, // len
);
return Buffer.from(derivedKey).toString('base64url');
}
/**
*
* @param {PostLoginEvent} event
* @param {PostLoginAPI} api
* @param {string} secondaryIdentityUserId
* @returns
*/
async function linkAndMakePrimary(event, api, secondaryIdentityUserId) {
const primaryUserId = event.user.user_id;
logger.info(
'Attempting account linking for %s with %s',
primaryUserId,
secondaryIdentityUserId,
);
if (primaryUserId === secondaryIdentityUserId) {
logger.info(
'Attempting already performed since %s === %s',
primaryUserId,
secondaryIdentityUserId,
);
return;
}
const client = await getManagementClient(event, api);
if (client === null) {
api.access.deny('Failed to link users');
return;
}
try {
await client.users.link({ id: primaryUserId }, splitSubClaim(secondaryIdentityUserId));
logger.info(
'link successful current user %s to %s',
primaryUserId,
secondaryIdentityUserId,
);
// api.authentication.setPrimaryUser(upstream_sub);
} catch (err) {
logger.error(`unable to link, no changes. error: ${JSON.stringify(err)}`);
return api.access.deny('error linking');
}
}
/**
*
* @param {string} str
*/
function sha256(str) {
return createHash('sha256').update(str).digest('base64url');
}
// End: Helper Utilities
