Authorization rules are a special type of application client setting: authorization rules are, effectively, a series of tests that a user (or, more correctly, a user account) must pass before he or she can be given an access token. For the most part, the authorization rules works like this:

1. A user logs on, either by using traditional login or by using social login.

2. After the user has been authenticated, Hosted Login checks to see if any authorization rules have been defined for the Hosted Login API client. Note that this check cannot take place until after the user has been authenticated; that’s because Hosted Login has to know who the user is in order to verify that their account meets the rule requirements.

3. If authorization rules have been defined, Hosted Login reviews the user profile to make sure that the user meets all the specified requirements. For example, suppose birthday is a required attribute (as specified by the authorization.rules.required_attributes rule). If the user did not specify their birthday, they will be required to do so before they can continue.

4. The user will be logged on only if they meet the requirements of all the authorization rules.

As noted above, the authorization rules process is all-or-nothing: you must meet the requirements of all the defined rules in order to logon or to register. For example, suppose you enable all the authorization rules, and users meets all of them except the rule requiring a verified email address. The net result? The user cannot logon until he or she verifies their email address. The fact that they meet all the other requirements is irrelevant.

That makes it critical that, before you enable an authorization rule, you’ve thought through the implications of implementing that rule. For example, suppose you configure the system so that users must agree to your marketing consent before they can log on. Needless to say, that means that users cannot log on to your site unless they agree to whatever your marketing program asks of them. In turn, that might cause you to lose a number of users and potential users; on the other hand, the registered users you do have given their consent for you to market away to your heart’s content. Whether that’s a reasonable tradeoff or not is a decision you’ll need to make yourself.

Hosted Login authorization rules

Here are the current authorization rules available for Hosted Login. All of these rules are optional: you can use any of them, you can use all of them, and you can skip authorization rules altogether.

Configure application client settings and authorization rules

Hosted Login provides two different ways to add client settings and authorization rules to your Hosted Login applications clients: you can use the Configuration APIs or you can use the Console. To use the Configuration APIs, call the /config/{appId}/clients/{client_id}/settings operation and the PUT method. For example:

curl -X PUT \
https://v1.api.us.janrain.com/config/pg65klnchge38jfhrs3c7pfww/clients/brg3q7xh8try6yy7clo09te24qaw487h5/settings \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj4oBfuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/json' \
  -d '{
   "custom": {"janrainOidcClientId": "7de8f0e4-5112-4e67-9cf7-a735050e965b",
               "theming.stylesheetURLs": "https://documentation.akamai.com/custom-styles.css",
              "theming.logoURL": "https://documentation.akamai.com/images/logo.svg",
              "theming.faviconURL": "https://documentation.akamai.com/images/favicon.svg",
"authorization.rules.consents": ["marketing"]
   },
    "user_entity_type": "user",
    "default_flow_name": "standard",
    "default_flow_version": "20190405205553900000",
    "rpx_key": "677fte5gftyoag56sd30sw2up572ec252cd3afnj",
    "rpx_realm": "documentation-login",
    "rpx_appid": "bdbppnbjfcibijknnfkk"
}   
'

Note that you can modify these settings at any time. If you do this, however, keep in mind that you must include all the desired settings in every API call you make. For example, suppose you add the preceding collection of client settings to an application client. You now decide to toss in an authorization role as well. With that in mind, you make the following API call.

curl -X PUT \ 
https://v1.api.us.janrain.com/config/pg65klnchge38jfhrs3c7pfww/clients/brg3q7xh8try6yy7clo09te24qaw487h5/settings \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj4oBfuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/json' \
  -d '{
   "custom": {"authorization.rules.consents": ["marketing"]}
}
'

This API call will work; however, it was also replace all your existing API settings with the one setting (the authorization rule) specified in your API call. Each API call must include all the settings for the API client. In other words, to add an authorization rule you need to make an API call similar to this:

