Federation requires the configuration of a trusted relationship between an identity provider and a service provider. Figure 5-2 illustrates setting up federation between two Identity Servers, because a Novell Identity Server can act as either an identity provider or a service provider.
Figure 5-2 Configuring Trust Between Site A and Site B
Site A must be configured to trust Site B as a service provider, and Site B must be configured to trust Site A as an identity provider. Until this two-way trust is established, federation cannot occur.
Before setting up a trusted relationship, you must make the following decisions:
Protocol: The Identity Server supports SAML 1.1, SAML 2.0, and Liberty. You need to decide which of these protocols to use. If no user interaction is needed, SAML 1.1 is probably a good choice. The SAML 2.0 and Liberty protocols permit user interaction when federating. The user decides whether to federate (link) the accounts and must be logged in at both sites to accomplish this. Liberty offers an additional service, not available with SAML 2.0, that allows the user to select attributes that can be shared with the service provider.
The instructions in this documentation, starting in Section 5.2.1, Prerequisites, use the Liberty protocol. They also indicate how to configure for the SAML 2.0 and SAML 1.1 protocols.
Trust Relationship: You need to decide whether the trusted relationship is going to be from Site A to Site B, from Site B to Site A, or bidirectionally from Site A to Site B and from Site B to Site A. Federation is set up to go from the most secure site to the less secure site. The only time federation is set up to be bidirectional is when both sites are equally secure. The scenario described in Figure 5-1 is an example of a trusted relationship that you would want to go only one way, from Site A to Site B, because Site B is not as secure as Site A.
The instructions, starting in Section 5.2.1, Prerequisites, explain how to set up the trusted relationship between Site A and Site B. You can easily modify them to set up the bidirectional trust relationships by substituting Site B for Site A (and vice versa) in the instructions and then repeating them for Site B
Attributes to Share: You need to decide whether there are user attributes or roles at Site A that you want to share with Site B. The attributes from Site A can be used to identify the users at Site B. Other attributes might be needed to access protected resources, for example, to satisfy the requirements of an Identity Injection policy.
For all the protocols, Section 5.3, Sharing Roles explains how to share the roles at Site A with Site B. For the SAML 1.1 protocol, the instructions starting in Section 5.2.1, Prerequisites use the LDAP mail attribute to share the user’s e-mail address.
User Identification: You need to decide how assertions can be used to map users from Site A to users at Site B. The Identity Server supports four methods:
Temporary: This method allows the user access to Site B solely from the credentials of Site A. No effort is made to map the user to a user account at Site B. A temporary account is set up for the user on Site B, and when the user logs out, the account is destroyed.
Login: This method requires that the user have login credentials at both Site A and Site B, and when logged in at both sites, the user can select to federate the accounts.
Mapped Attributes: This method requires that the sites share attributes and that these attributes are used to create a matching expression that determines whether the user accounts match. For an added security check, the first time the accounts are matched, the user is asked to verify the match by supplying the password for Site B.
If the match fails, you can allow the federation to fail or you can configure the method to allow the user to use the Login method or the Provisioning method.
Provisioning: This method allows the user to create a new, permanent account at Site B.
The configuration instructions, starting in Section 5.2.1, Prerequisites, use the Login method for the SAML 2.0 and Liberty protocols and Mapped Attributes method for the SAML 1.1 protocol.
The instruction for setting up a trusted relationship between two Novell Identity Servers have been divided as follows:
A basic Access Manager configuration with the Identity Server and Access Gateway configured for SSL.
This can be the one you set up using the instructions in either Section 1.0, Setting Up a Basic Access Manager Configuration or Section 6.0, Digital Airlines Example. For SSL configuration, see Section 2.0, Enabling SSL Communication.
The Identity Server from this configuration becomes Site B in Figure 5-2.
A second Identity Server with a basic configuration, an LDAP user store, and SSL. This Identity Server is configured to be Site A in Figure 5-2.
Time synchronization must be set up for all the machines, or authentication can fail if assertions expire before they can be used.
A DNS server must be configured to resolve the DNS names of Site A, Site B, and the Access Gateways.
(Recommended) Logging has been enabled on the Identity Servers of Site A and Site B. See Enabling Component Logging
in the Novell Access Manager 3.1 SP2 Identity Server Guide. Make sure that you enable at least Application and protocol (Liberty, SAML1, or SAML2) logging at an Info level or higher.
To set up this very basic example of federation, complete the following tasks.
To establish trust between Site A and Site B, you must perform two tasks:
The providers must trust the certificates of each other so you need to import the trusted root certificate of Site B to Site A.
You must also import the metadata of Site B to Site A. The metadata allows Site A to verify that Site B is truly Site B when Site B sends a request to Site A.
The following instructions explain how to import the certificate and the metadata:
Log in to the Administration Console for Site A.
The configuration for Site A can be created in the same Administration Console as Site B; it cannot be configured to be a cluster member of Site B.
Import the trusted root certificate of Site B into the NIDP trust store of Site A:
Click
> > > .In the Trusted Roots section, click
, then fill the following fields:Server IP/DNS: Specify the IP address or DNS name of Site B. For Site B in Figure 5-2 specify the following:
idp.siteb.novell.com
Server Port: Specify 8443.
Click
, then specify an alias for the certificate (for example, SiteB).Examine the trusted root that is selected for you.
If the trusted root is part of a chain, make sure you select the parent and all intermediate trusted roots.
Click
.The trusted root certificate of Site B is added to the NIDP trust store.
Click
.Click
> then update the Identity Server.Wait for the health status to return to green.
Configure a service provider for Site B:
Click
> > [or or ].Click
, select , then fill the following fields:Name: Specify a name for the provider. If you plan on configuring more than one protocol, include the protocol as part of the name, such as, SiteB_Liberty
Metadata URL: Specify the URL of the Liberty metadata on Site B. For Site B in Figure 5-2, specify the following:
http://idp.siteb.novell.com:8080/nidp/idff/metadata
This example uses port 8080 to avoid any potential certificate problems that occur when the Identity Server and the Administration Console are installed on separate machines.
SAML 2.0: If you are using SAML 2.0, the metadata path is /nidp/saml2/metadata. For Site B in Figure 5-2, specify the following for SAML 2.0:
http://idp.siteb.novell.com:8080/nidp/saml2/metadata
SAML 1.1: If you are using SAML 1.1, the metadata path is /nidp/saml/metadata. For Site B in Figure 5-2, specify the following for SAML 1.1:
http://idp.siteb.novell.com:8080/nidp/saml/metadata
Click
> .Update the Identity Server.
Wait for the health status to return to green.
Continue with Configuring Site B to Trust Site A as an Identity Provider.
The following instructions explain how to import the trusted root certificate and metadata of Site A into the configuration for Site B.
Log in to the Administration Console for Site B.
The configuration of Site B can be created in the same Administration Console as Site A; it cannot be configured to be a cluster member of Site A.
Import the trusted root certificate of Site A into the NIDP trust store of Site B.
Click
> > > .In the Trusted Roots section, click
, then fill the following fields:Server IP/DNS: Specify the IP address or DNS name of Site A. For Site A in Figure 5-2, specify the following:
idp.sitea.novell.com
Server Port: Specify 8443.
Click
, then specify an alias for the certificate (for example, Site A).Examine the trusted root that is selected for you.
If the trusted root is part of a chain, make sure you select the parent and all intermediate trusted roots.
Click
.The trusted root certificate of Site A is added to the NIDP trust store.
Click
.Click
> > .Wait for the health status to return to green.
Configure an identity provider for Site B.
Click
> > [or or ].Click
, select , then fill the following fields:Name: Specify a name for the provider. If you plan on configuring more than one protocol, include the protocol as part of the name, such as SiteA_Liberty
Metadata URL: Specify the URL of the Liberty metadata on Site A. For Site A in Figure 5-2, specify the following:
http://idp.sitea.novell.com:8080/nidp/idff/metadata
This example uses port 8080 to avoid any potential certificate problems that occur when the Identity Server and the Administration Console are installed on separate machines.
SAML 2.0: If you are using SAML 2.0, the metadata path is /nidp/saml2/metadata. For Site A in Figure 5-2, specify the following for SAML 2.0:
http://idp.sitea.novell.com:8080/nidp/saml2/metadata
SAML 1.1: If you are using SAML 1.1, the metadata path is /nidp/saml/metadata. For Site B in Figure 5-2, specify the following for SAML 1.1:
http://idp.siteb.novell.com:8080/nidp/saml/metadata
Click
.To configure an authentication card, fill in the following:
ID: (Optional) Specify an alphanumeric number that identifies the card. If you need to reference this card outside of the Administration Console, you need to specify a value here. If you do not assign a value, the Identity Server creates one for its internal use.
Text: Specify the text that is displayed on the card to the user
Image: Specify the image to be displayed on the card. Select the image from the drop down list. To add an image to the list, click
.Login URL: (Conditional) If you are configuring an authentication card for SAML 1.1, specify an Intersite Transfer Service URL. For Figure 5-1, specify the following value:
https://idp.sitea.novell.com:8443/nidp/saml/idpsend?PID=https://idp.siteb.novell.com:8443/nidp/saml/metadata&TARGET=https://idp.siteb.novell.com:8443/nidp/app
For more information, see Specifying the Intersite Transfer Service URL for the Login URL Option
in the Novell Access Manager 3.1 SP2 Identity Server Guide.
Show Card: Determine whether the card is shown to the user. If this option is not selected, the card is only used when a service provider makes a request for the card. For this scenario, select this option.
Passive Authentication Only: Do not select this option.
Click
.Update the Identity Server.
Wait for the health status to return to green.
Continue with one of the following:
If you are using Liberty or SAML 2.0, continue with Verifying the Trust Relationship.
If you are using SAML 1.1, continue with Configuring SAML 1.1 for Account Federation.
Before continuing with federation configuration, you need to verify that Site A and Site B trust each other.
To test the trusted relationship, log in to the user portal of Site B. For Site B in Figure 5-2, specify the following:
https://idp.siteb.novell.com:8443/nidp/app
The following login screen appears.
In this configuration, the customizable image was used for the Liberty authentication card.
Click the Liberty (or SAML 2.0) authentication card.
You are directed to Site A for login, with the default card selected for you. A screen similar to the following appears:
Enter the credentials for a user from Site A.
The Federation consent prompt appears.
Click
.You are returned to the login page for Site B.
Enter the credentials of a user from Site B that you want to federate with the user from Site A.
These two accounts are now federated. You can enter the URL to the user portal on Site A or Site B, and you are granted access without logging in again.
If you log out and log back in, the accounts are still federated, but you might be prompted for login credentials as you access resources on Site A and Site B. To enable a single sign-on experience, the Identity Server at Site A, the Identity Server at Site B, and the protected resources of the Access Gateways must be configured to share a contract.
To enable a single sign-on experience, continue with Configuring User Authentication.
The following instructions describe one way to enable single sign-on to the Identity Servers and Access Gateways in Figure 5-1. It explains how to configure all sites to use the same contract. The instructions explain the following tasks:
Selecting the contract for federation
Configuring the contract at Site B to allow authentication at Site A
Configuring Site A so its contract can satisfy the requirements of the contract at Site B
Configuring Site A and Site B to use this contract as their default contract
To configure the contracts:
Log in to the Administration Console for Site B.
Configure the authentication request:
Click
> > > [or ] > > > .(Liberty) Verify the settings of the following fields:
Allow federation: Make sure this option is selected. If this option is not selected, users cannot federate their accounts at Site A with an account at Site B.
After authentication: Make sure this option is selected. Enabling this option assumes that a user account exists at the service provider and that the account can be associated with a user’s account at the identity provider.
During authentication: Make sure this option is selected. Enabling this option allows federation to occur when the user selects the authentication card of the identity provider.
(SAML 2.0) Verify the settings of the following fields:
Persistent: Select this option to set up a persistent relationship between the two accounts.
After authentication: Make sure this option is selected. Enabling this option assumes that a user account exists at the service provider and that the account can be associated with a user’s account at the identity provider after authentication.
During authentication: Make sure this option is selected. Enabling this option allows federation to occur when the user selects the authentication card of the identity provider.
For
, select .(SAML 2.0) For Context Comparison, accept the default value of
.In the
section, select the name of the contract used by the protected resources and move it to the section.If the contract you require is not in the list, it has not been configured for federation. See Step 3.
Click
, then update the Identity Server configuration.(Conditional) Configure the contract at Site B to allow federation:
Click
> > > .Record the URI for the contract you are using. This URI needs to exist as a contract on Site A. The name of the contract can be different at each site, but the URI must be the same.
Click the name of the contract.
Make sure the
option is selected.Click
twice, then update the Identity Server if you made any changes.Return to Step 2 to select the contract.
Verify that Site A contains the same contract:.
Log in to the Administration Console for Site A.
Click
> > > .Match the URI from Step 3.b to a contract.
If such a contract does not exist, you need to create it. For help, see Configuring Authentication Contracts
in the Novell Access Manager 3.1 SP2 Identity Server Guide.
Click
.In the Administration Console for Site A, click
> > > .For the Authentication Contract, select the name of the contract from Step 4.c.
(Conditional) If you have multiple user stores, set the default contract for each user store.
Click
, then update the Identity Server.Test the configuration:
Enter the URL to the user portal of Site B.
Click the federated login link to Site A.
Enter the credentials for Site A and log in.
Enter the URL for a protected resource at Site B.
You are granted access without being prompted for credentials.
If you want to allow federated users to log in at Site A rather than using the card at Site B to redirect them to Site A, complete the following tasks:
In the Administration Console for Site B, click
> > > > .For the Authentication Contract, select the name of the contract whose URI matches the URI of the contract used by Site A.
Click
[or > > > .In the
section, enable the option.This enables single sign-on to Site B when the user has already federated the accounts at the two sites.
Click
, then update the Identity Server.To test single sign-on, log in to the user portal on Site A, then enter a URL for a protected resource at Site B.
SAML 1.1 does not support user-controlled federation, but you can configure it so that accounts that match are automatically federated. The Liberty and SAML 2.0 protocols allow users to federate accounts without sharing any common attributes, but the SAML 1.1 protocol requires that the user accounts need to share some common attributes in order for SAML 1.1 to match them and allow federation.
When federating with SAML 1.1, the security of a user matching method depends upon the accuracy of the mapping. You need to select an attribute or attributes that uniquely identify the user at both Site A and Site B. The attributes must identify only one user at Site A and match only one user at Site B. If the attributes match multiple users, you have a security problem,
The following steps use the e-mail address of the user and the LDAP mail attribute to set up a matching rule that matches one user account at Site A with one user account at Site B. To securely use such a matching rule, you need to have a rule in place at both Site A and Site B to ensure that all users have unique e-mail addresses.
In the Administration Console of Site B, click
> > > > > > .For the
option, select the contract that you want to use for single sign-on.For this example, select
.Select
.The
option is automatically selected. Leave this option enabled.Click the
icon.Move the user store that you want to search for the attribute to the
list.For the
, select .Specify a name for the matching expression, such as email.
In
, click the icon, select , then click .The form allows you to create a very complex set of matching rules, with multiple conditions. This example uses one attribute, the simplest form of a matching expression.
Click
, then select your matching expression for the .Click
.Click
twice, then update the Identity Server.Continue with Configuring the Attribute for Sharing.
In the Administration Console of the Site B (the service provider), click
> > .Click
, then click .Specify a
, such as email, then click .Click
, then fill the options:Local attribute: Select
.Remote attribute: Specify a name, such as email. Make sure you use the same remote name in the mapping for both Site B and Site A.
Leave the other options set to their default values.
Click
, then click .Your newly created attribute mapping appears in the list of Attribute Sets.
Repeat Step 1 through Step 5 for Site A (the identity provider).
If Site A and Site B are imported into the same Administration Console, skip this step.
Continue with Configuring the Providers to Use the Shared Attribute.
You need to configure Site A to send the shared attribute with the authentication credentials, and you need to configure Site B to process the shared attribute that is included with the authentication credentials.
In the Administration Console for Site B, click
> > > > > .Move the email attribute so that it is obtained at authentication.
Click
twice, then update the Identity Server.In the Administration Console for Site A, click
> > > > > .Move the email attribute so that it is sent with authentication.
Click
twice, then update the Identity Server.Continue with Configuring the Default Contract for Single Sign-On
The Identity Servers at Site A and Site B need to use the contract you specified in your user matching expression to be the default contract for Site A, Site B, and the protected resources of the Access Gateway.
For the user matching expression contract, see Step 2 in Configuring Site B for User Account Matching.
To configure the default contracts for Site A and Site B:
In the Administration Console for Site B, click
> > > > .For the Authentication Contract, select the name of the contract used by the user matching expression.
Click
, then update the Identity Server.For the Access Gateway, review the contracts you have assigned to the protected resources:
In the Administration Console for Site B, click
> > > > > .For single sign-on, change the contract to match the contract for the user matching expression.
(Conditional) If you have multiple reverse proxies and proxy services, verify the contracts on all protected services that you want enabled for single sign-on.
Click
to save your changes, then update the Access Gateway.Continue with Verifying the Trust Relationship with SAML 1.1.
To test the trusted relationship, enter the URL for the user portal of Site B. For Site B in Figure 5-2, you would specify the following:
https://idp.siteb.novell.com:8443/nidp/app
The following login screen appears:
Use the scroll bar to see all available cards.
Click the card you have configured for SAML 1.1 authentication.
You are directed to Site A for login.
Enter the credentials for Site A.
Enter the password for the user at Site B.
You are directed to the target page specified in the Login URL of the authentication card.
If you disabled the
option on the User Identification page, the accounts are mapped without any user interaction.(Conditional) If you receive an error, try one of the following:
If you are not redirected to the target URL on Site B, verify the value you enter for the Login URL option. See Step 3.d.
If you receive an authentication error at Site B, verify the user matching setup. See Configuring User Account Matching.
If you have enabled logging, open the logging file (catalina.out or stdout.log) and search for the error string. There should be additional information on the cause of the error in the error string entry as well as log entries before the error sting.
(Optional) If your protected resources on Site A and Site B use the same contract, enter the URLs of these resources.
You are granted access without entering any additional credentials.