Client reputation

Most of the people who visit a website (or who use a cell phone app) are there for the right reasons: they want to read the diabetes prevention articles that you’ve posted; they want to buy the sporting goods you have for sale; they want to upload their recipe for chocolate layer cake or redeem their customer loyalty points. And that’s great; after all, that’s why you put up your website (or created your app) in the first place.

Unfortunately, however, not everyone who visits a website (or uses an app) is there for the right reasons. Although they make up a small minority of Internet users, there are people who visit your web site hoping to do things like: steal data (either your proprietary data or your users’ private information); poke around hoping to find a door left unlocked or a window left open; or just generally wreak havoc. These malefactors can often be identified, and thwarted, after they’ve logged on to a site. Ideally, however, they could be stopped before they even get to your site.

To help keep bad actors from logging on to your website or app, the ​Akamai​ Identity Cloud has included Client Reputation as part of the Risk-based Authentication (RBA) add-on that uses a sophisticated risk-analysis engine to compute a set of “risk scores” for each IP address that tries to access your site. Explaining how a risk score is derived goes beyond what we can cover in this documentation; you can read more about that here. For now, it’s enough to know that Client Reputation (built on proprietary ​Akamai​ technology) is able to analyze an IP address and use such things as attacker persistency, number of targeted applications, severity of the attack, magnitude, industry, and previous attacks targeting a customer’s applications to come up with a score that specifies the likelihood of this IP address engaging in one (or more) of the following web attacks:

  • DOSATCK. Using botnets to launch Denial of Service (DoS) attacks. The goal of a DoS attack is to flood a site with bogus requests, so many requests that the site becomes unbearably slow, or even crashes. In a Distributed Denial of Service (DDoS) attack, these bogus requests  come from thousands of locations (typically malware-infected computers or phones), making it impossible to stop the attack simply by blocking a given IP address.

  • SCANTL. Using a web scanning tool to hunt for vulnerabilities on a website: scanning tools can identify potential security risks such as SQL injection, cross-site request forgery (CSRF), invalid redirects, and other vulnerabilities. Running a web scanning tool against your own site is a good idea. Having a malefactor run a scanning tool against your web site isn’t quite as good.

  • WEBATCK. Using techniques such as SQL injection, remote file inclusion, or cross-site scripting to do things like install malware or steal user data. For example, by maliciously modifying a SQL query a hacker might be able to retrieve all your user data, including passwords, credit card numbers, Social Security numbers, and any other information you might have stored in the user database.

  • WEBSCRP. Using automated tools to download a copy of a web page and then “scrape” (i.e., copy) all the content on that page. That content is then repurposed for other (sometimes illegal, oft-times unethical) uses.

How does client reputation help?

One way to help prevent malicious users from logging on to a website is to implement two-factor authentication. With two-factor authentication, providing an email address and password doesn’t automatically log you on to a website; instead, you need to provide some additional information (i.e., a second authentication factor) before you can be authorized. In the case of Hosted Login, this second factor is an access code that is sent to the user via email or SMS text messaging. The user must provide this access code before they can be fully logged on:

Two-factor authentication is definitely more secure than simply logging on with an email address and password. However, this tighter security comes with a tradeoff: although users want their accounts to be secure, these same users aren’t necessarily excited about two-factor authentication. The reasons for that should be obvious: not only are there extra steps involved, but – if you don’t have immediate access to your cell phone or email inbox – you might not be able to log on at all. What this means, of course, is that websites have to find a way to balance the need for security with the need to keep their user experiences as simple and as painless as possible.

This is where RBA and Client Reputation come in. Depending on how you want to look at it, two-factor authentication doesn’t care who you are: if it’s time to invoke 2FA then it’s time to invoke 2FA. By comparison, RBA gauges the risk factors involved in allowing you to log on with just an email address and password. If the risk is considered low enough, you can log on without having to go through 2FA. In fact (and in general), you’ll only be asked to go through two-factor authentication if that risk exceeds a specified threshold. With Client Reputation, users with low Client risk scores (which no doubt make up the vast majority of your users) can bypass 2FA; users with high Client risk scores can’t. 


Although we use the word “you” when we say things like “allowing you to log on with just your email address and password,” that’s not technically accurate: after all, Client Reputation doesn’t know who “you” even are. Instead, Client Reputation performs its analysis on your IP address, before you even log on. Consequently, it's more correct to say something like “allowing a user with your IP address to log on with just an email address and password.”

So how exactly does Client Reputation perform this magic. That’s something we’ll explore in more detail in the Client Reputation Workflow section of this documentation.

Client reputation and risk-based authentication

Client Reputation is included as a risk signal in the Identity Cloud's Risk-based Authentication package. Because it is part of the RBA package, that means that Client Reputation requires an additional purchase beyond Hosted Login itself. Two-factor authentication (and the ability to trust 2FA devices) is a core feature of Hosted Login v2 and, as such, is available to anyone who has Hosted Login. Client Reputation (which leverages both 2FA and the ability to trust devices) is only available as part of Risk-based Authentication.

Risk-based authentication with Client Reputation provides the following capabilities:

  • Access to the DOSATCK, SCANTL, WEBATCK, and WEBSCRP values in the CPANY_NICKNAME-Reputation HTTPS header.

  • The ability to assign threshold values to each of these header values. That means that you determine when, and if, you want to take additional actions based on a given client reputation score. Threshold values are assigned separately to each attack type using a scale of 1 to 10, with:

    • 1 indicating that all users with a Client risk score greater than or equal to 1 are considered high-risk. That will be almost all the users who visit your site.

    • 10 indicating that only users with a Client risk score greater than or equal to 10 are considered high-risk. That means that only those users with the highest-possible Client risk score will be considered high-risk

See the What Scores Should I Set for My Thresholds? section for more details.

  • The ability to take action if a client reputation score exceeds its threshold. For example, suppose you set the DOSATCK threshold to 5, and a client with a DOSATCK score of 6 attempts to log on. In a case like that, the client must complete 2FA before they can be fully logged on and before they can be issued an access token. By comparison, a client that passes all the client reputation checks will be able to log on without having to go through two-factor authentication.

The client reputation workflow

In this section, we take a closer look at how Client Reputation actually works. Even though Client Reputation leverages Hosted Login’s two-factor authentication capability, 2FA doesn’t have to be enabled in order for you to use Client Reputation. If 2FA is enabled then the following process takes place:

  1. Hosted Login checks to see if two-factor authentication is required for this login (for example, because the 2FA “grace period” has expired).

  2. If 2FA is required, then the two-factor authentication process is invoked and the client reputation process is skipped (because the user is already required to go through 2FA).

  3. If 2FA is not required for this login then the Client Reputation process is invoked. Depending on the results of the risk factor analysis, a user may (or may not) have to go through 2FA.

If 2FA isn’t enabled then all authorization requests are submitted to the Client Reputation process.

To summarize (in slightly-simplistic fashion):

  • If two-factor authentication is enabled the client must first undergo the 2FA process. If 2FA isn't required the client then goes through the Client Reputation process. Either of those processes could trigger two-factor authentication.

  • If two-factor authentication isn’t enabled then the client only undergoes the Client Reputation process.

If you’d like a little more detail about how this works, the following scenario walks you through a typical Client Reputation workflow. In this scenario we’re assuming that you’ve already configured the client reputation settings; if you haven’t, that process is described in this section of the documentation. We’re also assuming that 2FA isn’t enabled and that you aren’t logging on with a trusted device (something we’ll talk about momentarily).

Here’s a high-level overview of how the client reputation process works:

  1. A client (also known as a relying party) submits an authorization request. This request passes through the ​Akamai​ edge and, in doing so, is assigned a set of client risk scores. These scores are added to the ​Akamai​-Reputation header. As you can see, in this example the IP address was assigned a DOSATCK score of 10. That’s a high-risk score:
Akamai-Reputation: ID=;DOSATCK=10;WEBATCK=4;SCANTL=1; WEBSCRP=2
  1. The request is received by the Identity Cloud and the user logs on to Hosted Login using an email address and password or a social login provider (single factor authentication).

  2. If login succeeds, the Identity Cloud retrieves the Client Reputation scores from the header and compares them to the threshold values that you’ve configured. As long as these reputation scores don't equal or exceed the threshold value (for example, you’ve set the DOSATCK threshold to 8, but the corresponding client reputation score is a 2), skip to step 5.

  3. If any of the client reputation scores exceed their specified threshold then two-factor authentication is triggered. In our example header, we had a DOSATCK score of 10. That equals or exceeds the threshold, meaning that 2FA is required. The user must complete 2FA before they can proceed to step 5.

  4. The authentication process continues (for example, Hosted Login begins processing the authorization rules).

