You're currently browsing the Ignition 8.0 docs. Click here to view the latest docs.


When a user accesses a Perspective 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.


On this page ...

IULocgo

Security Level Rules


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 or the Security Zone that the user falls under.

Object NameDescription
{security-zones}
This object gives the collection of security zones that the user currently has. The collection can be handled using one of the unique functions: containsAll or containsAny.
{idp-attributes:X}

  This feature has been deprecated.

This object was deprecated in 8.0.16, but maintained for backwards compatibility. The {attribute-source:X:Y } object should be used instead. 

This object gives you access to specific information within the Identity Provider's response document, where "X" is the path to the attribute in the document. This path can vary depending on what IdP the user has authenticated through. Can be used in the unique functions containsAll or containsAny if the information returned is a collection object, such as a role list.

AttributePathExample
IDsub
{idp-attributes:sub}
Usernamepreferred_username
{idp-attributes:preferred_username}
First Namegiven_name
{idp-attributes:given_name}
Last Namefamily_name
{idp-attributes:family_name}
Emailemail
{idp-attributes:email}
Rolesroles
{idp-attributes:roles}
{attribute-source:X:Y }

The following feature is new in Ignition version 8.0.16
Click here to check out the other new features

As of 8.0.16, you can use this object to access values in deeper structures by using colons to delimit each object. 

Assuming the following JSON response from an identity provider:

{
    "idTokenClaims":
    {
        "foo" : "bar"
    },
    "userInfo":
    {
        "email" : "person@place.com"
    }
}

{attribute-source:userInfo:email} would retrieve the value of the user's email.

AttributePathExample
IDsub
{attribute-source:idTokenClaims:sub}
Usernamepreferred_username
{attribute-source:idTokenClaims:preferred_username}
First Namegiven_name
{attribute-source:idTokenClaims:given_name}
Last Namefamily_name
{attribute-source:idTokenClaims:family_name}
Emailemail
{attribute-source:idTokenClaims:email}
Rolesroles
{attribute-source:idTokenClaims:roles}

The {attribute-source:X:Y } object is 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 NameDescriptionExample
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 note 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

  1. From the Gateway Webpage under the Config tab, go to Security > Identity Providers.
  2. 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.



  3. 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. 



  4. After your enter your rule, click Save.



  • No labels