Managing Properties

Properties (also known as “API clients”) are used to make authenticated requests against the Janrain REST APIs. Typically, these calls are used for login and registration: when a user logs on to or registers with a website, that logon or registration is managed by a property. Properties are also involved when administering a website: access to site resources (such as user profiles) is dictated, in part, by the property used to make a management request.


Note. Why the name “property?” That’s because the term is often used to describe a specific website or web application. API clients (i.e., properties) are often-times associated with a specific website or web application as well, so it makes sense to refer to API clients as properties.

The Managing Properties section of the documentation includes the following topics:

Searching For and Filtering Properties

When you access the Manage Properties page, your properties are displayed in the Search Properties pane:

The Manage Properties Page

By default, the Console displays 5 properties at a time; to view the next (or the previous) set of 5 properties use the navigation controls at the bottom right of the pane:

Navigation Controls

If viewing 5 properties at a time isn’t sufficient, that can be changed by clicking the Rows per page arrow and then selecting either 10 or 50 from the dropdown list:

Changing the Number of Rows Per Page

For example, here’s the same Manage Properties page, this time with Rows per page set to 50:

Displaying 50 Rows Per Page

To see all the displayed properties simply scroll down the page.

Before you ask, yes, the Rows per page setting is “sticky:” the value you set remains when you leave the Manage Properties page. In fact, the value remains even after you log off: the next time you log back on, the Console “remembers” your previously-configured rows per page.

By default, properties are sorted by their Id, a unique value (e.g., rb8s6tpsu2uy2f6bs5m5vu5yc3dadhvv) assigned at the time the property is created. As a result, your list of properties will typically look something like this:

Properties Sorted by ID

If you prefer, however, you can sort properties by Name instead of ID. To do that, click the Name label to sort properties by name, and in ascending (A to Z) order:

Properties Sorted by Name

Click the Name label a second time to sort in descending (Z to A) order. Note that Id and Name are the only two columns you can sort by; you cannot sort by either Actions or Features.

You can also use the Search properties feature to search for properties by name or by Id. To search for a property, start by typing a letter (e.g., the letter p) in the Search properties field. The Console responds by showing you search results similar to these:

Searching for Properties
Those search results might have surprised you: there’s a good chance you were expecting to see all the properties whose Name starts with the letter p. But that’s not how Search properties works. Instead, it looks for the search term (p) anywhere in either the Name or the Id of the property. In the preceding example, all the returned properties have a p somewhere in their Name or Id:

Searching on the Letter P

Type an additional letter (e.g., o) and the results will be filtered to show properties that have the string value po somewhere in their Name or Id:

Searching for the String PO

Just remember that the search string can appear anywhere in the Name or Id; it’s not limited to appearing only at the start of the property name or Id. For example, the search string po also returns this property:

The Search String in the Middle of the Name

To view the entire list of properties again, select and delete any text in the Search properties field.

If you want to target a specific type of property (e.g., all the properties that have the direct_access feature), you can do so by clicking Filter by feature.

Filtering by Feature

For example, if you select direct_access the Console will only display the properties that have the direct_access feature:

Properties with the direct_access Feature

To display all the properties, click Filter by Feature and clear all the checkboxes.

Copying a Property

To make an exact copy of a property (that is, a property that has the same features, IP whitelist, and settings, albeit with a different client ID and client secret), complete the following procedure:

  1. From the Manage Properties page, click Actions next to the property you want to copy and then click Copy:

    Copying a Property

  2. In the Copy this property dialog box, enter a name for the new property (or accept the default name) and then click Copy:

    The Copy This Property Dialog Box

The default name chosen by the Console is created by appending copy to the end of the name. Thus, United States becomes United States copy. If you make a copy of United States copy, the proposed name will be United States copy copy.

You can also copy a property by opening the property in Edit mode and then clicking the Copy property icon:

The Copy Property Icon

After clicking Copy property, the Copy this property dialog box is displayed. Note that, regardless of the method you use to copy a property, the new property will inherit the original property’s features, IP whitelists, and settings.

Creating a Property

