Version: 8.1

Security Level Rules

When a user accesses a project, they can fall into one or more of many Security Levels that you can set up. The Security Level Rules determine if the user has that Security Level or not. The rules come in the form of expressions that can access any of the Expression Language's functions, Tag values, Security Zone information, or Identity Provider attributes. Security Level Rules are accessible from the Gateway Webpage Config tab in Security > Identity Providers.

Predefined Rulesets

One thing you may notice right away is that on the Security Level Rules page, many of the built in Security Levels are missing. Some Security Levels don't allow you to create an expression that defines their rules. These particular Security Levels already have a set of rules that govern how a user gets them. The Security Levels corresponding to the different Security Zones are automatically given to users depending on which zones they fall into. Similarly, the Security Levels that correspond to the Roles a user gets while authenticated are automatically given to users depending on what roles we receive from the Identity Provider. These Security Levels are removed from the tree here because rules can't be defined on them. The "Public" and "Authenticated" Security Levels also can't have Security Level Rules defined on them, but are present in the tree because they can potentially be a parent to custom nodes which can have Security Level Rules. The Public level is granted to every user when they open the project, and the Authenticated level is granted when the user authenticates against an Identity Provider, regardless of what roles they may have.

Defining Security Level Rules

For the Security Levels that can have rules defined, the rules are defined in the form of an expression which should return either True or False, the results of which determine whether a user falls into that level or not. The rules can take advantage of everything the expression language has to offer, including the built in expression functions and any Tag values. The expressions here also have the unique ability to access attributes from the Identity Providers response document for the authenticated user, as well as what Security Zone the user falls into.

Special Object Reference

These special objects can be used to reference information gathered from the IdP response document, mapped user attributes, or the Security Zone that the user falls under.

Object Type	Reference	Description
Response Attributes	Varies, see Expression Mappings for syntax info.	References Response Document Attributes directly.
User Attributes	`{user:id} {user:userName} {user:firstName} {user:lastName} {user:email} {user:roles}`	New in 8.1.5 References mapped User Attributes. Relies on mappings configured on the User Attribute Mappings page. The `roles` attribute can be handled using the containsAll or containsAny.
Security Zones	`{security-zones}`	References the collection of security zones that the user currently has. The collection can be handled using one of the unique functions: containsAll or containsAny.
Security Level Name	`{security-level-name}`	New in 8.1.5 References the name of the security level being configured. For example, if the Security Level is "Authenticated/PlantA/Administrator", then the security level name is "Administrator"
Security Level Path	`{security-level-path}`	New in 8.1.5 References the full path to the security level being configured, beginning with the first node below Public. For example, "Authenticated/PlantA/Administrator".

note

Response and User Attributes are only available to Security Levels that fall within the Authenticated Security Level. See below under Special Considerations for Rules.

Special Function Reference

When writing an expression to determine Security Level Rules, there are functions available that are not a part of the normal set available to Expression Bindings. These additional functions are:

Function Name	Description	Example
containsAll(collection, element 0, ..., element N)	Checks to see if all of the listed elements are present in the collection object. The function requires at least two arguments, a `collection` and an `element`.	`containsAll( {security-zones}, 'PlantA', 'Floor1', 'Press Room' )`
containsAny(collection, element 0, ..., element N)	Checks to see if any of the listed elements are present in the collection object. The function requires at least two arguments, a `collection` and an `element`.	`containsAny( {attribute-source:idTokenClaims:roles}, 'Manager', 'Operator' )`

Evaluating Tag Values

Tag values can be accessed in the Security Level Rules expression area by encasing the Tag Path (including the Tag Provider) in braces ( "{}" )

{[tagProvider]path/to/tag}

note

Security Levels are determined on initial login for each session, so if a Security Level is using an expression that references a Tag value, changing the value while the session is running won't change the Security Levels applied to the users already logged in.

Special Considerations for Rules

When defining rules for a Security Level, it is important to notice where in the Security Level tree you are. If you want to access information out of the Identity Provider such as the username, you will need to ensure that the Security Level is located in the Authenticated branch. User information is only captured once a user logs in, so that information will only fall under Security Levels that come from the user being Authenticated. If a Security Level lies outside of the Authenticated branch, then the level will only have access to information such as Tag values and Security Zones.

Configuring Security Level Rules

From the Gateway Webpage under the Config tab, go to Security > Identity Providers.
A list of the Identity Providers will be displayed. Click the More button for the Identity Provider you wand to edit, and select Security Level Rules.
Select the Security Level Name and, if a rule is defined, it will appear in the Rule field. If not, you can create one. We copied the expression "containsAny ({security-zones}, 'PlantA', 'Floor1', 'Press Room')" from the example above for the following example.
After your enter your rule, click Save.