Claims transformation manipulates claims during a federated single sign-on transaction. Claims, also known as attributes, help customize the attributes and improve the user experience at a partner.
Modifying assertion attributes lets the relying party adapt user information so a target application can use it. For example, claims transformation can associate roles at different partners in different domains. In one domain, a user is an engineering manager and belongs to a group named EngineerAdmins. However, the relying party identifies the same role as DevelAdmins. The asserting party alters the role attribute before issuing the assertion. The user is now identified with the DevelAdmins role, which the relying party application can understand.
Claims transformation occurs at the local asserting party during the assertion generation process. You configure the feature on a per-partnership basis. An assertion can be modified whether a local or remote party generates the assertion. Claims are transformed based on an expression that you configure for the partnership. The expression relies on user information from the user store and the CA SiteMinder® session store.
The software can perform three different modifications to assertion attributes:
The following figure shows the configuration steps:
To set up claims transformation, perform the following steps:
Before you configure claims transformation, consider the following prerequisites:
Expressions are rules that instruct the software how to manipulate assertion attributes. The expression directs the software to modify, add, or delete assertion attributes. You construct expressions using the Java Unified Expression Language (JUEL). A JUEL expression evaluator examines the configured expressions and generates the resulting assertion attributes.
Define expressions in the Assertion Attributes table of the Administrative UI. Access this table by navigating to the Assertion Configuration step of the partnership wizard. This table is shown in the following figure:
Enter expressions in the Value column of the assertion attributes table. All attributes in an expression are user store or session store attributes.
Typically, the expression operates on a conditional basis. If the condition is met, the designated claims modification occurs. For example, an incoming assertion contains the "role" attribute. The expression to modify the "role" assertion attribute is:
#{attr["title"] == 'manager' ? 'administrator' : attr["title"]}
The first part of the expression #{attr["title"] == 'manager' tells the software to determine whether the logged-in user has the title "manager." The lookup is done in the user directory. If this condition is met, the second part of the expression, ? 'administrator' : assigns the value "administrator" to the role assertion attribute. If the condition is not met, the last part of the expression, attr["title"]} indicates that the value of the user attribute "title" remains "manager." The value "manager" is assigned to the assertion attribute "role."
Note: You can use static values in an expression in place of the syntax attr["title"], such as 'administrator' in the previous example.
The example assumes the "role" attribute is already in the assertion. Therefore, the expression is a transformation of an existing attribute. If "role" is not part of the assertion, the software adds the role attribute to the assertion.
Expression Syntax
Construct expressions using the proper syntax:
Use lower-case text for the attr and session_attr prefixes. Attribute names are not case-sensitive.
Additionally, be aware of these conditional JUEL operators:
|
Operator |
Meaning |
|---|---|
|
conditional value ? value1 : value2 |
The conditional value resolves to either value1 or value 2. |
|
!= |
Does not equal |
|
== |
Equals |
Important! The attribute in the expression must be available in the user directory or the session store. If an attribute is incorrect, the system simply includes blanks for corresponding attributes. The assertion generation does not fail.
For more examples of expressions, read the section Configure claims Transformation at the Asserting Party.
Define expressions at the partnership level. The result of these expressions modifies, adds, or deletes attributes from assertions. After the rules are defined, the assertion is modified and sent to the relying party. If you do not configure claims transformation, assertion attributes are passed "as is" to the relying party.
Follow these steps:
In the Assertion Attributes section, click Add Row.
Enter an assertion attribute. All values in this column are assertion attributes. An attribute that is already in the assertion remains in the assertion, but it is set to a new value based on the configured expression. The attribute is removed from the assertion only if you configure a DELETE expression.
Keep the default, SSO.
Designates the format for the attribute being added to the assertion. The format options vary depending on the SAML profile for the entity.
Expression
Always use this value for claims transformation.
Enter an expression that reflects how you want the assertion attribute is modified.
Review the guidelines about constructing claims expressions and the following examples:
The relying party decrypts the assertion attributes using the private key that is associated with the certificate.
Claims transformation is implemented based on the configured entries in the partnership.
Transforming a claim changes an assertion attribute value to another value.
Note: These examples only show entries for Assertion Attribute, Type, and Value.
Transformation Example 1
The following example assumes the "title" attribute is already in the assertion. The table indicates the user attributes in the user store.
|
User Directory Attributes |
Attribute Value |
|---|---|
|
role |
admin |
|
admintitle |
SeniorAdmin |
|
supertitle |
SuperUser |
Transform the value of the existing title attribute using the following configuration:
title
Expression
#{attr[“role”] == ‘admin’ ? attr[“admintitle”] : attr[“supertitle”]}
Result: The expression is conditional based on the "role" user attribute being set to "admin." Assuming this condition is met, the assertion attribute "title" is set to the value SeniorAdmin, the "admintitle" attribute. If the role is something other than "admin," the "title" attribute becomes SuperUser, the value of the "supertitle" attribute.
Transformation Example 2
The following example assumes that the ContactNo attribute is already in the assertion.
|
User Directory Attributes |
Attribute Value |
|---|---|
|
homephone |
555-3344 |
|
mobile |
555-8888 |
Transform the value of the existing title attribute using the following configuration:
ContactNo
Expression
#{attr["homephone"] == '555-3344' ? attr["mobile"] : attr["homephone"]}
Result: The expression is conditional on the logged-in user having the "homephone" user attribute set to 555-3344. Assuming this condition is met, the assertion attribute is set to 555-8888, the value of the "mobile" attribute. If the condition is not met, the "homephone" value does not change.
Note: To configure an expression that uses session attributes, replace attr["attribute_name"] with session_attr[“attribute_name”]. For example:
#{session_attr[“att1”] == ‘admin’ ? session_attr[“attr2”] : attr[“attr3”]}
You can add an assertion attribute that is not already present.
Addition Example 1
The following example assumes the "title" assertion attribute is not in the assertion.
|
User Directory Attribute |
Attribute Value |
|---|---|
|
role |
admin |
|
admintitle |
director |
|
supertitle |
executive |
The following configuration adds the title attribute to the assertion.
title
Expression
#{attr[“role”] == ‘admin’ ? attr[“admintitle”] : attr[“supertitle”]}
Result: The expression is conditional on the logged-in user having the "role" attribute set to admin. Assuming this condition is met, the assertion attribute "title" is added to the assertion and set to the value "director," the "admintitle" attribute value. If the role is something other than "admin," the assertion attribute "title" is added but the value becomes "executive," the value of the "supertitle" attribute.
Addition Example 2
The following example assumes the "smtitle" assertion attribute is not in the assertion.
|
User Directory Attribute |
Attribute Value |
|---|---|
|
title |
manager |
smtitle
Expression
#{attr["title"] == 'manager' ? 'federation administrator' : attr["title"]}
Result: If the logged-in user has the title of "manager," add "smtitle" to the assertion and set its value to "federation administrator." You can enter any static value after the question mark instead of using the syntax attr["attribute_name"]. In this example, the static value is federation administrator,
Note: To configure an expression that uses session attributes, replace attr["attribute_name"] with session_attr[“attribute_name”]. For example:
#{session_attr[“att1”] == ‘admin’ ? session_attr[“attr2”] : attr[“attr3”]}
You can delete an assertion attribute.
Deletion Example 1
Delete the admintitle and supertitle assertion attributes by configuring two entries.
|
User Directory Attribute |
Attribute Value |
|---|---|
|
role |
admin or superuser |
|
title |
administrator |
|
su |
superuser |
admintitle
Expression
#{attr[“role”] == ‘superuser’ ? ‘DELETE’ : attr[“title”]}
Result: The expression string is conditional based on the "role" user attribute. If the logged-in user has the role of superuser, delete the assertion attribute "admintitle." If the role is not superuser, set the title assertion attribute to the value of administrator, the value of the title user directory attribute.
supertitle
Expression
#{attr[“role”] == ‘admin’ ? ‘DELETE’ : attr[“su”]}
Result: The expression string is conditional on the "role" user attribute. If the logged-in user role is "admin," delete the assertion attribute "supertitle." If the role is not "admin," set the supertitle assertion attribute to the value of superuser, the value of the su user directory attribute.
Deletion Example 2
The following example combines an addition and a deletion using one expression.
|
User Directory Attribute |
Attribute Value |
|---|---|
|
title |
manager |
ManagerName
Expression
#{attr["title"] != 'Manager' ? attr["manager"] : 'DELETE'}
Result: If the logged-in user does not have the user attribute title "manager," add the ManagerName attribute to the assertion. However, if the logged-in user title is manager, delete the ManagerName attribute, assuming it is part of the assertion.
Note: To configure an expression that uses session attributes, replace attr["attribute_name"] with session_attr[“attribute_name”]. For example:
#{session_attr[“att1”] == ‘admin’ ? session_attr[“attr2”] : attr[“attr3”]}
|
Copyright © 2015 CA Technologies.
All rights reserved.
|
|