To create a new property, complete the following procedure:

  1. From the Manage Properties page, click Create Property:
    The Create Property Button
  2. In the Name field, enter a name for the new property. Note that property names must be unique; for example, you cannot create a property named North America if a property by that name already exists. The Console will not overwrite an existing property.
  3. In the Permissions pane, select the features for the property (features are used to manage access to user profiles and application management capabilities):
    Choosing Property Features
    By default, the login_client feature is selected for you; this feature is used for API clients that handle user logins and registrations. To select a different feature (or set of features) clear the login_client checkbox and then choose the appropriate features:
    Choosing Property Features
    For more information, see Working with Features.
  4. If desired, click Add New IP Address and configure an IP whitelist for the client (IP whitelists specify the IP addresses of the computers allowed to make API calls using the property):
    Adding a New IP Address
    For more information, see Working with Whitelists.
  5. Click the Create Property icon to save the new property.

Two notes about creating new properties. First, beneath the Add New IP Address link you’ll see a section labeled Settings; this section shows all the client settings that have been configured at the global scope. These settings are informational-only: you cannot change setting values or add new settings from the Create Property page. If you want to configure local settings for the property you must first create and save the property, then open the property editor and change the settings.

Second, if you change your mind about creating a new property you can do one of two things: either leave the Create Property page, or click the Cancel icon:

Cancelling New Property Creation

If you click Cancel you’ll then have to click Yes in the Do you really want to cancel dialog box:

Cancelling New Property Creation

Working with Features

Features are the primary mechanism used to govern property access to user profiles and to application management services. If you intend to actually use a property then you must assign that property at least one feature.

When creating or modifying a property in the Console, you have six client features to choose from:

  • access_issuer. Has permission to issue tokens that can be used by all other property types.
  • direct_access. Has read/write access to all user profiles. You can use a direct_access property to update the user profile for any of your users.
  • direct_read_access. Has read-only access to all user profiles. You can use a direct_read_access property to return information for any of your user profiles, but you cannot use a direct_read_access property to modify a user profile.
  • login_client. Used primarily for logins and registrations, the login_client feature also allows the current user to modify his or her user profile. Client-side API calls should only be made using a login_client property.
  • metadata. When a metadata property updates an attribute value in a user profile, the attribute value will be modified but the lastUpdated attribute will remain as-is. These properties are reserved for use in Janrain data integrations, enabling those integrations to write a timestamp of the last time a profile update was synced to a third party without causing a profile update event (that is, without also updating the lastUpdated attribute).
  • owner. Has complete administrative access to an application. You have to use an owner property to do such things as create, modify, or delete other properties, or to manage your entity type schemas.

Depending on your needs, individual properties can be assigned multiple client features. However, there are some exceptions. For example, if you assign a property the login_client feature, no other features can be assigned to that property. As a result, the other features become unavailable in the Console UI:

The login_client Feature

Similarly, selecting a different client feature causes the login_client feature to become unavailable:

The direct_read_access Feature

This prevents you from creating, and then trying to save, an invalid property (e.g., one that tries to combine the direct_access and the login_client features).

And then there’s this: if you mark a property as being an owner, there’s no way to remove that feature. Instead, that feature becomes unavailable:

The owner Feature

If you need to change or delete an owner property, contact your Janrain representative.

Working with IP Whitelists

Each property has an “IP whitelist” that specifies the IP addresses of the devices allowed to make API calls using that property. By default, the IP whitelist for a property is set to 0.0.0.0/0, which means that any IP address can be used to make API calls.

If you’d prefer to restrict the IP addresses that can be used to make API calls, complete the following procedure:

  1. From the Edit page, click Add New IP Address:
    Adding a New IP Address
  2. In the Whitelist an IP network field, type a CIDR (Classless Inter-Domain Routing) address. CIDR addresses use IP address/network mask notation to specify a range of IP addresses. For example:

    Adding a New IP Address
    The preceding notation (192.168.0.0/30) refers to the IP addresses 192.168.0.0; 192.168.0.1; 192.168.0.2; and 192.168.0.3.

  3. To add additional IP addresses, click Add New IP Address again and then type in the next CIDR address:

    Adding a Second IP Address

  4. When you are finished, click the Save changes icon:

    The Save Changes Button

If you want to delete a set of IP addresses, click the trash can icon located next to the range of addresses to be deleted:

Removing an IP Address

