Skip to content

Commit 5862a16

Browse files
author
Kevin Strong-Holte
committed
Added article: Use Akamai Supplemental Signals in Actions
1 parent 8679c5f commit 5862a16

File tree

1 file changed

+199
-0
lines changed

1 file changed

+199
-0
lines changed

‎main/docs/secure/attack-protection/use-akamai-supplemental-signals-actions.mdx‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
'og:description': Learn how to use Akamai supplemental signals in Auth0 Actions.
3+
'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png
4+
'og:title': Use Akamai Supplemental Signals in Actions
5+
'og:url': https://auth0.com/docs/
6+
permalink: use-akamai-supplemental-signals-actions
7+
title: Use Akamai Supplemental Signals in Actions
8+
'twitter:description': Learn how to use Akamai supplemental signals in Auth0 Actions.
9+
'twitter:title': Use Akamai Supplemental Signals in Actions
10+
---
11+
<Warning>
12+
**Auth0 Supplemental Signals is currently in Early Access.**
13+
14+
By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0 product release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
15+
</Warning>
16+
<Info>
17+
**Before you start**
18+
19+
To use Akamai supplemental signals in Actions, you must:
20+
- [Configure Akamai as a reverse proxy](/docs/customize/custom-domains/self-managed-certificates)
21+
- [Configure Akamai to Send Supplemental Signals](./configure-akamai-supplemental-signals)
22+
</Info>
23+
24+
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](/docs/customize/actions).
25+
26+
## Supported supplemental signals by Action trigger
27+
| Trigger | Supplemental signal objects | Event object |
28+
| --- | --- | --- |
29+
| Login | <ul><li><code>akamaiBot</code></li><li><code>akamaiUserRisk</code></li></ul> | <a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object"><code>authentication.riskAssessment.supplemental.akamai</code></a> |
30+
| Pre-User Registration | None | N/A |
31+
| Post-User Registration| None | N/A |
32+
| Send Phone Message | None | N/A |
33+
| Post-Challenge | None | N/A |
34+
| Post-Change Password | None | N/A |
35+
| Credentials Exchange | None | N/A |
36+
37+
## Supplemental signal object schemas
38+
The `akamaiBot` and `akamaiUserRisk` objects contain multiple properties you can use to customize your authentication flow.
39+
40+
<ResponseField name="akamaiBot" type="object">
41+
<Expandable>
42+
<ResponseField name="action" type="string">
43+
The action of the Akamai bot manager results.
44+
45+
Example: `Monitor`
46+
</ResponseField>
47+
<ResponseField name="botCategory" type="string[]">
48+
The bot cateogry of the Akamai bot manager results.
49+
50+
Example: `["Web Search Engine Bots"]`
51+
</ResponseField>
52+
<ResponseField name="botScore" type="number">
53+
The bot score of the Akamai bot manager results.
54+
55+
Example: `90`
56+
</ResponseField>
57+
<ResponseField name="botScoreResponseSegment" type="string">
58+
The bot score response segment of the Akamai bot manager results.
59+
60+
Example: `aggressive`
61+
</ResponseField>
62+
<ResponseField name="botnetId" type="string">
63+
The botnet ID of the Akamai bot manager results.
64+
65+
Example: `googlebot`
66+
</ResponseField>
67+
<ResponseField name="type" type="string">
68+
The type of the Akamai bot manager results.
69+
70+
Example: `Akamai-Categorized Bot`
71+
</ResponseField>
72+
</Expandable>
73+
</ResponseField>
74+
75+
<ResponseField name="akamaiUserRisk" type="object">
76+
<Expandable>
77+
<ResponseField name="action" type="string">
78+
The action of the Akamai user risk assessment.
79+
80+
Example: `monitor`
81+
</ResponseField>
82+
<ResponseField name="allow" type="number">
83+
The allowed status of the Akamai user risk assessment.
84+
85+
Example: `0`
86+
</ResponseField>
87+
<ResponseField name="emailDomain" type="string">
88+
The email domain of the user.
89+
90+
Example: `example.com`
91+
</ResponseField>
92+
<ResponseField name="general" type="object">
93+
The general risk of the Akamai user risk assessment.
94+
95+
Example: `{ aci: “0”, db: “Chrome 85”, di: “0fc91b5ec42f5a471c16a85e3e388ca57697c1a9”, do: “Mac OX X 10” }`
96+
</ResponseField>
97+
<ResponseField name="ouid" type="string">
98+
The OUID of the user.
99+
100+
Example: `m534264`
101+
</ResponseField>
102+
<ResponseField name="requestid" type="string">
103+
The request ID of the user.
104+
105+
Example: `19e22e`
106+
</ResponseField>
107+
<ResponseField name="risk" type="object">
108+
The risk of the Akamai user risk assessment.
109+
110+
Example: `{ ugp: “ie/M”, unp: “432/H” }`
111+
</ResponseField>
112+
<ResponseField name="score" type="number">
113+
The score of the Akamai user risk assessment.
114+
115+
Example: `0`
116+
</ResponseField>
117+
<ResponseField name="status" type="number">
118+
The status of the Akamai user risk assessment.
119+
120+
Example: `4`
121+
</ResponseField>
122+
<ResponseField name="trust" type="object">
123+
The trust of the Akamai user risk assessment.
124+
125+
Example: `{ udbp: "Chrome85", udfp: "25ba44ec3b391ba4ce5fbbd2979635e254775werwe", udop: "Mac OS X 10", ugp: "FR", unp: "12322", utp: "weekday_3" }`
126+
</ResponseField>
127+
<ResponseField name="username" type="string">
128+
The username of the user.
129+
130+
Example: `[email protected]`
131+
</ResponseField>
132+
<ResponseField name="uuid" type="string">
133+
The UUID of the Akamai user risk assessment.
134+
135+
Example: `86b37525-8047-4a3c-8d7a-23e99666da05`
136+
</ResponseField>
137+
</Expandable>
138+
</ResponseField>
139+
140+
## Use cases
141+
<AccordionGroup>
142+
<Accordion title="Revoke a session based on Akamai Account Protector results">
143+
Here’s an example of how you could revoke a session based on the `akamaiUserRisk.score` property:
144+
```javascript
145+
exports.onExecutePostLogin = async (event, api) => {
146+
const userRiskHeader = event.authentication?.riskAssessment?.supplemental?.akamai?.akamaiUserRisk;
147+
if (userRiskHeader?.score && userRiskHeader?.score >= 90) {
148+
console.log('User is deemed high risk.');
149+
//This will revoke session cookies to deny login.
150+
api.session.revoke('Session revoked, User risk score is greater than 90.');
151+
}
152+
};
153+
154+
```
155+
156+
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 post-login Action flow is triggered.
157+
</Accordion>
158+
<Accordion title="Prompt multi-factor authentication (MFA) based on Akamai Bot Manager results">
159+
Here’s an example of how you could enforce MFA based on the `akamaiBot.score` property.
160+
161+
#### Enforce MFA
162+
This Action performs two tasks:
163+
1. **Update [app metadata](/docs/manage-users/user-accounts/metadata/metadata-fields-data)**: If the score property exceeds a specified value, record that MFA is required for the session.
164+
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.
165+
```javascript
166+
exports.onExecutePostLogin = async (event, api) => {
167+
const userRiskHeader = event.authentication?.riskAssessment?.supplemental?.akamai?.akamaiUserRisk;
168+
169+
if (userRiskHeader?.score && userRiskHeader?.score >= 90) {
170+
console.log(`Setting app metadata for session id: ${event.session?.id}`);
171+
api.user.setAppMetadata(`mfa_required_${event.session?.id}`, true);
172+
}
173+
174+
if (userRiskHeader?.score && userRiskHeader?.score >= 90 ||
175+
event.user.app_metadata[`mfa_required_${event.session?.id}`]) {
176+
console.log(`Requiring MFA FOR Session id: ${event.session?.id}`);
177+
api.multifactor.enable('any', {allowRememberBrowser: false});
178+
}
179+
};
180+
181+
```
182+
183+
#### Clean up app metadata
184+
This Action removes session-specific MFA information from app metadata after the user completes MFA successfully.
185+
186+
```javascript
187+
exports.onExecutePostLogin = async (event, api) => {
188+
const mfaMethod = event.authentication?.methods.find((method) => {
189+
return method.name === 'mfa';
190+
});
191+
192+
if (mfaMethod) {
193+
console.log(`Removing MFA requirement for session id: ${event.session?.id}`);
194+
api.user.setAppMetadata(`mfa_required_${event.session?.id}`, undefined);
195+
}
196+
};
197+
```
198+
</Accordion>
199+
</AccordionGroup>

0 commit comments

Comments
 (0)