Contents


Customizing SAML 2.0 with Tivoli Federated Identity Manager

Create custom SAML 2.0 assertions for single sign-on federated environments

Comments

There are many benefits to using multiple third-party applications in a distributed architecture—and some challenges as well. Users expect to be able to access enterprise application services with a single login, which requires integrating disparate web services under one authentication and authorization mechanism. For developers and administrators using IBM Tivoli Federated Identity Manager, the obvious solution is to set up a federated single sign-on environment, where one login authorizes access to multiple applications.

SAML is one of the most commonly used protocols for creating federation agreements, providing an XML schema-based metadata framework for describing and exchanging security information. Vendors may interpret and use SAML differently, but Tivoli Federated Identity Manager is flexible enough to handle the variation.

In this article, learn how to leverage Tivoli Federated Identity Manager's identity-mapping rules to customize SAML 2.0 for a single sign-on architecture. The article starts with a brief introduction to Tivoli Federated Identity Manager's identity-mapping capabilities. It then explains how to use identity mapping to create SAML assertions that meet a cloud service provider's authentication and authorization requirements.

Note that this article is intended for software developers and administrators with basic to advanced skills using Tivoli Federated Identity Manager.

Identity-mapping rules

Service providers expect to receive user authentication information in the form of a SAML subject-and-attribute list. You can easily provide this information using Tivoli Federated Identity Manager's identity-mapping rules. The Tivoli Federated Identity Manager identity-mapping rule shown in Listing 1 inserts an attribute called federationid into a SAML assertion.

Listing 1. An identity-mapping rule
importPackage(Packages.com.tivoli.am.fim.trustserver.sts);
importPackage(Packages.com.tivoli.am.fim.trustserver.sts.uuser);

var authnMethodAttr = new Attribute("AuthnContextClassRef","urn:oasis:names:tc:SAML:2.0:assertion",
"urn:oasis:names:tc:SAML:2.0:ac:classes:Password"); 
var attributeContainer = stsuu.getAttributeContainer();

var prinAttr = attributeContainer.getAttributeValueByName("tagvalue_credattrs_name"); 
var principalAttr = new Attribute("name", 
"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", ""+prinAttr);

var wsfloginid = attributeContainer.getAttributeValueByName("tagvalue_credattrs_name");
var sflognid = new Attribute("sfloginid", "urn:ibm:names:ITivoli Federated Identity Manager:5.1:accessmanager", ""+wsfloginid);

stsuu.clear(); 
stsuu.clearAttributeList(); 
stsuu.addPrincipalAttribute(principalAttr);
stsuu.addAttribute(authnMethodAttr); 
stsuu.addAttribute(sflognid);

You can insert an identity-mapping rule like this one into an existing federation agreement or use it to add a new federation partner, which we'll demonstrate next.

Adding a federation partner

You create a new federation partner anytime you add a third-party application or web service to your enterprise. In this section, we'll walk through the process of adding a new partner—cloud service provider Salesforce.com in our example—to an existing federation; later in the article we'll show you how to customize your sign-on requirements for a given service provider.

  1. Log on to the Tivoli Federated Identity Manager administrator console and navigate to the Federations page by clicking on Federations in the left panel, as shown in Figure 1.
    Figure 1. Navigate to the Federations page
    A screenshot of the Tivoli Federated Identity Manager administrator console.
    A screenshot of the Tivoli Federated Identity Manager administrator console.
  2. Select Federation and click Add Partner.
    Figure 2. Add a partner
    A screenshot of the console option to select a partner.
    A screenshot of the console option to select a partner.
  3. Provide the location of your new partner's metadata file. The metadata file, which you obtain from your partner, contains URLs to access services as well as certificate information. Click Next when you're done.
    Figure 3. Provide federation metadata
    A screenshot of the location field for federation metadata.
    A screenshot of the location field for federation metadata.
  4. Provide the requested signature validation information and click Next.
    Figure 4. Provide signature validation
    A screenshot of the field for signature validation information.
    A screenshot of the field for signature validation information.
  5. Client authentication is not required, so click Next.
    Figure 5. No authentication required
    Authentication is not required.
    Authentication is not required.
  6. Provide the requested partner setting information and click Next.
    Figure 6. Add partner settings
    A screenshot of the field to provide partner settings.
    A screenshot of the field to provide partner settings.
  7. Keep the default SAML Assertions settings and click Next.
    Figure 7. Keep default SAML assertions
    A screenshot of the option to keep the default SAML assertions.
    A screenshot of the option to keep the default SAML assertions.
  8. Select Use XSL or JavaScript transformation for identity mapping, then click Next.
    Figure 8. Select XSL or JavaScript transformation
    Select XSL or JavaScript.
    Select XSL or JavaScript.
  9. Provide the location of the file with the identity-mapping rule created in Listing 1.
    Figure 9. Provide the location of the identity-mapping rule
    A screenshot of the field to provide the identity-mapping file location.
    A screenshot of the field to provide the identity-mapping file location.
  10. Review the summary and click Finish.
    Figure 10. Review the summary
    Review summary.
    Review summary.
  11. Click Enable Partner.
    Figure 11. Enable partner
    Finish.
    Finish.

