4.2.1 Configuring Federation

This section describes what is federation, how to configure federation, and how to set up federation with third-party providers. Topics include:

Understanding a Simple Federation Scenario

Suppose Company A has a centralized user store that is used while authenticating to company’s most of the internal resources on its internal website.

In addition, Company A has a customer feedback application that employees and customers need to access. For this application, a second user store has been created. This user store contains accounts for both employees and customers. For this application, the centralized user store cannot be used because it contains only employees’ accounts.

In this situation, the employee must log in to both accounts to access the inner website and the customer feedback application. With federation, employees can access the resources of both sites by using a single login.

Figure 4-5 illustrates such a network configuration where the user accounts of Site A are configured to federate with the user accounts at Site B.

Figure 4-5 Using Federated Identities

In this configuration, Site A is identity provider for the corporate resources, and the employees authenticate to this site and have access to the resources on the web server with the URL of https://nam.example.com/inner.

Site B is identity provider for the Bugzilla application. Both employees and customers authenticate to this site to access to the resources of the web server with the URL of https://nam.example.com/bugz. After an account has been federated, the user can log in to Site A and access to the resources on the web servers of both Site A and Site B.

In this scenario, Site B is not as secure a site as Site A, so federation is configured to go only one way, from Site A to Site B. This means that users who log in to Site A have access to the resources at Site A and B, but users who log in to Site B have access only to the resources at Site B. Federation can be configured to go both ways, so that it does not matter whether the user logs into Site A or Site B. When federation is configured to be bidirectional, both sites need to be equally secure.

Access Gateways in Figure 4-5 are service providers and are configured to use Identity Servers as identity providers. The trusted relationship is automatically set up for you when you specify authentication settings for Access Gateway and select an Identity Server Cluster.

You can set up federation between providers in the same company or between providers of separate companies. For example, most companies have contracts with other companies for their user’s health benefits and retirement accounts. Their users have accounts with these companies. These accounts can be federated with the user’s employee account when both companies agree to set up the trusted relationship.

Configuring Federation

Federation requires the configuration of a trusted relationship between an identity provider and a service provider. Figure 4-6 illustrates setting up federation between two identity servers, because an Access Manager Identity Server can act as either an identity provider or a service provider.

Figure 4-6 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: 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 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 4-5 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 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, Sharing Roles explains how to share the roles at Site A with Site B. For the SAML 1.1 protocol, the instructions starting in 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. 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 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 Access Manager Identity Servers have been divided as follows:

Prerequisites

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.