{    "custom": {"janrainOidcClientId": "7de8f0e4-5112-4e67-9cf7-a735050e965b",
               "theming.stylesheetURLs": "https://documentation.akamai.com/custom-styles.css",
               "theming.logoURL": "https://documentation.akamai.com/images/logo.svg",
               "theming.faviconURL": "https://documentation.akamai.com/images/favicon.svg",
               "authorization.rules.consents": ["marketing"]
                },
     "user_entity_type": "user",
     "default_flow_name": "standard",
     "default_flow_version": "20190405205553900000",
     "rpx_key": "677fte5gftyoag56sd30sw2up572ec252cd3afnj",
     "rpx_realm": "documentation-login",
     "rpx_appid": "bdbppnbjfcibijknnfkk"
 }

Note, too that your authorization rules must be included in the custom section of the parameter value. If you don’t put the authorization rules in the custom section your API call will go through, but the rules will not be added to the application client.

And while we’re at it, remember that most of these settings can be configured at either the application scope and then be inherited by your API clients. To save settings at the application scope, use the /config/{appId}/settings operation.

There’s also a bit of a “trick” involved in using Console to add API client settings and authorization rules to an application client. For example, suppose you decide to add the authorization.rules.consents rule to a client. In Console, you do this by clicking Manage Properties, clicking the name of the application client, and then clicking Edit Settings. On the Edit Settings page, click the blue Add Setting icon:

That provides a new field for typing in the name of the setting:

Within seconds you’ll seemingly-encounter a couple of problems. To begin with, Console displays an error message telling you that you need to select an existing setting (authorization.rules.consents is not considered an existing setting). In addition to that, the Save Changes icon will be unavailable, meaning you couldn’t save this change anyway:

Like we said, all that seems to spell trouble. But don’t despair: here’s where our trick comes into play. If you click anywhere on authorization.rules.consents, a little popup labeled Create authorization.rules.consents appears:

Click the little popup, and two things happen. First, you’ll be able to add the custom setting (and its value)

Second, the Save Changes icon becomes available:

Continue adding settings (and providing values for those settings), and then click Save Changes. Just like that, your Hosted Login API client will be configured.

How authorization rules are processed

When authorization rules are in effect those rules are processed in a specific order. For example, if you’ve enabled all six authorization rules then those rules are processed like this:

1. authorization.rules.auth_ttl
2. authorization.rules.required_attributes
3. authorization.rules.min_age
4. authorization.rules.legal_accepted
5. authorization.rules.consents
6. authorization.rules.email_is_verified

In other words, even before a user has logged on, the authorization.rules.auth_ttl is triggered; this rule checks to see if there’s a valid session that can be used to authenticate the user. If there is, the user is automatically logged on. If there isn’t, the user is asked to login. Assuming authentication is successful, the other authorization rules are then processed in the order shown above; for example, immediately after a successful authentication Hosted Login checks to see if the user has supplied values for all the required user profile attributes. If the user passes that verification check, the system then verifies that the user meets the site’s minimum age requirements. This process continues, in the order shown, until the user has passed all the authorization rules. At that point the user is fully logged in and can be issued an access token.

Two things to note about this process. First, you don’t have to enable all the authorization rules (in fact, you don’t have to enable any of the authorization rules if you don’t want to). What happens if you only enable the authorization.rules.legal_accepted and the authorization.rules.consents rules? That’s fine: Hosted Login will skip the first three rules (authorization.rules.auth_ttl, authorization.rules.required_attributes, and authorization.rules.min_age), verify the two enabled rules, then skip the authorization.rules.email_is_verified rule. That's pretty straightforward: Hosted Login always processes authorization rules in the same order. For example, Hosted Login never checks to see if a user’s email address is verified and then verify that all the required attributes have values.

Second, if an authorization rule fails then the login process stops at that point (and, depending on the rule, does not continue). For example, suppose a user hasn’t agreed to the marketing consent and hasn’t verified his or her email address. In that case, as soon as the user fails the consents test the login process is suspended; that means that the user won’t know that they would also have failed the email verification rule. Hosted Login doesn't process all the rules and then issue a report saying, “Here are all the rules that you fail to meet.” Instead, login simply stops until, in this example, the consents rule has been met. When that rule has been satisfied the login process can resume and then the user will find out that they also need to verify their email address.