With these steps, you have configured a new federation partner with the identity-mapping rule specified in Listing 1. If you enable trace in Tivoli Federated Identity Manager and capture the SAML assertion, it displays the injected SAML attributes shown in Listing 2.

Listing 2. Output with SAML attributes
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
ID="Assertion-uuid7caf7d6f-013d-15e4-a142-cde6480fe8b0" IssueInstant="2013-03-18T08:48:28Z" 
Version="2.0">
....
<saml:AttributeStatement><saml:Attribute Name="portal_id" 
NameFor-mat="urn:ibm:names:ITivoli Federated Identity Manager:5.1:accessmanager">
<saml:AttributeValue xsi:type="xs:string">06090000000DWOy</saml:AttributeValue>
</saml:Attribute><saml:Attribute Name="sfloginid" 
NameFor-mat="urn:ibm:names:ITivoli Federated Identity Manager:5.1:accessmanager">
<saml:AttributeValue xsi:type="xs:string">15996</saml:AttributeValue>
</saml:Attribute></saml:AttributeStatement>
</saml:Assertion>

Customizing SAML attributes

Service providers occasionally request a custom SAML 2.0 message to support specific access control requirements or restrictions. You can use Tivoli Federated Identity Manager to override and customize the SAML 2.0 attributes shown in Table 1.

Table 1. Customizable SAML attributes
Setting numberSAML attributeDescription
1AudienceRestrictionSpecifies that the assertion is addressed to one or more specific audiences identified by <Audience> elements.
2NameQualifierThe security or administrative domain that qualifies the identifier. This attribute provides a means to federate identifiers from disparate user stores without collision.
3RecipientA URI specifying the entity or location to which an attesting entity can present the assertion. For example, this attribute might indicate that the assertion must be delivered to a particular network endpoint to prevent an intermediary from redirecting it someplace else.
4InresponseTo The ID of a SAML protocol message in response to which an attesting entity can present the assertion. For example, this attribute might be used to correlate the assertion to a SAML request that resulted in its presentation.

Overriding AudienceRestriction

In Listing 3, Tivoli Federated Identity Manager's identity-mapping rules override the AudienceRestriction URL in a SAML assertion.

Listing 3. A SAML assertion to override AudienceRestriction
importPackage(Packages.com.tivoli.am.fim.trustserver.sts);
importPackage(Packages.com.tivoli.am.fim.trustserver.sts.uuser);

var authnMethodAttr = new Attribute("AuthnContextClassRef","urn:oasis:names:tc:SAML:2.0:assertion",
"urn:oasis:names:tc:SAML:2.0:ac:classes:Password");
var attributeContainer = stsuu.getAttributeContainer();

var sfar = java.lang.reflect.Array.newInstance(java.lang.String, 1);
sfar[0] = "https://saml.salesforce.com";

var wsfloginid = attributeContainer.getAttributeValueByName("tagvalue_credattrs_name");

var AudienceRestriction = new Attribute("AudienceRestriction", null, sfar);
var principalAttr = new Attribute("name", "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
""+wsfloginid);

stsuu.clear();
stsuu.clearAttributeList();
stsuu.addAttribute(AudienceRestriction);
stsuu.addPrincipalAttribute(principalAttr);
stsuu.addAttribute(authnMethodAttr);

Note that when an attribute is added through an identity-mapping rule using the command

var AudienceRestriction = new Attribute("AudienceRestriction", null, sfar)

it expects three parameters:

  1. Attribute name
  2. Attribute type
  3. Attribute value

Attribute types

Each of the attributes in Table 1 requires specific attribute types, which are listed in Table 2.

Table 2. SAML attribute types
Setting numberSAML attributeType
1AudienceRestrictionNull
2NameQualifierurn:oasis:names:tc:SAML:2.0:assertion
3RecipientNull
4InresponseToNull

Case study: Salesforce.com

Let's say that our organization wants to consume two web services from Salesforce.com, Chatter and Employee Portal. Like many vendors, Salesforce.com has specific authentication requirements, which identity providers must meet to access its services. To authenticate users for the Salesforce.com web services, we must provide a SAML assertion with the following properties:

  • Every federation partner must have a unique Assertion Consumer Service (ACS) URL
  • Every federation partner must have the same Entity ID

Salesforce.com only provides one metadata file, and that is for the Employee Portal web service. To add the second partner and access the Chatter service, we'll need to customize the metadata using the file provided for Employee Portal. When we edit the Entity ID in the metadata file, the AudienceRestriction URL in the SAML will also be edited, leading Salesforce.com to reject the SAML message. (Using the identity-mapping rule, the AudienceRestriction URL is modified on the fly and inserted into the SAML message.)

Configuring federation partners

To access the two web services and meet Salesforce.com's custom authentication requirements, we will set up a single federation with two partners. We'll walk through the steps below.

Step 1. Configure the identity provider

  1. Log on to the Tivoli Federated Identity Manager administrative console. Click Federations in the left panel, then click Create.
    Figure 12. Create a federation
    Click Federations in the left-hand panel.
    Click Federations in the left-hand panel.
  2. Provide the federation name and select the Identity Provider role. Click Next.
    Figure 13. Configure the federation
    Name the federation and select its role.
    Name the federation and select its role.
  3. Provide the requested organizational information, then click Next.
    Figure 14. Provide organizational information
    A screenshot of the field for organizational information.
    A screenshot of the field for organizational information.
  4. Select SAML 2.0 as the federation protocol and click Next.
    Figure 15. Select the federation protocol
    Select SAML 2.0 as the federation protocol.
    Select SAML 2.0 as the federation protocol.
  5. Provide the point-of-contact server information and click Next.
    Figure 16. Provide a point-of-contact
    Add the point-of-contact server.
    Add the point-of-contact server.
  6. Select Typical as a profile selection, then click Next.
    Figure 17. Select a typical profile
    Select the typical profile option.
    Select the typical profile option.
  7. Specify the signature options and click Next.
    Figure 18. Specify signature options
    Specify signature options.
    Specify signature options.
  8. Specify the encryption options and click Next.
    Figure 19. Specify encryption options
    Specify encryption options.
    Specify encryption options.
  9. Specify the SAML Message settings and click Next.
    Figure 20. Specify SAML message settings
    Specify the SAML message settings.
    Specify the SAML message settings.
  10. Specify the SAML Assertion settings and click Next.
    Figure 21. Specify SAML assertion settings
    Specify the SAML assertion settings.
    Specify the SAML assertion settings.
  11. Select Use XSL and JavaScript for identity mapping then click Next.
    Figure 22. Specify XSL and JavaScript
    Use XSL and JavaScript.
    Use XSL and JavaScript.
  12. Select a sample identity-mapping rule (but note that the Partner setting rule will override this rule). Click Next.
    Figure 23. Select an identity-mapping rule
    Select a sample identity-mapping rule.
    Select a sample identity-mapping rule.
  13. Review the summary, then click Finish.
    Figure 24. Review summary
    Review the summary.
    Review the summary.
  14. Click Download Tivoli Access Manager Configuration Tool, which will configure the point-of-contact server. Then click Done.
    Figure 25.
    Download the Tivoli Access Manager configuration tool.
    Download the Tivoli Access Manager configuration tool.
  15. See that the federation has been successfully created and is listed on the Federations page.
    Figure 26. Listing for the new federation
    The new federation is listed.
    The new federation is listed.
  16. Export the federation information and share it with your federation partner, in this case Salesforce.com.
    Figure 27. Export federation information
    Export the federation information to Salesforce.com.
    Export the federation information to Salesforce.com.

Step 2. Configure the service provider

To set up a standard SAML 2.0 federation you will need to exchange metadata files between the identity provider and the service provider. We start with the metadata file from Salesforce.com, which we'll modify to create our second federation partner.

Figure 28. Salesforce.com metadata file
The original metadata file from Salesforce.com.
The original metadata file from Salesforce.com.