If you delete all the ranges from your IP whitelist, then the property resumes allowing API calls from any IP address.

If you decide to use IP whitelisting, keep in mind that not all Janrain APIs are governed by the whitelist. For example, calls to the Configuration API (CAPI) can be made from any device regardless of what is (or isn’t) on the IP whitelist.

As a general rule, whitelisting is not recommended in organizations that rely on dynamic IP addressing. That’s because, by definition, dynamically-allocated IP addresses are subject to frequent change.

Working with Client IDs and Client Secrets

Each property has a client ID and a client secret; for authentication purposes, these values serve as the property’s username (ID) and password (secret):

Property Credentials

Each property also has a name. Unlike the client ID and client secret, however, the name is not used for authentication purposes; in fact, you can rename a property any time you want. As we’ll see, you can also reset a client secret any time you want.

This section of the documentation includes the following topics:

Renaming a Property

Suppose you named your new property Test, and now you’re beginning to think that maybe that wasn’t an especially good, or especially descriptive, name. That’s fine; you can rename a property at any time by completing the following procedure:

  1. From the Manage Properties page, click the property you want to rename.
  2. On the Edit page, select the existing property name and then type the name for the property:
    Changing the Property Name
  3. Click the Save Changes icon:
    The Save Changes Button

The property will be renamed. Note, however, that only the name changes: the client ID remains as-is.

Resetting Client Secrets

As mentioned a moment ago, the client secret functions as the property password when making API calls. Because of that, it’s important to keep your client secrets secret: secrets should never be shared with anyone, including Janrain. If you are experiencing problems with a property, the support ticket you file should include the client ID. But that’s all the information Janrain needs. Your support tickets should not include the client secret.

But what happens if a client secret does leak out, or what happens if someone who had access to the secret leaves your company? In that case, Application Admins and Application Configuration Admins can use the Console to reset the client secret (i.e., generate a new password). To reset a client secret, complete the following procedure:

  1. From the Manage Properties page, click the property whose client secret needs to be reset.
  2. On the Edit page, click Reset Secret:
    The Reset Secret Button
  3. In the How long would you like the current secret to remain active? dialog box, in the Hours to Expire field, enter an integer value between 0 and 168, inclusive:
    Setting the Time-to-Live Value
    The value entered here specifies how long you want the current client secret to remain usable. During the designated time period (e.g., 8 hours), your property will have two valid secrets: the old client secret, and the new client secret you are about to generate. That means that applications can make API calls using either the old secret or the new secret; it doesn’t matter. Keeping the old secret active for a little while is useful if you have deployed applications or utilities that use the old secret; this provides a “grace period” that gives you a chance to update those applications or utilities to the new secret. If this isn’t a concern, then set the Hours to Expire field to 0. That way, the old secret expires immediately, and only the new secret can be used to make API calls.
  4. In the Are you sure you want to reset this secret? dialog box, click Yes:
    The Reset Secret Confirmation Dialog
  5. In the Secret successfully reset dialog box, click Close:
    The New Property Secret

Viewing Client Secrets

As noted in the preceding section, client secrets are typically required when making API calls: with very rare exceptions, API endpoints won’t authenticate you unless you can supply both the client ID and the client secret. That leads to at least one problem: how do you determine the client secret for a property? After all, even in the Console UI that value seems pretty secretive:

Property Credentials

And before you try, no, selecting and copying the obfuscated password won’t work: you can select the string of dots, but you can’t copy them.

So what’s the solution here? Actually, there are two solutions. If all you want to do is copy the secret, then click the Copy secret to clipboard icon:

Copying the Property Secret

You can then paste the secret into whatever tool you’re using to make API calls.

And if you want to actually see the client secret, just click the eyeball icon:

The Show Secret Icon

That puts the client secret on full display:

The Displayed Client Secret

To hide the secret, just click the eyeball icon a second time.

Deleting a Property

To delete a property, complete the following steps:

  1. From the Manage Properties page, click the Actions icon next to the property you want to delete and then click Delete:
    Deleting a Property
  2. In the Would you like to delete this property? dialog box, click Delete:
    The Delete Property Confirmation Dialog

The property will be deleted.

Properties can also be deleted by opening the property in edit mode and then clicking the Delete property icon:

The Delete Property Icon

