Use Akamai Supplemental Signals in Actions

Use Auth0 Actions with Akamai Account Protector signals to enrich login decisions with bot, fraud, and risk scores from Akamai’s edge network.

Supplemental Signals is available for Enterprise customers, and you must request the Attack Protection Add-on. Contact Auth0 Sales for more information.

Before you start

To use Akamai Supplemental Signals in Actions, you must:

• Configure Akamai as a reverse proxy
• Configure Akamai to Send Supplemental Signals

Once you have configured Akamai to use Supplemental Signals, you can use the data provided in those signals in Auth0 Actions.

Supported Supplemental Signals by Action trigger

Trigger	Supplemental Signal objects	Event object
Login	akamaiBot akamaiUserRisk	event.authentication.riskAssessment.supplemental.akamai
Pre-User Registration	akamaiBot akamaiUserRisk	event.authentication.riskAssessment.supplemental.akamai
Post-User Registration	akamaiBot akamaiUserRisk	event.authentication.riskAssessment.supplemental.akamai
Send Phone Message	None	N/A
Post-Challenge	akamaiBot akamaiUserRisk	event.authentication.riskAssessment.supplemental.akamai
Post-Change Password	akamaiBot akamaiUserRisk	event.authentication.riskAssessment.supplemental.akamai
Credentials Exchange	None	N/A

Supplemental Signal object schemas

The akamaiBot and akamaiUserRisk objects contain multiple properties you can use to customize your authentication flow.

akamaiBot · object

Show child attributes

action · string

The action of the Akamai bot manager results.

Example: Monitor

botCategory · string[]

The bot category of the Akamai bot manager results.

Example: ["Web Search Engine Bots"]

botScore · number

The bot score of the Akamai bot manager results.

Example: 90

botScoreResponseSegment · string

The bot score response segment of the Akamai bot manager results.

Example: aggressive

botnetId · string

The botnet ID of the Akamai bot manager results.

Example: googlebot

type · string

The type of the Akamai bot manager results.

Example: Akamai-Categorized Bot

akamaiUserRisk · object

Show child attributes

action · string

The action of the Akamai user risk assessment.

Example: monitor

allow · number

The allowed status of the Akamai user risk assessment.

Example: 0

emailDomain · string

The email domain of the user.

Example: example.com

general · object

The general risk of the Akamai user risk assessment.

Example: { aci: “0”, db: “Chrome 85”, di: “0fc91b5ec42f5a471c16a85e3e388ca57697c1a9”, do: “Mac OS X 10” }

ouid · string

The OUID of the user.

Example: m534264

requestid · string

The request ID of the user.

Example: 19e22e

risk · object

The risk of the Akamai user risk assessment.

Example: { ugp: “ie/M”, unp: “432/H” }

score · number

The score of the Akamai user risk assessment.

Example: 0

status · number

The status of the Akamai user risk assessment.

Example: 4

trust · object

The trust of the Akamai user risk assessment.

Example: { udbp: "Chrome85", udfp: "25ba44ec3b391ba4ce5fbbd2979635e254775werwe", udop: "Mac OS X 10", ugp: "FR", unp: "12322", utp: "weekday_3" }

username · string

The username of the user.

Example: [e-mail]

uuid · string

The UUID of the Akamai user risk assessment.

Example: 86b37525-8047-4a3c-8d7a-23e99666da05

Use cases

Revoke a session based on Akamai Account Protector results

Here’s an example of how you could revoke a session based on the akamaiUserRisk.score property:

exports.onExecutePostLogin = async (event, api) => {
  const userRiskHeader = event.authentication?.riskAssessment?.supplemental?.akamai?.akamaiUserRisk;
  if (userRiskHeader?.score && userRiskHeader?.score >= 90) {
        console.log('User is deemed high risk.');
        //This will revoke session cookies to deny login.
        api.session.revoke('Session revoked, User risk score is greater than 90.');
    }
};

Using the api.session.revoke method (compared to the api.access.deny method) ensures that if the user refreshes the application, the Akamai Supplemental Signals are sent with the authentication request and the post-login Action flow is triggered.

Prompt multi-factor authentication (MFA) based on Akamai Bot Manager results

Here’s an example of how you could enforce MFA based on the akamaiBot.score property.

Enforce MFA

This Action performs two tasks:

1. Update app metadata: If the score property exceeds a specified value, record that MFA is required for the session.
2. Require MFA: If the score property exceeds a specified value or if there is a record in the app metadata indicating MFA is required for the session, enforce MFA.

exports.onExecutePostLogin = async (event, api) => {
  const userRiskHeader = event.authentication?.riskAssessment?.supplemental?.akamai?.akamaiUserRisk;

  if (userRiskHeader?.score && userRiskHeader?.score >= 90) {
    console.log(`Setting app metadata for session id: ${event.session?.id}`);
    api.user.setAppMetadata(`mfa_required_${event.session?.id}`, true);
  }

  if (userRiskHeader?.score && userRiskHeader?.score >= 90 ||
      event.user.app_metadata[`mfa_required_${event.session?.id}`]) {
        console.log(`Requiring MFA FOR Session id: ${event.session?.id}`);
        api.multifactor.enable('any', {allowRememberBrowser: false});
  }
};

Clean up app metadata

This Action removes session-specific MFA information from app metadata after the user completes MFA successfully.

exports.onExecutePostLogin = async (event, api) => {
  const mfaMethod = event.authentication?.methods.find((method) => {
    return method.name === 'mfa';
  });

  if (mfaMethod) {
    console.log(`Removing MFA requirement for session id: ${event.session?.id}`);
    api.user.setAppMetadata(`mfa_required_${event.session?.id}`, undefined);
  }
};