5.2 Configuring Federation

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

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 NetIQ Identity Servers have been divided as follows:

5.2.1 Prerequisites

5.2.2 Establishing Trust between Providers

To set up this very basic example of federation, complete the following tasks.

Configuring Site A to Trust Site B as a Service Provider

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:

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

  2. Import the trusted root certificate of Site B into the NIDP trust store of Site A:

    1. Click Devices > Identity Servers > Edit > Security > NIDP Trust Store.

    2. In the Trusted Roots section, click Auto-Import From Server, 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.

    3. Click OK, then specify an alias for the certificate (for example, SiteB).

      You will get two certificate options: Root CA Certificate andServer certificate. We recommend you to select Root CA Certificate.

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

    5. Click OK.

      The trusted root certificate of Site B is added to the NIDP trust store.

    6. Click Close.

    7. Click Devices > Identity Servers, then update the Identity Server.

      Wait for the health status to return to green.

  3. Configure a service provider for Site A:

    1. Click Identity Servers > Edit > Liberty [or SAML 2.0 or SAML 1.1].

    2. Click New, select Service Provider, 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
      
    3. Click Next > Finish > OK.

    4. Update the Identity Server.

      Wait for the health status to return to green.

  4. Continue with Configuring Site B to Trust Site A as an Identity Provider.

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.

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

  2. Import the trusted root certificate of Site A into the NIDP trust store of Site B.

    1. Click Devices > Identity Servers > Edit > Security > NIDP Trust Store.

    2. In the Trusted Roots section, click Auto-Import From Server, 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.

    3. Click OK, then specify an alias for the certificate (for example, SiteA).

      You will get two certificate options: Root CA Certificate andServer certificate. We recommend you to select Root CA Certificate.

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

    5. Click OK.

      The trusted root certificate of Site A is added to the NIDP trust store.

    6. Click Close.

    7. Click Identity Servers > Update > OK.

      Wait for the health status to return to green.

  3. Configure an identity provider for Site B.

    1. Click Identity Servers > Edit > Liberty [or SAML 2.0 or SAML 1.1].

    2. Click New, select Identity Provider, 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
      
    3. Click Next.

    4. 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 Select local image.

      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 NetIQ Access Manager 3.2 SP3 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.

    5. Click Finish > OK.

    6. Update the Identity Server.

      Wait for the health status to return to green.

  4. Continue with one of the following:

Verifying the Trust Relationship

Before continuing with federation configuration, you need to verify that Site A and Site B trust each other.

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

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

  3. Enter the credentials for a user from Site A.

    The Federation consent prompt appears.

  4. Click Yes.

    You are returned to the login page for Site B.

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

  6. To enable a single sign-on experience, continue with Configuring User Authentication.

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:

  1. Log in to the Administration Console for Site B.

  2. Configure the authentication request:

    1. Click Devices > Identity Servers > Edit > Liberty [or SAML 2.0] > [Name of Identity Provider] > Authentication Card > Authentication Request.

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

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

    4. For Requested By, select Use Contracts.

    5. (SAML 2.0) For Context Comparison, accept the default value of Exact.

    6. In the Authentication contracts section, select the name of the contract used by the protected resources and move it to the Contracts section.

      If the contract you require is not in the list, it has not been configured for federation. See Step 3.

    7. Click OK, then update the Identity Server configuration.

  3. (Conditional) Configure the contract at Site B to allow federation:

    1. Click Identity Servers > Edit > Local > Contracts.

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

      NOTE:If site A only understands authentication class or type, select Use Types in the Requested By field and specify the authentication class in the Allowable Class field. Record the allowable class for the contract you are using. This allowable class should exist as a contract on site B. The name of the contract can be different at each site, but the allowable class must be the same.

    3. Click the name of the contract.

    4. Make sure the Satisfiable by External Provider option is selected.

    5. Click OK twice, then update the Identity Server if you made any changes.

    6. Return to Step 2 to select the contract.

  4. If Site A is configured as a SAML 2.0 identity provider, move the contract(s) from the Available contracts list to the Satisfies contract list.

    This will automatically redirect the authentication request from Site B to Site A when this contract is executed. Note that you can have multiple contracts in the Satisfies contract list.

  5. Verify that Site A contains the same contract:.

    1. Log in to the Administration Console for Site A.

    2. Click Identity Servers > Edit > Local > Contracts.

    3. Match the URI from Step 3.b to a contract.

      NOTE:Match the allowable class if you have selected Use Types in the Requested By field at site B.

      If such a contract does not exist, you need to create it. For help, see Configuring Authentication Contracts in the NetIQ Access Manager 3.2 SP3 Identity Server Guide.

    4. Click OK.

  6. In the Administration Console for Site A, click Identity Servers > Edit > Local > Defaults.

  7. For the Authentication Contract, select the name of the contract from Step 5.c.

  8. (Conditional) If you have multiple user stores, set the default contract for each user store.

  9. Click OK, then update the Identity Server.

  10. Test the configuration:

    1. Enter the URL to the user portal of Site B.

    2. Click the federated login link to Site A.

    3. Enter the credentials for Site A and log in.

    4. Enter the URL for a protected resource at Site B.

      You are granted access without being prompted for credentials.

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

    1. In the Administration Console for Site B, click Devices > Identity Servers > Edit > Local > Defaults.

    2. For the Authentication Contract, select the name of the contract whose URI matches the URI of the contract used by Site A.

    3. Click Liberty [or SAML 2.0] > [Name of Identity Provider] > Authentication Card > Authentication Request.

    4. In the Options section, enable the Use automatic introduction option.

      This enables single sign-on to Site B when the user has already federated the accounts at the two sites.

    5. Click OK, then update the Identity Server.

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

5.2.3 Configuring SAML 1.1 for Account Federation

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.

Configuring User Account Matching

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.

Configuring Site B for User Account Matching
  1. In the Administration Console of Site B, click Devices > Identity Servers > Servers > Edit > SAML 1.1 > [Identity Provider] > User Identification.

  2. For the Satisfies contract option, select the contract that you want to use for single sign-on.

    For this example, select Secure Name/Password-Form.

  3. Select Attribute matching.

    The Prompt for password on successful match option is automatically selected. Leave this option enabled.

  4. Click the Define Attribute Matching Settings icon.

  5. Move the user store that you want to search for the attribute to the User stores list.

  6. For the User Matching Expression, select New User Matching Expression.

  7. Specify a name for the matching expression, such as email.

  8. In Logic Group 1, click the Add Attributes icon, select Ldap Attribute:mail [LDAP Attribute Profile], then click OK.

    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.

  9. Click Finish, then select your matching expression for the User Matching Expression.

  10. Click OK.

  11. Click OK twice, then update the Identity Server.

  12. Continue with Configuring the Attribute for Sharing.

Configuring the Attribute for Sharing
  1. In the Administration Console of the Site B (the service provider), click Devices > Identity Servers > Shared Settings.

  2. Click Attribute Sets, then click New.

  3. Specify a Set Name, such as email, then click Next.

  4. Click New, then fill the Add Attribute Mapping options:

    Local attribute: Select Ldap Attribute:mail [LDAP Attribute Profile].

    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.

  5. Click OK, then click Finish.

    Your newly created attribute mapping appears in the list of Attribute Sets.

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

  7. Continue with Configuring the Providers to Use the Shared Attribute.

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.

  1. In the Administration Console for Site B, click Devices > Identity Servers > Edit > SAML 1.1 > [Name of Identity Provider] > Attributes.

  2. For the Attribute set, select the set name you created in Configuring the Attribute for Sharing.

  3. Move the email attribute so that it is obtained at authentication.

  4. Click OK twice, then update the Identity Server.

  5. In the Administration Console for Site A, click Devices > Identity Servers > Edit > SAML 1.1 > [Name of Service Provider] > Attributes.

  6. For the Attribute set, select the set name you created in Configuring the Attribute for Sharing.

  7. Move the email attribute so that it is sent with authentication.

  8. Click OK twice, then update the Identity Server.

  9. Continue with Configuring the Default Contract for Single Sign-On

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:

  1. In the Administration Console for Site B, click Devices > Identity Servers > Edit > Local > Defaults.

  2. For the Authentication Contract, select the name of the contract used by the user matching expression.

  3. Click OK, then update the Identity Server.

  4. For Site A, repeat Step 1 through Step 3.

  5. For the Access Gateway, review the contracts you have assigned to the protected resources:

    1. In the Administration Console for Site B, click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > Protected Resources.

    2. For single sign-on, change the contract to match the contract for the user matching expression.

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

    4. Click OK to save your changes, then update the Access Gateway.

  6. Continue with Verifying the Trust Relationship with SAML 1.1.

Verifying the Trust Relationship with SAML 1.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.

  2. Click the card you have configured for SAML 1.1 authentication.

    You are directed to Site A for login.

  3. Enter the credentials for Site A.

  4. 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 Prompt for password on successful match option on the User Identification page, the accounts are mapped without any user interaction.

  5. (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 about the cause of the error in the error string entry as well as log entries before the error sting.

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