Previous Topic: Define a User ClassNext Topic: Directory 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.

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:

The named expression types are:

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

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

User Attribute Mapping Type

Data Types

Visibility

Prefix?

alias (RW)

string, number, Boolean

directory-specific

no

group name (RW)

Boolean

directory-specific

no

mask (RW)

Boolean

directory-specific

no

constant (R)

string, number, Boolean

directory-specific

no

expression (R)

string, number, Boolean

directory-specific

no

Named Expression Type

Data Types

Visibility

Prefix?

virtual user attribute (R)

string, number, Boolean

global

#

user class (R)

Boolean

global

@

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:

Diagram showing the attribute mapping overview case

  1. Two user directories identify the first name of users differently:

    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:
  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:

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:

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.

Graphic showing 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:

    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 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:

Group name attribute mapping differs from user classes as follows:

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.

Graphic showing two group name attribute mappings creating a common view of the same user information

  1. Two user directories identify membership to the administrator group differently:

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

Graphic showing two mask attribute mappings creating 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.

    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.

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:

Bit Pattern

Flag

00?

account disabled?

0?0

password expired?

?00

gold member?

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

Bit Pattern

Account Status

000 (0)

no flags are TRUE

001 (1)

account disabled

010 (2)

password expired

100 (4)

gold member

011 (3)

password expired, account disabled

101 (5)

gold member, account disabled

110 (6)

gold member, password expired

111 (7)

gold member, password expired, account disabled

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:

Account Status

Bit Mask

Result of Bitwise AND

Gold Member?

000 (0)

100 (4)

000 (0)

FALSE

001 (1)

100 (4)

000 (0)

FALSE

010 (2)

100 (4)

000 (0)

FALSE

011 (3)

100 (4)

000 (0)

FALSE

100 (4)

100 (4)

100 (4)

TRUE

101 (5)

100 (4)

100 (4)

TRUE

110 (6)

100 (4)

100 (4)

TRUE

111 (7)

100 (4)

100 (4)

TRUE

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:

Account Status

Bit Mask

Result of Bitwise AND

Both Flags Set?

000 (0)

011 (3)

000 (0)

FALSE

001 (1)

011 (3)

001 (1)

FALSE

010 (2)

011 (3)

010 (2)

FALSE

011 (3)

011 (3)

011 (3)

TRUE

100 (4)

011 (3)

000 (0)

FALSE

101 (5)

011 (3)

001 (1)

FALSE

110 (6)

011 (3)

010 (2)

FALSE

111 (7)

011 (3)

011 (3)

TRUE

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:

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.

Graphic showing two constant attribute mappings representing 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:
  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:

Expression attribute mapping differs from virtual user attributes as follows:

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.

Illustation showing an attribute-mapping expression

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.

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.

Attribute Description

Directory A Attributes (LDAP)

Directory B Attributes (ODBC)

First name of each user

givenname

u_first_name

Last name of each user

surname

u_last_name

Sort name of each user (last name, first name)

The user directory does not uniquely store the user attribute.

sort_name

User as a customer

group:cn=customer,ou=groups,o=acme.com

Users are always customers.

Status of a user account

AccountStatus attribute (a set of flags).

Second bit is a disabled account.

u_disabled

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

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

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

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.