Note that there is no way to restore a deleted property. And, as mentioned previously, you cannot delete properties that have been assigned the owner feature.

Managing Property Settings

By default, properties inherit settings configured at the global scope; these settings specify such things as the default flow name and locale, the email address used for all transactional emails (i.e., messages sent from the Console itself, such a password reset notifications), and the URL used to verify user email addresses.

However, properties can override values configured at the global scope, and even add additional settings not configured at the global scope. This enables individual properties to be configured, and managed, in a way that best suits your organizational needs.

The Managing Property Settings section of the documentation includes the following topics:

Modifying Property Settings

To modify the configuration settings for a property, scroll to the bottom of the Edit page and then click Edit Settings:

The Edit Property Settings Button

In turn, that opens the Edit Settings page:

Editing Property Settings

As you can see, the Edit Settings page for properties looks a little different than the Edit Settings page for applications. For example, on the properties page, you might have noticed the icon of a globe with a padlock superimposed on it:

The Global Settings Icon

This icon indicates that the setting has been configured at the global scope; that also means that the setting cannot be deleted from the property settings page. (To delete a global setting, you must go to the Manage Application page). If you hover the mouse over one of these icons you’ll see a tooltip stating that you can only change the property value; you cannot delete the setting or change the global value:

The Global Settings Icon Tooltip

By comparison, a setting configured at the local scope will show the more-familiar trashcan icon:

A Local Setting

That’s because you can delete settings defined at the local scope.

Speaking of property values and global values, both of those setting types are displayed on the property Edit Settings page:

Property and Global Settings

As you might expect, the Property Value column shows the setting value as configured for this property; if this column only displays the word Value (in gray text) that means that a local value has not been configured for this property. The Global Value column shows the setting value as configured at the global (application) scope. For example, here we see that login_attempts has been set to 4 at the local scope and to 6 at the global scope:

Configuring a Setting Value

If a setting is configured both at the global scope and at the local scope, the local setting takes precedence. In this case, that means that the property in question will allow up to 6 failed login attempts, with the local property value overriding the global value.

The preceding question brings up an interesting point. As we saw a few moments ago, you cannot delete a global setting from the property settings page. That makes sense. But now that we’ve configured login_attempts locally, what happens if we change our mind? What are we supposed to do if we no longer want to define login_attempts at the property scope?

Fortunately, it’s very easy to remove a local setting that has also been defined at the global scope. In fact, all you have to do is select the local value and delete it (e.g., select 6 and then press Delete on the keyboard). Do that, and the Property Value column will display the gray Value text once again:

Resetting a Setting

Case closed!

Adding a New Property Setting

To add a new property setting, complete the following procedure:

  1. Click the Add Setting icon:
    Adding a New Property Setting
  2. To add a standard Janrain setting, in the Edit Settings pane, click Select setting key and then click the setting you want to add:
    Selecting a Standard Setting
    Depending on the sitution, some of the setting names in the dropdown list might be grayed-out. That means that those settings are already in your list of settings, having been previously-configured at either the global or the property scope.
  3. In the Value field, enter the value for the new setting:
    Configuring the Setting Value
  4. To add a custom setting, type the setting name in the Select setting key field. Note that setting names cannot contain blank spaces; individual words in a name are typically separated by using underscores (my_setting_name):
    Adding a Custom Setting
  5. As you type, the setting name appears in the Create setting button located just above the new setting. Click (in this example) Create site_locale. If you click anywhere other than Create site_locale, you’ll see an error message similar to this:
    An Incorrectly-Added Custom Setting
    To resolve this error, click the setting name (site_locale) and then click Create site_locale. You will not be able to save your changes until this error has been resolved.
  6. Type the value for the custom setting in the Value field:
    Configuring a Custom Property Setting
  7. When you are finished adding new settings, click the Save Changes icon:
    The Save Changes Button

Removing a Property Setting

To remove a property setting, click the trash can icon located to the left of the setting you want to delete:

Removing a Property Setting

When you click the trash can icon, the setting disappears from the screen; you won’t be presented with any sort of confirmation dialog box. However, to actually delete the setting from the application you must then click Save Changes:

The Save Changes Button

If you leave the Edit Settings page without saving your changes, the setting will not be deleted.

Scroll ↓