Perform the following steps to import the certificate and the metadata:

  1. Log in to 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.

    3. Specify the following details:

      Field

      Description

      Server IP/DNS

      Specify the IP address or DNS name of Site B. For Site B in Figure 4-6, specify the following value:

      idp.siteb.example.com

      Server Port

      Specify 8443.

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

      You will get two certificate options: Root CA Certificate and Server certificate. Select Root CA Certificate.

    5. Examine the trusted root that is selected for you.

      If the trusted root is part of a chain, ensure that you select the parent and all intermediate trusted roots.

    6. Click OK.

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

    7. Click Close.

    8. Click Devices > Identity Servers, then update 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.

    3. Specify the following details:

      Fields

      Description

      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 4-6, specify the following:

      http://idp.siteb.example.com:8080/nidp/idff/metadata

      This example uses port 8080 to avoid any potential certificate problems that occur when Identity Server and 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 4-6, specify the following value:

      http://idp.siteb.example.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 4-6, specify the following value:

      http://idp.siteb.example.com:8080/nidp/saml/metadata

    4. Click Next > Finish > OK.

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

    3. Specify the following details:

      Field

      Description

      Server IP/DNS

      Specify the IP address or DNS name of Site B. For Site B in Figure 4-6, specify the following value:

      idp.sitea.example.com

      Server Port

      Specify 8443.

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

      You will get two certificate options: Root CA Certificate and Server certificate. Select Root CA Certificate.

    5. Examine the trusted root that is selected for you.

      If the trusted root is part of a chain, ensure that you select the parent and all intermediate trusted roots.

    6. Click OK.

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

    7. Click Close.

    8. 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 and select Identity Provider.

    3. Specify the following details:

      Field

      Description

      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 4-6, specify the following:

      http://idp.sitea.example.com:8080/nidp/idff/metadata

      This example uses port 8080 to avoid any potential certificate problems that occur when Identity Server and 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 4-6, specify the following for SAML 2.0:

      http://idp.sitea.example.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 4-6, specify the following for SAML 1.1:

      http://idp.siteb.example.com:8080/nidp/saml/metadata

    4. Click Next.

    5. To configure an authentication card, specify the following details:

      Field

      Description

      ID

      (Optional) Specify an alphanumeric number that identifies the card. If you need to reference this card outside of Administration Console, you need to specify a value here. If you do not assign a value, 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 4-5, specify the following value:

      https://idp.sitea.example.com:8443/nidp/saml/idpsend?PID=https://idp.siteb.example.com:8443/nidp/saml/metadata&TARGET=https://idp.siteb.example.com:8443/nidp/app

      For more information, see Specifying the Intersite Transfer Service URL for the Login URL Option.

      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.

    6. Click Finish > OK.

    7. Update 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 4-6, specify the following:

    https://idp.siteb.example.com:8443/nidp/app

    In this configuration, the customizable image was used for the Liberty authentication card.

  2. Click the menu, then click Liberty (or SAML 2.0) authentication card.

    You are directed to Site A for login, with the default card selected for you.

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

    The Federation consent prompt appears.

    NOTE:To disable this prompt, add the following parameter in the web.xml file under the ldapLoadThreshold context parameter:

    <context-param><param-name>federationConsent</param-name><param-value>true</param-value></context-param>

    Linux: /opt/novell/nids/lib/webapp/WEB-INF/web.xml

    Windows: \Program Files\Novell\Tomcat\webapps\nidp\WEBINF\web.xml

    After updating web.xml, restart Identity Server.

  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, Identity Server at Site A, Identity Server at Site B, and the protected resources of 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 Identity Servers and Access Gateways in Figure 4-5. 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, perform the following steps:

  1. Log in to 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: Ensure that 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: Ensure that 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: Ensure that 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: Ensure that 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: Ensure that 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 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 must 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. Ensure that the Satisfiable by External Provider option is selected.

    5. Click OK twice, then update 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 Administration Console for Site A.

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

    3. Match the URI from step 3b 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 Section 4.1.4, Configuring Authentication Contracts.

    4. Click OK.

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

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

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

  9. Click OK, then update 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 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 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.

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 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 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 Identity Server.

  12. Continue with Configuring the Attribute for Sharing.

Configuring the Attribute for Sharing

  1. In 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. Ensure that 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 step1 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 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 Identity Server.

  5. In 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 Identity Server.

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

Configuring the Default Contract for Single Sign-On

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 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 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 Identity Server.

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

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

    1. In 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 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 4-6, you would specify the following:

    https://idp.siteb.example.com:8443/nidp/app

    Use the scroll bar to see all available cards.

  2. Click the menu then click 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.e.

    • 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 must 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.

Sharing Roles

When two Identity Servers are configured to trust each other, one as an identity provider and the other as a service provider, they can be configured so that roles are shared. The following instructions are written for when both the identity provider and the service provider are Access Manager Identity Servers. If you are using a third-party identity or service providers, you need to modify the instructions.

Figure 4-7 illustrates a configuration where Identity Server of Site A is acting as an identity provider for Site B. When you configure Identity Servers correctly, Access Gateway can use the roles defined for the users of Site A in its policies.

Figure 4-7 Two Federated Identity Servers

The key to sharing roles is to set up the configuration so that the SAML assertion that the identity provider (Site A) sends to the service provider (Site B) contains the roles that the user has been assigned. Site B evaluates the roles and assigns them to the federated users at Site B. Access Gateway can use these roles in its policy evaluations, and grant or deny access based on the assigned roles.

For example, when user tsmith authenticates to Site A, tsmith is assigned the role of doc. Tom, a user at Site B, is federated with the tsmith user. The doc role is shared with Site B, and Site B contains a policy that assigns users with the shared doc role to the tester role. Access Gateway is configured with an Authorization policy that grants access to a resource when the requester is assigned the tester role. However, Tom does not have the qualifications at Site B to be assigned the tester role.

In this scenario, when Tom requests access to the protected resource at Site B, a login page with a federated link to Site A is displayed. If Tom selects to log in to Site A, Site A assigns him to the doc role. The doc role is sent with tsmith’s authentication credentials to Site B. Site B evaluates the credentials and assigns Tom to the tester role because the following conditions are met:

  • Tom is federated with tsmith.

  • tsmith was assigned the doc role.

  • The shared role and tester policies on Site B qualify the user to be assigned the tester role.

