Sun Java Systems Access Manager 6 2005Q1 Federation Management Guide |
Chapter 3
Federation ManagementSun Java System Access Manager provides an interface for creating, modifying, and deleting authentication domains and, service and identity providers (both remote and hosted types). This chapter is an overview of how to use this module to create a Liberty-based federation. It contains the following sections:
OverviewThe Federation Management module is the Access Manager implementation of the Liberty Alliance Project (LAP) Liberty Identity Federation Framework (ID-FF) specification. The ID-FF defines a set of protocols, bindings and profiles that provides a solution for identity profile federation, cross-domain authentication and session management. The Federation Management module is the Access Manager Web interface to the ID-FF implementation. It is accessible through the Federation Management tab in the Header frame of the Access Manager console.
Note
More detailed information on the Liberty Identity Federation Framework can be found in the Liberty ID-FF Protocols and Schema Specifications (http://www.projectliberty.org/specs/draft-liberty-idff-protocols-schema-1.2-errata-v1.0.pdf).
The Federation Management InterfaceThe Federation Management module uses JavaServer Pages (JSP) to define its look and feel. JSP are HTML files that contain additional code to generate dynamic content. More specifically, JSP contain 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 will contain both the static HTML content and, in the case of the Federation Management module, dynamic content retrieved via calls to the Federation Management API. An administrator can customize the look and feel of the interface by changing the HTML tags in the JSP, but the APIs invoked 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 Management module. To customize it for a specific organization, this default directory can be copied and renamed to reflect the name of the organization (or any value). It would then be placed at the same level as the default directory and the files within this directory would be modified as needed. Table 3-1 is a list of the JSP with details on what each page is used for and the invoked APIs that cannot be modified. More information on modifying these pages to customize the console can be found in the Sun Java System Access Manager 6 2005Q1 Developer’s Guide (http://docs.sun.com/doc/817-7649).
The Process of FederationThe process of federation begins with authentication. By default, Access Manager comes with two options for user authentication. The first is the proprietary Authentication Service; the second is the Liberty-enabled Federation process. 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 they provide credentials, the Authentication Service allows or denies access to the resource based on the outcome.
Note
For more information on the proprietary Authentication Service, see Chapter 4, Authentication Service in the Sun Java System Access Manager 6 2005Q1 Developer’s Guide (http://docs.sun.com/doc/817-7649).
With Liberty-enabled federation, when a principal attempts to access a Web site belonging to a member provider from an authentication domain, the process begins with a search for a valid Access Manager session token from the Authentication Service. If a session token is found, the principal is granted (or denied) access. Assuming access is granted, the page then displayed would contain a link that provides the principal an opportunity to federate the authenticated identity provider identity with the accessed service provider identity. When the principal clicks this link, the Single Sign-on Process process begins.
If no session token is found, the principal is directed through the Pre-login Process. Figure 1-1 illustrates these different paths.
Figure 3-1 Liberty-based Access Manager Authentication Process Flow
Pre-login Process
The pre-login process establishes a valid session. When a principal attempts to access a service provider site and no Access Manager session token is found, the pre-login process then begins with the search for a federation cookie.
The pre-login process can take one of the following paths:
- If a federation cookie is found and its value is no, an Access Manager login page is displayed and the principal submits credentials to the Authentication Service. When authenticated by Access Manager, the principal is redirected to the requested page which might contain a link to allow for identity federation. If the user clicks this link, the Single Sign-on Process begins.
- If a federation cookie is found and its value is yes, the principal has already federated an identity but has not been authenticated by an identity provider within the authentication domain for this session. Authentication to Access Manager is accomplished on the back-end by sending a request to the principal’s identity provider. After authentication, the principal is directed back to the requested page.
- If no federation cookie is found, a passive authentication request is sent to the principal’s identity provider. (A passive authentication request does not allow identity provider interaction with the principal.) If an affirmative authentication is received back from the identity provider, the principal is redirected to the Access Manager Authentication Service a session token is granted and the principal is redirected to the requested page. If the response from the identity provider is negative (for example, if the session has timed out), the principal is sent to a common login page to complete either a local login or the Liberty-enabled Single Sign-on Process.
Single Sign-on Process
When a principal logs in for access to 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 membered within the authentication domain. If the identity provider sends a negative response, the principal is directed to authenticate again using the Liberty-enabled single sign-on process.
In Liberty-enabled single sign-on, principals select an identity provider and send their credentials for authentication. (This is accomplished through the Common Domain Services.) Once authentication is complete and access is granted, the principal is automatically 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 sign on again.
Common Domain ServicesThe Common Domain Services allow a service provider to discover the specific identity provider used by a principal in an authentication domain with multiple identity providers. The Services rely on a cookie that is written in a domain that is common to all identity providers and service providers in the authentication domain. The domain (predetermined by all members of the authentication domain) is known as the common domain. The Common Domain Services use a common domain cookie (which contains a list of Base64-encoded identity provider identifiers) to determine the preferred identity provider.
Note
The Common Domain Services are based on the Identity Provider Introduction Profiles detailed in the Liberty ID-FF Bindings and Profiles Specifications located at http://www.projectliberty.org/specs/draft-liberty-idff-bindings-profiles-1.2-errata-v2.0.pdf.
Let’s assume an authentication domain contains more than one identity provider. Because of this, a service provider in the authentication domain trusts more than one identity provider. But, a principal can only issue a federation request to one identity provider so, the service provider to which the principal is requesting access must discover the correct one. When the request contains no common domain cookie, the service provider presents a list of trusted identity providers from which the principal may choose. When the request contains a common domain cookie, the service provider reads the cookie to discover the correct identity provider.
Installing the Common Domain Services
The Common Domain Services for Federation Management are installed as one Web application within the Access Manager product using the Sun Java Enterprise System installer. However, they can also be installed as one Web application (separate from the Access Manager product) on a J2EE web container using the same installer.
Note
For more information on installing the service, see the Sun Java Enterprise System Installation Guide on docs.sun.com. As of this writing, the latest version is available at http://docs.sun.com/doc/817-5760.
Common Domain Service URLs
In Access Manager, the Common Domain Services are exposed through two URLs that point to services developed for writing and reading the common domain cookie. The URLs are defined as attributes when an authentication domain is created.
Note
The Reader and Writer service URLs are Access Manager specific. The concepts are not defined in the Liberty ID-FF Bindings and Profiles Specifications.
The format for the Writer Service URL is:
protocol://common_domain_hostname:port/deloy_uri/writer
The format for the Reader Service URL is:
protocol://common_domain_hostname:port/deloy_uri/transfer
See To Create An Authentication Domain for information on configuring these attributes.
Federation ManagementThe Federation Management module in the Access Manager console provides an interface for creating, modifying, and deleting providers, authentication domains, and affiliations. The subsequent sections define these concepts and detail procedures for using the Federation Management interface.
Authentication Domains
An authentication domain (also referred to as a circle of trust) 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 have established business relationships based on the LAP architecture and operational agreements.
Creating and Maintaining Authentication Domains
The following sections describe how to create, modify, and delete authentication domains using the Access Manager console.
To Create An Authentication Domain
- Choose Authentication Domain from the View menu in the Navigation pane of the Federation Management module.
- Click New in the Navigation pane.
The New Authentication Domain attributes are displayed in the Data pane.
- Enter a name for the authentication domain.
This is a required field.
- Enter a description of the authentication domain in the Description field.
- Enter a value for the Writer Service URL.
The Writer Service URL specifies the location of the service that writes the common domain cookie. The URL is in the format:
http://common_domain_host:port/common/writer
- Enter a value for the Reader Service URL.
The Reader Service URL specifies the location of the service that reads the common domain cookie. The URL is in the format:
http://common_domain_host:port/common/transfer
- Select Active or Inactive.
The default status is Active. Selecting Inactive disables communication within the authentication domain.
- Click OK.
The new authentication domain is now displayed in the Navigation pane.
To Modify An Authentication Domain
To Delete An Authentication Domain
Entity Descriptors
An entity descriptor contains one or more descriptions of individual providers, or affiliations. In the Access Manager Liberty implementation, there are two types:
Provider Entity Descriptor
The provider entity descriptor holds information configured for providers (both service and identity) associated with an authentication domain. Within this descriptor, the provider combinations detailed in Table 3-2 can be represented.
Affiliate Entity Descriptor
The affiliate entity descriptor holds information configured for a group of providers, but this group is formed outside of the boundaries of an authentication domain. This affiliation is formed and maintained by an affiliation owner that chooses trusted providers without regard to their particular authentication domain. This descriptor does not contain single or multiple providers unless they are specifically configured as an affiliation. An affiliation document describes a group of providers collectively identified by one providerID and maintained by an affiliation owner (referenced by its affiliationOwnerID). The document lists each member using their configured providerID.
Note
More information on entity descriptors can be found in the Liberty Metadata Description and Discovery Specification (http://www.projectliberty.org/specs/draft-liberty-metadata-1.0-errata-v2.0.pdf).
Creating and Maintaining Entity Descriptors
Creating an entity descriptor using the Access Manager console is a two-step process. First, you create the entity descriptor itself. Then, you populate the descriptor with provider information (either service or identity) or an affiliation, depending on the descriptor created. The following sections describe how to create, modify, and delete entity descriptors using the Access Manager console.
To Create an Entity Descriptor of Either Type
- Choose Entity Descriptors from the View menu in the Navigation pane of the Federation Management module.
- Click New in the Navigation pane.
The New Entity Descriptor attributes are displayed in the Data pane.
- Enter a value for the Entity ID.
This required field should specify the URL identifier of the entity. It must be unique across all entities.
- Enter a description of the entity descriptor in the Description field.
- Select Provider or Affiliate to define the Type.
- If you select Provider, click OK.
- If you select Affiliate, enter a value for both the Affiliate ID and Affiliate Owner ID attributes and click OK.
The Affiliate ID should specify the URL identifier of the affiliate. It must be unique across all entities. The Affiliate Owner ID is the Provider ID of the owner or parent operator of the affiliation, from which additional metadata can be received. These fields are required.
The new entity descriptor is now displayed in the Navigation pane.
To Configure a Provider Entity Descriptor
To Configure General Attributes for a Provider Entity Descriptor
After selecting the desired provider entity descriptor from the Navigation pane:
- Select General from the View menu in the Data pane and provide information for the following attributes (separated into three groups):
Entity Common Attributes
- Entity Type. The static value of this attribute is Provider.
- Description. Enter a description of the provider.
- Valid Until. Enter the expiration date for the metadata pertaining to the provider. The value is defined in the format:
yyyy-mm-ddThh:mm:ss.SZ
For example, 2004-12-31T12:30:00.0-0800
- Cache Duration. Enter the maximum amount of time the entity descriptor can be cached. The value is defined in 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.
Entity Contact Person
- First Name. Enter the first name of the entity’s contact person.
- Last Name. Enter the last name of the entity’s contact person.
- Type. Select the type of entity from the drop down menu. The choices are Billing, Technical, Administrative, and Other.
- Company. Enter the name of the company to which the contact person is employed.
- Liberty Principal Identifier. Enter the name identifier that points to an online instance of the contact person’s personal information profile.
- Email. Enter the email address of the contact person.
- Telephone. Enter the telephone number of the contact person.
Entity Organization
- Name. Enter the name of the entity’s organization. The value is defined in the format:
locale|organization_name
For example, en|organization_name.com
- Display Name. Enter the display name of the entity’s organization. The value is defined in the format:
locale|organization_display_name
For example, en|organization_display_name.com
- URL. Enter the URL of the organization. The value is defined in the format:
locale|organization_URL
For example, en|http://www.organization_name.com
- Click Save.
To Configure Identity Provider Attributes for a Provider Entity Descriptor
After selecting the desired provider entity descriptor from the Navigation pane:
- Select Identity Provider from the View menu in the Data pane to add an identity provider to the entity descriptor.
- Click the New Provider button to display the New Provider Wizard.
- Provide information for the following Common Provider attributes displayed in Step 1.
- Provider ID. Enter a unique identifier for the provider.
- Description. Enter a description of the provider.
- Provider is Hosted or Remote. Select Local if the provider is hosted on the same server as Access Manager or Remote, if not. By default, Remote is selected.
Caution
Attributes displayed and configured in subsequent steps depend on the type defined for the Provider is Hosted or Remote attribute.
- Valid Until. Enter the expiration date for the metadata pertaining to the provider. The value is defined in the format:
yyyy-mm-ddThh:mm:ss.SZ
For example, 2004-12-31T12:30:00.0-0800
- Cache Duration. Enter the maximum amount of time an entity descriptor can be cached. The value is defined in 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 protocol release supported by this entity.
urn:liberty:iff:2003-08 refers to the Liberty Identity Federation Framework version 1.2 and urn:liberty:iff:2002-12 refers to the Liberty Identity Federation Framework version 1.1.
- Server Name Identifier Mapping Binding. Enter a URI describing the SAML authority binding used by the identity provider. Identifier mapping queries are able to locate and communicate with the SAML authority using this URI.
- Additional Meta Locations. Enter the location of other relevant metadata concerning the provider.
Signing Key
- Key Alias. Enter the signing certificate key alias used to sign requests and responses for a hosted (local) provider. For a remote provider, this is a public key that the provider uses to verify the signatures.
Encryption Key
- Key Alias. Enter the security certificate alias. Certificates are stored in a JKS keystore file. Each specific certificate is mapped to an alias which is used to fetch the certificate.
- Key Size. Enter the length for keys used by the Web service consumer when interacting with another entity.
- Encryption Method. Choose the method of encryption. The choices are None, 3DES, AES, and DES.
- Click Next to provide information for the following Communications and Service Provider attributes displayed in Step 2.
Caution
Some of the following attribute subsections are displayed based upon whether the identity provider is defined as Remote or Hosted (Local) in Step III. This is called out in parentheses next to the heading.
Communication URLs
- SOAP Endpoint URL. Enter a location for the identity provider’s SOAP messages receiver.
This value communicates the location of the SOAP receiver in non-browser communications.
- Single Sign-On Service URL. Enter a location to which service providers can send single sign-on and federation requests.
- Single Logout Service URL. Enter a location 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 URL. Enter a location to which the identity provider will redirect the principal after completing a logout.
- Federation Termination Service URL. Enter a location to which a service provider will send federation termination requests.
- Federation Termination Return URL. Enter a location to which the identity provider will redirect the principal after completing federation termination.
- Name Registration Service URL. Enter a location to which a service provider will send requests to specify the name identifier that will be used when communicating with the identity provider about a principal.
Registration can occur only after a federation session is established.
- Name Registration Return URL. Enter a location to which the identity provider will redirect the principal after HTTP name registration has been completed.
- Authentication Service URL. Enter a location for the identity provider’s ID-FF-based Authentication Service.
Communication Profiles
- Federation Termination Profile. Select a profile to notify other providers of a principal’s federation termination. The choices are SOAP and HTTP/Redirect.
- Single Logout Profile. Select a profile to notify other providers of a principal’s logout. The choices are SOAP and HTTP/Redirect.
- Name Registration Profile. Select a profile to notify other providers of a principal’s name registration. The choices are SOAP and HTTP/Redirect.
- Single Sign-on/Federation Profile. Select a profile used by a hosted provider for sending authentication requests. The choices are:
- Enable Name Identifier Encryption. Select the check box to enable encryption of the name identifier.
Proxy Authentication Configuration (only displayed when identity provider is defined as Remote)
- Enable Proxy Authentication. If selected, this attribute enables proxy authentication for a service provider.
- Proxy Identity Providers List. This attribute displays the list of identity providers that can be proxied for authentication.
- Maximum Number Proxies. This attribute specifies the maximum number of identity provider proxies.
- Use Introduction Cookie For Proxying. If enabled, introductions will be used to find the proxying identity provider.
Access Manager Configuration (only displayed when identity provider is defined as Hosted (Local))
- Provider URL. Enter the URL of the local identity provider.
- Alias. Enter 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 to be used if the identity provider does not receive it as part of a service provider request. It also specifies the authentication context used by the service provider when an unknown user tries to access a protected resource. The choices are Previous-Session, Time-Sync-Token, Smartcard, MobileUnregistered, Smartcard-PKI, MobileContract, Password, Password-ProtectedTransport, MobileDigitalID, and Software-PKI.
- Forced Authentication at Identity Provider. Select the check box to indicate if the identity provider must reauthenticate (even during a live session) when an authentication request is received.
- 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
- Organization DN. Enter the location of the DN of the organization if each hosted provider chooses to manage users across different organizations leading to a hosted model.
- Liberty Version URI. Enter the URI of the version of the Liberty specification.
- Name Identifier Implementation. This field allows the option for 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 to the service provider.
- Provider Home Page URL. Enter the URL of the home page of the identity provider.
- Single Sign-on Failure Redirect URL. Enter the URL to which a principal will be redirected if single sign-on has failed.
SAML Configuration (only displayed when identity provider is defined as Hosted (Local))
- Assertion Interval. Enter the interval of time for which an assertion issued by the identity provider will remain valid. A principal will remain authenticated until the assertion interval expires.
- Cleanup Interval. Enter the interval of time before assertions stored in the identity provider will be cleared.
- Artifact Timeout. Enter an interval to specify the timeout of a identity provider for assertion artifacts.
- Assertion Limit. Enter a number to define the amount of assertions an identity provider can issue, or the number of assertions that can be stored.
- Click Next to provide information for the following Organization Attributes and Contact Persons attributes displayed in Step 3.
Organization
- Name. Enter the name of the entity’s organization. The value is defined in the format:
locale|organization_name
For example, en|organization_name.com
- Display Name. Enter the display name of the entity’s organization. The value is defined in the format:
locale|organization_display_name
For example, en|organization_display_name.com
- URL. Enter the URL of the organization. The value is defined in the format:
locale|organization_URL
For example, en|http://www.organization_name.com
- Click New to access the attributes for Contact Persons.
Contact Persons
- First Name. Enter the first name of the entity’s contact person.
- Last Name. Enter the last name of the entity’s contact person.
- Type. Select the type of entity from the drop down menu. The choices are Billing, Technical, Administrative, and Other.
- Company. Enter the name of the company to which the contact person is employed.
- Liberty Principal Identifier. Enter the name identifier that points to an online instance of the contact person’s personal information profile.
- Email. Enter the email address of the contact person.
- Telephone. Enter the telephone number of the contact person.
- Click OK to save the values assigned to the Contact Person attributes.
- Click Next to configure the Authentication Domains to which the provider belongs in Step 4.
- Use the direction arrows to move a Selected authentication domain into the Available list.
- Click Save.
This will assign the provider to an authentication domain. 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.
- Click Finish.
To Configure Service Provider Attributes for a Provider Entity Descriptor
After selecting the desired provider entity descriptor from the Navigation pane:
- Select Service Provider from the View menu to add a service provider to the entity descriptor.
- Click the New Provider button to display the New Provider Wizard.
- Provide information for the following Common Provider attributes displayed in Step 1.
- Provider ID. Enter a unique identifier for the provider.
- Description. Enter a description of the provider.
- Provider is Hosted or Remote. Select Local if the provider is hosted on the same server as Access Manager or Remote, if not. By default, Remote is selected.
Caution
Attributes displayed and configured in subsequent steps depend on the type defined for the Provider is Hosted or Remote attribute.
- Valid Until. Enter the expiration date for the metadata pertaining to the provider. The value is defined in the format:
yyyy-mm-ddThh:mm:ss.SZ
For example, 2004-12-31T12:30:00.0-0800
- Cache Duration. Enter the maximum amount of time an entity descriptor can be cached. The value is defined in 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 protocol release supported by this entity.
urn:liberty:iff:2003-08 refers to the Liberty Identity Federation Framework version 1.2 and urn:liberty:iff:2002-12 refers to the Liberty Identity Federation Framework version 1.1.
- Server Name Identifier Mapping Binding. Enter a URI describing the SAML authority binding used by the identity provider. Identifier mapping queries are able to locate and communicate with the SAML authority using this URI.
- Additional Meta Locations. Enter the location of other relevant metadata concerning the provider.
Signing Key
- Key Alias. Enter the signing certificate key alias used to sign requests and responses for a hosted (local) provider. For a remote provider, this is a public key that the provider uses to verify the signatures.
Encryption Key
- Key Alias. Enter the security certificate alias. Certificates are stored in a JKS keystore file. Each specific certificate is mapped to an alias which is used to fetch the certificate.
- Key Size. Enter the length for keys used by the Web service consumer when interacting with another entity.
- Encryption Method. This field defines the encryption method. The choices are None, 3DES, AES, and DES.
- Click Next to provide information for the following Communications and Service Provider attributes in Step 2.
Caution
Some of the following attribute subsections are displayed based upon whether the service provider is defined as Remote or Hosted (Local) in Step III. This is called out in parentheses next to the heading.
Communication URLs
- SOAP Endpoint URL. Enter a location for the service provider’s SOAP messages receiver.
This value communicates the location of the SOAP receiver in non-browser communications.
- Single Logout Service URL. Enter a location 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 URL. Enter a location to which the service provider will redirect the principal after completing a logout.
- Federation Termination Service URL. Enter a location to which a service provider will send federation termination requests.
- Federation Termination Return URL. Enter a location to which the service provider will redirect the principal after completing federation termination.
- Name Registration Service URL. Enter a location to which a service provider will send requests to specify the name identifier that will be used when communicating with the identity provider about a principal.
Registration can occur only after a federation session is established.
- Name Registration Return URL. Enter a location to which the identity provider will redirect the principal after HTTP name registration has been completed.
- Authentication Service URL. Enter a location for the identity provider’s ID-FF-based Authentication Service.
Communication Profiles
- Federation Termination Profile. Select a profile to notify other providers of a principal’s federation termination. The choices are SOAP and HTTP/Redirect.
- Single Logout Profile. Select a profile to notify other providers of a principal’s logout. The choices are SOAP and HTTP/Redirect.
- Name Registration Profile. Select a profile to notify other providers of a principal’s name registration. The choices are SOAP and HTTP/Redirect.
- Single Sign-on/Federation Profile. Select a profile used by a hosted provider for sending authentication requests. The choices are:
- Enable Name Identifier Encryption. Select the check box to enable encryption of the name identifier.
Service Provider
- Assertion Consumer URL. Enter the SAML endpoint to which a provider will send SAML assertions.
- Assertion Consumer Service URL ID. Enter the identifier of the Assertion Consumer Service URL to be used as a reference in authentication requests.
This identifier is required if Protocol Support Enum (Step VI) is urn:liberty:iff:2002-12.
- Set Assertion Consumer Service URL as Default. Select this check box to use the Assertion Consumer URL as the default.
- Sign Authentication Request. Select this check box to specify that the service provider send signed authentication and federation requests. The identity provider will not process unsigned requests.
- Name Registration After Federation. Select this check box to allow for a service provider to participate in name registration after it has been federated. For more information, see Name Registration Protocol of Chapter 1, "Introduction to the Liberty Alliance Project."
- Name ID Policy. Choose an option to determine the name identifier format generated by the identity provider. The choices are None, One-time, and Federated. This attribute value is part of the authentication request. If the Name ID Policy value is federated, the name identifier format is urn:liberty:iff:2003:federated.
- Enable Affiliation Federation. If enabled, federation based on affiliation IDs is allowed.
Access Manager Configuration (only displayed when service provider is defined as Hosted (Local))
- Provider URL. Enter the URL of the local identity provider.
- Alias. Enter 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 to be used if the identity provider does not receive it as part of a service provider request. It also specifies the authentication context used by the service provider when an unknown user tries to access a protected resource. The choices are Previous-Session, Time-Sync-Token, Smartcard, MobileUnregistered, Smartcard-PKI, MobileContract, Password, Password-ProtectedTransport, MobileDigitalID, and Software-PKI.
- Forced Authentication at Identity Provider. Select the check box to indicate if the identity provider must reauthenticate (even during a live session) when an authentication request is received.
- 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
- Organization DN. Enter the location of the DN of the organization if each hosted provider chooses to manage users across different organizations leading to a hosted model.
- Liberty Version URI. Enter the URI of the version of the Liberty specification.
- Name Identifier Implementation. This field allows the option for 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 to the service provider.
- Provider Home Page URL. Enter the URL of the home page of the identity provider.
- Single Sign-on Failure Redirect URL. Enter the URL to which a principal will be redirected if single sign-on has failed.
SAML Configuration (only displayed when service provider is defined as Hosted (Local))
- Assertion Interval. Enter the interval of time for which an assertion issued by the identity provider will remain valid. A principal will remain authenticated until the assertion interval expires.
- Cleanup Interval. Enter the interval of time before assertions stored in the identity provider will be cleared.
- Artifact Timeout. Enter an interval to specify the timeout of a identity provider for assertion artifacts.
- Assertion Limit. Enter a number to define the amount of assertions an identity provider can issue, or the number of assertions that can be stored.
Proxy Authentication Configuration
- Enable Proxy Authentication. If selected, this attribute enables proxy authentication for a service provider.
- Proxy Identity Providers List. This attribute displays the list of identity providers that can be proxied for authentication.
- Maximum Number Proxies. This attribute specifies the maximum number of identity provider to be proxied.
- Use Introduction Cookie For Proxying. If enabled, introductions will be used to find the proxying identity provider.
- Click Next to provide information for the following Organization Attributes and Contact Persons attributes displayed in Step 3.
Organization
- Name. Enter the name of the entity’s organization. The value is defined in the format:
locale|organization_name
For example, en|organization_name.com
- Display Name. Enter the display name of the entity’s organization. The value is defined in the format:
locale|organization_display_name
For example, en|organization_display_name.com
- URL. Enter the URL of the organization. The value is defined in the format:
locale|organization_URL
For example, en|http://www.organization_name.com
- Click New to access the attributes for Contact Persons detailed below.
Contact Persons
- First Name. Enter the first name of the entity’s contact person.
- Last Name. Enter the last name of the entity’s contact person.
- Type. Select the type of entity from the drop down menu. The choices are Billing, Technical, Administrative, and Other.
- Company. Enter the name of the company to which the contact person is employed.
- Liberty Principal Identifier. Enter the name identifier that points to an online instance of the contact person’s personal information profile.
- Email. Enter the email address of the contact person.
- Telephone. Enter the telephone number of the contact person.
- Click OK to save the values assigned to the Contact Person attributes.
- Click Next to configure the Authentication Domains to which the provider belongs in Step 4.
- Use the direction arrows to move a Selected authentication domain into the Available list.
- Click Save.
This will assign the provider to an authentication domain. 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.
- Click Finish.
To Configure an Affiliate Entity Descriptor
To Configure General Attributes for an Affiliate Entity Descriptor
After selecting the desired affiliate entity descriptor from the Navigation pane:
- Select General from the View menu in the Data pane and provide information for the following attributes (separated into three groups):
Entity Common Attributes
- Entity Type. The static value of this attribute is Affiliate.
- Description. Enter a description of the affiliation.
- Valid Until. Enter the expiration date for the metadata pertaining to the affiliation. The value is defined in the format:
yyyy-mm-ddThh:mm:ss.SZ
For example, 2004-12-31T12:30:00.0-0800
- Cache Duration. Enter the maximum amount of time the entity descriptor can be cached. The value is defined in 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.
Entity Contact Person
- First Name. Enter the first name of the entity’s contact person.
- Last Name. Enter the last name of the entity’s contact person.
- Type. Select the type of entity from the drop down menu. The choices are Billing, Technical, Administrative, and Other.
- Company. Enter the name of the company to which the contact person is employed.
- Liberty Principal Identifier. Enter the name identifier that points to an online instance of the contact person’s personal information profile.
- Email. Enter the email address of the contact person.
- Telephone. Enter the telephone number of the contact person.
Entity Organization
- Name. Enter the name of the entity’s organization. The value is defined in the format:
locale|organization_name
For example, en|organization_name.com
- Display Name. Enter the display name of the entity’s organization. The value is defined in the format:
locale|organization_display_name
For example, en|organization_display_name.com
- URL. Enter the URL of the organization. The value is defined in the format:
locale|organization_URL
For example, en|http://www.organization_name.com
- Click Save.
To Configure Affiliates Attributes for an Affiliate Entity Descriptor
After selecting the desired affiliate entity descriptor from the Navigation pane:
- Select Affiliates from the View menu in the Navigation pane.
- Provide information for the following Affiliate Common attributes (separated into three groups):
Affiliate Common Attributes
- Affiliate ID. The value of this attribute should be defined during the creation of the Affiliate Entity Descriptor. For more information, see To Create an Entity Descriptor of Either Type.
- Affiliate Owner ID. The value of this attribute should be defined during the creation of the Affiliate Entity Descriptor. For more information, see To Create an Entity Descriptor of Either Type.
- Valid Until. Enter the expiration date for the metadata pertaining to the provider. The value is defined in the format:
yyyy-mm-ddThh:mm:ss.SZ
For example, 2004-12-31T12:30:00.0-0800
- Cache Duration. Enter the maximum amount of time an entity descriptor can be cached. The value is defined in 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. Enter the signing certificate key alias used to sign requests and responses for a hosted (local) provider. For a remote provider, this is a public key that the provider uses to verify the signatures.
Encryption Key
- Key Alias. Enter the security certificate alias. Certificates are stored in a JKS keystore file. Each specific certificate is mapped to an alias which is used to fetch the certificate.
- Key Size. Enter the length for keys used by the Web service consumer when interacting with another entity.
- Encryption Method. Choose the method of encryption. The choices are None, 3DES, AES, and DES.
Affiliate Members
- Affiliate Members. Use the direction arrows to move a Selected provider into the Available list.
This field allows you to define one or more providers as members of the affiliation. The providers displayed in the Selected list are pre-defined in existing container entity descriptors.
- Click Save.
To Delete an Entity Descriptor of Either Type
Federation Management APIThe com.sun.liberty package provides the interface that forms the basis of the Federation Management API. The LibertyManager class must be instantiated by web applications that want to access the Federation Management module. It contains the methods needed by the module JSPs for account federation, session termination, log in, log out and other actions. Some of these methods are:
For more detailed API reference information, see the Javadocs in /AccessManager_base/SUNWam/docs.
Federation Management SamplesAccess Manager provides a collection of sample files, located in the /AccessManager_base/SUNWam/samples/liberty/Sample1 directory, to configure a basic environment for creating and managing a federation. The example demonstrates the basic use of various Liberty-based federation protocols including account federation, SSO, single logout, and federation termination. The sample should be completed in the following sequence:
The following sections include more information on these steps.
Note
The Readme file located with the sample in /AM_Install_Dir/SUNWam/samples/liberty/sample1 also contains instructions for configuring a common domain. For information on common domains, see Common Domain of Chapter 1, "Introduction to the Liberty Alliance Project" and Common Domain Services of this chapter.
Installing Access Manager
The first step in creating a federated environment is installing Access Manager on two separate machines. One installation will act as a service provider, and one will act as an identity provider.
Note
Instructions on installing Access Manager can be found in the Sun Java Enterprise System Installation Guide (http://docs.sun.com/coll/entsys_05q1).
The default installation directory for the Solaris operating system is /opt/SUNWam.
Updating and Loading the Metadata
Update and load the sp1Metadata.xml file with values appropriate to your Access Manager installation. The file is located in /AccessManager_base/SUNWam/samples/liberty/sample1. Table 3-4 summarizes the default values which should be modified based on your installation configuration.
Load the updated sp1Metadata.xml file using the following command:
/AccessManager_base/SUNWam/bin/amadmin -u amadmin -w password -t sp1Metadata.xml
Deploying the Service Provider
The following sequence should be followed in order to deploy the service provider:
To Configure AMClient.properties
Replace the following tags in the AMClient.properties file with values appropriate to your configuration. AMClient.properties is located in /AccessManager_base/SUNWam/samples/liberty/sample1/sp1/WEB-INF/classes/.
- SERVER_PROTO: Enter HTTPS or HTTP.
- SERVER_HOST: Enter the fully-qualified host name for your installation. For example, www.sp1.com.
- SERVER_PORT: Enter the port number on which Access Manager is running.
- SERVICE_DEPLOY_URI: Enter the Access Manager services deployment URI. The default value is amserver.
- META_ALIAS: Enter the metaAlias for SP1. In sp1Metadata.xml, the default value is www.sp1.com.
To Create a WAR File for SP1
To Deploy the Service Provider WAR File
Choose the option appropriate to your environment.
If Access Manager is Installed on Sun Java System Web Server
- Enter the command
wdeploy deploy -u uri_path -i instance -v vs_id [-d directory] war_filewhere:
- uri_path is the URI prefix for the web application.
- instance is the server instance name.
- vs_id is the virtual server ID.
- directory is the directory to which the application is deployed. If not specified, the application is deployed to the document root directory.
- war_file is the WAR file name.
An example might be:
wdeploy deploy -u /sp1 -i www.sp1.com -v https-www.sp1.com
-d begin_dir/web-apps/sp1 sp1.war- Restart the Web Server.
If Access Manager is Installed on Sun Java System Application Server
- Use the asadmin deploy command to deploy the WAR module.
The complete syntax is:
asadmin deploy --user admin_user [--password admin_password] [--passwordfile password_file] --host hostname
--port adminport [--secure | -s] [--virtualservers virtual_servers] --type application|ejb|web|connector]
[--contextroot contextroot] [--force=true] [--precompilejsp=false] [--verify=false]
[--name component_name] [--upload=true]
[--retrieve local_dirpath]
[--instance instance_name] path_to_fileFor example:
asadmin deploy --user amadmin --password pswd1234
--host www.sp1.com --port 4848 --type web --contextroot SP1
--instance server1 sp1.war- Restart the Application Server.
Deploying the Identity Provider
The following sequence should be followed in order to deploy the identity provider:
To Configure AMClient.properties
Replace the following tags in the AMClient.properties file with values appropriate to your configuration. AMClient.properties is located in /AccessManager_base/SUNWam/samples/liberty/sample1/idp1/WEB-INF/classes/.
- SERVER_PROTO: Enter HTTPS or HTTP.
- SERVER_HOST: Enter the fully-qualified host name for your installation. For example, www.idp1.com.
- SERVER_PORT: Enter the port number on which Access Manager is running.
- SERVICE_DEPLOY_URI: Enter the Access Manager services deployment URI. The default value is amserver.
- META_ALIAS: Enter the metaAlias for IDP1. In idp1Metadata.xml, the default value is www.idp1.com.
To Create a WAR File for IDP1
To Deploy the Identity Provider WAR File
Choose the option appropriate to your environment.
If Access Manager is Installed on Sun Java System Web Server
- Enter the command
wdeploy deploy -u uri_path -i instance -v vs_id [-d directory] war_filewhere:
- uri_path is the URI prefix for the web application.
- instance is the server instance name.
- vs_id is the virtual server ID.
- directory is the directory to which the application is deployed. If not specified, the application is deployed to the document root directory.
- war_file is the WAR file name.
An example might be:
wdeploy deploy -u /idp1 -i www.idp1.com -v https-www.idp1.com
-d /AccessManager_base/SUNWam/web-apps/idp1 idp1.war- Restart the Web Server.
If Access Manager is Installed on Sun Java System Application Server
- Use the asadmin deploy command to deploy the WAR module.
The complete syntax is:
asadmin deploy --user admin_user [--password admin_password] [--passwordfile password_file] --host hostname
--port adminport [--secure | -s] [--virtualservers virtual_servers] --type application|ejb|web|connector]
[--contextroot contextroot] [--force=true] [--precompilejsp=false] [--verify=false]
[--name component_name] [--upload=true]
[--retrieve local_dirpath]
[--instance instance_name] path_to_fileFor example:
asadmin deploy --user amadmin --password pswd1234
--host www.idp1.com --port 4848 --type web --contextroot IDP1
--instance server1 idp1.war- Restart the Application Server.
Creating and Managing a Federation
The following sections provide procedures for creating, managing, and terminating a federation.
To Federate the Service Provider and Identity Provider Accounts
- Access the following URL in a web browser:
SERVER_PROTO//SERVER_HOST:PORT/sp1/index.jsp
For example, http://www.sp1.com:58080/sp1/index.jsp.
- Click the Local Login link on the common login page.
You are redirected to the SP1’s login page.
- Log in to SP1.
After successful authentication at SP1, the index.jsp is displayed. index.jsp has three links:
- Click the Federate link.
The Federate page is displayed.
- Select the identity provider with which you want to federate.
In Sample1, you would select the deployed IDP1 as your identity provider, and IDP1’s login page is displayed.
- Provide authentication credentials for your IDP1 account.
If the authentication is successful, the Federation Done page is displayed indicating that you have successfully federated these two accounts.
To Accomplish Single Sign-On
After successfully federating the two providers, follow these instructions to accomplish single sign-on.
- Start a new browser session and access the SP1 protected page, SERVER_PROTO//SERVER_HOST:PORT/sp1/index.jsp.
For example, http://www.sp1.com:58080/sp1/index.jsp.
- You will be redirected to the IDP1 Login page for authentication.
- Provide authentication credentials for your IDP1 account.
If authentication is successful, the initially accessed SP1 protected page is displayed without asking for SP1 authentication credentials. If authentication is not successful, an error message is displayed, and you are directed to start over.
To Perform a Single Logout
From either the SP1 protected page or the IDP1 protected page, index.jsp, click the Logout link. You will be logged out from both providers, and the Logout Done page is displayed.
Note
Both the service provider and identity provider have different protected index.jsp pages. The URLs are:
To Terminate Account Federation
- From either the SP1 protected page or the IDP1 protected page, click the Terminate Federation link.
The Federation Termination page is displayed.
- Select a provider to terminate your account federation.
For Sample1, select IDP1. Upon successful federation termination, the Termination Done page is displayed.
Note
Appendix A, "Included Samples" includes information on two more samples that make use of the Federation Management module.