Configure Akamai to Send Supplemental Signals

Configure Akamai as a reverse proxy to send Supplmental Signals to your Auth0 tenant.

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 configure Akamai to send Supplemental Signals to your Auth0 tenant, you must configure Akamai as a reverse proxy.

If you use Akamai Bot Manager and/or Akamai Account Protector, you can configure your reverse proxy in Akamai to send the results to Auth0 and use the results in Actions.

Supported login flows

Auth0 currently supports the following login flows for Supplemental Signals:

• Universal Login: Identifier + Password
• Universal Login: Identifier First
• Universal Login: Signup on database connections
• Universal Login: Password reset, including Auth0 Organizations
• Resource Owner Password Grant (ROPG)

Step 1: Register an API in Akamai

For Akamai to know when login attempts succeed or fail, you’ll need to register an API in Akamai, and then define an endpoint for each Auth0 login flow you’d like to support.

To learn more, read Register an API on Akamai TechDocs and Add API resources on Akamai TechDocs.

New Universal Login Identifier + Password

Use the following values to register your API in Akamai:

Property	Value
API base path	/u
API key location	Header

After you’ve created your API, you’ll need to add an API resource for each of the following Auth0 endpoints:

• /u/login/password
• /u/signup
• /u/signup/password

The process is the same for all endpoints, but the configuration values differ slightly.

Add API resource

Use the following values to configure a resource on your Akamai API:

/u/login/password

Property	Value
API undefined parameters	Specific (Request body)
Path	/login/password
Methods	POST

/u/signup

Property	Value
API undefined parameters	Specific (Request body)
Path	/signup
Methods	POST

/u/signup/password

Property	Value
API undefined parameters	Specific (Request body)
Path	/signup/password
Methods	POST

Add parameters to methods

After you’ve created your API resource, you’ll need to define the Request body parameter so Akamai can parse login requests properly.

Use the following values to define the Request body parameter:

/u/login/password

Property	Value
Format	JSON
Required	Yes
Define body format	Yes
Schema details	See below.

{
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "required": [
            "state"
          ],
          "properties": {
            "state": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            },
            "username": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            },
            "password": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            },
            "action": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            }
          }
        }
      }
    },
    "required": true
  }
}

/u/signup

Property	Value
Format	JSON
Required	Yes
Define body format	Yes
Schema details	See below.

{
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "required": [
            "email",
            "password"
          ],
          "properties": {
            "email": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            },
            "password": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            }
          }
        }
      }
    },
    "required": true
  }
}

/u/signup/password

Property	Value
Format	JSON
Required	Yes
Define body format	Yes
Schema details	See below.

{
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256,
              "description": "email"
            }
          }
        }
      }
    },
    "required": true
  }
}

New Universal Login Identifier First

Use the following values to register your API in Akamai:

Property	Value
API base path	/u
API key location	Header

After you’ve created your API, you’ll need to add an API resource for each of the following Auth0 endpoints:

• /u/login
• /u/signup
• /u/signup/password

The process is the same for all endpoints, but the configuration values differ slightly.

Add API resource

Use the following values to configure a resource on your Akamai API:

/u/login

Property	Value
API undefined parameters	Specific (Request body)
Path	/login
Methods	POST

/u/signup

Property	Value
API undefined parameters	Specific (Request body)
Path	/login/signup
Methods	POST

/u/signup/password

Property	Value
API undefined parameters	Specific (Request body)
Path	/signup/password
Methods	POST

Add parameters to methods

After you’ve created your API resource, you’ll need to define the Request body parameter so Akamai can parse login requests properly.

Use the following values to define the Request body parameter:

/u/login

Property	Value
Format	JSON
Required	Yes
Define body format	Yes
Schema details	See below.

{
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "required": [
            "state"
          ],
          "properties": {
            "state": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            },
            "username": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            },
            "password": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            },
            "action": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            }
          }
        }
      }
    },
    "required": true
  }
} 

/u/signup

Property	Value
Format	JSON
Required	Yes
Define body format	Yes
Schema details	See below.

{
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "required": [
            "email",
            "password"
          ],
          "properties": {
            "email": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            },
            "password": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            }
          }
        }
      }
    },
    "required": true
  }
} 

/u/signup/password

Property	Value
Format	JSON
Required	Yes
Define body format	Yes
Schema details	See below.

{
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256,
              "description": "email"
            }
          }
        }
      }
    },
    "required": true
  }
}

ROPG

Use the following values to register your API in Akamai:

Property	Value
API base path	None.
API key location	Header

After you’ve created your API, you’ll need to add an API resource for each of the following Auth0 endpoints:

• /oauth/token

The process is the same for all endpoints, but the configuration values differ slightly.

Add API resource

Use the following values to configure a resource on your Akamai API:

/oauth/token

Property	Value
API undefined parameters	Specific (Request body)
Path	/oauth/token
Methods	POST

Add parameters to methods

After you’ve created your API resource, you’ll need to define the Request body parameter so Akamai can parse login requests properly.

Use the following values to define the Request body parameter:

/oauth/token

Property	Value
Format	JSON
Required	Yes
Define body format	Yes
Schema details	See below.

{
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "username": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            },
            "password": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 256
            }
          }
        }
      }
    },
    "required": true
  }
} 

Step 2: Forward bot results from Akamai to Auth0

To configure Akamai to forward bot results to Auth0, read Forward Bot Results to Origin on Akamai TechDocs.

The akamai-user-risk header may not be present on every login request, as Akamai only sends the header when it creates a user risk score.

Step 3: Enable processing of Akamai headers in Auth0

You can configure Auth0 to accept Supplemental Signals sent from Akamai in the Auth0 Dashboard or with the Auth0 Management API.

Dashboard

To enable Supplemental Signals in the Dashboard:

1. Navigate to Auth0 Dashboard > Security > Attack Protection.
2. Select Supplemental Signals.
3. Enable the toggle for Enable Akamai headers.

If you do not see the option for Supplemental Signals in Auth0 Dashboard, you need to request the Attack Protection Add-on. To learn more, contact Auth0 Sales.

Management API

To enable Supplemental Signals with the Management API:

1. Get a Management API access token with the update:attack_protection scope.
2. Call the Management API Update the Supplemental Signals configuration for a tenant endpoint with the following body:

{
  "akamai_enabled": true
}

Step 4: Test and verify configuration

Test your configuration by calling each endpoint for the login flow(s) you have configured.

If you’ve configured everything properly:

• The akamai-user-risk and akamai-bot headers will be present in your tenant logs for related events.
• You can use the following properties in the post-login Action event object:
  • authentication.riskAssessment.supplemental.akamai.akamaiBot
  • authentication.riskAssessment.supplemental.akamai.akamaiUserRisk