Policy Server Guides › Policy Server Configuration Guide › User Directories › Named Expressions

Named Expressions

User directories store user attributes such as organizational information, user and group attributes, and individual credentials. Some user attribute values are read directly from the user directory, while other values must be calculated each time that they are needed. These calculations are stored as expressions that can be named or unnamed.

Named expressions are policy store objects that you reference by name. You can reuse them in security policies defined in application objects. Unnamed expressions are stored in domain objects, like responses. They are rules for use in traditional security policies.

Note: Named expressions can only be used in application objects. Named expressions cannot be used in traditional security policies defined using domain objects like responses and rules.

All expressions, both named and unnamed, are used to determine the values of calculated user attributes.

To create named expressions, an administrator must have the appropriate privileges.

Note: Active expressions and named expressions are not the same. While both types of expressions are evaluated at run-time, they differ in the following ways:

• While active expressions are Boolean expressions, named expressions can return a string, number, or Boolean value.
• While active expressions are referenced as is and must be reentered each time that they are used, named expressions are referenced by name and can be referenced from anywhere and reused.

More information:

User Attribute Mapping

Benefits of Named Expressions

Named expressions provide the following benefits::

• Named expressions are stored in the policy store as objects that you can referenced by name and reuse.
• System administrators create each named expression once. Domain administrators reference the expression name, not the underlying expression, to obtain user information. Administrators do not have to reenter the entire expression each time that the user information is required.
• System administrators create and manage named expressions in one place. If an expression must be changed, the administrator only change once.
• If business logic requires a change to an expression, system administrators only change once. Domain administrators can continue to reference the expression name without regard for the underlying change.
• Only administrators who have the appropriate privileges can create named expressions. Named expressions can call privileged built-in functions and any named expression, including expresions that are marked as private. For example, a named expression can call a private expression that adds the current user to a group, while an unnamed expression cannot. This restriction prevents a domain administrator from bypassing security, such as adding the current user to an administrative group.

Define Named Expressions

Named expressions are policy store objects that can be referenced by name and reused in security policies defined in application objects.

Note: Named expressions can only be used in application objects. Named expressions cannot be used in traditional security policies defined using domain objects like responses and rules.

CA SiteMinder® evaluates named expressions to determine the values of calculated user attributes.

There are two types of named expressions:

• Virtual user attributes
• User classes

Virtual User Attributes

A virtual user attribute lets you define a re-usable expression to calculate user information. You use this type of expression when the user attribute is not uniquely referenced by the user directory. Rather, the user attribute must be calculated using attributes and other criteria that is established by business logic.

Virtual user attributes name expressions that result in values having one of the following data types:

• string
• number
• Boolean

