Sun Java System Access Manager 7 2005Q4 Federation and SAML Administration Guide

Chapter 3 Federation

Sun Java™ System Access Manager provides an interface for creating, modifying, and deleting authentication domains, service providers, and identity providers. This chapter explains how to use the Federation component to configure a Liberty-based provider federation.

This chapter covers the following topics:

Features of Federation

Access Manager provides a web interface to the Liberty Identity Federation Framework (Liberty ID-FF) which is accessible through the Federation tab in the Access Manager Console. The Federation component includes the features and functions described in the following sections.


Note –

For more information about the Liberty ID-FF functions, see the Liberty ID-FF Protocols and Schema Specifications.


Identity Federation and Single Sign-On

Let's assume that a principal has separate user accounts with both a service provider and an identity provider in the same authentication domain. In order to gain access to these individual accounts, the principal authenticates with each provider. After the principal has authenticated with the service provider though, they can be given the option to federate the service provider account with an identity provider account. Consenting to the federation of these two accounts links them for the purpose of single sign-on.

Providers differentiate between federated users by defining a unique handle for each account. (They are not required to use the principal's actual provider account identifier.) Providers can also choose to create multiple handles for a particular principal. However, identity providers must create one handle per user for each service provider that has multiple web sites so that the handle can be resolved across all of them.


Note –

Because both the identity provider and service provider in a federation need to remember the principal's handle, they create entries that note the handle in their respective user repositories. In some scenarios, only the identity provider's handle is conveyed to a service provider. For example, if a service provider does not maintain its own user repository, the identity provider's handle is used.


Access Manager can accommodate the following functions:

Auto-Federation

Auto federation will automatically federate a user's disparate provider accounts based on a common attribute. During single sign-on, if it is deemed a user at provider A and a user at provider B have the same value for the defined common attribute (for example, an email address), the two accounts will be federated without consent or interaction from the principal. For more information, see Auto-Federation.

Bulk Federation

Federating one user's service provider account with their identity provider account generally requires the principal to visit both providers and link them. In situations when an enterprise is both a service provider and an identity provider, the organization should have the ability to federate user accounts behind the scenes. Access Manager provides a script for federating user accounts in bulk. The script allows the administrator to federate many (or all) of a principal's provider accounts based on metadata passed to the script. Bulk federation is useful when adding a new service provider to an enterprise so you can federate a group of existing employees to the new service. For more information, see Bulk Federation.

Authentication and Authentication Context

Single sign-on is the means by which a provider of either type can convey to another provider that the principal has been authenticated. Identity providers use local (to the identity provider) session information that is mapped to a user agent as the basis for issuing SAML authentication assertions to service providers. Thus, when the principal uses a user agent to interact with a service provider, the service provider requests authentication information from the identity provider based on the user agent's session information. If this information indicates that the user agent's session is presently active, the identity provider will return a positive authentication response to the service provider.

Access Manager accommodates these authentication actions:

SAML is used for provider interaction during authentication but not all SAML assertions are equal. Different authorities issue SAML assertions of different quality. Therefore, the Liberty Alliance Project defines how the consumer of a SAML assertion can determine the amount of assurance to place in the assertion. This is referred to as the authentication context, information added to the SAML assertion that gives the assertion consumer information they need to make an informed entitlement decision. For example, a principal uses a simple identifier and a self-chosen password to authenticate to an identity provider. The identity provider sends an assertion that states the principal has been authenticated to a service provider. By sending the authentication context, the service provider can place the appropriate level of assurance on the associated authentication assertion. For example, if the service provider were a bank, they might require stronger authentication than that which has been used and send a response to the identity provider with a request to authenticate the user again. The authentication context information might include:

An XML schema has been defined by which the authority can assert the context of the SAML assertions it issues. The Liberty Alliance Project specifications have also defined Authentication Context classes against which an identity provider can claim conformance. The Liberty-defined authentication contexts are listed and described in the following table.

Table 3–1 Authentication Context Classes

Class 

Description 

MobileContract 

Identified when a mobile principal has an identity for which the identity provider has vouched. 

MobileDigitalID 

Identified by detailed and verified registration procedures, a user's consent to sign and authorize transactions, and DigitalID-based authentication. 

MobileUnregistered  

Identified when the real identity of a mobile principal has not been strongly verified. 

Password 

Identified when a principal authenticates to an identity provider by using a password over an unprotected HTTP session. 

Password-ProtectedTransport 

Identified when a principal authenticates to an identity provider by using a password over an SSL-protected session. 

Previous-Session 

Identified when an identity provider must authenticate a principal for a current authentication event and the principal has previously authenticated to the identity provider. This affirms to the service provider a time lapse from the principal's current resource access request. 


Note –

The context for the previously authenticated session is not included in this class because the user has not authenticated during this session. Thus, the mechanism that the user employed to authenticate in a previous session should not be used as part of a decision on whether to now allow access to a resource.


Smartcard 

Identified when a principal uses a smart card to authenticate to an identity provider. 

Smartcard-PKI 

Identified when a principal uses a smart card with an enclosed private key and a PIN to authenticate to an identity provider. 

Software-PKI 

Identified when a principal uses an X.509 certificate stored in software to authenticate to the identity provider over an SSL-protected session. 

Time-Sync-Token 

Identified when a principal authenticates through a time synchronization token. 


Note –

For more information on authentication context, see the Liberty ID-FF Authentication Context Specification.


Identifiers and Name Registration

Access Manager supports name identifiers that are unique across all providers in an authentication domain. This identifier can be used to obtain information for or about the principal (with consent) without requiring the user to consent to a long-term relationship with the service provider. During federation, the identity provider generates an opaque value that serves as the initial name identifier that both the service provider and the identity provider use to refer to the principal when communicating with each other.

After federation though, the identity provider or the service provider may register a different opaque value. The reasons for doing this would be implementation-specific. If a service provider registers a different opaque value for the principal, the identity provider must use the new identifier when communicating with the service provider about the principal.


Note –

The initial name identifier defined by the identity provider is always used to refer to the principal unless a new name identifier is registered.


Global Logout

A principal may establish authenticated sessions with both an identity provider and individual service providers, based on authentication assertions supplied by the identity provider. When the principal logs out of a service provider session, the service provider sends a logout message to the identity provider that provided the authentication for that session. When this happen, or the principal manually logs out of a session at an identity provider, the identity provider sends a logout message to each service provider to which it provided authentication assertions under the relevant session. The one exception is the service provider that sent the logout request to the identity provider.

Dynamic Identity Provider Proxying

An identity provider can choose to proxy an authentication request to an identity provider in another authentication domain if it knows that the principal has been authenticated with this identity provider. The proxy behavior is defined by the local policy of the proxying identity provider. However, a service provider can override this behavior and choose not to proxy. This function can be implemented as a form of authentication when, for instance, a roaming mobile user accesses a service provider that is not part of the mobile home network. For more information see Dynamic Identity Provider Proxying.

Process of Federation

The process of federation begins with authentication. A standard installation of Access Manager provides two options for user authentication: the proprietary Authentication Service and the Liberty-based Federation component.

With the proprietary option, users attempting to access a resource protected by Access Manager are redirected to the Authentication Service via an Access Manager login page. After the users provide credentials, the Authentication Service allows or denies access to the resource based on the outcome.


Note –

For more information about the proprietary Authentication Service, see the Sun Java System Access Manager 7 2005Q4 Administration Guide.


The second option for user authentication is Liberty-based federation. When a principal attempts to access a web site that belongs to the trusted member provider of a configured authentication domain, the process of user authentication begins with the search for a valid Access Manager session token from the proprietary Authentication Service.

The following figure illustrates these divergent paths.


Note –

The process shown in the figure below is the default process when no application has been deployed. When an application is deployed and using Access Manager, the process will change based on the application's query parameters and preferences. For more information, see The Pre-login URL.


Figure 3–1 Default Process of Federation

Illustration depicting the default process of federation
in Access Manager.

Pre-login Process

The pre-login process establishes a valid Access Manager session. When a principal attempts to access a service provider site and no Access Manager session token is found, Access Manager searches for a federation cookie. A federation cookie is implemented by Access Manager and is called fedCookie. It can have a value of either yes or no, based on the principal’s federation status.


Note –

A federation cookie is not defined in the Liberty Alliance Project specifications.


At this point, the pre-login process may take one of the following paths:


Note –

This pre-login process is the default behavior of Access Manager. This process might change based on parameters passed to Access Manager from the participating application. For more details, see the section on The Pre-login URL.


Federation and Single Sign-On

When a principal logs in to access a protected resource or service, Access Manager sends a request to the appropriate identity provider for authentication confirmation. If the identity provider sends a positive response, the principal gains access to all provider sites within the authentication domain. If the identity provider sends a negative response, the principal is directed to authenticate again using the Liberty-based federation process.

In the Liberty-based federation process, a principal selects an identity provider and sends credentials for authentication. After authentication is complete and access is granted, the principal is issued a session token from the Access Manager Authentication Service and redirected to the requested page. As long as the session token remains valid, the principal can access other service providers in the authentication domain without having to authenticate again.


Note –

Common Domain Services are used by a service provider to determine the identity provider used by a principal in an authentication domain that contains multiple identity providers. See Chapter 4, Common Domain Services for details.


Federation Graphical User Interface

The Federation component uses JavaServer Pages™ (JSP™) to define its look and feel. JSP are HTML files that contain additional code to generate dynamic content. More specifically, a JavaServer page contains HTML code to display static text and graphics, as well as application code to generate information. When the page is displayed in a web browser, it contains both the static HTML content and, in the case of the Federation component, dynamic content retrieved through calls to the Federation API. An administrator can customize the look and feel of the interface by changing the HTML tags in the JSP but the invoked APIs must not be changed.

The JSP are located in /AccessManager-base/SUNWam/web-src/services/config/federation/default. The files in this directory provide a default interface to the Federation component. To customize the pages for a specific organization, this default directory can be copied and renamed to reflect the name of the organization (or any value). This directory would then be placed at the same level as the default directory, and the files within this directory would be modified as needed. The following table lists the JSP including details on what each page is used for and the invoked APIs that cannot be modified. For more information about modifying these pages to customize the console, see the Sun Java System Access Manager 7 2005Q4 Developer’s Guide.

JSP Name and Implemented APIs 

Purpose 

  • CommonLogin.jsp

    Invoked APIs are:

    • LibertyManager.getLoginURL(request)

    • LibertyManager.getInterSiteURL(request)

    • LibertyManager.getIDPList(providerID)

    • LibertyManager.getNewRequest(request)

    • LibertyManager.getSuccintID(idpID)

    • LibertyManager.cleanQueryString(request)

Displays a link to the local login page as well as links to the login pages of the trusted identity providers. This page is displayed when a user is not logged in locally or with an identity provider. The list of identity providers is obtained by using the getIDPList(hostedProviderID) method.

  • Error.jsp

Displays an error page when an error has occurred. No APIs are invoked. 

  • Federate.jsp

    Invoked APIs are:

    • LibertyManager.isLECPProfile(request)

    • LibertyManager.getAuthnRequestEnvelope(request)

    • LibertyManager.getUser(request)

    • LibertyManager.getProvidersToFederate(providerID,userDN)

Displays when a user clicks a federate link on a provider page. Contains a drop-down of all providers with which the user is not yet federated. This list is constructed by using the getProvidersToFederate(userName,providerID) method.

  • FederationDone.jsp

    Invoked API is:

    • LibertyManager.isFederationCancelled(request)

Displays the status of a federation (success or cancelled). This page checks the status by using the isFederationCancelled(request) method.

  • Footer.jsp

Displays a branded footer that is included on all the pages. No APIs are invoked. 

  • Header.jsp

Displays a branded header that is included on all the pages. No APIs are invoked. 

  • ListOfCOTs.jsp

    Invoked API is:

    • LibertyManager.getListOfCOTs(providerID)

Displays a list of circles of trust. When a user is authenticated by an identity provider and the service provider belongs to more than one circle of trust, the user is shown this JSP and is prompted to select an authentication domain as their preferred domain. In the case that the provider belongs to only one domain, this page will not be displayed. The list is obtained by using the getListOfCOTs(providerID) method.

  • LogoutDone.jsp

    Invoked API is:

    • LibertyManager.isLogoutSuccess(request)

Displays the status of the local logout operation. 

  • NameRegistration.jsp

    Invoked APIs are:

    • LibertyManager.getUser(request)

    • LibertyManager.getRegisteredProviders(userDN)

Displays when the Name Registration link is clicked on a provider page. When a federated user chooses to register a new Name Identifier from a service provider to an identity provider, this JSP is displayed. 

  • NameRegistrationDone.jsp

    Invoked APIs are:

    • LibertyManager.isNameRegistrationSuccess(request)

    • LibertyManager.isNameRegistrationCanceled(request)

Displays the status of NameRegistration.jsp. When finished, this page is displayed.

  • Termination.jsp

    Invoked APIs are:

    • LibertyManager.getUser(request)

    • LibertyManager.getFederatedProviders(userDN)

Displays when a user clicks a defederate link on a provider page. Contains a drop-down of all providers to which the user has federated and from which the user can choose to defederate. The list is constructed by using the getFederatedProviders(userName) method, which returns all active providers to which the user is already federated.

  • TerminationDone.jsp

    Invoked APIs are:

    • LibertyManager.isTerminationSuccess(request)

    • LibertyManager.isTerminationCanceled(request)

Displays the status of federation termination (success or cancelled). Status is checked using the isTerminationCancelled(request) method.

Entities and Authentication Domains

The Federation component in the Access Manager Console provides an interface for configuring, modifying, and deleting authentication domains, and identity and service providers. To create and populate an authentication domain, you first create an entity to hold the metadata for each provider that will become a member of the authentication domain. Then, you configure and save the authentication domain. Finally, to add an entity to the authentication domain, you edit the entity's properties. The following sections contain more information:


Note –

In a federation setup, all service providers and identity providers must share a synchronized clock. You can implement the synchronization by pointing to an external clock source or by ensuring that, in case of delays in receiving responses, the responses are captured without fail through adjustments of the timeouts.


Entities

In Access Manager an entity can contain configuration information for an individual identity provider, an individual service provider, or one of each. An entity can also contain configuration information for an affiliation, a group of providers of either type. Both provider and affiliation entities can be configured using the Access Manager Console.


Note –

For general information about entities, see the Liberty Metadata Description and Discovery Specification.


Provider Entity

A provider entity holds the metadata for individual providers of either type. All identity providers and service providers must first be configured within a provider entity. After they are configured in an entity, they can be associated with an authentication domain, or chosen to be included in an affiliate entity. Using the descriptor attributes, one individual identity provider, one individual service provider, or one of each can be defined within a provider entity.

Affiliate Entity

An affiliate entity holds the metadata that defines a group of one or more providers that was formed without regard to the boundaries of an authentication domain. This affiliation (referenced by an affiliationID) is formed and maintained by an affiliation owner (referenced by the providerID of the entity that defined it) who chooses the trusted providers from already configured provider entities. Members of the affiliation may invoke services either as a member of the affiliation (using the affiliationID), or individually (using their providerID). For example, when a service provider issues an authentication request on behalf of an affiliation, the AffiliationID will be used to achieve single sign-on and the identity provider will resolve federations based on the same AffiliationID. The affiliate entity itself does not contain the configuration information for any providers, only the configuration information for the entity.


Note –

The name identifier (a single persistent randomized string) is used to achieve single sign-on between an identity provider and a group of service providers acting as a single affiliation. If there are several service providers and identity providers in the same circle of trust, use an affiliate entity to avoid having to generate different name identifiers for commonly shared services.


Creating an entity is a two-step process. First, you create a provider or affiliate entity. Then, you populate the entity with remote or hosted provider information (either service or identity) or affiliation information. This process is described in the following sections:

Creating Entities

This section describes the process for creating a provider entity or an affiliate entity.

ProcedureTo Create a Provider Entity or an Affiliate Entity

An entity can be created but it will not be available for assignment to an authentication domain until it has been populated with provider(s). Once created and configured, the entity (and thus the providers) can be added to an authentication domain.

  1. In the Access Manager Console, select the Federation tab.

  2. Under Federation, select the Entities tab.

  3. Select New.

    The new entity attributes are displayed.

  4. Type a value for the Entity Name.

    This field specifies the Uniform Resource Identifier (URI) of the entity and must be unique. For example, http://shivalik.sun.com or http://provider2.com:875.

  5. (Optional) Enter a description of the entity in the Description field.

  6. Select one of the following options to define the entity’s type.

    • Select Provider and click OK.

      The new entity is now displayed as a provider in the list of configured Entities. To configure the entity, see To Configure a Provider Entity.

    • Select Affiliate, type a value for both Affiliate Name and Affiliate Owner, and click OK.

      The Affiliate Name (also referred to as the affiliation ID) specifies a URI defined by the Affiliate Owner that uniquely represents the affiliate entity, for example, http://shivalik.sun.com or http://provider2.com:875. The Affiliate Owner is the provider ID of the service provider (defined in a provider entity) that is forming the affiliation. After entering these values and clicking OK, the new entity is displayed as an affiliate in the list of configured Entities. To configure the entity, see To Configure an Affiliate Entity.


      Note –

      Defining a service provider as the Affiliate Owner does not automatically include it as a member of the affiliate. If an owner is also a member, the provider ID must be defined in both attributes.


Configuring Provider Entities

After you create a provider entity, you populate it with remote or hosted provider information (either service or identity). This section contains the following procedures:

ProcedureTo Configure a Provider Entity

When you configure a provider entity, you are populating it with remote or hosted provider information (either service or identity). You might also be configuring values for attributes that were not available when the entity was initially created.

  1. In the Access Manager Console, select the Federation tab.

  2. Under Federation, select the Entities tab.

  3. Select the provider entity that you want to configure.

    Ensure that you select an entity marked as type Provider.

  4. Define values for the General, Identity Provider or Service Provider attributes by choosing from the View menu:

ProcedureTo Configure General Attributes for a Provider Entity

Before performing this procedure, you must have completed the steps in To Configure a Provider Entity.

  1. Choose General from the View menu, and provide information for the Entity Common Attributes.

    Entity Common Attributes contain values that define the entity itself.

    Entity Name

    The static value of this attribute is the name that you provided when creating the entity.

    Type

    The static value of this attribute is Provider.

    Description

    The value of this optional attribute is the description that you provided when creating the entity. You can modify the description.

    Valid Until

    Type the expiration date for the entity metadata. Use Coordinated Universal Time (UTC) in the format yyyy-mm-ddThh:mm:ss.SZ. For example, 2004-12-31T14:30:00.0Z.

    Cache Duration

    Type the maximum amount of time that the entity metadata can be cached. Use the format PnYnMnDTnHnMnS, where n is an integer variable. For example, P1Y2M4DT9H8M20S defines the cache duration as 1 year, 2 months, 4 days, 9 hours, 8 minutes, and 20 seconds.

  2. Provide information for the Entity Contact Person Profile attributes.

    Entity Contact Person Profile attributes contain values that define the administrator of the entity.

    First Name

    Type the given name of the entity’s contact person.

    Last Name

    Type the surname of the entity’s contact person.

    Type

    Choose the type of contact from the drop-down menu:

    • Administrative

    • Billing

    • Technical

    • Other

    Company

    Type the name of the company that employs this person.

    Liberty Principal ID

    Type a URI that points to an online instance of the contact person’s personal information profile.

    Emails

    Type one or more email addresses for the contact person.

    Telephone Numbers

    Type one or more telephone numbers for the contact person.

  3. (Optional) Provide information for the Organization Profiles.

    The Organization Profiles attributes contain values that define the organizational name of the entity.

    Names

    Type the complete legal name of the entity’s organization. Use the format locale|organization-name. For example, en|organization-name.com.


    Note –

    If the Names attribute contains a value, it is required to add values to the Display Names and URL attributes.


    Display Names

    Type a name that is suitable for display. Use the format locale|organization-display-name. For example, en|organization-display-name.com.

    URL

    Type a URL that can be used to direct a principal to additional information on the entity's organization. Use the format locale|organization-URL. For example, en|http://www.organization-name.com.

  4. Click Save to complete the configuration, or define values for Identity Provider or Service Provider attributes by choosing from the View menu:

ProcedureTo Configure Hosted or Remote Identity Provider Attributes for a Provider Entity

Before performing this procedure, you must have completed the steps in To Configure a Provider Entity.

  1. Choose Identity Provider from the View menu.

  2. Select the type of provider that you are configuring:

    • New Hosted Provider

    • New Remote Provider

    A hosted provider is installed on the same server as Access Manager. A remote provider is not installed on the same server as Access Manager.

  3. Provide information for the Common Attributes.

    Common Attributes contain values that generally define the identity provider.

    Provider Type

    The static value of this attribute is the type of provider being configured: hosted or remote. This attribute is visible only after saving your configuration.

    Description

    The value of this attribute is a description of the identity provider.

    Valid Until

    Type the expiration date for the provider metadata. Use Coordinated Universal Time (UTC) and the format yyyy-mm-ddThh:mm:ss.SZ, for example, 2004-12-31T14:30:00.0Z.

    Cache Duration

    Type the maximum amount of time that the provider metadata can be cached. Use the format PnYnMnDTnHnMnS, where n is an integer. For example, P1Y2M4DT9H8M20S defines the cache duration as 1 year, 2 months, 4 days, 9 hours, 8 minutes, and 20 seconds.

    Protocol Support Enumeration

    Choose the Liberty ID-FF release that is supported by this provider.

    • urn:liberty:iff:2003-08 refers to the Liberty Identity Federation Framework Version 1.2.

    • urn:liberty:iff:2002-12 refers to the Liberty Identity Federation Framework Version 1.1.

    Server Name Identifier Mapping Binding

    Name identifier mapping allows a service provider to obtain a name identifier for a principal that has federated in the namespace of a different service provider. Implementing this protocol allows the requesting service provider to communicate with the second service provider without an identity federation having been enabled. Type a URI that identifies the communication specifications.


    Note –

    Currently, the Name Identifier Mapping profile only supports SOAP. If this attribute is used, its value must be http://projectliberty.org/profiles/nim-sp-http.


    Additional Meta Locations

    Type a URL that points to other relevant metadata concerning the provider.

    Signing Key: Key Alias

    Type the key alias that is used to sign requests and responses.

    Encryption Key: Key Alias

    Type the security certificate alias. Certificates are stored in a Java keystore file. Each specific certificate is mapped to an alias that is used to fetch the certificate.

    Encryption Key: Key Size

    Type the length for keys that are used by the web service consumer when interacting with another entity.


    Note –

    If the encryption method is DESede, the key size must be 192. If the encryption method is AES, the key size must be 128, 192 or 256.


    Encryption Key: Encryption Method

    Choose the method of encryption:

    • None

    • AES

    • DESede

    Name Identifier Encryption

    Select the check box to enable encryption of the name identifier.

  4. Provide information for the Communication URLs.

    Communication URLs attributes contain locations for redirects and sending requests.

    SOAP Endpoint

    Type a URI to the identity provider’s SOAP message receiver. This value communicates the location of the SOAP receiver in non browser communications.

    Single Sign-On Service URL

    Type a URL to which service providers can send single sign-on and federation requests.

    Single Logout Service

    Type a URL to which service providers can send logout requests. Single logout synchronizes the logout functionality across all sessions authenticated by the identity provider.

    Single Logout Return

    Type a URL to which the identity provider will redirect the principal after completing a logout.

    Federation Termination Service

    Type a URL to which a service provider will send federation termination requests.

    Federation Termination Return

    Type a URL to which the identity provider will redirect the principal after completing federation termination.

    Name Registration Service

    Type a URL to which a service provider will send requests to specify a new name identifier to be used when communicating with the identity provider about a principal. This service can only be used after a federation session is established.

    Name Registration Return

    Type a URL to which the identity provider will redirect the principal after HTTP name registration has been completed.

  5. Provide information for the Communication Profiles.

    Communication Profiles attributes define the transmission methods used by the identity provider.

    Federation Termination

    Select a profile to notify other providers of a principal’s federation termination:

    • HTTP Redirect

    • SOAP

    Single Logout

    Select a profile to notify other providers of a principal’s logout:

    • HTTP Redirect

    • HTTP Get

    • SOAP

    Name Registration

    Select a profile to notify other providers of a principal’s name registration:

    • HTTP Redirect

    • SOAP

    Single Sign-on/Federation

    Select a profile for sending authentication requests:

    • Browser Post (specifies a browser-based HTTP POST protocol)

    • Browser Artifact (specifies a non-browser SOAP-based protocol)

    • LECP (specifies a Liberty-enabled Client Proxy)


      Note –

      Access Manager can handle requests that come from a Liberty-enabled client proxy profile, but it requires additional configuration that is beyond the scope of this manual.


  6. Select any of the available authentication domains to assign to the provider.

    A provider can belong to one or more authentication domains. However, a provider without a specified authentication domain can not participate in Liberty-based communications. If no authentication domains have been created, you can define this attribute later.


    Note –

    To continue configuring a remote identity provider, skip to step 11.


  7. (Hosted Identity Provider Only) Provide mappings for the Authentication Context classes.

    This attribute maps the Liberty-defined authentication context classes to authentication methods available at the identity provider.

    Supported

    Select the check box next to the authentication context class if the identity provider supports it.

    Context Reference

    The Liberty-defined authentication context classes are:

    • Password

    • Mobile Digital ID

    • Smartcard

    • Smartcard-PKI

    • MobileUnregistered

    • Software-PKI

    • Previous-Session

    • Mobile Contract

    • Time-Sync-Token

    • Password-ProtectedTransport

    Key

    Choose the Access Manager authentication type to which the context is mapped.

    Value

    Type the Access Manager authentication option.

    Priority

    Choose a priority level for cases where there are multiple contexts.

  8. (Hosted Identity Provider Only) Select any of the available provider entities to assign as a Trusted Provider and click Add.

    This attribute tallies providers that the identity provider trusts. It is visible after the provider configuration has been saved.

  9. (Hosted Identity Provider Only) Provide information for the Access Manager Configuration attributes.

    Access Manager Configuration attributes define general information regarding the instance of Access Manager being used as an identity provider.

    Provider URL

    Type the URL of the local identity provider.

    Provider Alias

    Type an alias name for the local identity provider.

    Authentication Type

    Select the provider that should be used for authentication requests from a provider hosted locally:

    • Remote specifies that the provider hosted locally would contact a remote identity provider upon receiving an authentication request.

    • Local specifies that the provider hosted locally should contact a local identity provider upon receiving an authentication request (essentially, itself).

    Default Authentication Context

    Select the authentication context class (method of authentication) to use if the identity provider does not receive this information as part of a service provider request. This value also specifies the authentication context used by the service provider when an unknown user tries to access a protected resource. The options are as follows:

    • Password

    • Mobile Digital ID

    • Smartcard

    • Smartcard-PKI

    • MobileUnregistered

    • Software-PKI

    • Previous-Session

    • Mobile Contract

    • Time-Sync-Token

    • Password-ProtectedTransport

    Identity Provider Forced Authentication

    Select the check box to indicate that the identity provider must reauthenticate (even during a live session) when an authentication request is received. This attribute is enabled by default.

    Request Identity Provider to be Passive

    Select the check box to specify that the identity provider must not interact with the principal and must interact with the user.

    Realm

    Type a value that points to the realm in which this provider is configured. For example, /sp.

    Liberty Version URI

    Type the URI of the version of the Liberty Alliance Project specification being used. The default value is http://projectliberty.org/specs/v1.

    Name Identifier Implementation

    This field defines the class used by a service provider to participate in name registration. Name registration is a profile by which service providers specify a principal’s name identifier that an identity provider will use when communicating with the service provider. The value is com.sun.identity.federation.services.util.FSNameIdentifierImpl.

    Home Page URL

    Type the URL of the home page of the identity provider.

    Single Sign-on Failure Redirect URL

    Type the URL to which a principal will be redirected if single sign-on has failed.

    Assertion Issuer

    Type the name of the host that issues the assertion. This value might be the load balancer's host name if Access Manager is behind one.

    Generate Discovery Bootstrapping Resource Offering

    Select the check box if you want a Discovery Service Resource Offering to be generated during the Liberty-based single sign-on process for bootstrapping purposes.

    Auto Federation

    Select the check box to enable auto-federation.

    Auto Federation Common Attribute Name

    When creating an Auto Federation Attribute Statement, the value of this attribute will be used. The statement will contain the AutoFedAttribute element and this common attribute as its value.

    Attribute Statement Plugin

    Specify a pluggable class used for adding attribute statements to an assertion that is generated during the Liberty-based single sign-on process.

  10. (Hosted Identity Provider Only) Provide information for the SAML Attributes.

    SAML Attributes define general information regarding SAML assertions that are sent by the identity provider.

    Assertion Interval

    Type the interval of time (in seconds) that an assertion issued by the identity provider will remain valid. A principal will remain authenticated until the assertion interval expires.

    Cleanup Interval

    Type the interval of time (in seconds) before assertions stored in the identity provider will be cleared.

    Artifact Timeout

    Type the interval of time (in seconds) to specify the timeout for assertion artifacts.

    Assertion Limit

    Type a number to define how many assertions an identity provider can issue, or how many assertions that can be stored.


    Note –

    To continue configuring a hosted identity provider, skip to step 12.


  11. (Remote Identity Provider Only) Provide information for the Proxy Authentication Configuration attributes.

    Proxy Authentication Configuration attributes define values for dynamic identity provider proxying.

    Enable Proxy Authentication

    Select the check box to enable proxy authentication for a service provider.

    Proxy Identity Providers List

    Add a list of identity providers that can be used for proxy authentication. The value is a URI defined as the provider's identifier.

    Maximum Number of Proxies

    Enter the maximum number of identity providers that can be used for proxy authentication.

    Use Introduction Cookie for Proxying

    Select the check box if you want introductions to be used to find the proxying identity provider.

  12. Provide information for the Organization Profiles.

    The optional Organization Profiles attributes contain values that define the organizational name of the entity.

    Names

    Type the complete legal name of the organization. Use the format locale|organization-name, for example, en|organization-name.com.


    Note –

    If the Names attribute contains a value, it is required to add values to the Display Names and URL attributes also.


    Display Names

    Type a name that is suitable for display to a principal. The value is defined in the format locale|organization-display-name, for example, en|organization-display-name.com.

    URL

    Type a URL that can be used to direct a principal to additional information on the entity. Use the format locale|organization-URL, for example, en|http://www.organization-name.com.

  13. Click New Contact Person to create a contact person for the provider.

    The Contact Person attributes contain information regarding a human contact for the identity provider.

    First Name

    Type the given name of the identity provider’s contact person.

    Last Name

    Type the surname of the identity provider's contact person.

    Type

    Choose the contact's role from the drop-down menu:

    • Administrative

    • Billing

    • Technical

    • Other

    Company

    Type the name of the company that employs the contact person.

    Liberty Principal Identifier

    Type the name identifier that points to an online instance of the contact person’s personal information profile.

    Emails

    Type one or more email addresses for the contact person.

    Telephone Numbers

    Type one or more telephone numbers for the contact person.

  14. Click Create to create the contact person.

  15. Click Save to complete the configuration, or define values for General or Service Provider attributes by choosing from the View menu:

ProcedureTo Configure Hosted or Remote Service Provider Attributes for a Provider Entity

Before performing this procedure, you must have completed the steps in To Configure a Provider Entity.

  1. Choose Service Provider from the View menu.

  2. Select the type of provider that you are configuring:

    • New Hosted Provider

    • New Remote Provider

    A hosted provider is installed on the same server as Access Manager. A remote provider is not installed on the same server as Access Manager.

  3. Provide information for the Common Attributes.

    Common Attributes contain values that generally define the service provider.

    Provider Type

    The static value of this attribute is the type of provider being configured: hosted or remote. This attribute is visible only after saving your configuration.

    Description

    The value of this attribute is a description of the service provider.

    Valid Until

    Type the expiration date for the provider metadata. Use Coordinated Universal Time (UTC) and the format yyyy-mm-ddThh:mm:ss.SZ, for example, 2004-12-31T14:30:00.0Z.

    Cache Duration

    Type the maximum amount of time that the provider metadata can be cached. Use the format PnYnMnDTnHnMnS, where n is an integer. For example, P1Y2M4DT9H8M20S defines the cache duration as 1 year, 2 months, 4 days, 9 hours, 8 minutes, and 20 seconds.

    Protocol Support Enumeration

    Select the Liberty ID-FF release that is supported by this provider.

    • urn:liberty:iff:2003-08 refers to the Liberty Identity Federation Framework Version 1.2.

    • urn:liberty:iff:2002-12 refers to the Liberty Identity Federation Framework Version 1.1.

    Server Name Identifier Mapping Binding

    Name identifier mapping allows a service provider to obtain a name identifier for a principal that has federated in the namespace of a different service provider. Implementing this protocol allows the requesting service provider to communicate with the second service provider without an identity federation having been enabled. The value of this attribute is a URI that identifies the communication specifications.


    Note –

    Currently, the Name Identifier Mapping profile only supports SOAP. If this attribute is used, its value must be http://projectliberty.org/profiles/nim-sp-http.


    Additional Meta Locations

    Type a URL that points to other relevant metadata concerning the provider.

    Signing Key: Key Alias

    Type the key alias that is used to sign requests and responses.

    Encryption Key: Key Alias

    Type the security certificate alias. Certificates are stored in a Java keystore file. Each specific certificate is mapped to an alias that is used to fetch the certificate.

    Encryption Key: Key Size

    Type the length for keys that are used by the web service consumer when interacting with another entity.

    Encryption Key: Encryption Method

    Select the method of encryption:

    • None

    • AES

    • DESede

    Name Identifier Encryption

    Select the check box to enable encryption of the name identifier.

  4. Provide information for the Communication URLs.

    Communication URLs attributes contain locations for redirects and sending requests.

    SOAP Endpoint

    Type a URI to the service provider’s SOAP message receiver. This value communicates the location of the SOAP receiver in non browser communications.

    Single Logout Service

    Type a URL to which identity providers can send logout requests.

    Single Logout Return

    Type a URL to which the service provider will redirect the principal after completing a logout.

    Federation Termination Service

    Type a URL to which identity providers will send federation termination requests.

    Federation Termination Return

    Type a URL to which the service provider will redirect the principal after completing federation termination.

    Name Registration Service

    Type a URL that will be used when communicating with the identity provider to specify a new name identifier for the principal. (Registration can occur only after a federation session is established.)

    Name Registration Return

    Type a URL to which the service provider will redirect the principal after HTTP name registration has been completed.

  5. Provide information for the Communication Profiles.

    Communication Profiles attributes define the transmission methods used by the service provider.

    Federation Termination

    Select a profile to notify other providers of a principal’s federation termination:

    • HTTP Redirect

    • SOAP

    Single Logout

    Select a profile to notify other providers of a principal’s logout:

    • HTTP Redirect

    • HTTP Get

    • SOAP

    Name Registration

    Select a profile to notify other providers of a principal’s name registration:

    • HTTP Redirect

    • SOAP

    Single Sign-on/Federation

    Select a profile for sending authentication requests:

    • Browser Post (specifies a browser-based HTTP POST protocol)

    • Browser Artifact (specifies a non-browser SOAP-based protocol)

    • LECP (specifies a Liberty-enabled Client Proxy)


      Note –

      Access Manager can handle requests that come from a Liberty-enabled client proxy profile, but it requires additional configuration that is beyond the scope of this manual.


  6. Select any of the available authentication domains to assign to the provider.

    A provider can belong to one or more authentication domains. However, a provider without a specified authentication domain cannot participate in Liberty-based communications. If no authentication domains have been created, you can define this attribute later.


    Note –

    To continue configuring a remote service provider, skip to step 9.


  7. (Hosted Service Provider Only) Provide a hierarchy for the Authentication Context classes.

    This attribute corresponds to the authentication level defined for an Access Manager authentication module. It will redirect the principal to the authentication type with an authentication level equal to the number defined.

    Context Reference

    The Liberty-defined authentication context classes are:

    • Password

    • Mobile Digital ID

    • Smartcard

    • Smartcard-PKI

    • MobileUnregistered

    • Software-PKI

    • Previous-Session

    • Mobile Contract

    • Time-Sync-Token

    • Password-ProtectedTransport

    Level

    Type a level for each authentication context class. The number can be any positive number.

  8. (Hosted Service Provider Only) Select any of the available provider entities to assign as a Trusted Provider and click Add.

    This attribute tallies providers that the service provider trusts.

  9. Provide information for the Service Provider attributes.

    Service Provider attributes define general information regarding the service provider.

    Assertion Consumer URL

    Type the URL to the end point that defines where a provider will send SAML assertions.

    Assertion Consumer Service URL ID

    If the value of the Protocol Support Enumeration common attribute is urn:liberty:iff:2003-08, type the required ID.

    Set Assertion Consumer Service URL as Default

    Select the check box to use the Assertion Consumer Service URL as the default value when no identifier is provided in the request.

    Sign Authentication Request

    Select the check box to make the service provider always signs authentication requests.

    Name Registration after Federation

    Select the check box to enable the service provider to participate in name registration after a principal has been federated.

    Name ID Policy

    Select the option permitting requester influence over name identifier policy at the identity provider. The options are:

    • None specifies that the identity provider will return the name identifier(s) for the principal corresponding to the federation that exists between the identity provider and the requesting service provider or affiliation group. If no such federation exists, an error will be returned.

    • One-time specifies that the identity provider will issue a temporary, one-time-use identifier for the principal after federation.

    • Federation specifies that the identity provider may start a new identity federation if one does not already exist for the principal.

    Enable Affiliation Federation

    Select the check box to enable affiliation federation.


    Note –

    To continue configuring a remote identity provider, skip to step 11.


  10. (Hosted Service Provider Only) Provide information for the Access Manager Configuration attributes.

    Access Manager Configuration attributes define general information regarding the instance of Access Manager being used as a service provider.

    Provider URL

    Type the URL of the local service provider.

    Provider Alias

    Type an alias name for the local service provider.

    Authentication Type

    Select the provider that should be used for authentication requests from a provider hosted locally:

    • Remote specifies that the provider hosted locally would contact a remote identity provider upon receiving an authentication request.

    • Local specifies that the provider hosted locally should contact a local identity provider upon receiving an authentication request (essentially, itself).

    Default Authentication Context

    This attribute defines the service provider's default authentication context class (method of authentication). This method will always be called when the service provider sends an authentication request. This value also specifies the authentication context used by the service provider when an unknown user tries to access a protected resource. The options are:

    • Password

    • Mobile Digital ID

    • Smartcard

    • Smartcard-PKI

    • MobileUnregistered

    • Software-PKI

    • Previous-Session

    • Mobile Contract

    • Time-Sync-Token

    • Password-ProtectedTransport

    Identity Provider Forced Authentication

    Select the check box to indicate that the identity provider must reauthenticate (even during a live session) when an authentication request is received. This attribute is enabled by default.

    Request Identity Provider to be Passive

    Select the check box to specify that the identity provider must not interact with the principal and must interact with the user.

    Realm

    Type a value that points to the realm in which this provider is configured, for example, /sp.

    Liberty Version URI

    Type the URI of the version of the Liberty specification being used. The default value is http://projectliberty.org/specs/v1.

    Name Identifier Implementation

    This field defines the class used by a service provider to participate in name registration. Name registration is a profile by which service providers specify a principal’s name identifier that an identity provider will use when communicating with the service provider. The value is com.sun.identity.federation.services.util.FSNameIdentifierImpl.

    Home Page URL

    Type the URL of the home page of the service provider.

    Single Sign-on Failure Redirect URL

    Type the URL to which a principal will be redirected if single sign-on has failed.

    Auto Federation

    Select the check box to enable auto-federation.

    Auto Federation Common Attribute Name

    When creating an Auto Federation Attribute Statement, the value of this attribute will be used. The statement will contain the AutoFedAttribute element and this common attribute as its value.

    Attribute Statement Plugin

    Specify a pluggable class used for adding attribute statements to an assertion that is generated during the Liberty-based single sign-on process.

  11. Provide information for the Proxy Authentication Configuration attributes.

    Proxy Authentication Configuration attributes define values for dynamic identity provider proxying.

    Enable Proxy Authentication

    Select the check box to enable proxy authentication for a service provider.

    Proxy Identity Providers List

    Add a list of identity providers that can be used for proxy authentication. The value is a URI defined as the provider's identifier.

    Maximum Number of Proxies

    Enter the maximum number of identity providers that can be used for proxy authentication.

    Use Introduction Cookie for Proxying

    Select the check box if you want introductions to be used to find the proxying identity provider.


    Note –

    To continue configuring a remote identity provider, skip to step 13.


  12. (Hosted Service Provider Only) Provide information for the SAML Attributes.

    SAML Attributes define general information regarding SAML assertions sent by the identity provider.

    Assertion Interval

    Type the interval of time (in seconds) that an assertion issued by the identity provider will remain valid. A principal will remain authenticated until the assertion interval expires.

    Cleanup Interval

    Type the interval of time (in seconds) before assertions stored in the identity provider will be cleared.

    Artifact Timeout

    Type the interval of time (in seconds) to specify the timeout for assertion artifacts.

    Assertion Limit

    Type a number to define how many assertions an identity provider can issue, or how many assertions can be stored.

  13. Provide information for the Organization Profiles.

    The optional Organization Profiles attributes contain values that define the organizational name of the entity.

    Names

    Type the complete legal name of the entity’s organization. Use the format locale|organization-name, for example, en|organization-name.com.


    Note –

    If the Names attribute contains a value, it is required to add values to the Display Names and URL attributes.


    Display Names

    Type a name that is suitable for display. Use the format locale|organization-display-name, for example, en|organization-display-name.com.

    URL

    Type a URL that can be used to direct a principal to additional information on the entity's organization. Use the format locale|organization-URL, for example, en|http://www.organization-name.com.

  14. Click New Contact Person to create a contact person for the provider.

    The Contact Person attributes contain information regarding a human contact for the identity provider.

    First Name

    Type the given name of the identity provider’s contact person.

    Last Name

    Type the surname of the identity provider's contact person.

    Type

    Choose the contact's role from the drop-down menu:

    • Administrative

    • Billing

    • Technical

    • Other

    Company

    Type the name of the company that employs the contact person.

    Liberty Principal Identifier

    Type the name identifier that points to an online instance of the contact person’s personal information profile.

    Emails

    Type one or more email addresses for the contact person.

    Telephone Numbers

    Type one or more telephone numbers for the contact person.

  15. Click Create to create the contact person.

  16. Click Save to complete the configuration, or define values for General or Identity Provider attributes by choosing from the View menu:

Configuring Affiliate Entities

After you create an affiliate entity, you populate it with affiliation information. This section contains the following procedures:

ProcedureTo Configure an Affiliate Entity

  1. In the Access Manager Console, select the Federation tab.

  2. Under Federation, select the Entities tab.

  3. Select the provider entity that you want to configure.

    Ensure that you select an entity marked as type Affiliate.

  4. Define values for the General or Affiliate attribute groupings by choosing from the View menu:

ProcedureTo Configure General Attributes for an Affiliate Entity

Before performing this procedure, you must have completed the steps in To Configure an Affiliate Entity.

  1. Choose General from the View menu, and provide information for the Entity Common Attributes.

    Entity Common Attributes contain values that define the entity.

    Entity Name

    The static value of this attribute is the name that you provided when creating the entity.

    Type

    The static value of this attribute is Provider.

    Description

    The value of this optional attribute is the description that you provided when creating the entity. You can modify the description.

    Valid Until

    Type the expiration date for the entity metadata. Use Coordinated Universal Time (UTC) in the format yyyy-mm-ddThh:mm:ss.SZ, for example, 2004-12-31T14:30:00.0Z.

    Cache Duration

    Type the maximum amount of time that the entity metadata can be cached. Use the format PnYnMnDTnHnMnS, where n is an integer variable. For example, P1Y2M4DT9H8M20S defines the cache duration as 1 year, 2 months, 4 days, 9 hours, 8 minutes, and 20 seconds.

  2. Provide information for the Entity Contact Person Profile attributes.

    Entity Contact Person Profile attributes contain values that define the administrator of the entity.

    First Name

    Type the given name of the entity’s contact person.

    Last Name

    Type the surname of the entity’s contact person.

    Type

    Choose the type of contact from the drop-down menu:

    • Administrative

    • Billing

    • Technical

    • Other

    Company

    Type the name of the company that employs this person.

    Liberty Principal ID

    Type a URI that points to an online instance of the contact person’s personal information profile.

    Emails

    Type one or more email addresses for the contact person.

    Telephone Numbers

    Type one or more telephone numbers for the contact person.

  3. Provide information for the Organization Profiles.

    The optional Organization Profiles attributes contain values that define the organizational name of the entity.

    Names

    Type the complete legal name of the organization. Use the format locale|organization-name, for example, en|organization-name.com.


    Note –

    If the Names attribute contains a value, it is required to add values to the Display Names and URL attributes also.


    Display Names

    Type a name that is suitable for display to a principal. The value is defined in the format locale|organization-display-name. For example, en|organization-display-name.com.

    URL

    Type a URL that can be used to direct a principal to additional information on the entity. Use the format locale|organization-URL, for example, en|http://www.organization-name.com.

  4. Click Save to complete the configuration, or choose Affiliate from the View menu to configure the Affiliate attributes.

    To define values for Affiliate attributes, see To Configure Affiliate Attributes for an Affiliate Entity.

ProcedureTo Configure Affiliate Attributes for an Affiliate Entity

Before performing this procedure, you must have completed the steps in To Configure an Affiliate Entity.

  1. Choose Affiliate from the View menu and provide information for the Common Attributes.

    Common Attributes contain values that generally define the affiliation.

    Name

    The value of this attribute is the name of the affiliation.

    Owner

    The value of this attribute is the owner of the affiliation.

    Valid Until

    Type the expiration date for the affiliation metadata. Use Coordinated Universal Time (UTC) and the format yyyy-mm-ddThh:mm:ss.SZ, for example, 2004-12-31T14:30:00.0Z.

    Cache Duration

    Type the maximum amount of time affiliation metadata can be cached. Use the format PnYnMnDTnHnMnS, where n is an integer. For example, P1Y2M4DT9H8M20S defines the cache duration as 1 year, 2 months, 4 days, 9 hours, 8 minutes, and 20 seconds.

    Signing Key: Key Alias

    Type the key alias that is used to sign requests and responses.

    Encryption Key: Key Alias

    Type the security certificate alias. Certificates are stored in a JKS keystore file. Each specific certificate is mapped to an alias that is used to fetch the certificate.

    Encryption Key: Key Size

    Type the length for keys used by the web service consumer when interacting with another entity.

    Encryption Key: Encryption Method

    Select the method of encryption:

    • None

    • AES

    • DESede

  2. Select any of the available provider entities to assign as members of the affiliation.

    A provider can belong to one or more affiliations. However, a provider without a specified authentication domain cannot participate in Liberty-based communications. Also, be sure that the service provider entity being assigned to the affiliate entity has enabled affiliation federation.

  3. Click Save to complete the configuration.

  4. Click OK to complete the configuration, or choose General from the View menu to configure the General attributes.

    To define values for General attributes, see To Configure General Attributes for an Affiliate Entity.

Deleting Entities

If an entity is to be deleted from the console, it first needs to be manually removed from the Trusted Providers list (if the provider is hosted) or the Available Providers list (if part of an affiliation).

ProcedureTo Delete a Provider or Affiliate Entity

  1. In the Access Manager Console, click the Federation tab.

  2. Under Federation, select the Entities tab.

  3. Select the check box next to the entity that you want to delete.

    No warning message is displayed when performing a delete.

  4. Click Delete.

Authentication Domains

An authentication domain is a federation of any number of service providers (and at least one identity provider) with whom principals can transact business in a secure and apparently seamless environment. (The members of the domain must have previously established a circle of trust based on the Liberty Alliance Project architecture and operational agreements.)


Note –

An authentication domain is not a domain in the domain name system (DNS) sense of the word.


The following procedures describe how to create, configure, and delete authentication domains using the Access Manager Console.

ProcedureTo Create An Authentication Domain

  1. In the Access Manager Console, click the Federation tab.

  2. Under Federation, select the Authentication Domains tab.

  3. Select New.

    The New Authentication Domain attributes are displayed.

  4. Type a name for the authentication domain.

  5. (Optional) Type a description of the authentication domain in the Description field.

  6. (Optional) Type a value for the Writer Service URL.

    The Writer Service URL specifies the location of the service that writes the common domain cookie. Use the format http://common-domain-host:port/common/writer. For more information about the Common Domain Services, see Chapter 4, Common Domain Services.

  7. (Optional) Type a value for the Reader Service URL.

    The Reader Service URL specifies the location of the service that reads the common domain cookie. Use the format http://common-domain-host:port/common/transfer. For more information about the Common Domain Services, see Chapter 4, Common Domain Services.

  8. Select Active or Inactive.

    The default status is Active. Selecting Inactive disables communication within the authentication domain.

  9. Click OK.

    The new authentication domain is now displayed in the list of configured Authentication Domains.

ProcedureTo Configure or Modify an Authentication Domain

  1. In the Access Manager Console, click the Federation tab.

  2. Under Federation, select the Authentication Domains tab.

    All created Authentication Domains are displayed.

  3. Click the name of the authentication domain that you want to modify.

    The General and Providers properties for the authentication domain are displayed.

  4. (Optional) Enter or modify a description of the authentication domain in the Description field.

  5. (Optional) Enter or modify the value for the Writer Service URL.

    The Writer Service URL specifies the location of the service that writes the common domain cookie. Use the format http://common-domain-host:port/common/writer. For more information on the Common Domain Services, see Chapter 4, Common Domain Services.

  6. (Optional) Enter or modify the value for the Reader Service URL.

    The Reader Service URL specifies the location of the service that reads the common domain cookie. Use the format http://common-domain-host:port/common/transfer. For more information on the Common Domain Services, see Chapter 4, Common Domain Services.

  7. Select Active or Inactive.

    The default status is Active. Selecting Inactive disables communication within the authentication domain.

  8. Click Add to populate the authentication domain with providers.

    The Trusted Providers page is displayed.

  9. Choose from the list of Available Providers and click Add.

  10. Click OK to save the providers to the authentication domain.

    The authentication domain's attribute page is displayed.

  11. Click Save to complete the configuration.

ProcedureTo Delete an Authentication Domain

Deleting an authentication domain does not delete the providers that belong to it although it will impact the trusted relationship.

  1. In the Access Manager Console, click the Federation tab.

  2. Under Federation, select the Authentication Domains tab.

    All created Authentication Domains are displayed.

  3. Select the check box next to the authentication domain that you want to delete.

  4. Click Delete.

Auto-Federation

The auto-federation feature in Access Manager will automatically federate a user's disparate provider accounts based on a common attribute. This common attribute will be exchanged in a single sign-on assertion so that the consuming service provider can identify the user and create account federations. If auto-federation is enabled and it is deemed that a user at provider A and a user at provider B have the same value for the defined common attribute (for example, emailaddress), the two accounts will be federated automatically without principal interaction.


Note –

Auto-federating a principal's two distinct accounts at two different providers requires each provider to have agreed to implement support for this functionality beforehand.


ProcedureTo Enable Auto Federation

Ensure that each local service and identity provider participating in auto federation is configured for it. Remote providers would not be configured in your deployment.

  1. In the Access Manager Console, click the Federation tab.

  2. Under Federation, select the Entities tab.

  3. Select the name of a hosted provider entity to edit its profile.

    Whether an entity is configured to hold hosted or remote providers is not information that is disclosed on this screen.

  4. Select Identity Provider or Service Provider from the View menu.

  5. Select Access Manager Configuration.

  6. Enable Auto Federation by checking the box.

  7. Type a value for the Auto Federation Common Attribute Name attribute.

    For example, enter emailaddress or userID. You should be sure that each participating user profile (at both providers) has a value for this attribute.

  8. Click Save to complete the configuration.

Bulk Federation

Access Manager provides a script for federating user accounts in bulk. It is called ambulkfed and is located in /opt/SUNWam/bin. The script assumes that the user database is LDAPv3–compliant.


Note –

The ambulkfed script is the primary script for bulk federation. It uses two other Perl scripts, amGenerateLDIF.pl and amGenerateNI.pl, behind the scenes.


As input, the script takes a file that maps the user distinguished name (DN) of the identity provider to the user DN of the service provider. Each line of the file must place the mappings in the following order and separated by a pipe (”|”): uid=spuser,dc=iplanet,dc=com | uid=idpuser,dc=iplanet,dc=com. The script generates unique random identifiers for each mapping and creates four files:

These files contain the data for bulk federation. The LDIFs are used for instances of Access Manager. ambulkfed generates and loads the LDIF data into Access Manager based on its given provider role. For example, it will load spuserdata.ldif if Access Manager acts as a service provider and it will load idpuserdata.ldif if Access Manager acts as an identity provider. The LDIFs will also be stored locally and can be used with ldapmodify to load the data into a remote instance of Access Manager. If the remote provider is not an instance of Access Manager, the generated text files spnameidentifiers.txt and idpnameidentifiers.txt can be used to generate federation data based on the input needs of the provider.

Dynamic Identity Provider Proxying

An identity provider that is asked to authenticate a principal that has already been authenticated with another identity provider may proxy the authentication request, on behalf of the requesting service provider, to the authenticating identity provider. This is called dynamic identity provider proxying. When the first identity provider receives an authentication request regarding a principal, it prepares a new authentication assertion on its own behalf by referencing the relevant information from the original assertion and sending the assertion to the authenticating identity provider.


Note –

The service provider requesting authentication may control this proxy behavior by setting a list of preferred identity providers or by defining the amount of times the identity provider can proxy the request.


ProcedureTo Configure and Test Dynamic Identity Provider Proxying

The following steps describe the procedure to enable three machines for identity provider proxying and test the configuration. The procedure assumes the three machines have Access Manager installed and are configured as follows:

Machine 

Authentication Function 

Federation Function 

Machine 1 

Authenticating Identity Provider 

Identity Provider 

Machine 2 

Proxying Identity Provider 

Identity Provider and Service Provider 

Machine 3 

Requesting Service Provider 

Service Provider 

All of the WAR files and metadata used in the following procedure can be found in /AccessManager-base/samples/liberty/sample1.

  1. To configure machine 3, deploy the SP1 WAR files and load sp1Metadata.xml.

    Ensure that the metadata defines machine 2 as an identity provider and machine 3 as a service provider.

  2. To configure machine 1, deploy the IDP1 WAR files and load idp1Metadata.xml.

    Ensure that the metadata defines machine 1 as an identity provider and machine 2 as a service provider.

  3. To configure machine 2, do the following:

    1. To configure machine 2 as a service provider, deploy the SP1 WAR files.

      Modify AMClient.properties to reflect this.

    2. To configure machine 2 as an identity provider, load a second, modified idp1Metadata.xml.

      Ensure that idp1Metadata.xml contains only data that defines machine 1 as an identity provider. Remove all other metadata.

  4. Log in to machine 2 and modify the following metadata:

    1. Change the value of the Authentication Type attribute to Local.

      This attribute can be found in the Access Manager Configuration section of the entity describing machine 2 as a service provider.

    2. Add machine 1 and machine 3 to the list of Trusted Providers configured for machine 2.

      This attribute can be found in the Trusted Provider section of the entity describing machine 2 as a service provider.

    3. Save the configuration.

  5. Also on machine 2, modify the following metadata regarding machine 3.

    1. Select the check box next to Enable Proxy Authentication.

      This attribute can be found in the Proxy Authentication Configuration section of the entity that defines machine 3 as an identity provider.

    2. Add machine 1 to the list of Proxy Identity Providers List.

      This attribute can be found in the Proxy Authentication Configuration section of the entity that defines machine 3 as an identity provider. The value is a URI defined as the provider's identifier.

    3. Set Maximum Number of Proxies to 1.

    4. Save the configuration.

  6. Federate a user between machine 3 (acting as a service provider) and machine 2 (acting as an identity provider).

  7. Federate a user between machine 2 (acting as a service provider) and machine 1 (acting as an identity provider).

  8. Close the browser and attempt single sign-on.

    You will be redirected to machine 1 rather than machine 2 if you enter the username and password used to federate with machine 1.

The Pre-login URL

The pre-login process is the entry point for applications participating in Liberty-based single sign-on. As described in Process of Federation, the principal would be redirected to the location defined by the pre-login URL if no Access Manager session token is found. This default process, though, can be modified based on the values of URL query parameters passed to Access Manager by the service provider.


Note –

A URL parameter is a name/value pair appended to the end of a URL. The parameter starts with a question mark (?) and takes the form name=value. A number of parameters can be combined in one URL although if more than one parameter exists, they are separated by an ampersand (&).


In order to modify the pre-login URL, edit the property in either the AMConfig.properties file or the AMAgent.properties file, dependant on your deployment. Use the format http://hostname:port/deploy-uri/preLogin?metaAlias=metaAlias. Query parameters can be appended to the URL as &param1=value1&param2=value2 and so on. These parameters and their usage and values are described in the following table.

Table 3–2 Pre-login URL Parameters for Federation

Parameter 

Description 

actionOnNoFedCookie

The actionOnNoFedCookie parameter provides the flexibility to redirect a user when the fedCookie is not present in the browser, and when there is only one identity provider. It takes the following values:

  • commonlogin will redirect to a common login page.

  • locallogin will redirect to the local Access Manager login page.

  • passive will issue a request to the identity provider by setting the isPassive parameter of the AuthnRequest element to true.

  • active will issue a normal single sign-on request to the identity provider.

anonymousOnetime

The anonymousOnetime parameter can be used by service providers that authenticate users with anonymous, one time federation sessions. A value of true enables the service provider to issue a one time federation request and generate an anonymous session after successful verification of the authentication assertion from the identity provider. This feature is useful when the service provider doesn't have a user repository (for example, http://www.weather.com) but would like to depend on an identity provider for authentication. When the service provider receives a successful authentication assertion from an identity provider, they would generate an anonymous, temporary session.

authlevel

The authlevel parameter takes as a value a positive number that maps to an authentication level defined in the Access Manager Authentication Framework. The authentication level indicates how much to trust a method of authentication.


Note –

More information on the authentication framework can be found in Sun Java System Access Manager 7 2005Q4 Administration Guide.


In this framework, each service provider is configured with a default authentication context (preferred method of authentication). However, the provider might like to change the assigned authentication context to one that is based on the defined authentication level. For example, provider B would like to generate a local session with an authentication level of 3 so it requests the identity provider to authenticate the user with an authentication context assigned that level. The value of this query parameter determines the authentication context to be used by the identity provider. 

gotoOnFedCookieNo

The gotoOnFedCookieNo parameter takes as a value a URL to which the principal is redirected if a fedCookie with a value of no is found. The default behavior is to redirect the user to the Access Manager login page.

Federation API

The com.sun.liberty package provides the interface that forms the basis of the Federation API. It contains the LibertyManager class which must be instantiated by web applications that want to access the Federation component. It also contains the methods needed for account federation, session termination, log in, log out and other actions. Some of these methods are described in the following table. For more detailed information, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

Table 3–3 Federation API Methods

Method 

Description 

getFederatedProviders(String userName)

Returns a specific user’s federated providers. 

getIDPFederationStatus(String user, String provider)

Retrieves a user’s federation status with a specified identity provider. This method assumes that the user is already federated with the provider. 

getIDPList()

Returns a list of all trusted identity providers. 

getIDPList(java.lang.String hostedProviderID)

Returns a list of all trusted identity providers for the specified hosted provider. 

getProvidersToFederate(java.lang.String providerID, java.lang.String userName)

Returns a list of all trusted identity providers to which the specified user is not already federated. 

getSPList()

Returns a list of all trusted service providers. 

getSPList(java.lang.String hostedProviderID)

Returns a list of all trusted service providers for the specified hosted provider. 

getSPFederationStatus(java.lang.String user, java.lang.String provider)

Retrieves a user’s federation status with a specified service provider. This method assumes that the user is already federated with the provider. 

Sample Federation Environment

Access Manager provides a collection of samples based on the Liberty Alliance Project specifications. They are located in the /AccessManager-base/SUNWam/samples/liberty/ directory. Appendix A, Liberty-based and SAML Samples includes information about these samples.

Sample 1, located in /AccessManager-base/SUNWam/samples/liberty/Sample1, can be used to configure an environment for creating and managing a federation. The sample demonstrates the basic use of various Liberty-based federation protocols including account federation, single sign-on, single logout, and federation termination. Completing the procedures in the sample Readme.txt or Readme.html will help to give you a more complete understanding of how federation works.


Note –

The Readme file also contains instructions for configuring a common domain. For information about common domains, see Chapter 4, Common Domain Services.