The preceding workflow makes the process sound pretty simple and pretty straightforward. And there's a good reason for that: it is. However, there are times when additional actions aren't triggered even though the Client Reputation scores might exceed the specified threshold:

  • The user has marked their device as a trusted device. When a user goes through two-factor authentication, they have the option of marking their device (a specific web browser on a specific computer or cell phone) as being a trusted devices. By default, that means the user can log on for the next 30 days without having to go through 2FA. Client Reputation respects the trusted device setting and won’t require a user to go through 2FA.

  • The user has already completed two-factor authentication. Users will only need to complete 2FA once per login transaction: even if a Client Reputation threshold is exceeded, the user will not be presented with 2FA a second time.


We should note that Client Reputation usually respects the trusted device setting. There is an exception, however. When Client Reputation is enabled and when you trust a device, your IP address and Client Reputation scores are recorded. As long as those values remain the same Client Reputation will trust your device. However, suppose your DOSATCK score has gone up since your device was trusted. In that case, you might be required to go through 2FA even though the device is trusted and even though your trusted device grace period hasn’t expired. The trust between a device and Client Reputation can change if your Client Reputation scores change.

Here's a more visual look at the workflow:

To summarize:

  • If you don't have 2FA enabled, each time you log on your Client Reputation scores are checked. If one or more of those scores exceed their specified threshold then you'll need to go through two-factor authentication. If you don't have any scores that exceed exceed their thresholds then you can log on without going through 2FA.

  • If you have 2FA enabled, Hosted Login checks to see if you're logging on with a trusted device. If you are, and your Client Reputation scores are unchanged (and if your network is unchanged) then you can skip two-factor authentication, If your scores have changed (or if you're on a new network), then you'll need to go through 2FA.

  • If 2FA is enabled but you're not using a trusted device, Client Reputation scores are checked. If one or more of those scores exceed their specified threshold then you'll need to go through two-factor authentication. If you don't have any scores that exceed their thresholds then you can log on without going through 2FA.

Configure client reputation in Hosted Login