The following table lists the Hosted Login authorization rules (in the order in which they are processed), along with a brief description of the rule and what happens if that rule fails:

Order	Authorization Rule	What happens if the rule fails?
1	authorization.rules.auth_ttl Specifies the length of a Hosted Login session. If a user returns to the site before the specified time limit has expired (30 days by default), the user will automatically be logged on without having to authenticate. (In addition, the time-to-live clock will be reset.) Use this rule if you want to make that 30-day session length longer or shorter.	The sign-in screen is displayed and the user must reauthenticate.
2	authorization.rules.required_attributes Specifies the user profile attributes that must have a non-null value before the user can be logged on. This rule is often employed to by sites that require users to meet a specific age restriction: by making birthday a required attribute users must provide their date of birth before they can log in.	The authRules_reqAttrs screen is displayed. The user must supply the missing values before he or she can log on and be issued an access token.
3	authorization.rules.min_age Specifies how old the user must be (in years) in order to log on to a website. The user’s age is based on the value of the birthday attribute; if this attribute is set to a null value then the login attempt will be rejected.	The login process stops with the error Authorization rule 'authorization.rules.min_age' failed. Hosted Login does not include a screen where users can provide a missing birthday or update an incorrect birthday.
4	authorization.rules.legal_accepted Verifies whether the user has agreed to the privacy policy and the terms of service. Users must agree to both of the legal acceptances in order to log in.	The authRules_acceptLegal screen is displayed. The user must click Continue to accept the privacy policy and the terms of service before he or she can log on and be issued an access token.
5	authorization.rules.consents Verifies whether the user has agreed to the required consents (e.g., the marketing consent). Users cannot log on unless they agree to all the required consents.	The authRules_consents screen is displayed. The user must select the checkbox and agree to the missing consent before he or she can log on and be issued an access token.
6	authorization.rules.email_is_verified Specifies whether the user has an email address and whether or not that email address has been verified. Users cannot log on until their email address has been verified.	In Hosted Login v2, an Access Code Required screen is displayed and an access code is sent to the user's email address. The user enter that code and click Continue verify their email address. In Hosted Login v1, the Resend Verification Email screen displays. The user needs to click Send on that screen. In turn, an email is sent to the user; that email contains a link for verifying the user's email address. All the user has to do at that point is click the link.

The following sections walk you through each of these authorization rules, and provide more detail on what it means to meet (or not to meet) the rule requirements.

authorization.rules.auth_ttl

When a user logs on to Hosted Login, they also start a Hosted Login session. If a user leaves the site without logging out (and without closing their web browser) their Hosted Login session continues to run for 30 days. That means that, if you use the same web browser, you can return to the site anytime in the next 30 days and gain access without having to log in; instead, Hosted Login automatically reauthenticates you based on the credentials used to create the still-active session.

📘

The 30-day time-to-live value is automatically reset each time a user access the site. For example, suppose a user’s session is due to expire on July 1st. On June 30th, however, the user visits the site; that resets the 30-day clock, meaning that the session will not expire on July 1st. If a user visited a site every 29 days (i.e., right before a given session expired), that session could extend indefinitely.

For many organizations that’s fine. However, if users share computers then you might not want to have sessions run for 30 days. For example, suppose Bob logs on to a site and then, when he leaves for the day, doesn’t log out and doesn’t close his web browser. If Mary uses the computer and navigates to that same Hosted Login site, Hosted Login will note that there’s a valid session running and automatically log Mary on using Bob’s credentials. That might not be a common occurrence, but it can, and does, happen.

To help address issues like these, you can use the authorization.rules.auth_ttl authorization rule to change the maximum length of a session. For example, suppose you set authorization.rules.auth_ttl to 1 day seconds (86,400 seconds):

authorization.rules.auth_ttl = 86400

Let’s say that Bob logs in on a Friday afternoon and then leaves the site. If he returns Saturday morning he can simply resume his existing session; after all, his last authentication (Friday afternoon) falls within the 24-hour time-to-live (TTL) restriction. And what if Bob doesn't return until Sunday? In that case, he’ll need to reauthenticate, because the TTL restriction has expired. And Bob will have to reauthenticate regardless of whether or not he still has a valid access token and a valid refresh token: the TTL value takes precedence over everything else.