Open the original metadata file in Figure 28 in a text editor and modify it as shown in Figure 29 to support a different ACS URL:

Figure 29. Modified XML metadata file
The modified metadata file.
The modified metadata file.

Note that in Figure 29 we've change the Entity ID to uniquely identify the federation partner in Tivoli Federated Identity Manager. We've also specified an alternate ACS URL in the AssertionConsumerService field.

Step 3. Prepare the identity-mapping rule

Next, we'll configure the identity-mapping rules for the two partners.

Listing 4 displays the identity-mapping rule that will go along with the original metadata file. This metadata file simply adds the additional SAML attribute sfloginid to the SAML message.

Listing 4. Identity-mapping rule for the original metadata
importPackage(Packages.com.tivoli.am.fim.trustserver.sts);
importPackage(Packages.com.tivoli.am.fim.trustserver.sts.uuser);

var authnMethodAttr = new Attribute("AuthnContextClassRef","urn:oasis:names:tc:SAML:2.0:assertion",
"urn:oasis:names:tc:SAML:2.0:ac:classes:Password");
var attributeContainer = stsuu.getAttributeContainer();

var wsfloginid = attributeContain-er.getAttributeValueByName("tagvalue_credattrs_name");
var sflognid = new Attribute("sfloginid", "urn:ibm:names:ITFIM:5.1:accessmanager", ""+wsfloginid);
var principalAttr = new Attribute("name", "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
""+wsfloginid);

stsuu.clear();
stsuu.clearAttributeList();
stsuu.addPrincipalAttribute(principalAttr);
stsuu.addAttribute(authnMethodAttr);
stsuu.addAttribute(sflognid);

The identity-mapping rule in Listing 5 overrides the AudienceRestriction URL from the original metadata configuration (https://saml.salesforce.com_communities) with the one specified (https://saml.salesforce.com).

Listing 5. Identity-mapping rule for the modified metadata
importPackage(Packages.com.tivoli.am.fim.trustserver.sts);
importPackage(Packages.com.tivoli.am.fim.trustserver.sts.uuser);

var authnMethodAttr = new Attrib-ute("AuthnContextClassRef","urn:oasis:names:tc:SAML:2.0:assertion",
"urn:oasis:names:tc:SAML:2.0:ac:classes:Password");
var attributeContainer = stsuu.getAttributeContainer();

var sfar = java.lang.reflect.Array.newInstance(java.lang.String, 1);
sfar[0] = "https://saml.salesforce.com";
var AudienceRestriction = new Attribute("AudienceRestriction", null, sfar);
var wsfloginid = attributeContainer.getAttributeValueByName("tagvalue_credattrs_name");
var sflognid = new Attribute("sfloginid", "urn:ibm:names:ITFIM:5.1:accessmanager", ""+wsfloginid);
var principalAttr = new Attribute("name", "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
""+wsfloginid);

stsuu.clear();
stsuu.addAttribute(AudienceRestriction);
stsuu.addPrincipalAttribute(principalAttr);
stsuu.addAttribute(authnMethodAttr);
stsuu.addAttribute(sflognid);

After your identity-mapping rules are ready, import the partner profiles and the corresponding identity-mapping rules as demonstrated in the section on identity-mapping rules. Figure 30 shows the configuration in Tivoli Federated Identity Manager.

Figure 30. Tivoli Federated Identity Manager setting and configuration
A screenshot of the single sign-on federation partner configuration.
A screenshot of the single sign-on federation partner configuration.

With this configuration, correctly formulated SAML messages are sent to different ACS URLs, all bearing the same Entity ID, as stipulated by Salesforce.com. This configuration enables single sign-on for employees and vendors accessing Salesforce.com's Employee Portal and Chatter services.

In conclusion

In this article, you've learned how to use Tivoli Federated Identity Manager's identity-mapping rules to customize SAML 2.0 assertions to meet the unique requirements of a service provider. In our example, the Salesforce.com case study, we demonstrated how to set up a single federation with two partners, walking through the required steps to configure and load the federation into the server. The resulting system generates a SAML assertion for each federation partner, meeting Salesforce.com's authentication requirements while enabling single sign-on authentication and authorization for enterprise system users.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Security
ArticleID=952964
ArticleTitle=Customizing SAML 2.0 with Tivoli Federated Identity Manager
publish-date=11192013