Authorization Rules

Authorization rules are a special type of API 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.

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.

Setting

Can Inherit

Required

authorization.rules.auth_ttl

Amount of time, in seconds, that a session can last before a user must re-authenticate; the default value is 86400 (24 hours). This is a per-device setting, and is enforced regardless of whether or not the user still has a valid access or refresh token: when the time limit is reached, the user must re-authenticate.

For example:

"authorization.rules.auth_ttl": "172800"

Although not required, this authorization rule is recommended.

Yes

No (but recommended)

authorization.rules.required_attributes

List of profile attributes that must contain be completed (i.e., that must contain a non-null value) before a user will be allowed to log on. For example:

"authorization.rules.required_attributes": ["displayName", "primaryAddress.country"]

In the preceding example, the user must have a valid display name  and a valid country of residence in order to logon. If either of these values are missing, the user will be asked to provide a display name/country name before they can log on.

Yes

No

authorization.rules.min_age

Specific the minimum age (in years) that the user must be before he or she can log on. Note that the user age is based on the birthday attribute, and is calculated by determining the user’s age as of 00:00 UTC time on the specified day. For example, suppose a user lives in Portland, OR, and turns 18 on 7/12/2019. At 00:00 UTC time on July 12th, the user will “officially” become 18 years old. Because Portland time is 8 hours offset from UTC time, that means the user doesn’t become 18 (for Hosted Login purposes) until 4:00 PM on July 12th.

If you implement this rule, the birthday attribute should be collected at registration time and should be set as a required field. 

For example:

"authorization_rules.min_age": "18"

Yes

No

authorization.rules.legal_accepted

Indicates that the user has agreed to the required legal acceptances; these acceptances are based on the legalAcceptanceId values in the legalAcceptances plural. The values in this list must match the legal_acceptance_id_1 and legal_acceptance_id_settings (which correspond to your organization’s privacy policy and terms of service). For example:

"authorization.rules.legal_accepted": ["privacyPolicy-v1", "termsOfService-v1"]

Yes

No

legal_acceptance_id_1

Setting used by the flow to add new legal acceptances to the user's profile at registration time. The value used here must match the value in the first legal_accepted authorization rule list. For example:

"legal_acceptance_id_1": "privacyPolicy-v1"

Yes

No

legal_acceptance_id_2

Setting used by the flow to add new legal acceptances to the user's profile at registration time. The value used here must match the value in the second legal_accepted authorization rule list. For example:

"legal_acceptance_id_2": " termsOfService-v1"

Yes

No

authorization.rules.consents

Consent that the user must agree to in order to log on. “Agreeing to a consent” means that the granted property for the consent must be set to true. For example:

"consents.marketing.grant = true"

When specifying the list of consents, you only need to include the consent name (highlighted in red above). For example:

"authorization.rules.consents": ["marketing"]

Important. At this point in time, the marketing consent (shown in the preceding example) is the only consent supported by Hosted Login.

Keep in mind that these are consents that all users must agree to before they will be able to log on. That means that consents need to be used judiciously. For example, suppose you are running a contest that users can enter if they want to, and suppose that contest is recorded in your consents attribute. In that case, you might not want to include the contest consent in your authorization rule. If you do, then users will not be able to log on unless they have agreed to enter the contest.

Yes

No

authorization.rules.email_is_verified

Indicates whether the user’s email address has been verified; this will be true only if:

  • The email attribute has a value
  • The emailVerified attribute has a value

 For example:

"authorization.rules.email_is_verified": "true"

Yes

No


Configuring API Client Settings and Authorization Rules

Hosted Login provides two different ways to add API client settings and authorization rules to your Hosted Login API clients: you can use the Configuration APIs or you can use the Console. To use the Configuration APIs, call the /config/{app_id}/clients/{client_id}/settings endpoint 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 API settings to an API 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 API 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/{app_id}/settings endpoint.

There’s also a bit of a “trick” involved in using Console to add API client settings and authorization rules to an API 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 API 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.