Note that there’s no real “penalty” involved here: Bob will simply be shown the signIn screen and be asked to login again. The only time a problem might occur is if the prompt parameter is set to none and no sessions are active. In that case, access to the site fails with the following error:

And for those of you who are wondering, yes, the authorization.rules.auth_ttl rule is the server-side equivalent of the max_age parameter that can be included in a user’s authorization request.

Akamai recommends that you enable the authorization.rules.auth_ttl authorization rule, setting the time-to-live value to the number of days that make sense for your website and for your user base.

authorization.rules.required_attributes

Hosted Login gives you the ability to mark user profile attributes as being mandatory: that means users must provide a non-null value for those attributes before they can be logged on and before they can be issued an access token. For example, when a user creates a new account by using a social login provider such as Facebook or Twitter, the socialRegistrationForm form requires users to provide a display name (the displayName attribute) and an email address (the email attribute). That’s why users are presented with the following screen and asked to provide (or confirm) the values of those two attributes:

But what if there are other attributes that you’d like to mark as required, and what if you’d like these requirements to apply to all your users, not just the ones using social login? As it turns out, by using the authorization.rules.required_attributes authorization rule you can mark pretty much any user profile attribute as being required, and being required for everyone. If it’s important for you to know a user’s age (birthday) or the country a user resides in (primaryAddress.country) you can use this authorization rule to make those attributes mandatory. For example, this setting makes three attributes – email, displayName, and birthday – required attributes:

As you can see, the required attributes are formatted as an array; that’s why the list of attributes is surrounded by a set of square brackets ([ ]). Inside those brackets, each required attribute is enclosed in double quote marks, and is separated from other attributes by using commas:

["email", "displayName", "birthday"]

If this rule is in effect then, after a user has been authenticated, Hosted Login checks the user profile to see if non-null values have been provided for each required attribute. If they have, login continues to the authorization.rules.min_age authorization rule (or whatever the next authorization rule happens to be). But if one or more of the required attributes are null, the login process is halted and the user must provide the missing values before login can continue.

That’s pretty cut-and-dried, but there is a catch here. Suppose you decide to make familyName (last name) your one required attribute:

authorization.rules.required_attributes = [“familyName”]

A user is authenticated, and Hosted Login discovers that this user hasn’t provided their last name. In turn, this screen is displayed to the user:

There’s no point in looking for the Last Name field; you won’t find it here. Why not? Well, when the authorization.rules.required_attributes rule is triggered, Hosted Login responds by showing the authRule_reqAttrs screen. And that screen (or, more accurately, the authRuleRequiredAttributesForm form included on that screen) shows the display name and email address fields by default: the screen is not dynamically re-rendered to fit the authorization rule.

And there’s a good reason for that: this enables you to trigger the rule based on a required attribute or set of required attributes and, at the same time, ask the user if they’d like to provide values for some optional attributes as well. For example, you might set mobileNumber as your only required attributes: the authorization rule is then triggered only if a user has failed to enter a value for the mobileNumber attribute. However, when the authRule_reqAttrs screen is displayed you can ask the user for additional information. The difference is that these additional attributes are optional: the user does not have to provide a value for them. Login will continue as long as the user provides their mobile number, regardless of whether they also provide, say, their birthday or the organization they work for.

Because the user can’t enter their last name on the default authRule_reqAttrs screen that means they can’t add their last name to their user profile. As a result, they get stuck in an endless loop: if they enter their display name and email address and then click Save and Continue, they’ll briefly see the Profile Updated screen, then end up right back the Almost Done screen. Why? That’s right: because they still haven’t supplied their last name. (Admittedly, through no fault of their own.)

In a case like this you need to edit the authRuleRequiredAttributesForm form and make sure that the real set of required attributes are shown. For our example here, that means displaying the last name field:

Now the user can supply their last name, click Save and Continue, and keep going,

authorization.rules.min_age

