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
- Copying a Property
- Creating a Property
- Working with Features
- Working with IP Whitelists
- Working with Client IDs and Client Secrets
- Deleting a Property
- Managing Property Settings
Searching For and Filtering Properties
When you access the Manage Properties page, your properties are displayed in the Search Properties pane:
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:
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:
For example, here’s the same Manage Properties page, this time with Rows per page set to 50:
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:
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:
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: 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:
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:
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:
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.
For example, if you select direct_access the Console will only display the properties that have 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:
From the Manage Properties page, click Actions next to the property you want to copy and then click Copy:
In the Copy this property dialog box, enter a name for the new property (or accept the default name) and then click Copy:
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:
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:
- From the Manage Properties page, click Create Property:
- 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.
- In the Permissions pane, select the features for the property (features are used to manage access to user profiles and application management capabilities): 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: For more information, see Working with Features.
- 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): For more information, see Working with Whitelists.
- 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:
If you click Cancel you’ll then have to click Yes in the Do you really want to cancel dialog box:
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:
Similarly, selecting a different client feature causes the login_client feature to become unavailable:
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:
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:
- From the Edit page, click Add New IP Address:
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:
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.
To add additional IP addresses, click Add New IP Address again and then type in the next CIDR address:
When you are finished, click the Save changes icon:
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:
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):
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:
- From the Manage Properties page, click the property you want to rename.
- On the Edit page, select the existing property name and then type the name for the property:
- Click the Save Changes icon:
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:
- From the Manage Properties page, click the property whose client secret needs to be reset.
- On the Edit page, click Reset Secret:
- 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: 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.
- In the Are you sure you want to reset this secret? dialog box, click Yes:
- In the Secret successfully reset dialog box, click Close:
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:
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:
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:
That puts the client secret on full display:
To hide the secret, just click the eyeball icon a second time.
Deleting a Property
To delete a property, complete the following steps:
- From the Manage Properties page, click the Actions icon next to the property you want to delete and then click Delete:
- In the Would you like to delete this property? dialog box, click Delete:
The property will be deleted.
Properties can also be deleted by opening the property in edit mode and then clicking 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:
In turn, that opens the Edit Settings page:
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:
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:
By comparison, a setting configured at the local scope will show the more-familiar trashcan icon:
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:
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:
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:
Adding a New Property Setting
To add a new property setting, complete the following procedure:
- Click the Add Setting icon:
- To add a standard Janrain setting, in the Edit Settings pane, click Select setting key and then click the setting you want to add: 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.
- In the Value field, enter the value for the new setting:
- 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):
- 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: 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.
- Type the value for the custom setting in the Value field:
- When you are finished adding new settings, click the Save Changes icon:
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:
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:
If you leave the Edit Settings page without saving your changes, the setting will not be deleted.