Contained WithinFind More DocumentationFeatured Support Resources |  Download this book in PDF (1996 KB)
Part II Federation ManagementChapter 3 FederationSun 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 module to configure these components, allowing for Liberty-based provider federation. It covers the following topics: Process of FederationThe 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.1 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
Pre-login ProcessThe 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-OnWhen 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 for Federation Management 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 Federation Management for details. Federation Graphical User InterfaceThe 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.1 Developer’s Guide.
Entities and Authentication DomainsThe Federation component in the Access Manager Console provides an interface for configuring, modifying, and deleting authentication domains, and its member identity providers and service providers. To enable provider federation using Access Manager, create and populate an authentication domain using the following process:
Note – The establishment of contractual agreements between providers is beyond the scope of this guide. For information, see the Liberty Trust Model Guidelines. The following sections contain more detailed information: Tip – 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 time outs. EntitiesAn entity may be configured with metadata (configuration information that defines a particular identity service architecture) for an individual identity provider, an individual service provider, or one of each. Contrarily, an entity may be configured as an affiliation, a selected 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.
Configuring an entity using the Access Manager Console is a two-step process. First, you create a provider or affiliate entity. Then, you populate the entity with either remote or hosted provider metadata (either service or identity) or affiliation information. This process is described in the following sections.
Creating EntitiesThis section describes the process for creating a provider entity or an affiliate entity.
|
Caution –
amadmin --runasdn userdn --password password --import metadata_filename |
This option is usually used to load provider metadata sent from a trusted partner in an XML file compliant with the Liberty ID-FF. Here is an example of a service provider metadata XML file compliant with the Liberty ID-FF.
Example 3–1 Service Provider Standard Metadata XML File for amadmin
<!--
Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved
Use is subject to license terms.
-->
<EntityDescriptor meta:providerID="http://sp10.com" meta:cacheDuration="360"
xmlns:meta="urn:liberty:metadata:2003-08" xmlns="urn:liberty:metadata:2003-08">
<SPDescriptor cacheDuration="180" xmlns:meta="urn:liberty:metadata:2003-08"
aaa="aaa" protocolSupportEnumeration="urn:liberty:iff:2003-08">
<KeyDescriptor use="signing">
<EncryptionMethod>http://something/encrypt</EncryptionMethod>
<KeySize>4567</KeySize>
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Certificate xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
MIIC1DCCApICBD8poYwwCwYHKoZIzjgEAwUAMFAxCzAJBgNVBAYTAlVTMQwwCgYDVQQKEwNTdW4x
IDAeBgNVBAsTF1NVTiBPTkUgSWRlbnRpdHkgU2VydmVyMREwDwYDVQQDEwhzdW4tdW5peDAeFw0w
MzA3MzEyMzA5MDBaFw0wNDAxMjcyMzA5MDBaMFAxCzAJBgNVBAYTAlVTMQwwCgYDVQQKEwNTdW4x
IDAeBgNVBAsTF1NVTiBPTkUgSWRlbnRpdHkgU2VydmVyMREwDwYDVQQDEwhzdW4tdW5peDCCAbcw
ggEsBgcqhkjOOAQBMIIBHwKBgQD9f1OBHXUSKVLfSpwu7OTn9hG3UjzvRADDHj+AtlEmaUVdQCJR
+1k9jVj6v8X1ujD2y5tVbNeBO4AdNG/yZmC3a5lQpaSfn+gEexAiwk+7qdf+t8Yb+DtX58aophUP
BPuD9tPFHsMCNVQTWhaRMvZ1864rYdcq7/IiAxmd0UgBxwIVAJdgUI8VIwvMspK5gqLrhAvwWBz1
AoGBAPfhoIXWmz3ey7yrXDa4V7l5lK+7+jrqgvlXTAs9B4JnUVlXjrrUWU/mcQcQgYC0SRZxI+hM
KBYTt88JMozIpuE8FnqLVHyNKOCjrh4rs6Z1kW6jfwv6ITVi8ftiegEkO8yk8b6oUZCJqIPf4Vrl
nwaSi2ZegHtVJWQBTDv+z0kqA4GEAAKBgCNS1il+RQAQGcQ87GBFde8kf8R6ZVuaDDajFYE4/LNT
Kr1dhEcPCtvL+iUFi44LzJf8Wxh+eA5K1mjIdxOo/UdwTpNQSqiRrm4Pq0wFG+hPnUTYLTtENkVX
IIvfeoVDkXnF/2/i1Iu6ttZckimOPHfLzQUL4ldL4QiaYuCQF6NfMAsGByqGSM44BAMFAAMvADAs
AhQ6yueX7YlD7IlJhJ8D4l6xYqwopwIUHzX82qCzF+VzIUhi0JG7slSpyis=
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</KeyDescriptor>
<SingleLogoutServiceURL>http://www.sun.com/slo"</SingleLogoutServiceURL>
<SingleLogoutServiceReturnURL>http://www.sun.com/sloservice
</SingleLogoutServiceReturnURL>
<FederationTerminationServiceURL>http://www.sun.com/fts
</FederationTerminationServiceURL>
<FederationTerminationServiceReturnURL>http://www.sun.com/ftsr
</FederationTerminationServiceReturnURL>
<FederationTerminationNotificationProtocolProfile>http://projectliberty.org/profiles/
fedterm-sp-http</FederationTerminationNotificationProtocolProfile>
<SingleLogoutProtocolProfile>http://projectliberty.org/profiles/slo-sp-http
</SingleLogoutProtocolProfile>
<RegisterNameIdentifierProtocolProfile>http://projectliberty.org/profiles/
rni-sp-http</RegisterNameIdentifierProtocolProfile>
<RegisterNameIdentifierServiceURL>http://www.sun2.com/risu
</RegisterNameIdentifierServiceURL>
<RegisterNameIdentifierServiceReturnURL>http://www.sun2.com/rstu
</RegisterNameIdentifierServiceReturnURL>
<RelationshipTerminationNotificationProtocolProfile>http://projectliberty.org/
profiles/rel-term-soap</RelationshipTerminationNotificationProtocolProfile>
<NameIdentifierMappingBinding AuthorityKind="ppp:AuthorizationDecisionQuery"
Location="http://eng.sun.com" Binding="http://www.sun.com"
xmlns:ppp="urn:oasis:names:tc:SAML:1.0:protocol"></NameIdentifierMappingBinding>
<AdditionalMetaLocation namespace="abc">http://www.aol.com</AdditionalMetaLocation>
<AdditionalMetaLocation namespace="efd">http://www.netscape.com</AdditionalMetaLocation>
<AssertionConsumerServiceURL id="jh899" isDefault="true">
http://www.iplanet.com/assertionurl</AssertionConsumerServiceURL>
<AuthnRequestsSigned>true</AuthnRequestsSigned>
</SPDescriptor>
<ContactPerson xmlns:meta="urn:liberty:metadata:2003-08" contactType="technical"
meta:libertyPrincipalIdentifier="myid">
<Company>SUn Microsystems</Company>
<GivenName>Joe</GivenName>
<SurName>Smith</SurName>
<EmailAddress>joe@sun.com</EmailAddress>
<EmailAddress>smith@sun.com</EmailAddress>
<TelephoneNumber>45859995</TelephoneNumber>
</ContactPerson>
<Organization xmlns:xml="http://www.w3.org/XML/1998/namespace">
<OrganizationName xml:lang="en">sun com</OrganizationName>
<OrganizationName xml:lang="en">sun micro com</OrganizationName>
<OrganizationDisplayName xml:lang="en">sun.com</OrganizationDisplayName>
<OrganizationURL xml:lang="en">http://www.sun.com/liberty</OrganizationURL>
</Organization>
</EntityDescriptor>
|
Loading Proprietary Metadata Using amadmin
Access Manager provides proprietary attributes that are not a specific part of the Liberty ID-FF. To load Access Manager proprietary metadata use the following command:
amadmin --runasdn userdn --password password --data proprietary_metadata_filename |
After loading the metadata, the --export option can be used to export metadata compliant with the Liberty ID-FF. This file can then be exchanged with trusted partners. Here is an example of an identity provider metadata XML file for proprietary attributes.
Example 3–2 Identity Provider Proprietary Metadata XML File for amadmin
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Requests PUBLIC "-//iPlanet//Sun Java System Access Manager 2005Q4 Admin CLI
DTD//EN" "jar://com/iplanet/am/admin/cli/amAdmin.dtd">
<Requests>
<OrganizationRequests DN="dc=companyA,dc=com">
<CreateHostedProvider id="http://sp.companyA.com" role="SP"
defaultUrlPrefix="http://sp.companyA.com:80">
<AttributeValuePair>
<Attribute name="iplanet-am-provider-name"/>
<Value>sp</Value>
</AttributeValuePair>
<AttributeValuePair>
<Attribute name="iplanet-am-provider-alias"/>
<Value>sp.companyA.com</Value>
</AttributeValuePair>
<AttributeValuePair>
<Attribute name="iplanet-am-list-of-authenticationdomains"/>
<Value>samplecot</Value>
</AttributeValuePair>
<AttributeValuePair>
<Attribute name="iplanet-am-certificate-alias"/>
<Value>cert_alias</Value>
</AttributeValuePair>
<AttributeValuePair>
<Attribute name="iplanet-am-trusted-providers"/>
<Value>http://idp.companyB.com</Value>
<Value>http://idp.companyC.com</Value>
</AttributeValuePair>
<SPAuthContextInfo AuthContext="Password" AuthLevel="1"/>
<AttributeValuePair>
<Attribute name="iplanet-am-provider-homepage-url"/>
<Value>http://sp.companyA.com:80/idff/index.jsp</Value>
</AttributeValuePair>
</CreateHostedProvider>
</OrganizationRequests>
</Requests>
|
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.
To Create An Authentication Domain
-
In the Access Manager Console, click the Federation tab.
-
Under Federation, select the Authentication Domains tab.
-
Select New.
The New Authentication Domain attributes are displayed.
-
Type a name for the authentication domain.
-
(Optional) Type a description of the authentication domain in the Description field.
-
(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 for Federation Management.
-
(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 for Federation Management.
-
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 list of configured Authentication Domains.
To Configure or Modify an Authentication Domain
-
In the Access Manager Console, click the Federation tab.
-
Under Federation, select the Authentication Domains tab.
All created Authentication Domains are displayed.
-
Click the name of the authentication domain that you want to modify.
The General and Providers properties for the authentication domain are displayed.
-
(Optional) Enter or modify a description of the authentication domain in the Description field.
-
(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 for Federation Management.
-
(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 for Federation Management.
-
Select Active or Inactive.
The default status is Active. Selecting Inactive disables communication within the authentication domain.
-
Click Add to populate the authentication domain with providers.
The Trusted Providers page is displayed.
-
Choose from the list of Available Providers and click Add.
-
Click OK to save the providers to the authentication domain.
The authentication domain's attribute page is displayed.
-
Click Save to complete the configuration.
To Delete an Authentication Domain
Deleting an authentication domain does not delete the providers that belong to it although it will impact the trusted relationship.
-
In the Access Manager Console, click the Federation tab.
-
Under Federation, select the Authentication Domains tab.
All created Authentication Domains are displayed.
-
Select the check box next to the authentication domain that you want to delete.
-
Click Delete.
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 query parameters passed to Access Manager by the service provider via a URL.
A query 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; when more than one parameter exists, they are separated by an ampersand (&). Use the format http://hostname:port/deploy-uri/preLogin?metaAlias=metaAlias. Additional parameters are appended to the URL as ¶m1=value1¶m2=value2 and so on. These parameters and their usage and values are described in the following table.
Table 3–1 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:
|
|
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.1 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. |
|
goto |
The goto parameter takes as a value a URL to which the principal will be redirected after a successful SSO. If the value is not specified, default redirection will occur based on the value of the Provider Home Page URL attribute defined in the service provider configuration. The value of this URL can be configured by changing the iplanet-am-provider-homepage-url attribute in the amProviderConfig.xml file. |
|
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. |
In order to modify the pre-login URL, edit the relevant properties in either the AMConfig.properties file or the AMAgent.properties file, dependant on your deployment. See the following procedures for more information:
To Configure for Pre-login
In a federation setup, Access Manager acts as a service provider and manages an application that runs on a separate instance of Sun Java System Web Server. You must configure the agent that is protecting this application as follows:
-
Point the com.sun.am.policy.loginURL property in the AMAgent.properties file to the pre-login service URL running on Access Manager.
For example: com.sun.am.policy.loginURL = http://www.sp1.com:58080/amserver/preLogin?metaAlias=www.sp1.com
-
Point the com.sun.am.policy.am.library.loginURL in the AMAgent.properties file to the login URL of the instance of Access Manager acting as the service provider.
For example: com.sun.am.policy.am.library.loginURL = http://www.sp1.com:58080/amserver/UI/Login
To Configure for Global Logout
To implement the logout process for all service providers using the Liberty Logout method, do the following:
-
Copy the AMClient.properties file to the service provider's web container.
-
Revise the Logout method, as follows:
ResourceBundle rsbu =ResourceBundle.getBundle("AMClient"); String logouturl = rsbu.getString ("com.sun.identity.federation.client.samples.logoutURL"); response.sendRedirect(logouturl);
This revision is equivalent to a redirection to http://www.sp1.com:58080/amserver/liberty-logout?metaAlias=www.sp1.com.
Federation API
The following packages form the Federation API.
com.sun.identity.federation.plugins
The com.sun.identity.federation.plugins package contains the FederationSPAdapter interface which can be implemented to allow applications to customize their actions before and after invoking the federation protocols. For example, a service provider may want to choose to redirect to a specific location after single sign-on. For more detailed information, see the Java API Reference in /AccessManager-base/SUNWam/docs or on Sun Java System Access Manager 7.1 Java API Reference.
com.sun.identity.federation.services
The com.sun.identity.federation.services package provides interfaces for writing custom plug-ins that can be used during the federation or single sign-on process. The interfaces are described in the following table. For more detailed information, see the Java API Reference in /AccessManager-base/SUNWam/docs or on Sun Java System Access Manager 7.1 Java API Reference.
Table 3–2 com.sun.identity.federation.services Interfaces|
Interface |
Description |
|---|---|
|
FSAttributeMapper |
Plug-in for mapping the attributes passed from the identity provider to local attributes on the service provider side during the single sign-on. |
|
FSAttributePlugin |
Plug-in for an identity provider to add AttributeStatements into a SAML assertion during the single sign-on process. |
|
FSIDPProxy |
Interface used to find a preferred identity provider to which an authentication request can be proxied. |
com.sun.liberty
The com.sun.liberty package 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 Sun Java System Access Manager 7.1 Java API Reference.
Table 3–3 com.sun.liberty 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. |
Liberty ID-FF Operations
This section contains procedures illustrating how to use Access Manager to configure interactions based on the Liberty ID-FF. They are:
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.
To 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.
-
In the Access Manager Console, click the Federation tab.
-
Under Federation, select the Entities tab.
-
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.
-
Select Identity Provider or Service Provider from the View menu.
-
Select Access Manager Configuration.
-
Enable Auto Federation by checking the box.
-
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.
-
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:
-
spnameidentifiers.txt
-
idpnameidentifiers.txt
-
spuserdata.ldif
-
idpuserdata.ldif
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.
Configuring Trust Between Providers
In order to complete interactions based on the Liberty ID-FF, trust must exist between all communicating providers. Each provider that wishes to be part of a federated trust model does so after complex business negotiations, the exchange of provider configuration metadata, and the configuration of trust. Using the Access Manager console, trusted providers are configured using the metadata and are then grouped (as entities) into an authentication domain. To accomplish this, you load the provider metadata, and assign the configured providers to the same authentication domain. The following procedure explains how to configure trust using either the command line interface or the Access Manager console. Additional information can be found in Entities and Authentication Domains.
To Configure Trust Between Service Providers
and Identity Providers
Before You Begin
You must have metadata files specific to each provider you are configuring. Access Manager includes sample metadata XML files that you can modify for your purposes. See sample1 Directory for more information.
-
Load the hosted and remote provider metadata XML files to Access Manager using the amadmin command line interface.
See Creating and Configuring Entities using amadmin for information.
-
Login to the Access Manager console as amadmin, the default administrator.
-
Under Federation, click the Authentication Domains tab.
-
Select New.
The new Authentication Domain attributes are displayed.
-
Create the authentication domain and click OK.
See To Create An Authentication Domain for information.
-
Under Federation, click the Entities tab.
-
Select the name of a provider.
The provider was created when the metadata was loaded. The General attributes for the chosen provider are displayed.
-
Select the appropriate provider type from the View pull down menu.
-
Scroll down to Authentication Domains, select the authentication domain just created and click Add.
The authentication domain will be moved under Selected.
-
Click Save to store the change.
Repeat this configuration for all providers (remote and hosted) with which you want to establish trust.
-
Under Federation, click the Authentication Domains tab.
-
Select the name of the authentication domain which was previously created.
The General attributes are displayed.
-
Under Providers, click Add.
The Select Trusted Partner Type and Profile page is displayed.
-
Select the appropriate provider(s) as trusted members of the authentication domain and click Add.
The provider(s) will be moved under Selected.
-
Click OK to save the change.
-
Click Save to store the change.
Trust is now established between the appropriate providers.
Signing Liberty ID-FF Requests and Responses
Federation-based communications passing between identity providers and service providers are generally required to be digitally signed and verified. Signing and verifying messages provides data integrity, data origin authentication, and a basis for non-repudiation. To turn on signing for all Liberty ID-FF requests and responses emanating from your instance of Access Manager, set the value of the com.sun.identity.federation.services.signingOn property in AMConfig.properties to true and restart Access Manager and its web container. This allows for signing of Liberty ID-FF requests being sent and verification of signature validity for Liberty ID-FF responses received. If set to false, signing is disabled. If set to optional, requests and responses will be signed or verified only if required by the federation profile being used. After installation, AMConfig.properties is located in the etc/opt/SUNWam/config directory.
Note –
More information on com.sun.identity.federation.services.signingOn and the other identity federation properties in AMConfig.properties can be found in the Chapter 6, amConfig.properties Reference, in Sun Java System Access Manager 7.1 Administration Reference.
Additionally, you can enable the signing of an authentication request from a service provider configured on your instance of Access Manager, use the following procedure.
To Enable Signing of Service Provider Authentication
Requests
Before You Begin
A keystore must be set up before turning on the signing properties. See Appendix B, Key Management information on how to do this.
-
Log in to the Access Manager console as the top-level administrator, by default, amadmin.
-
Select the Federation tab.
-
Select the Entities tab.
-
Select the name of the entity that contains the service provider configuration for which you want to enable the signing of an authentication request.
-
Select Service Provider from the View pull-down menu.
-
Enable the Sign Authentication Request property under the Service Provider configuration and click Save.
-
Log out of the Access Manager console.
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.
To 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.
-
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.
-
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.
-
To configure machine 2, do the following:
-
To configure machine 2 as a service provider, deploy the SP1 WAR files.
Modify AMClient.properties to reflect this.
-
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.
-
-
Log in to machine 2 and modify the following metadata:
-
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.
-
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.
-
Save the configuration.
-
-
Also on machine 2, modify the following metadata regarding machine 3.
-
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.
-
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.
-
Set Maximum Number of Proxies to 1.
-
Save the configuration.
-
-
Federate a user between machine 3 (acting as a service provider) and machine 2 (acting as an identity provider).
-
Federate a user between machine 2 (acting as a service provider) and machine 1 (acting as an identity provider).
-
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.
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 for Federation Management.
Chapter 4 Common Domain Services for Federation Management
Sun Java System Access Manager provides the Common Domain Services for Federation Management that enable a service provider to determine the identity provider used by a principal in an authentication domain that contains multiple identity providers.
This chapter covers the following topics:
-
Configuring the Common Domain Services for Federation Management URLs
-
Configuring the Common Domain Services for Federation Management Properties
-
Installing the Common Domain Services for Federation Management
Common Domain
Service providers need a way to determine which identity provider is used by a principal requesting authentication. Because authentication domains are configured without regard to their location, this function must work across DNS-defined domains. Thus, a common domain is configured for this purpose. The common domain is established for use only within the scope of the Common Domain Services for Federation Management. In Access Manager deployments, the Common Domain Services for Federation Management are deployed in a web container installed in a predetermined and pre-configured common domain so that the common domain cookie is accessible to all providers in the authentication domain. If the HTTP server in the common domain is operated by the service provider, the service provider will redirect the user agent to the appropriate identity provider.
Let's suppose an authentication domain contains more than one identity provider; in this case, 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 have the means to determine the correct one. To ascertain a principal’s identity provider, the service provider invokes a protocol exchange to retrieve the common domain cookie, a cookie written for the purpose of introducing the identity provider to the service provider. If no common domain cookie is found when the principal issues a federation request, the service provider must present a list of trusted identity providers from which the principal will choose. After successful authentication, the identity provider writes (using the Writer Service URL as defined in Configuring the Common Domain Services for Federation Management URLs) a common domain cookie. The next time the principal attempts to access a service, the service provider finds and reads the common domain cookie (using the Reader Service URL as defined in Configuring the Common Domain Services for Federation Management URLs), to determine the identity provider.
After a principal authenticates with a particular identity provider, the identity provider redirects the principal's browser to their Common Domain Services for Federation Management using a parameter that indicates they are the identity provider for this principal. The Common Domain Services for Federation Management then writes a cookie using that parameter. Thereafter, all providers configured in this common domain will be able to tell which identity provider is used by the principal. For example, suppose an identity provider is available at http://www.Bank.com and a service provider is available via http://www.Store.com. If the common domain they define is RetailGroup.com, the addresses will be Bank.RetailGroup.com and Store.RetailGroup.com, respectively.
Note –
The Common Domain Services for Federation Management is based on the Identity Provider Introduction Profile detailed in the Liberty ID-FF Bindings and Profiles Specifications.
Common Domain Cookie
After an identity provider authenticates a principal, the identity provider sets a URL-encoded cookie that is defined in a predetermined domain common to all identity providers and service providers within the authentication domain. The common domain cookie is named _liberty_idp. After successful authentication, a principal’s identity provider appends their encoded identifier to a list in the cookie. If their identifier is already present in the list, the identity provider may remove the initial appearance and append it again. The intent is that the service provider reads the last identifier on the cookie’s list to find the principal’s most recently established identity provider.
The identifiers in the common domain cookie are a list of SuccinctID elements encoded in the Base64 format. One element maps to each identity provider in the authentication domain. Service providers then use this SuccinctID element to find the user's preferred identity provider.
Note –
When the request contains no common domain cookie, the service provider presents a list of trusted identity providers from which the principal may choose.
Configuring the Common Domain Services for Federation Management URLs
In Access Manager, the Common Domain Services for Federation Management are configured using two URLs that point to servlets developed for writing and reading the common domain cookie. They are:
Note –
For more information on how to configure these URLs, see To Create An Authentication Domain in Chapter 3, Federation.
Writer Service URL
The Writer Service URL is used by the identity provider. After successful authentication, the common domain cookie is appended with the query parameter _liberty_idp=entity-ID-of-identity-provider. This parameter is used to redirect the principal to the Writer Service URL defined for the identity provider. The URL is configured as the value for the Writer Service URL attribute when an authentication domain is created. Use the format http://common-domain-host:port/deployment-uri/writer where common-domain-host:port refers to the machine on which the Common Domain Services for Federation Management are installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs). The default URI is amcommon.
Reader Service URL
The Reader Service URL is used by the service provider. The service provider redirects the principal to this URL in order to find the preferred identity provider. Once found, the principal is redirected to the identity provider for single sign-on. The URL is defined as the value for the Reader Service URL attribute when an authentication domain is created. It is formatted as http://common-domain-host:port/deployment-uri/transfer where common-domain-host:port refers to the machine on which the Common Domain Services for Federation Management are installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs). The default URI is amcommon.
Configuring the Common Domain Services for Federation Management Properties
FSIntroConfig.properties is a file that contains properties used to configure the Common Domain Services for Federation Management. It is deployed as part of the web application and located in /AccessManager-base/web-src/common/WEB-INF/classes. It contains the properties described in the following table (which may be modified).
Table 4–1 Common Domain Services for Federation Management Properties in FSConfig.properties|
Property |
Description |
|---|---|
|
com.sun.identity.federation.services.introduction.cookiedomain |
The value of this property is the name of the common domain. |
|
com.sun.identity.federation.services.introduction.cookietype |
This property takes a value of either PERSISTENT or SESSION. PERSISTENT defines the cookie as one that will be stored and reused after a web browser is closed and reopened. SESSION defines the cookie as one that will not be stored after the web browser has been closed. |
|
com.iplanet.am.cookie.secure |
This property takes a value of either false or true. It defines whether the cookie needs to be secured or not. |
|
com.iplanet.am.cookie.encode |
This property takes a value of either false or true. It defines whether the cookie will be URL encoded or not. This property is useful if, for example, the web container that reads or writes the cookie decrypts or encrypts it by default. |
Installing the Common Domain Services for Federation Management
The Common Domain Services for Federation Management are installed as a web application within Access Manager using the Sun Java Enterprise System installer. However, the Common Domain Services for Federation Management can also be installed as a standalone web application (separate from the Access Manager product) on a Java Enterprise Edition web container. This option allows for generating common domain cookies on a machine on which Access Manager is not installed. Once the Common Domain Services for Federation Management is installed, you must set up the writer URL attribute for any identity providers and the reader URL for any service providers. These URLs point to the machine on which Common Domain Services for Federation Management is installed. For more information, see the Sun Java Enterprise System 5 Installation Guide for UNIX.
Tip –
In most real world deployments, installing the Common Domain Services for Federation Management on a separate machine is the obvious choice because of the need to setup a third-level common domain between service providers and identity providers in disparate enterprises.
To Test a Common Domain Services for Federation Management Installation
For troubleshooting, make sure the debug level property in FSIntroConfig.properties is set to message.
-
Install the Common Domain Services for Federation Management as a standalone application in a web container in the common domain.
Ensure that the common domain has been defined and the web container is installed in it.
-
Modify the properties in FSIntroConfig.properties as needed.
See Configuring the Common Domain Services for Federation Management Properties for more information.
-
Configure at least two identity providers for a service provider.
Ensure that the Writer Service URL is configured for each identity provider and the Reader Service URL is configured for each service provider.
-
Login as a user and complete federation and single sign-on between one identity provider and the service provider.
Ensure that the _liberty_idp cookie is set to the common domain.
-
Login as a user and complete federation and single sign-on between the second identity provider and the service provider.
After the initial successful federation and single sign-on, all service providers in the common domain are redirected to the first identity provider based on the information in the common domain cookie.
Note –Whether the cookie is persistent or for this browser session alone is dependent on how FSIntroConfig.properties is configured.