When Access Gateway evaluates the credentials of Tom, Tom is granted access to the protected resource because he now has the tester role.

This section describes how to set up such a configuration. It assumes that the following have already been done:

This section explains how to configure Site A and Site B so that Site A shares its roles with Site B.

Configuring Role Sharing

Configuring role sharing includes the following three major tasks:

Defining a Shared Attribute Set

Configure a shared attribute for transferring the roles.

  1. In Administration Console of the Site A (the identity provider), click Devices > Identity Servers > Shared Settings.

  2. Click Attribute Sets, then New.

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

  4. Click New and fill the Add Attribute Mapping options:

    Local attribute: Select All Roles.

    Remote attribute: Specify a name, such as roles. Ensure that you use the same remote name in the mapping for both the identity provider and the service provider.

    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 on Site B (the service provider).

  7. Continue with Obtaining the Role Assignments.

Obtaining the Role Assignments

Configure the identity provider and the service provider so that the role assignments can be added to the attribute and retrieved from the attribute.

  1. To export the roles from the identity provider, log in to Administration Console for the identity provider. (In Figure 4-7, this is Site A.)

    1. Click Devices > Identity Servers > Edit > Liberty > [Name of Service Provider] > Attributes.

      If you are using SAML 2.0 or SAML 1.1 protocol, the steps are the same. You just need to click the appropriate tab after clicking Edit. The path is the same for these protocols.

    2. Select the attribute set you created, then move All Roles so this attribute is sent with authentication.

    3. Click OK.

    4. Update Identity Server of Site A.

  2. To import the roles from the identity provider to the service provider, log in to Administration Console for the service provider. (In Figure Figure 4-7, this is Site B.)

    1. Click Devices > Identity Servers > Edit > Liberty > [Name of Identity Provider]> Attributes.

    2. Select the attribute set you created, then move All Roles so this attribute is obtained with authentication.

    3. Click OK.

    4. Update Identity Server of Site B.

    5. Continue with Configuring Policies to Process Received Roles.

Configuring Policies to Process Received Roles

Create a shared Role policy for each role sent to the service provider. This policy defines how the role must be processed.

For each role that is sent from Site A, you need to create a Role policy that specifies the role that must be activated on Site B. For example, suppose the tsmith user from Site A is assigned the doc role at authentication. You can create a Role policy on Site B that assigns the tester role to anyone with the doc role from Site A.

  1. Log in to Administration Console for Site B.

  2. Click Policies > Policies > New.

  3. Specify a name for the policy, select Identity Server: Roles for the type, then click OK.

  4. In the Condition Group 1 section, click New, then select Roles from Identity Provider.

  5. (Conditional) If you have federated with more than one identity provider, select the provider. If you have federated with only one identity provider, the provider is selected for you.

    In this example, you have federated with only the identity provider at Site A, and it is selected for you.

  6. For the value, select Data Entry Field, then specify the name of a role that is assigned by Site A, for example doc.

    If you leave Mode set to Case Sensitive, ensure that you specify the case correctly.

  7. In the Actions section, specify the role to activate on Site B for the role received from Site A.

    Your policy must look similar to the following:

  8. Click OK > OK, then click Apply Changes.

  9. To enable the role for Identity Server, click Identity Servers > Edit > Roles.

  10. Select the role, then click Enable.

  11. (Optional) Repeat Step 2 through Step 10 for other roles assigned at Site A.

    If you have other Role policies at Site A, you need to set up Role policies at Site B to have the roles activated. For example, if Site A had a Tester Role policy and you wanted users assigned to the Tester Role policy to also be assigned to the Tester Role policy at Site B, you could create a separate policy for this activation, or you could add an Or condition group with a value field of tester to the policy in Step 7. The policy would assign federated users who belonged to the doc or tester roles at Site A, to the tester role at Site B.

  12. To test role sharing:

    1. Enter the URL of a protected resource that requires a role for access. For the policy above, it would be a resource requiring the tester role.

    2. Click the federated link to Site A.

    3. Log in with the credentials of a user who is assigned the doc role.

      You are granted access to the resource. If you are denied access, continue with Verifying the Configuration to discover the problem.

Verifying the Configuration

This section traces the role assignment from Identity Server that assigns it to the user, through Identity Server that receives the roles with the user’s authentication assertion, to the policy evaluation. If you are having trouble, this must help you determine the source of the problem.

