Policy Server Guides › Policy Server Configuration Guide › User Directories › User Attribute Mapping

User Attribute Mapping

When you configure a connection from the Policy Server to a user directory, you can map SiteMinder's seven built-in attributes to directory-specific user attribute names.

• Universal ID
• Disabled Flag
• Password Attribute
• Password Data
• Anonymous ID
• Email
• Challenge/Response

User attribute mapping extends this capability by allowing you to define your own common names in SiteMinder and to map each one to user attribute names in multiple user directories with different underlying schema. After the connections from the Policy Server to the user directories are configured, you can use one common name to reference the same user information in different user directories.

More information:

Named Expressions

User Attribute Mapping Overview

There are five types of user attribute mappings and two types of named expressions. The attribute mapping types are:

• alias
• group name
• mask
• constant
• expression

The named expression types are:

• virtual user attributes
• user classes

User attribute mappings are similar to named expressions, but there are important differences, as follows:

• Access
  • While some types of user attribute mappings are read only (R) and map to user attribute values that cannot be changed, other types of user attribute mappings are read/write (RW) and map to user attribute values that can be read or changed:

    Read Only (R): Designates a mapping whose target can be read, but not changed.

    Read/Write (RW): Designates a mapping whose target can be read or changed.

  • All named expressions are read only (R).
• Data Types
  • User attribute mappings map to user attributes that have specified data types.
  • Named expressions, when evaluated, result in specified data types.
• Visibility
  • User attribute mappings are not global and must be defined for each user directory to which they apply.
  • Named expressions are global and can apply to any user in any user directory.
