Use Akamai Supplemental Signals in Actions

Before you start

To use Akamai supplemental signals in Actions, you must:

If you have configured Akamai as a reverse proxy and set it up to send supplemental signals to Auth0, you can use the data provided in those signals in Auth0 Actions.

Supplemental signal object schemas

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

akamaiBot

The akamaiBot object contains information provided by Akamai Bot Manager.

Property Data type Description Example
action String The action of the Akamai bot manager results. Monitor
botCategory Array of strings The bot category of the Akamai bot manager results. ["Web Search Engine Bots"]
botScore Number The bot score of the Akamai bot manager results. 90
botScoreResponseSegment String The bot score response segment of the Akamai bot manager results. aggressive
botnetId String The botnet ID of the Akamai bot manager results. googlebot
type String The type of the Akamai bot manager results. Akamai-Categorized Bot

akamaiUserRisk

The akamaiUserRisk object contains information provided by Akamai Account Protector.

Property Data type Description Example
action String The action of the Akamai user risk assessment. monitor
allow Number The allowed status of the Akamai user risk assessment. 0
emailDomain String The email domain of the user. example.com
general String The general risk of the Akamai user risk assessment. { aci: “0”, db: “Chrome 85”, di: “0fc91b5ec42f5a471c16a85e3e388ca57697c1a9”, do: “Mac OX X 10” }
ouid String The OUID of the user. m534264
requestid String The request ID of the user. 19e22e
risk String The risk of the Akamai user risk assessment. { ugp: “ie/M”, unp: “432/H” }
score Number The score of the Akamai user risk assessment. 0
status Number The status of the Akamai user risk assessment. 4
trust String The trust of the Akamai user risk assessment. { udbp: "Chrome85", udfp: "25ba44ec3b391ba4ce5fbbd2979635e254775werwe", udop: "Mac OS X 10", ugp: "FR", unp: "12322", utp: "weekday_3" }
username String The username of the user. testuser@example.com
uuid String The UUID of the Akamai user risk assessment. 86b37525-8047-4a3c-8d7a-23e99666da05

Supported supplemental signals by Action trigger

Trigger Supplemental signal object(s) Event object
Login
  • akamaiBot
  • akamaiUserRisk
 authentication.riskAssessment.supplemental.akamai
Pre-User Registration None N/A
Post-User Registration None N/A
Send Phone Message None N/A
Post-Challenge None N/A
Post-Change Password None N/A
Credentials Exchange None N/A

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.');
    }
};

Was this helpful?

/

Please note the use of the api.session.revoke method (compared to the api.access.deny method). Using the revoke method ensures that if the user refreshes the application, the Akamai supplemental signals are sent with the authentication request and the Action Login trigger flow is executed.

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});
  }
};

Was this helpful?

/

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);
  }
};

Was this helpful?

/

Learn more