If you’re using Risk-based Authentication, Client Reputation signals are always monitored. That means you don’t have to worry about enabling or disabling Client Reputation: Client Reputation is always on and always working (that is, it's always calculating risk scores and adding those scores to the ​Akamai​-Reputation header). Instead, the decisions you have to make are:

  • Do you even want to use the Client Reputation signal? Like we said, the Client Reputation signal is always available. However, it's up to you to decide whether you want Hosted Login to extract that signal and then use those values to require high-risk users to go through two-factor authentication.

  • If you do want to use Client Reputation, which attack types do you want to include in your risk analyses? And at what point (i.e., at what Client risk score) do you want to require users to undergo 2FA?

If you decide to employ Client Reputation, you can configure and manage the technology by adding/modifying/deleting client settings in your application client. Those settings include the following:

  • authentication.risk.client_reputation_threshold.DOSATCK. Makes client reputation decisions based on the DOSATCK value.

  • authentication.risk.client_reputation_threshold.SCANTL. Makes client reputation decisions based on the SCANTL value.

  • authentication.risk.client_reputation_threshold.WEBATCK. Makes client reputation decisions based on the WEBATCK value.

  • authentication.risk.client_reputation_threshold.WEBSCRP. Makes client reputation decisions based on the value WEBSCRP value.

By default, none of these settings appear in your application client; to use one of them, you’ll need to add that setting to the application client. For example, if you want to make client reputation decisions based in part on the DOSATCK value then you’ll need to add the authentication.risk.client_reputation_threshold.DOSATCK setting to the client and configure the value of that setting. (More on that in a moment.) If you want to use the SCANTL value to make client reputation decisions then you’ll need to add and configure  authentication.risk.client_reputation_threshold.SCANTL.


So what does it mean to “configure” a client reputation setting? Each setting accepts a value between 1 and 10, inclusive. These settings, which act as triggers for further action, are directly aligned with the COPANY_NICKNAME-Reputation header values. For example, a DOSATCK value of 1 means that this client has a very low likelihood of engaging in a denial-of-service attack. Now, suppose you set authentication.risk.client_reputation_threshold.DOSATCK to 1. That means that any client with DOSATCK score greater than or equal to 1 will trigger further action. In other words, almost any client will trigger this action.


As we noted, the Client Reputation settings are “directly aligned with the ​Akamai​-Reputation header values.” But what if some of these values – say, DOSATCK – don’t appear in the header? That’s fine: in that case the value is automatically set to 0 and, in this example, no client reputation score is calculated for DOSATCK. And if the header itself is missing? Then no client reputation scores are calculated for this client and this authentication session.

Suppose you set authentication.risk.client_reputation_threshold.DOSATCK to 5. In that case, only clients with a DOSATCK score greater than or equal to 5 are flagged for further action: a client with a DOSATCK score less than 5 will be allowed access without having to jump through any additional hoops. Any client with a score less than the threshold value passes the Client Reputation test. (At least for that particular attack type.) 

Two quick notes about configuring client reputation scores. First, if you don’t want to use a setting anymore simply remove the setting from the application client. Remember, you don’t have to use all four settings: if your only concern is with Denial of Service attacks then you can calculate and check only the DOSATCK score.

Second, your settings don’t have to have the same values. For example, suppose you aren’t overly concerned about web scraping but are very concerned about denial-of-service attack. In that case, you might set authentication.risk.client_reputation_threshold.WEBSCRP to 10, meaning that a very high score is needed before further action is taken. In turn, you might set authentication.risk.client_reputation_threshold.DOSATCK to 6, which means a much lower DOSATCK score will trigger additional action.

What score should I use for my thresholds?

Client Reputation settings can be configured with any integer value from 1 to 10, with 1 meaning that almost everybody will need to go through 2FA and 10 meaning that hardly anybody will ever need to go through 2FA.


At first glance that might not make sense: doesn’t a score of 1 mean that the users are low-risk users? Yes, it does. However, when you set a threshold  to 1 that means that all users who have a Client Reputation score equal to or greater than 1 (in other words, pretty much everyone) triggers 2FA. The lower the threshold score the more users you'll have that will equal or exceed that score. The higher the threshold score the fewer users you'll have that will equal or exceed that value.

It’s nice that organizations can configure threshold scores ranging from 1 to 10, but you probably don’t care about that. Instead, what you want to know is this: what scores should you use for your Client Reputation thresholds? Admittedly, there are lots of “well, it depends” factors to consider here. However, as a general rule, ​Akamai​ recommends setting threshold scores to 8 or greater. 

Why? Well, a threshold of less than 8 might be too sensitive, which runs the risk of triggering too many false positives (that is, users who are marked as being high-risk even though they really aren’t). Using a higher score, such as 8, increases your confidence that any user tagged as high-risk is just that: high-risk. If that doesn’t sound right to you, your Identity Cloud representative can help you decide how high (or low) you might want to set your thresholds.

Here's another way to look at threshold settings. Suppose you set your Client Reputation threshold to 4. That means that any user with a score of 4 or higher will be tagged as high-risk and will have to go through two-factor authentication. That's going to be a lot of users; in fact, only users with scores of 1, 2, or 3 will be allowed to skip 2FA:

A low threshold score (like a 4) means a large number of users have to go through 2FA. 

By comparison, suppose we set the threshold score to 8 (the recommended value). In that case, only users with a Client Reputation score of 8, 9, or 10 need to go through 2FA; the rest of the users (most likely the majority of the users) will be able to bypass two-factor authentication:

A higher threshold score allows more users to bypass 2FA.

Add a client setting to an application client

The easiest way to add a Client Reputation setting to an application client is to use Console. (These settings can also be managed by using the Identity Cloud Configuration API.) To add a Client Reputation setting by using Console, complete the following procedure:

  1. In Console, click Manage Properties in the navigation pane, click the Action icon located next to your application client name, and then click Edit:

  2. On the Edit page, scroll to the bottom and then click Edit Settings:

  3. On the Edit Settings page, click the Add Settings icon:

  4. In the Select Setting Key field, type the name of the client reputation setting (for example, authentication.risk.client_reputation_threshold.DOSATCK) and then click the Create link:

  5. In the Value field, set the desired client reputation threshold:

  6. Click the Save Changes icon:

To delete a setting, return to the Edit Settings page and then click the trashcan icon located next to the setting to be removed:

After clicking the trashcan icon, click Save Settings to remove the setting and its value.