• Prefix?
  • User attribute mappings follow the same syntax rules as user attribute names.
  • Named expressions follow the same syntax rules as user attribute names and have a prefix:
    • Virtual user attributes must begin with the "pound" sign (#).
    • User classes must begin with the "at" sign (@).

For a summary of these differences, see the following tables:

More information:

Named Expressions

How Attribute Mapping Works

User directories store user information such as organizational information, user and group attributes, and individual credentials. Multiple user directories in a SiteMinder environment often store the same user information, but use different underlying schema and user attribute names to identify them. This results in a disparate view of the same user information from a SiteMinder perspective.

The purpose of user attribute mapping is to create a common view of the same user information by defining a universal schema. SiteMinder uses this universal schema to resolve user information across multiple user directories.

You can define a user attribute mapping by mapping a common name to the underlying directory schema that identifies a user attribute. Mapping the same common name to the underlying schema of each user directory in the environment results in a universal schema for the user attribute. This creates a common view of the same user information.

Creating such a view lets SiteMinder reference user attributes without regard for the directory type, greatly reducing the number of policies or other objects that must be configured to account for multiple user directories. Each user attribute mapping is specific to the user directory in which it is defined.

The following illustrates the basic concept of user attribute mapping:

1. Two user directories identify the first name of users differently:
   • Directory A identifies the first name of users with givenname.
   • Directory B identifies the first name of users with u_givenname.

   This results in two different representations and views of the same user information.

2. FirstName is a common name that is mapped to the underlying directory schema:
   • FirstName is mapped to givenname in Directory A.
   • FirstName is mapped to u_givenname in Directory B.
3. FirstName results in a common view of the same user information. You can reference FirstName when defining policies, expressions, or other objects that require the first name of users, without concern for the directory-specific schema, because the directories are operationally identical. SiteMinder determines that FirstName is givenname in Directory A and u_givenname in Directory B.

Define an Attribute Mapping

User attribute mapping lets you map one common name to the underlying directory schema of multiple user directories. Mapping the same common name to the underlying schema of each user directory in the environment results in a universal schema for the user information. Each user attribute mapping is specific to the user directory in which it is defined.

You can use one or more of the following attribute mapping types to define mappings that identify the same user information across multiple user directories:

• Alias
• Group Name
• Mask
• Constant
• Expression

More information:

Attributes and Expressions Reference

Alias

Alias attribute mapping lets you map a common name to the name used by the underlying directory schema to identify a user attribute. Alias attribute mappings map common names to user attribute values that can be read or changed. This type of access is called read/write (RW).

Alias attribute mappings can map to user attributes that have any of the following data types:

• string
• number
• Boolean

Alias Attribute Use Case

This use case shows two LDAP user directories, which identify the last name of users, but the directories have different underlying schema.

Note: Review the advanced user attribute mapping examples, which detail how to use different attribute mapping types to identify the same user attribute across different directory types.

The following illustration details how two alias attribute mappings can create a common view of the same user information.

1. Two user directories identify the last name of users differently:
   • Directory A identifies the last name of users with sn.
   • Directory B identifies the last name of users with lastname.

   This results in two different views of the same user information.

2. LastName is the common name or alias that is mapped to the underlying directory schema:
   • LastName is mapped to sn in Directory A.
   • LastName is mapped to lastname in Directory B.

LastName results in a common view of the same user information. Use LastName when defining policies, expressions, or other objects that require the last names. The system has no concern for the directory-specific schema because the directories are operationally identical.

More information:

Named Expressions

Advanced User Attribute Mapping Examples

Create an Alias Attribute Mapping

You can map a common name or alias to the user attribute name specified by the user directory's underlying schema. The user attribute's data type can be string, number, or Boolean. You can use an alias attribute mapping to read or change a user attribute value in a user directory. User attribute mappings are directory-specific.

To create an alias attribute mapping

1. Navigate to the User Directory: Name pane.
2. Click Create on the Attribute Mapping List group box.

   The Create Attribute Mapping pane opens.

3. Verify that Create a new object is selected, and click OK.

   The Create Attribute Mapping: Name pane opens.

4. Type the common name and a description of the attribute mapping in the fields on the General group box.

   Note: Common names must conform to the same rules as user attribute names.

5. Select Alias on the Properties group box.
6. Type the definition in the Definition box on the Properties group box.

   Example:

   Name: FirstName

   Definition: givenname

   Description: The common name FirstName is mapped to the user attribute name givenname.

7. (Optional) Select Disabled to disable this attribute mapping.
8. Click OK.

   The Create Attribute Mapping task is submitted for processing, and the new attribute mapping is added to the list on the Attribute Mapping List group box.

Group Name

A group name attribute lets you map a common name to the underlying directory schema that identifies whether a user belongs to a specific group. Group name attribute mappings map common names to user attributes that can be read or changed. This type of access is called read/write (RW).

Group name attribute mappings result in a Boolean value. If the user is a member of the specified group, the mapping results in a TRUE value. Otherwise, the result is FALSE.

Group name attribute mapping and user classes, one type of named expression, are similar in the following ways:

• Both are used to determine group membership.
• Both result in a Boolean value.

Group name attribute mapping differs from user classes as follows:

• A group name attribute mapping is defined for particular user directories. User classes are global and can be applied to any user in any user directory.
• A group name attribute mapping can change a user's membership in a group in a user directory. User classes are Boolean expressions and cannot be changed.
• User classes must begin with the "at" sign (@). A group name mapping does not.

Note: For more information about user classes, see the Named Expressions.

More information:

Named Expressions

Group Name Use Case

This use case shows two LDAP user directories, which use different underlying schema to identify users that belong to an Administrator group.

Note: Review the advanced user attribute mapping examples, which detail how to use different attribute mapping types to identify the same user attribute across different directory types.

The following illustration details how two group name attribute mappings can create a common view of the same user information.

1. Two user directories identify membership to the administrator group differently:
   • Directory A identifies membership in the administrator group as cn=Administrators,ou=groups,o=acme.com.
   • Directory B identifies membership in the administrator group as cn=Admin,ou=groups,o=acme.com.

   This results in two different views of the same user information.

2. IsAdmin is the common name that is mapped to the underlying directory schema:
   • IsAdmin is mapped to cn=Administrators,ou=groups,o=acme.com in Directory A.
   • IsAdmin is mapped to cn=Admin,ou=groups,o=acme.com in Directory B.

IsAdmin results in a common view of the administrator group. You can reference IsAdmin when defining policies, expressions, or other objects that apply to the Administrator group. The system has no concern for the directory-specific schema because the directories are operationally identical.

More information:

Named Expressions

Advanced User Attribute Mapping Examples

Create a Group Name Attribute Mapping

You define a group name attribute to map a common name to the underlying directory schema that identifies whether a user belongs to a specific group. The result of a group name attribute mapping is a Boolean value. You can use a group name attribute mapping to read or change a user's group name in a user directory. User attribute mappings are directory-specific.

Note: For information about creating a global object that returns group membership, see user classes in the Named Expression chapter in this guide.

To Create a User Attribute Mapping of Type Group

1. Navigate to the User Directory: Name pane.
2. Click Create on the Attribute Mapping List group box.

   The Create Attribute Mapping pane opens.

3. Verify that Create a new object is selected, and click OK.

   The Create Attribute Mapping: Name pane opens.

4. Type the common name and a description of the attribute mapping in the fields on the General group box.

   Note: Common names must conform to the same rules as user attribute names.

5. Select Group on the Properties group box.
6. Type the definition in the Definition box on the Properties group box.

   Example:

   Name: IsAdmin

   Definition: cn=administrators,ou=groups,o=acme.com

   Description: The common name IsAdmin is mapped to the group name cn=administrators,ou=groups,o=acme.com. If the user is a member of cn=administrators,ou=groups,o=acme.com, IsAdmin is TRUE.

7. (Optional) Select Disabled to disable this attribute mapping.
8. Click OK.

   The Create Attribute Mapping task is submitted for processing, and the new attribute mapping is added to the list on the Attribute Mapping List group box.

More information:

Named Expressions

Mask

Mask attribute mapping lets you map a common name to the name used by the underlying directory schema to identify a user attribute that stores a bit pattern. Mask attribute mappings map common names to user attributes that can be read or changed. This type of access is called read/write (RW).

Mask attribute mappings result in a Boolean value. If the bit pattern in the user directory matches the specified mask, the mapping results in a TRUE value. Otherwise, the result is FALSE.

Mask Use Case

Some directory implementations use individual bits in an attribute to provide information about that attribute, such as the state of an account. You can apply a bit mask to an attribute.

This use case shows two Active Directory user stores that identify disabled user accounts. Each account has a different underlying schema.

Note: Review the advanced user attribute mapping examples, which detail how to use different attribute mapping types to identify the same user attribute across different directory types.

The following illustration details how two mask attribute mappings can create a common view of the same user information.

1. Two user directories contain a user attribute named AccountStatus. AccountStatus stores user information in a bit pattern, where each bit is a flag.
   • In Directory A, the second bit flags a disabled account. When the second bit equals 1, the account is disabled.
   • In Directory B, the third bit flags a disabled account. When the third bit equals 1, the account is disabled.

   This results in two different views of the same user information.

2. IsDisabled is the common name that is mapped to the underlying directory schema. In both directories, IsDisabled is mapped to AccountStatus.
   • In Directory A, the bit mask 2 (decimal) determines whether the second bit of AccountStatus is set and the account is disabled.
   • In Directory B, bit mask 4 (decimal) determines whether the third bit of AccountStatus is set and the account is disabled.

IsDisabled results in a common view of disabled user accounts. You can reference IsDisabled when defining policies, expressions, or other objects that require the account status of users. The system has no concern for the directory-specific schema because the directories are operationally identical.

More information:

Named Expressions

Advanced User Attribute Mapping Examples

Create a Mask Attribute Mapping

You can map a common name to a bit pattern whose user attribute name is specified by the user directory's underlying schema. The result of a mask attribute mapping is a Boolean value. You can use a mask mapping to read or change a user attribute value in a user directory. User attribute mappings are directory-specific.

To Create a User Attribute Mapping of Type Mask

1. Navigate to the User Directory: Name pane.
2. Click Create on the Attribute Mapping List group box.

   The Create Attribute Mapping pane opens.

3. Verify that Create a new object is selected, and click OK.

   The Create Attribute Mapping: Name pane opens.

4. Type the common name and a description of the attribute mapping in the fields on the General group box.

   Note: Common names must conform to the same rules as user attribute names.

5. Select Mask on the Properties group box.
6. Type the definition in the Definition box on the Properties group box.

   Example:

   Name: IsDisabled

   Definition: AccountStatus:4

   Description:

   The common name IsDisabled is mapped to the user attribute name AccountStatus. AccountStatus stores one or more states in a bit pattern. For example, AccountStatus stores the account state in the third bit. When the account is disabled, the third bit is set to 1. Conversely, when the account is enabled, the third bit is set to 0.

   SiteMinder performs a bitwise AND operation on AccountStatus and the specified state or mask, which in this example is 4, to determine whether the account is disabled. If the account is disabled, IsDisabled is TRUE.

7. (Optional) Select Disabled to disable this attribute mapping.
8. Click OK.

   The Create Attribute Mapping task is submitted for processing, and the new attribute mapping is added to the list on the Attribute Mapping List group box.

Bit Masks in Mask Attribute Mapping

A bit mask attribute mapping tests the value of one or more bits by masking the values of the other bits in a user attribute.

A mask attribute mapping is defined as follows:

user_attribute_name:bit_mask

For example, assume that the user attribute is named AccountStatus. The attribute AccountStatus stores the states of the following three flags in a bit pattern:

When a bit equals one, the flag is TRUE. The table shows the results:

Note: Equivalent decimal values are shown in parentheses.

Assume that you only want to test whether a user is a gold member. To test this bit, select the bit pattern that corresponds to a gold member as the bit mask or 100 (binary) and specify it as 4 (decimal). The resulting mask attribute mapping is defined as follows:

AccountStatus:4

A bitwise AND operation on AccountStatus is performed on the bit mask and tests whether the result is equal to the bit mask. An equal result means the value of the tested bit is one and the flag is TRUE. The following table shows the results:

Note: Equivalent decimal values are shown in parentheses.

You can also use a bit mask to test the value of a bit set or more than one bit at a time. Assume that you want to know whether the account is disabled and the password has expired. To test these bits, specify a bit mask of 011 (binary) or 3 (decimal). The resulting mask attribute mapping is defined as follows:

AccountStatus:3

A bitwise AND operation on AccountStatus is performed on the bit mask and tests whether the result is equal to the bit mask. An equal result means the value of both tested bits is one and both flags are TRUE. The following table shows the results:

Note: Equivalent decimal values are shown in parentheses.

Constant

Constant attribute mapping lets you map a common name to a value that is the same or constant for every user in a directory. Since constant attribute mappings map common names to constants, which are read only (R), they cannot be changed (except by a system administrator).

Constant attribute mappings can map to constants that have any of the following data types:

• string
• number
• Boolean

Constant Use Case

This use case represents a scenario in which one user directory stores only customers, while another user directory stores only employees.

Note: Review the advanced user attribute mapping examples, which detail how to use different attribute mapping types to identify the same user attribute across different directory types.

The following illustration details how two constant attribute mappings can represent different values for different user directories.

1. Directory A only stores customers. Directory B only stores employees.
2. IsCust is the common name that is mapped to different values in different directories:
   • IsCust is mapped to TRUE in Directory A.
   • IsCust is mapped to FALSE in Directory B.
3. Reference IsCust when defining policies, expressions, or other objects. The common name lets the system determine whether a user is a customer, without regard to the particular directory in which the user is stored. The mapping indicates that every user in Directory A is a customer, while every user in Directory B is not a customer.

More information:

Named Expressions

Advanced User Attribute Mapping Examples

Create a Constant Attribute Mapping

You can map a common name to a constant value that conveys information about every user in a directory. The constant's data type can be string, number, or Boolean. You can use a constant attribute mapping to read a user attribute value that applies to every user in a user directory. User attribute mappings are directory-specific.

To create a constant attribute mapping

1. Navigate to the User Directory: Name pane.
2. Click Create on the Attribute Mapping List group box.

   The Create Attribute Mapping pane opens.

3. Verify that Create a new object is selected, and click OK.

   The Create Attribute Mapping: Name pane opens.

4. Type the common name and a description of the attribute mapping in the fields on the General group box.

   Note: Common names must conform to the same rules as user attribute names.

5. Select Constant on the Properties group box.
6. Type the definition in the Definition box on the Properties group box.

   Example:

   Name: IsCustomer

   Definition: TRUE

   Description: The common name IsCustomer is mapped to the constant value TRUE. Because the user directory only stores customers, the user is always a customer, and IsCustomer is always mapped to TRUE.

7. (Optional) Select Disabled to disable this attribute mapping.
8. Click OK.

   The Create Attribute Mapping task is submitted for processing, and the new attribute mapping is added to the list on the Attribute Mapping List group box.

Expression

An expression attribute mapping lets you map a common name to an expression. The expression can contain one or more user attribute names specified by the user directory's underlying schema and must conform to the syntax rules of a SiteMinder expression.

Expression attribute mappings map common names to expressions that can be read, but not changed. This type of access is called read only (R). When evaluated, the expressions result in a string, number, or Boolean value.

Expression attribute mapping and virtual user attributes, one type of named expression, are similar in the following ways:

• Both are SiteMinder expressions.
• As expressions, both are read only (R).
• As expressions, both result in one of the following data types:
  • string
  • number
  • Boolean

Expression attribute mapping differs from virtual user attributes as follows:

• An expression attribute mapping is defined for particular user directories. Virtual user attributes are global and can be applied to any user in any user directory.
• Virtual user attributes must begin with the pound sign (#). An expression mapping does not.

More information:

Named Expressions

Expression Use Case

This use case shows how you can use an expression attribute mapping to simplify references to multiple user attributes in one directory. A protected resource needs the sort name of each user (last name,first name). The user directory does not uniquely reference this attribute. Instead, the directory does store the last name of each user as surname and the first name of each user as givenname.

The following illustration details how an expression attribute mapping can create a common view of the same user information.

In the single user directory, a common name is mapped to an expression that creates the sort name using the user attribute names in the directory.

• Directory A contains all user records.
• The name of the mapping is SortName.
• The expression that defines SortName is:

  {surname + "," + givenname}
  

  Note: The expression conforms to the syntax rules of a SiteMinder expression.

• SortName is the common name that is mapped to the expression that includes the surname and the givenname attributes.

Reference SortName when defining policies, expressions, or other objects that require the sort name of users without concern for the directory-specific schema.

More information:

Named Expressions

Expression Syntax Overview

Advanced User Attribute Mapping Examples

Create an Expression Attribute Mapping

You can map a common name to an expression that references one or more user attribute names specified by the user directory's underlying schema. An expression attribute mapping's data type is string, number, or Boolean. You can use expression attribute mapping to read the result of an expression, but not to write a value to a user directory.

Note: User attribute mappings are directory-specific. To create a global object that is defined as an expression, create a named expression.

To create an expression attribute mapping

1. Navigate to the User Directory: Name pane.
2. Click Create on the Attribute Mapping List group box.

   The Create Attribute Mapping pane opens.

3. Verify that Create a new object is selected, and click OK.

   The Create Attribute Mapping: Name pane opens.

4. Type the common name and a description of the attribute mapping in the fields on the General group box.

   Note: Common names must conform to the same rules as user attribute names.

5. Select Expression on the Properties group box.

   Note: Selecting Expression activates the Edit button. Clicking Edit opens the Expression Editor. The expression must conform to the syntax rules of a SiteMinder expression.

6. Type the definition in the Definition box on the Properties group box.

   Example:

   Name: SortName

   Definition: (surname + ',' + givenname)

   Description: The common name SortName is mapped to an expression that references the user attribute names surname and givenname.

7. (Optional) Select Disabled to disable this attribute mapping.
8. Click OK.

   The Create Attribute Mapping task is submitted for processing, and the new attribute mapping is added to the list on the Attribute Mapping List group box.

More information:

Named Expressions

Advanced User Attribute Mapping Examples

The following examples show more complex user attribute mapping configurations.

The example deployment is a retail clothing company that uses two user directories of different types:

Directory A

An internal LDAP user directory for employees only.

Directory B

An ODBC user directory for customers only.

Each user attribute mapping is specific to the user directory for which it is defined.

The following table details how Directory A and Directory B identify the same user information. The accompanying use cases explain how to use different attribute mappings to define a common view of the same user information. The common view serves as a universal schema, which makes the directories operationally identical.

Map a First Name Attribute with an Alias Mapping Type

Use two alias attribute mappings to represent the first name user attribute in Directory A and Directory B.

Deployment

User Directory A identifies the first name of users with givenname. Directory B identifies the first name of users with u_first_name.

Solution

1. Create an alias attribute mapping for Directory A.

   Name

   FirstName

   Mapping Type

   Alias

   Definition

   givenname

2. Create an alias attribute mapping for Directory B.

   Name

   FirstName

   Mapping Type

   Alias

   Definition

   u_first_name

When referencing users in Directory A, the FirstName is mapped to givenname. When referencing users in Directory B, the FirstName maps to u_first_name.

Map a Last Name Attribute with an Alias Mapping Type

Use two alias attribute mappings to represent the last name user attribute in Directory A and Directory B.

Deployment

User Directory A identifies the last name of users with surname. Directory B identifies the last name of users with u_last_name.

Solution

1. Create an alias attribute mapping for Directory A.

   Name

   LastName

   Mapping Type

   Alias

   Definition

   surname

2. Create an alias attribute mapping for Directory B.

   Name

   LastName

   Mapping Type

   Alias

   Definition

   u_last_name

When referencing users in Directory A, the common view determines that the last name of users is identified by surname. When referencing users in Directory B, the common view determines that the last name is identified by u_last_name.

Map a Sort Name Attribute with Expression and Alias Mapping Types

Use an expression attribute mapping and an alias attribute mapping to represent the sort name of a user in Directory A and Directory B.

Deployment

• Directory A does not uniquely identify a the sort name for each user. For each user, Directory A stores the first name as givenname and a last name as surname for each user.
• Directory B identifies a sort name using sort_name.

Solution

1. Create an expression attribute mapping for Directory A:

   Name

   SortName

   Mapping Type

   Expression

   Definition

   (surname + "," + givenname)
   

   Note: The expression must conform to the syntax rules of an expression.

2. Create an alias attribute mapping for Directory B:

   Name

   SortName

   Mapping Type

   Alias

   Definition

   sort_name

When referencing users in Directory A, the sort name is calculated based on the specified expression. When referencing users in Directory B, the sort name is represented by the attribute sort_name.

More information:

Attributes and Expressions Reference

Map Customers with Group and Constant Mapping Types

Use a group and a constant attribute mapping to identify customers in Directory A and Directory B.

Deployment

• Directory A stores employee. An employee of the company can also be a customer, so Directory A identifies customers as those employees that belong to the following group:

  cn=Customers,ou=Groups,o=acme.com
  

• Directory B only stores customers. Directory B does not have a user attribute that identifies customers because to store a user in Directory B implies that the user is a customer.

Solution

1. Create a group attribute mapping for Directory A.

   Name

   IsCustomer

   Mapping Type

   Group

   Definition

   cn=Customers,ou=Groups,o=acme.com
   

2. Create a constant attribute mapping for Directory B.

   Name

   IsCustomer

   Mapping Type

   Constant

   Definition

   TRUE

When referencing Directory A, a user is considered a customer if they belong to cn=Customers,ou=Groups,o=acme.com. When referencing Directory B, every user is a customer.

Map the Account Status with the Mask and Expression Mapping Types

Use a mask attribute mapping and an expression attribute mapping to identify user accounts that are disabled in Directory A and Directory B.

Deployment

• Directory A identifies disabled accounts with a user attribute named AccountStatus, which is a set of flags. The second bit indicates a disabled account.
• Directory B identifies disabled accounts with a user attribute named u_disabled. When u_disabled is equal to "y", the account is disabled. When u_disabled is equal to "n", the account is active.

Solution

1. Create a mask attribute mapping for Directory A.

   Name

   IsDisabled

   Mapping Type

   Mask

   Definition

   AccountStatus:2

   The definition indicates that the bit pattern is stored in AccountStatus, and the bit mask is 2 (decimal).

2. Create a expression attribute mapping for Directory B.

   Name

   IsDisabled

   Mapping Type

   Expression

   Definition

   (u_disabled = "y")
   

   u_disabled is a Boolean expression.

When referencing Directory A, the bit pattern determines if a user is disabled. When referencing Directory B, the expression determines if a user is disabled.