Configuring Secured Variables

Overview #

Secured Variables resolve to values based on the User that is logged into the system. They are derived from an individual User or a User’s Domain. They are applied to queries in the pipeline like Node Variables, but their values are based on a User’s identity rather than a record in the underlying dataset.

Default Secured Variables #

Default Secured Variables can be treated two different ways within the system:

  1. They can be used to simply validate sources, which requires an admin to set up different Secured Variables for Domains or Users.
  2. They can be applied as defaults for all Users, which makes setting Secured Variables for Domains and Users optional.

Creating a Default Secured Variable #

A default Secured Variable has to be created before the Secured Variable options show up for Domains and Users.

To create a default Secured Variable, select “Manage By: Defaults”, and then click on the “Secured Variables” tab.

The following actions are available via footer controls:

Action
Description

Add a new Secured Variable. Adding a new default secured variable will cause it to show up as an option for all Domains and Users.

Edit an existing Secured Variable. This action requires first selecting a Secured Variable.

Delete a Secured Variable from the system. Deleting a default secured variable is a global action which affects Domains and Users. This action requires first selecting a Secured Variable.

Deleting a default Secured Variable will also remove that variable from all Domains and Users.
A Secured Variable can only be deleted once all references to it have been removed from dependent configuration. Attempting to delete a Secured Variable which is still referenced will be blocked, and any remaining references will be listed.

Adding a “Default” Secured Variable #

Adding a global Secured Variable will cause new Secured Variables to show up on the User and Domain Provisioning views.

Property
Description
Name Symbolic name to use for this Variable. This label will be displayed on the User and Domain Provisioning views.
Validation Value
  1. Static: This option takes a STRING value. This STRING will always be used as the default value, regardless of who is logged in.
  2. Expression: This option binds the default value to session information. The resulting value will vary based on who is logged in.
Value Usage This setting determines how the Secured Variable will be used.

  1. Use for validation only: This value will only be used to validate endpoints. It will not be inherited as a default for Domains or Users. With this option selected, a separate value must be set for a User, or a User’s Domain.
  2. Use as a default value: This value will be used to validate endpoints, as well as a default value for all Users. This “default” value can be overwritten at the User or Domain level. However, if nothing is explicitly set for the User, or the User’s Domain, they will inherit the value supplied here.

Adding Secured Variables for Users and Domains #

Once a default Secured Variable has been created, an administrator can set up different values to use for individual Users, or for groups of users (Domains).

  1. Select “Manage By: Domains”
  2. Click a Domain Name (left panel)
  3. Select the “Secured Variables” tab (right panel)
  4. Click on the Secured Variable to add (right panel)
  5. To set a different value, click the  icon (right panel)

Properties #

Properties
Description
Inherited? This option determines whether to inherit a global default for the selected Domain.

Yes The Default Value for this Security Variable will be inherited from the globally defined default value.

See Defaults for more information.

No This new property will be used to override the global Default Value with a unique value for this Domain. This enables a Value property.
Default Value

Shows the globally defined “Default” value for this Secured Variable. This value is in effect when “Inherited?” is set to “Yes”.

Value This Property will appear when “Inherited?” is set to “No”. The value entered for this property will override the globally defined Default Value. It can be set two different ways:

  1. Static: Manually enter a STRING value.
  2. Expression: Derive the value from a common object in the system, such as the login name for a user.

Inheriting Default Values #

When inheriting values for Secured Variables, the “Default Value” will be displayed as a reference.

When trying to inherit a Secured Variable that has no default value set, a warning message will appear in place of the “Default Value”.

If the default Secured Variable is undefined, and no default value is provided for a Domain, then any underlying query using this Secured Variable will fail with an error.

Overriding Secured Variables #

Overriding Secured Variables can be done statically, with a STRING value.

A more advanced “Expression” option is also available to dynamically create values based on common objects, such as the login name for a User.

Applying Secured Variables in Queries and Scripts #

To take advantage of the Secured Variables that have been configured, they have to be introduced into queries using the Insert > Secured Variable button. This is done in the in the pipeline.

The example below assumes we have information from multiple companies, and that the administrator wants to limit those records based on the company a specific user works for. The resulting query would look something like this:

The green block used in the where clause shows a Secured Variable. The CompanyName Secured Variable will resolve to the value set up in the provisioning interface.  For example:

  • If “User1@CompanyA” logs in, they will see only events for Company A.
  • If “User1@CompanyB” logs in, they will see only events for Company B.

Because the Secured Variable is used inside of a WHERE clause, it will act as a filter. The CompanyName Secured Variable will evaluate based on the user that is logged into the system. Depending on how the provisioning has been set up, CompanyName will resolve to one of the following:

  1. Default value
  2. Domain value
  3. User value

The order is important here.  A value set at the user level with override the Domain value, and a value set at the Domain level will override the default value.