Virtual user attributes are prefixed by the "pound" sign (#). The "pound" sign prevents name clashes with user attribute names and mappings and is a visual reminder that the user attribute value is calculated.

As an expression, a virtual user attribute can include:

• User attributes, either directory-specific or mapped
• References to other named expressions
• Built-in functions and expression syntax

Note: Named expressions can only be used in application objects. Named expressions cannot be used in traditional security policies defined using domain objects like responses and rules.

More information:

Expression Syntax Overview

Virtual User Attribute Use Case

This use case represents a basic scenario in which two LDAP user directories identify the last and first names of users with different underlying schema.

The following illustration shows how the virtual user attribute #SortName (LastName,FirstName) can be calculated for users in different user directories through user attribute mapping. User attribute mapping lets you map one common name to different user attribute names in different user directories.

1. Two user directories identify the last and first names of users differently. To create a common view of this information, you can create user attribute mappings:
   • FirstName maps to the underlying directory schema that identify the first names of users in Directory A and Directory B.
   • LastName maps to the underlying directory schema that identify the last names of users in Directory A and Directory B.
2. #SortName is a virtual user attribute that can calculate the sort name of users in both directories with the following expression:

   (LastName + "," + FirstName)
   

3. Instead of entering the expression (LastName + "," + FirstName) repeatedly, you can create a virtual user attribute named #SortName that is defined as: (FirstName + "," + LastName). Then, you can enter #SortName each time that the expression is needed.

Define a Virtual User Attribute

You define a virtual user attribute to calculate user information that is not uniquely referenced by one or more user directories.

Note: The following procedure assumes that you are creating an object. You can also copy the properties of an existing object to create an object.

Follow these steps:

1. Click Policies, Expression.
2. Click Named Expressions.
3. Click Create Named Expression.
4. Verify that the create new object option is selected and click OK.

   Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

5. Select the Virtual User Attribute option and enter a name for the expression in the General area.
6. Type the expression in the Expression field in the Add Named Expression area.
7. (Optional) Select the Disabled option in the Add Named Expression area to disable the expression. A disabled expression is not listed in the expression editor and another named or unnamed expression cannot call it.
8. (Optional) Select the Private option in the Add Named Expression area. Only other named expressions can call a private expression. An unnamed expression cannot call a private expression.
9. (Optional) Click Edit in the Add Named Expression area to open the Expression Editor.
10. Click Submit.

    The named expression is created.

User Classes

A user class lets you define a re-usable expression to calculate user information. You use this type of expression when the user attribute is not uniquely referenced by the user directory. Rather, the user attribute must be calculated using attributes and other criteria that is established by business logic.

A user class names an expression that returns a TRUE value if a user is a member of a specified class or a FALSE value if not.

User classes are prefixed by the "at" symbol (@). The "at" symbol prevents name clashes with user attribute names and mappings and is a visual reminder that the user attribute value is calculated.

As an expression, a user class can include:

• User attributes, either directory-specific or mapped
• References to other named expressions
• CA SiteMinder® built-in functions and expression syntax

Note: Named expressions can only be used in application objects. Named expressions cannot be used in traditional security policies defined using domain objects like responses and rules.

A user class is not a role. A role is a feature of Enterprise Policy Management. While roles can use user classes, they have additional information associated with them. For more information about roles, see the Enterprise Policy Management.

More information:

Expression Syntax Overview

User Class Use Case

This use case represents a basic scenario in which two LDAP user directories identify membership in the Administrator group using different underlying schema.

The following illustration details how the user class @Admin can be calculated for users in different user directories through user attribute mapping. User attribute mapping lets you map one common name to different user attribute names in different user directories.

1. Two user directories identify membership in the Administrator group differently. To create a common view of this information, you can create user attribute mappings:
   • IsAdmin maps to the underlying directory schema that identifies membership in the Administrator group in Directory A.
   • IsAdmin maps to the underlying directory schema that identifies membership in the Administrator group in Directory B.
2. @Admin is the named expression of type user class that CA SiteMinder® evaluates to determine if users in both directories are Administrators:

   (IsAdmin)
   

3. Instead of entering the expression (IsAdmin) repeatedly, you can create a user class named @Admin that is defined as: (IsAdmin). Then, you can enter @Admin each time that the expression is needed.

Define a User Class

You define a user class attribute to calculate user information that is not uniquely referenced by one or more user directories. The result of the calculation can only be TRUE or FALSE. The result either applies to the user or it does not.

Note: The following procedure assumes that you are creating an object. You can also copy the properties of an existing object to create an object.

Follow these steps:

1. Click Policies, Expression.
2. Click Named Expressions.
3. Click Create Named Expression.
4. Verify that the Create New Object option is selected and click OK.
5. Select the User Class option and enter a name for the expression in the General area.
6. Type the expression in the Expression field in the Add Named Expression area.

   Note: The expression must be a Boolean expression.

7. (Optional) Select the Disabled option in the Add Named Expression area to disable the expression. A disabled expression is not listed in the expression editor and any other named or unnamed expression cannot call it.
8. (Optional) Select the Private option in the Add Named Expression area. Only other named expressions can call a private expression. An unnamed expression cannot call a private expression.
9. (Optional) Click Edit in the Add Named Expression area to open the Expression Editor.
10. Click Submit.

    The named expression is created.

How to Use the Expression Editor

You can use the expression editor to do the following tasks::

• Look up functions and operators and user-defined named expressions
• Build a Boolean expression

Note: If you prefer to enter an expression directly, you can click Cancel and return to the Create Expression: Name pane, where you can type the expression in the Expression field on the Add Named Expression group box.

Building a Boolean expression in the expression editor is a two-part process. The parts of the process can be repeated in any order:

1. Create conditions
2. Edit the expression

In the first part of the process, you can create conditions and add them to the Infix Notation group box. A condition is a simple Boolean expression that consists of a single function or operation. In the editor, a function can have up to three parameters and has the following format:

FUNCTION_NAME(parameter_1[, parameter_2][, parameter_3])

An operation requires two operands and has the following format:

left_operand operator right_operand

Since conditions are Boolean expressions, they result in a Boolean value. If a condition contains a function or operation that results in a string, it will be converted to a Boolean value. Specifically, the following string values are converted to TRUE: "TRUE", "true", "YES", and "yes". All other string values are converted to FALSE.

Likewise, if a condition contains a function or operation that results in a number, it will be converted to a Boolean value. All non-zero numbers are converted to TRUE, while zero is converted to FALSE.

Each condition is displayed on a separate line in the field on the Infix Notation group box and is connected to the condition in the line above by one or two Boolean operators, as follows:

condition_1
AND | OR | XOR [NOT] condition_2

In the second part of the process, you can edit the expression by modifying and deleting the conditions, changing the parentheses that group the conditions, and by changing the Boolean operators that connect the conditions in the field on the Infix Notation group box. For example, you can change how the conditions are grouped:

(condition_1
AND condition_2)
OR NOT condition_3

can become

condition_1
AND (condition_2
OR NOT condition_3)

Create a Condition Containing a Function

You can create a condition containing a built-in CA SiteMinder® function and add the condition to an expression in the expression editor.

To create a condition containing a built-in CA SiteMinder® function

1. Select a name from the drop-down list of functions or type a name in the Function field on the Condition group box on the Expression Editor pane.
2. Specify the first parameter by clicking Named Expression or by typing it in the First Parameter field on the Condition group box.

   Note: Clicking Named Expression opens the Variable Lookup group box.

3. (Optional) Specify the second parameter by clicking Named Expression or by typing it in the Second Parameter field on the Condition group box.

   Note: Clicking Named Expression opens the Variable Lookup group box.

4. (Optional) Specify the last parameter by selecting TRUE or FALSE from the drop-down list or by typing it in the Last Parameter field on the Condition group box.
5. Click Add.

   The specified function is added to the Infix Notation and Resulting Notation group boxes.

Create a Condition Containing an Operation

You can create a condition containing a built-in CA SiteMinder® operation and add the condition to an expression in the expression editor.

Follow these steps:

1. Select an Operator Type and an Operator from the drop-down lists on the Condition group box on the Expression Editor pane.
2. Specify the left operand by clicking Named Expression or by typing it in the Left Operand field on the Condition group box.
3. Specify the right operand by clicking Named Expression or by typing it in the Right Operand field on the Condition group box.
4. Click Add.

   The specified operation is added to the Infix Notation and Resulting Notation group boxes.

How to Edit an Expression

Each condition that you create in the expression editor is displayed on a separate line in the field on the Infix Notation group box. As you build an expression, you can change the parentheses that group the conditions and the Boolean operators that connect the conditions by using the buttons on the Infix Notation group box.

Editing an expression is a three-step process. The first step includes four options, which can be repeated in any order:

1. Select an option:
   • Modify a Condition in an Expression
   • Delete a Condition from an Expression
   • Group the Conditions in an Expression
   • Change a Boolean Operator in an Expression
2. (Optional) Repeat step 1.
3. Close the expression editor by clicking OK.

Modify a Condition in an Expression

You can modify a condition in an expression by clicking the Modify button on the Infix Notation group box in the expression editor.

To modify a condition in an expression

1. Select a condition by clicking it.
2. Click Modify.

   The Edit group box opens, and the condition is displayed in the group box.

Delete a Condition from an Expression

You can delete one or more conditions from an expression by clicking the Remove button on the Infix Notation group box in the expression editor.

To delete a condition from an expression

1. Select a condition by clicking it.

   Note: To select multiple adjacent conditions, hold down the Shift key while clicking.

2. Click Remove.

   The selected condition is removed from the expression.

   Note: If multiple conditions are selected, clicking Remove deletes them one at a time.

Group the Conditions in an Expression

You can change the grouping of conditions in an expression by clicking the buttons that add and remove parentheses on the Infix Notation group box in the expression editor.

To change the grouping of conditions in an expression

1. Select two or more adjacent conditions by clicking them.

   Note: To select multiple adjacent conditions, hold down the Shift key while clicking.

2. Click one of the two following buttons:

   ( )

   Adds parentheses to the outside of the selected conditions.

   Example:

   condition_1

   AND condition_2

   becomes

   (condition_1

   AND condition_2)

   Remove( )

   Deletes parentheses from the outside of the selected conditions.

   Example:

   (condition_1

   OR condition_2

   OR condition_3)

   becomes

   condition_1

   OR condition_2

   OR condition_3

   The edited expression is displayed in the fields on the Resulting Notation and Infix Notation group boxes in the expression editor.

Change a Boolean Operator in an Expression

You can change a Boolean operator in an expression by clicking one of the following buttons on the Infix Notation group box in the expression editor:

• And/Or
• Not
• XOR
• Conditional?YES:NO

Follow these steps:

1. Select one condition or group of conditions by clicking it.

   Note: To select multiple adjacent conditions, hold down the Shift key while clicking.

2. Click one of the following buttons:

   And/Or

   Switches between the Boolean operators AND and OR.

   Example:

   AND condition_1

   becomes

   OR condition_1

   Note: The AND/OR button switches XOR to AND.

   Not

   Switches between adding and removing the Boolean operator NOT.

   Example:

   AND condition_1

   becomes

   AND NOT condition_1

   XOR

   Switches the Boolean operators AND and OR to XOR.

   Example:

   AND condition_1

   becomes

   XOR condition_1

   Note: The exclusive OR (XOR) operator takes two Boolean operands and returns TRUE if either operand is TRUE, but not both.

   Conditional?YES:NO

   Adds the conditional decision operator.

   Example:

   condition_1

   becomes

   condition_1 ? "YES" : "NO"

   The edited expression is displayed in the fields on the Resulting Notation and Infix Notation group boxes in the expression editor.

Apply Named Expressions

This use case represents a scenario in which a retail clothing company wants to define a role that prevents customers from making Web-based credit purchases if they have met or exceeded their credit limit. The company policy dictates that customers have a $1,000 credit limit, while company employees have a $2,000 credit limit.

In this use case, the environment contains two user directories:

• Directory A stores employees. Employees can also be customers. Therefore, Directory A identifies customers as those employees who are members of the group: cn=Customers,ou=Groups,o=acme.com.
• Directory B only stores customers. Because every user is a customer, Directory B does not have a user attribute that identifies customers.

The following details how you can use attribute mapping, virtual user attributes, and user classes to satisfy the company's credit policy.

1. Create user attribute mappings and a universal schema or common name that identifies customers for each user directory:
   1. Create a group name attribute mapping for Directory A (employees):
      • Name the mapping IsCustomer.
      • Define IsCustomer as cn=Customers,ou=Groups,o=acme.com.
   2. Create a constant attribute mapping for Directory B (customers):
      • Name the mapping IsCustomer.
      • Define IsCustomer as TRUE.

      Note: IsCustomer is a common name that maps to the same user information in Directories A and B. To access this information, you can use IsCustomer in an expression.

2. Create constant attribute mappings and a universal schema or common name that identifies the company's credit limit for each user directory:
   1. Create a constant attribute mapping for Directory A (employees):
      • Name the mapping CreditLimit.
      • Define CreditLimit as 2000.
   2. Create a constant attribute mapping for Directory B (customers):
      • Name the mapping CreditLimit.
      • Define CreditLimit as 1000.

      Note: CreditLimit is a common name that maps to the same user information in Directories A and B. To access this information, you can use CreditLimit in an expression.

3. Assume that #CreditBalance is a virtual user attribute that retrieves the user's credit balance from the accounting database.
4. Create a user class that returns a TRUE value if a customer's credit balance is under the credit limit:
   • Name the user class @IsUnderCreditLimit.
   • Define @IsUnderCreditLimit as:

     (IsCustomer AND (#CreditBalance < CreditLimit))
     

     Note: This expression conforms to the syntax rules of a CA SiteMinder® expression.

5. Create an EPM Role that lets customers make Web-based purchases if their credit balance is less than their credit limit:
   • Name the Role PurchaseWithCredit
   • Define the Role as @IsUnderCreditLimit

More information:

Attributes and Expressions Reference