The following procedures refer to the configuration displayed in Figure 4-7, Two Federated Identity Servers. A tsmith user from Site A, who is assigned the doc role, is federated with a Tom user at Site B. Site B does not assign Tom the tester role. The web server has been configured to protect the bugz site, which requires the tester role.

To verify the configuration:

  1. Ensure that policy logging is enabled on the identity provider and the service provider. Ensure that you enable at least Application logging at an Info level.

    For configuration procedures, see Section 23.3.1, Configuring Logging for Identity Server.

    You can access log files for downloading and viewing by clicking Auditing > General Logging.

  2. Have a user access a resource that is protected by a policy requiring a role from Site A.

    For this trace, the tsmith user from Site A requests access to the bugz page. The user uses the federated link and logs in with the credentials of the tsmith user.

  3. Verify that Site A is assigning the user the role.

    1. View the catalina.out file (Linux) or the stdout.log file (Windows) of Identity Server at Site A.

    2. Search for the name of the role. You must find a line similar to the following:

      <amLogEntry> 2009-08-22T20:30:19Z INFO NIDS Application: AM#500105013: AMDEVICEID#C5F467BA50B009AC: AMAUTHID#YfdEmqCT2ZutwybD1eYSpfph8g5a5aMl6MGryq1hIqc=: Authenticated user cn=tsmith,o=novell in User Store sitea-nids-user-store with roles doc,authenticated. </amLogEntry>

      If the role you need is not listed, look at the policy evaluation trace to discover why the user has not been assigned the role. For more information about how to understand role traces, see Role Assignment Traces.

  4. Verify that Site A is sending an authentication assertion to Site B.

    In the catalina.out file (Linux) or the stdout.log file (Windows) of Identity Server from Site A, look for lines similar to the following:

    <amLogEntry> 2009-08-22T20:30:19Z INFO NIDS Application: AM#500105018: AMDEVICEID#C5F467BA50B009AC: AMAUTHID#YfdEmqCT2ZutwybD1eYSpfph8g5a5aMl6MGryq1hIqc=: Responding to AuthnRequest with artifact AAPLsCVpfv3ha9Mpn+cUiCXcf3D63sc0QfscL5mZaaygHBKVOOh9aPSQ </amLogEntry>

<amLogEntry> 2009-08-22T20:30:19Z INFO NIDS Application: AM#500105019: AMDEVICEID#C5F467BA50B009AC: AMAUTHID#YfdEmqCT2ZutwybD1eYSpfph8g5a5aMl6MGryq1hIqc=: Sending AuthnResponse in response to artifact AAPLsCVpfv3ha9Mpn+cUiCXcf3D63sc0QfscL5mZaaygHBKVOOh9aPSQ </amLogEntry>

    If you do not see these types of entries, verify that you have configured Site A to send the roles. See Obtaining the Role Assignments.

  5. Verify that Site B is receiving the SAML assertion with the roles.

    In the catalina.out file (Linux) or the stdout.log file (Windows) of Identity Server from Site B, look for lines similar to the following:

    <amLogEntry> 2009-08-22T20:30:19Z INFO NIDS Application: AM#500105020: AMDEVICEID#488475009C6D3DDF: AMAUTHID#YfdEmqCT2ZutwybD1eYSpfph8g5a5aMl6MGryq1hIqc=: Received and processing artifact from IDP - AAPLsCVpfv3ha9Mpn+cUiCXcf3D63sc0QfscL5mZaaygHBKVOOh9aPSQ </amLogEntry>

<amLogEntry> 2009-08-22T20:30:19Z INFO NIDS Application: AM#500105021: AMDEVICEID#488475009C6D3DDF: AMAUTHID#YfdEmqCT2ZutwybD1eYSpfph8g5a5aMl6MGryq1hIqc=: Sending artifact AAPLsCVpfv3ha9Mpn+cUiCXcf3D63sc0QfscL5mZaaygHBKVOOh9aPSQ to URL https://rholm.nam.example.com:8443/nidp/idff/soap at IDP </amLogEntry>

    The artifact ID must be the same as the artifact ID in Step 4.

    If you do not see these types of entries, verify that you have configured Site B to receive the roles. See Obtaining the Role Assignments.

  6. Verify that Site B is evaluating the received role assignments and activating the roles.

    In the catalina.out file (Linux) or the stdout.log file (Windows) of Identity Server from Site B, search for a policy evaluation for RolesFromIdentityProvider. You must find lines similar to the following:

    ~~CO~1~RolesFromIdentityProvider(6670):https://ipd.sitea.nam.example.com:
8443/nidp/idff/metadata:TESTER,DOC,AUTHENTICATED~com.novell.nxpe.condition.
NxpeOperator@string-equals~(0):hidden-param:hidden-value:~~~True(69)

~~PA~ActionID_1203705845727~~AddRole~tester~~~Success(0)

<amLogEntry> 2009-08-22T20:30:20Z INFO NIDS Application: AM#500105013: AMDEVICEID#488475009C6D3DDF: AMAUTHID#YfdEmqCT2ZutwybD1eYSpfph8g5a5aMl6MGryq1hIqc=: Authenticated user cn=Tom,o=novell in User Store Internal with roles tester,authenticated. </amLogEntry>

    The policy evaluation shows that the condition evaluates to true and that the tester role is activated. Tom is the user that is federated with the tsmith user, and the entry shows that Tom has been assigned the tester role.

    If you do not see a policy evaluation for RolesFromIdentityProvider, ensure that you have created such a Role policy and that you have enabled it. See Configuring Policies to Process Received Roles.

  7. If the user has been assigned the correct role, the last step is to verify how the embedded service provider evaluated the policy protecting the resource.

    In the catatina.out file of the ipd-esp file for Access Gateway, search for lines similar to the following for the authorization policy trace:

    <amLogEntry> 2009-08-22T20:30:20Z INFO NIDS Application: AM#501102050: AMDEVICEID#esp-2559E77C93738D15: AMAUTHID#YfdEmqCT2ZutwybD1eYSpfph8g5a5aMl6MGryq1hIqc=: PolicyID#65LN233O-KN19-1L7M-176M-P942LMN6P832: NXPESID#1411: AGAuthorization Policy Trace:
 ~~RL~1~~~~Rule Count: 2~~Success(0)
 ~~RU~RuleID_1198874340999~Allow_Tester~DNF~~1:1~~Success(0)
 ~~CS~1~~ANDs~~1~~True(69)
 ~~CO~1~CurrentRoles(6660):no-param:TESTER,AUTHENTICATED~com. novell.nxpe.condition.NxpeOperator@string-substring~SelectedRole (6661):hidden-param:hidden-value:~~~True(69)
 ~~PA~1~~Permit Access~~~~Success(0)
 ~~PC~1~~Document=(ou=xpemlPEP,ou=mastercdn,ou=ContentPublisher Container,ou=Partition,ou=PartitionsContainer,ou=VCDN_Root,ou=accessManagerContainer,o=novell:romaContentCollectionXMLDoc),Policy=(Allow_Tester),Rule=(1::RuleID_1198874340999),Action=(Permit::1)~~~~Success(0)
 </amLogEntry>

    If the PA line does not evaluate to Permit Access, then you need to review the Authorization policy and discover the conditions, other than the tester role, that must be met to permit access.

Setting Up Federation with Third-Party Providers

Setting up federation with providers other than Access Manager Identity Servers requires the same basic tasks as setting up federation with Access Manager Identity Servers, with some modifications.

When you set up federation with identity providers and service providers that are controlled by a single company, you have access to Administration Consoles for both Identity Servers and know the admin credentials. When setting up federation with another company, additional steps are required.

  • You need to negotiate with the other company and gain approval for federation because metadata must be shared and both sites require configuration. You need to negotiate a schedule for these configuration changes.

  • The other site might not be using Access Manager for its identity or service provider. The basic tasks need to be modified to accommodate how that implementation shares metadata, authentication methods, and roles.

  • Many SAML 1.1 providers do not support a metadata URL, and the data must be imported manually.

    For example, instead of sharing URLs that allow you to import metadata, you might need to share the actual metadata and paste it into the configuration. The Access Manager Identity Server validates the metadata of another identity provider or service provider; some implementations do not validate it. If Identity Server determines that the metadata is invalid, you need to negotiate with the provider to send you metadata that has been validated.

  • Most third-party providers do not support authentication cards and contracts. However, most do support either authentication types or authentication URIs. You can use either of these to map from their authentication procedure to an Identity Server authentication contract.

For sample implementations with third-party providers that explain the modifications that were required to set up the federation, see the following: