SAML Trusted Affiliate Object
The samlTrustedAffiliate object defines the SAML trust relationship between your site (as defined in the samlSiteConfig object) and a SAML partner. The relationship between two SAML partner sites has two halves: settings that deal with incoming users from the partner site and settings that define how outgoing users going to the partner site are handled.
- Incoming SAML settings define how incoming SAML users from this Trusted Affiliate site are handled.
- Outgoing SAML settings define how to generate SAML assertions for users going to this Trusted Affiliate site.
(Where there could be confusion, this document clarifies which settings apply to which half of the relationship.)
To create a samlTrustedAffiliate object, right-click a samlSiteConfig object, then select New > Trusted Affiliate. See Figure 42. It is good idea to name the samlTrustedAffiliate object something similar to the actual SAML Site ID of the SAML partner site.
Figure 42Creating a SAML Trusted Affiliate Object
Open the properties page of a samlTrustedAffiliate by right-clicking it and selecting the properties menu. Each of the property pages are described below:
General
Figure 43 shows the samlTrustedAffiliate General page. This page contains the identification settings for this Trusted Affiliate object. This page is similar to the General page for the samlSiteConfig object. The settings for this page are described below.
Figure 43samlTrustedAffiliate: General Page
Site ID: Contains the SAML Site ID for this Trusted Affiliate. This value is used to identify the Trusted Affiliate when performing SAML operations. It is used to determine the source of SAML assertions generated by this partner site.
Source ID: Contains the SAML Source ID for this Trusted Affiliate, and is used as part of the SAML Browser/Artifact profile. In the Browser/Artifact profile. an incoming user is presented to the SAML service with a SAML artifact. The SAML artifact contains two critical pieces of information:
Assertion Handle: A reference to the SAML assertion generated for the user that the receiving site must request from the referring site.
Source ID: A 20-byte value that uniquely identifies the referring site. The receiving site uses this value to know who to request the assertion from.
The Source ID for the Trusted Affiliate can be imported or auto-generated, as shown on the samlSiteConfig properties page. In general, this value is received from the partner site in either HEX or Base64 format and is imported.
SAML Signature: Located under Trusted Root Information. This partner site might include a digital signature on SAML data it generates. You must have a public key certificate associated with the key used to generate the digital signature in order to validate it. This setting allows the administrator to specify the certificates that are to be used to validate digitally signed SAML information from this partner site. These certificates must have been imported into the directory using the Novell Certificate Server utilities. See SAML Security Considerations for details on the SAML security settings.
Secure SAML Communication: Located under Trusted Root Information. Direct communication between the SAML extension server and the Trusted Affiliates is generally done over mutually authenticated SSL. In order to create these SSL connections, you must trust the server certificate associated with your partner's SAML service. The trusted roots listed here are used to create these connections. These certificates must have been imported into the directory using Novell Certificate Server utilities. Since incoming SSL requests pass through the iChain server, the SSL communication trusted roots must be imported into the same Trusted Root container as that specified in the iChainServiceObject. This setting is found in the iChainServiceObject property page on the General page as shown below:
Figure 44iChainServiceObject Property Page
Assertion Generation Enabled: Indicates whether you allow assertions to be generated for this Trusted Affiliate. If you set this to Off, you cannot send users from your site to this Trusted Affiliate site.
Assertion Receiving Enabled: Indicates whether you will allow incoming users from this Trusted Affiliate. If you set this to Off, incoming users from this Trusted Affiliate cannot access your site.
User Mapping
The User Mapping page deals exclusively with the incoming half of the relationship. The user mapping rules define how incoming SAML users from this Trusted Affiliate are mapped to identities at your site. There are two different user mapping rule types:
Dynamic: Performs an LDAP search at a specified search base in the directory. Any attribute on the incoming assertion can be used as a search parameter. The first matching user object that is found matching the specified criteria are used as the user identity at this site. This type of rule is good for 1-to-1 mappings where this site and the partner site have the same set of users.
Static: Performs a comparison operation of a static value against a value in the incoming SAML assertion. If the comparison operation evaluates to TRUE, then a statically defined user mapping takes place. This type of rule works well for many-to-one mappings where users are mapped to roles rather than their individual identity.
The user mapping rules are stored in an ordered list. This means they are evaluated in order until a mapping is found. If no mapping rules exist or no mapping is found, the default user mapping as defined in the samlSiteConfig object is applied. If there is no default user mapping, the incoming user cannot access your site.
Figure 45 shows the User Mapping page:
Figure 45samlTrustedAffiliate: User Mapping Page
Click the plus sign (+) on the right side to launch the Add A User Mapping Rule dialog box, as shown in Figure 46:
Figure 46Add a User Mapping Rule Dialog Box
This dialog box allows the administrator to give the new user mapping rule a description and decide whether dynamic or static user mapping rule is created.
Dynamic User Mapping Rules
To create a dynamic user mapping rule, provide a description, select Make This a Dynamic Mapping Rule, then click Rule Specification. The dynamic user mapping dialog box launches, as shown in Figure 47:
Figure 47New Dynamic Mapping Rule Dialog
The LDAP Search filter contains the LDAP search string that performs the search. The SAML Attributes that you want to search against are defined by using the SAML (attribute name) key word. For example, if you want to perform a search against the LDAP mail attribute and you have an incoming SAML Attribute named Email, the search string is:
(mail=SAML(Email))
When this search is evaluated for an incoming user, the SAML(Email) value is replaced with the SAML Email attribute. For example, if the SAML assertion contains an Email attribute of joe@excite.com, the resulting search string is:
(mail=joe@excite.com)
The search base defines the organization or organizational unit where the search begins. The scope defines whether the sub-tree of the search base is included in the search. If the value one is used, only the container specified in the Search base is searched. If sub is used, the Search base and all its subcontainers are searched for a match.
The following figure shows the complete definition of the Email search rule:
Figure 48New Dynamic Mapping Rule: Email Search Rule
This rule performs a search matching users' mail attribute with the incoming SAML assertion's email attribute. The search begins in the o=novell container, but sub-trees are not searched.
After you click OK, the User Mapping page now has a rule entry, as shown in Figure 49:
Figure 49User Mapping Page: Rule Entry
Static User Mapping Rules
Static user mapping rules take attributes in the SAML assertion and compare them against statically defined values. If the comparison evaluates to TRUE, then a statically defined user reference is used as the mapping. Static user mapping rules are ideal to map many users into a smaller set of groups or roles. For example, an airline may have four different customer categories:
- Gold: 100,000 or more frequent flyer miles
- Silver: 50,000 or more frequent flyer miles
- Bronze: 10,000 or more frequent flyer miles
- Lead: Less than 10,000 frequent flyer miles
Consider that two airlines are sharing customers with each other. When users are sent to the airline's portal, the airline requests that the number of frequent flier miles are sent as a SAML Attribute called frequentFlierMiles. This way, the airline portal can present the user with different offers and content based upon his or her customer category. This type of mapping is ideal for a set of static user mapping rules.
To create a new mapping rule, select the plus sign (+). The New Mapping Rule dialog box is displayed. Select Static Mapping Rule > Rule Specification. The static user mapping dialog box is shown. Figure 50 contains the gold user mapping rule, as shown:
Figure 50New Static Mapping Rule: User Mapping Rule
This rule states that if the frequentFlierMiles SAML attribute is greater than or equal to 100,000, the user is mapped to cn=gold_customer,o=novell user object.
Next, define the mapping rule for silver users, as shown in Figure 51:
Figure 51Modify Static Mapping Rule
The upper bound on this rule has not been set, meaning that if a gold user were to be evaluated with this rule, he or she would be mapped to cn=silver_customer,o=novell rather than the correct gold user. This shows the importance of rule ordering. If you place the gold user before silver in the list, you are assured that gold users are always be successfully mapped by the gold rule before the silver rule is ever evaluated. Figure 52 shows the user mapping table:
Figure 52Rule Ordering
Take note of the blue arrow icons on the right ride of the panel. Use these arrows to change the order of the rules in the list. The upward-pointing arrow moves the rule higher up in the list so that it will be evaluated sooner, and the downward-pointing arrow moves the rule down in the list so that it is evaluated later.
If you want to be certain that the silver user mapping rule didn't accidentally map gold users to silver, you can add an additional constraint (upperbound) onto the silver mapping rule as shown in Figure 53:
Figure 53Mapping Rule: Adding an Additional Constraint
This rule ensures that the number of frequent flier miles is less than the gold threshold so that no gold users will be erroneously mapped to silver.
A similar rule can be created for bronze. You can create a special wildcard rule for the catch-all lead user. For lead, it doesn't really matter how may frequentFlierMiles the user has. Because he or she already failed the mapping test for gold, silver, and bronze, you know that he or she must be considered as lead. An asterisk (*) character placed in the attribute or value name causes the rule to always evaluate to TRUE, as shown in the lead mapping rule in Figure 54:
Figure 54Mapping Rule: Wildcard Rule
The resulting user mapping list is shown in Figure 55:
Figure 55User Mapping List
According to the ordering of the mapping rules used in this example, the rules will always be evaluated in the following order:
- gold_mapping
- silver_mapping
- bronze_mapping
- lead_mapping
Mixing User Mapping Rule Types
Static and dynamic user mapping rules can be used in the same user mapping rules list. Generally, it is a good idea to include a wildcard user mapping after a dynamic user mapping rule to prevent cases where no results are found. Dynamic user mapping rules follow the same ordering rules as the static rules.
Default User Mapping Rule
If the user mapping rules table is left blank, the Default user mapping defined in the samlSiteConfig object is always performed. If the Default user mapping is blank, no one from the specified Trusted Affiliate can access your site because the user mapping process always fails.
User Password Attribute
Some applications fronted by iChain still require a user password in order to function properly. This value allows the administrator to specify an incoming SAML attribute value to use as the user's password when the session is created on iChain. For instance, if the Trusted Affiliate sends the user's password as a SAML Attribute named UserPwd, by placing UserPwd in this field, the resulting iChain session creates using the UserPwd value.
NOTE: This feature is included to support legacy applications that require a user password for authentication. You should avoid using it if possible.
Audience
You can address a SAML assertion to any specific audience. This audience value specifies which audiences are accepted for incoming assertions from the affiliate. If an audience is marked as "restrict," all assertions outbound to this affiliate include the audience value in the audience restriction.
The value of an audience is a URI reference that identifies an intended audience. The URI reference could even identify a document that describes the terms and conditions of audience membership. In the Liberty specification, which uses SAML assertions, the audience that is used is the provider ID. When you first set up a SAML partnership, adding audience restrictions conditions is probably unnecessary and could add complexity.
Figure 56 shows an example where SAML assertions are accepted with the test:audience:value or test:audience2:value, and a SAML Audience restriction condition is added:
Figure 56Audience Page
For more information about how SAML Audiences restriction conditions are used in the SAML protocol, please refer to the SAML specification documents.
Assertions Tab
The Assertions page contains settings relating to security constraints placed on assertions that are accepted from the Trusted Affiliate site, and how to generate SAML assertions for the Trusted Affiliate. Figure 57 shows the Assertions page with the default settings applied:
Figure 57Assertions Tab: Default Settings
The first two settings apply to SAML assertions that you generate for this Trusted Affiliate for outgoing users:
Digitally Sign Assertions for Browser/Artifact Profile: Indicates whether a digital signature should be generated when creating SAML assertions intended for this Trusted Affiliate using the browser/Artifact profile. The SAML specification does not require that browser/Artifact SAML data be signed, so the default value is set to False.
Digitally Sign Assertions for Browser/POST Profile: Indicates whether a digital signature should be generated when creating SAML assertions intended for this Trusted Affiliate. The SAML specification requires that browser/POST SAML data be signed, so the default value is set to True.
The next three settings apply to SAML assertions that you accept from this Trusted Affiliate for incoming users:
Require Digitally Signed Messages for Browser/Artifact Profile: Indicates whether you accept SAML assertions from this Trusted Affiliate using the browser/Artifact profile if they are not signed. Because the SAML specification does not require that browser/Artifact SAML data be signed, the default value is set to False. If the value is True and a browser/Artifact SAML assertion is received without a digital signature, it is rejected and the incoming user cannot access your site.
Require Digitally Signed Messages for Browser/POST Profile: Indicates whether you accept SAML assertions from this Trusted Affiliate using the browser/POST profile if they are not signed. Because the SAML specification requires that browser/POST SAML data be signed, the default value is set to True. If the value is True and a browser/POST SAML assertion is received without a digital signature, it is rejected and the incoming user cannot access your site.
This setting applies to both the incoming and outgoing halves of the SAML relationship:
Require Client Authentication for Secure SAML Communication: The SAML back-channel can be run over HTTPS with or without client authentication. The SAML Extension server has two separate URLs to handle SSL and SSL-M. These are:
https://<host>/cmd/ext/samlext/saml/resp: This is for non-client-authenticated communication.
https://<host>/cmd/mutExt/samlext/saml/resp: This is for client-authenticated communication.
Because the SAML specification requires client authentication, the default value for this setting is True. If communication requests are received over the non-mutually authenticated channel (/cmd/ext) and this setting is True, the communication request is rejected.
The final two settings relate to SAML assertion generation, and relate to the outbound user half of the relationship:
Assertion Generation Will Be Valid for this Long Before the Current System Time: Allows the default value defined in the samlSiteConfig object to be overridden for this Trusted Affiliate. For details on what the setting does, see Assertions.
Assertion Generation Will Be Valid for this Long After the Current System Time: allows the default value defined in the samlSiteConfig object to be overridden for this Trusted Affiliate. For details on what the setting does, see Assertions.
User Attributes
The user attributes page applies only the out-bound aspect of the SAML trust relationship. On this page, the SAML administrator defines what attributes are made available to SAML Trusted Affiliate sites, as well as which attributes are included in SAML single sign-on Assertions. Figure 58 shows the User Attributes page:
Figure 58User Attributes Page
Typically, the names and namespaces for these attributes are requested by the Trusted Affiliate site. The Trusted Affiliate requests, for instance, that the user's e-mail address be made available and that it be named "InternetMail" with namespace "partner:attributes" in the SAML assertion. Click the plus sign (+) to create a new attribute. The Add a User Attribute dialog box launches, as shown in Figure 59:
Figure 59Add A User Attribute Dialog Box
SAML Attribute: The SAML attribute name value in the generated SAML assertion.
SAML Namespace: The SAML attribute namespace value in the generated SAML assertion.
LDAP Attribute: The LDAP attribute value that is to be queried and used as the SAML attribute value.
Include With Authentication Assertion: Indicates whether this attribute is to be sent with SAML authentication assertions generated for this Trusted Affiliate. Generally, unless the partner site requests the SAML attributes in a separate SAML attribute query, this caption should be selected.
The SAML extension server can also respond to SAML attribute queries. The SAML Extension server provides attributes included only in this User Attributes list.
Advanced Usage: Overriding LDAP Attributes
In some cases, the user for which you are generating the SAML assertion didn't directly access your site, but rather, single signed-on using SAML. The initial SAML assertion used to authenticate to the site could have included some attribute values about the user. If the user then wants to access another site, you might want to use the attributes from the initial SAML assertion for the user rather than attributes read from the directory. The SAML extension server for Novell iChain stores the initial SAML attribute values so they are available for outbound assertion generation. This is done by creating a User Attribute as shown in Figure 60:
Figure 60Overriding LDAP Attributes
In this example, you would override the LDAP mail attribute with the initial SAML attribute named InitialEmailName. The system recognizes that this is a cached SAML attribute because of the SAML: prefix on the LDAP Attribute name. In searching for the cached SAML attribute, the SAML: prefix is removed, so in this example, the initial SAML attribute InitialEmailName is used as the outgoing InternetMail SAML assertion Attribute.
The resulting User Attributes table is shown in Figure 61:
Figure 61User Attributes Table: Overriding the LDAP Mail Attribute
Password Attribute
As mentioned in User Mapping, some applications still require a user password in order to function properly. When performing SAML single sign-on, the destination site receives no user password, so some applications might not function properly. To get around this, the ability to pass the user password as a SAML attribute has been added. This attribute should not be used unless absolutely necessary, because the user password is exposed to the partner site. Furthermore, the password attribute should only be sent when using the browser/Artifact profile, since the browser/Artifact passes the SAML assertion directly between the sites using SSL. The password attribute is specified by placing ICHAIN_PWD as the LDAP Attribute name, as shown in Figure 62:
Figure 62Specifying the Password Attribute
The ICHAIN_PWD can also be used by OLAC at the receiving site to pass the password to the back-end Web server as a query string or header parameter.
In order for a SAML Extension for iChain partner site to use this attribute, the User Mapping page would need to have its User Password Attribute setting equal My Password.
URLs
The URLs page is the most important page in the Trusted Affiliate configuration. This page is where you enter the information that tells the SAML extension server for Novell iChain service where to send or redirect users when a SAML event or error occurs.
Figure 63samlTrustedAffiliate: URLs Tab
The sample data in the above graphic is valid for a Trusted Affiliate site running the SAML Extension server for iChain with host name =www.partner.com.
Artifact Receiver URL: The user is redirected to this URL when a Browser/Artifact authentication is requested between this site and the partner site.
POST Receiver URL: The user is sent to this URL when a Browser/POST authentication is requested between this site and the partner site.
SOAP Responder URL: The SOAP endpoint that this site sends SAML artifact requests to when authenticating users from this partner site using the Browser/Artifact profile. In Figure 63, the mutually authenticated communications channel is being used (notice the /cmd/mutExt URL extension). To use the non-client authentication channel, replace /cmd/mutExt with /cmd/ext.
Assertion Generation URL: If an error occurs during SAML assertion generation, the user is sent to this URL. If there is no value specified, the General error URL or samlSiteConfig Default error URL is used.
User Mapping Error URL: If an error occurs during the SAML user mapping processes, the user is sent to this URL. If there is no value specified, the General error URL or samlSiteConfig Default error URL is used.
General Error URL: If an error occurs during assertion validation for SAML data received from this affiliate, or if other error URLs are not set, the user is sent to this URL. If this value is not set, the samlSiteConfig Default error URL is used.