Managing Global Settings

As noted previously, applications typically contain multiple properties, with each property representing a specific level of API access. Properties also have a collection of API client settings that specify such things as the default flow name and locale, the email address used for transactional emails (i.e., messages sent after registration or from the Console itself, such password reset notifications), and the URL used to verify user email addresses. These settings enable you to create properties that have the same access level (e.g., login_client) but differ in functionality.

With some exceptions, settings can be applied at either the global (application) scope or the local (individual property) scope. For example, the {entity_type}_distinguisher_field_values setting (which restricts agent access to user profiles) can only be set at the global scope. However, other settings can be configured at the local scope, meaning that different properties might have different values for the same setting.

To better explain how this works, suppose you have an application with three properties:

  • Property A
  • Property B
  • Property C

You can configure each of these properties to use a different login_attempts value: Property A could allow a maximum of 4 login attempts; Property B could allow a maximum of 5 login attempts; and Property C could allow a maximum of 9 login attempts. Different properties can have different configuration settings.

Of course, that leads to an obvious question: what happens if a setting is configured at the global scope, but that same exact setting is configured differently at the local scope? When settings conflict, who wins?

In a nutshell, here’s the answer:

  • If a setting is not configured at all (that is, at either the global scope or the local scope), then the platform default value for that setting is used by all properties. For example, if login_attempts is not configured at either the global scope or the local scope, then all properties will allow a maximum of 6 login attempts. That’s because 6 is the default value applied at the Janrain platform level.
    Note. Some settings (such as email verification or password reset URLs) don’t have a default value. If one of those settings is not configured at either the global scope or the local scope then that setting won’t have a value.
  • If a setting is configured at the global scope but is not configured at the local scope, then the global value is used. For example, suppose login_attempts is set to 5 at the global scope, but is not configured at the local scope for Property A. In that case, Property A will allow a maximum of 5 login attempts: the value configured at the global scope. By default, properties inherit the values configured at the global scope.
     
  • If a setting is configured at the local scope, then that value is used regardless of whether or not the setting is configured at the global scope. For example, suppose login_attempts is set to 5 at the global scope, but is set to 8 for Property A’s local scope. In that case, Property A will allow a maximum of 8 login attempts: values at the local scope override values configured at the global scope.

In other words:

Setting

Default Value

Global Scope

Local Scope

Effective Value

login_attempts

6

5

-

5 – The global scope value is inherited by the property.

login_attempts

6

-

8

8 – The local setting is used when there is no global setting.

login_attempts

6

5

8

8 – The local setting overrides the global setting.

login_attempts

6

-

-

6 – When a setting is not specified at the global scope or the local scope, the default value is used.