The authorization.rules.min_age authorization rule is triggered if either of the following conditions are true:

• The user has not supplied a value for their birthday attribute.

• Based on their birthday attribute, the user does not meeting the minimum age requirements for logging on to the site. For example, suppose you set the minimum age to 21 years:

  authorization.rules.min_age = 21
  

  If a user’s birthday is 9/3/2004 that user isn’t 21 years-old. As a result, their login attempt is rejected.

Should either of the preceding conditions be true the login process stops cold with the following error:

One thing we need to point out here is that Hosted Login doesn’t differentiate between users who aren’t old enough to log on to the site and users who might be old enough but who simply haven’t supplied a value for the birthday attribute. Because of that, you might want to make birthday a required attribute. Since required attributes are verified before the minimum age is verified, this allows users who haven’t reported their birthday to do so. If the supplied birthday meets the minimum age requirements then the authorization.rules.min_age authorization rule won’t be triggered and login can continue. In turn, only users who don’t meet the minimum age requirements will have their login denied.

authorization.rules.legal_accepted

Hosted Login includes a pair of legal acceptances (one for a site’s terms of service and the other for a site’s privacy policy); you can use the authorization.rules.legal_accepted authorization rule to prevent users from logging on if they haven’t agreed to these two legal acceptances. (Note that this is an all-or-nothing proposition: either you agree to both legal acceptances or you don’t agree with either of them.)

If the authorization.rules.legal_accepted authorization rule is enabled then, following a successful authentication, Hosted Login checks the user profile to see if: 1) the two legal acceptances can be found in the legalAcceptances attribute; and. 2) if both the terms of service (termsOfService-v1) and the privacy policy (privacyPolicy-v1) have been agreed to. If the acceptances can’t be found (or haven’t been agreed to), then the authRule_acceptLegal screen is displayed:

The only way that the user can log on is to click Continue and accept the terms of service. Granted, the user can click Cancel Request and discontinue the login process:

(

However, the next time the user logs on he or she will again have to deal with the authRule_acceptLegal screen.

authorization.rules.consents

Consents can also be used to dictate whether a not a user can log on to a site: if you implement the authorization.rules.consents authorization rule your users must agree to the required consents before they can log on. For example, if a user has agreed to the marketing consent (that is, if consents.marketing.grant is true) then the login process continues. If the user hasn’t agree to the consent (consents.marketing.grant is null or is set to false), then the authRules_consents screen is displayed:

For login to continue, the user must select the Marketing Consents checkbox and then click Continue:

If the user doesn’t select the checkbox but clicks Continue anyway. the authRules_consents screen will simply be displayed again. This loop will continue ad infinitum, or at least until the user either agrees to the consent or navigates somewhere else.

Incidentally, the default text for the marketing consent looks like this:

Aliquip irure Lorem sint labore commodo pariatur ullamco
deserunt duis pariatur aliquip ipsum ex. Excepteur excepteur cillum cillum laborum. Dolor ipsum sit dolor minim ullamco cupidatat et ad pariatur sit. Aliqua dolor ipsum nulla amet Lorem aute minim laboris est officia minim magna tempor. Laborum amet ad est sit Lorem.

That’s something you might want to change (and might want to change regardless of whether or not you enable the authorization.rules.consents authorization rule). See Modify screen text for more information.

authorization.rules.email_is_verified

As the name suggests, the authorization.rules.email_is_verified authorization rule checks to see if a user’s email address has been verified. If it has (that is, if there’s a timestamp on the emailVerified attribute) then the login process continue. If a Hosted Login v2 user’s email address hasn’t been verified an access code is emailed to that user and the user must type that code into the Enter access code field and then click Continue:

Assuming the user supplies the correct access code the, after clicking enter, their email address will be verified and their user profile updated with the date and time that verification took place:

If you're running Hosted Login v1, a user with an unverified user account sees a screen asking them to verify their email address. After ensuring that the correct email address is shown on the screen , the user clicks Send. In response, Hosted Login sends them an email containing an email verification link. All the user has to do is click that link to verify their email address.

The following video shows how the authorization rule works in Hosted Login v2: