Main Page >
Liberty Sample Page
Liberty Samples
1. Introduction
This sample includes two Service Providers and two Identity Providers.
This sample demonstrates the different Liberty protocols such as Account
Federation, Single Sign On, Single Logout and Federation Termination.
This sample scenario requires only one Access Manager installation.
Four hosted providers (two Service Providers and two Identity Providers)
are created on the same Access Manager Installation. Each hosted provider
requires a virtual server instance. You need to host the same IP address
(on which the Access Manager is installed) in four different DNS domains.
This can be simulated by adding entries in the /etc/hosts file for the
fully qualified host names of the virtual servers.
Since there are multiple Identity Providers, you also need to install a
common domain service. This service will be installed with the Access
Manager default installation. You may choose to install it separately on
a different machine. This sample assumes on the same machine.
SP1 and SP2 are two Service Providers. IDP1 and IDP2
are two Identity Providers.
- We assume
<begin_dir> = <IS_Root>/SUNWam
-
<begin_dir>/samples/liberty/sample3/ will be referred to
as <sample3_dir> .
- The instruction is based on Sun Jave System Web Server 6.1sp4, for
other container like Sun Java System Application Server, WebLogics and
Websphere, equivalent steps need to be performed accordingly.
2. Instructions
A. Create and configure sub realms
For this sample you will need to create four sub realms under
the root realm. Each hosted provider will be associated with one
of these sub realm. The subOrgRequests.xml available
under <sample3_dir> will do it automatically.
The subOrgRequests.xml could be loaded in realm mode only.
If you are running in legacy mode, you need to login to console and perform
following steps manually:
a. Create four sub organizations namely sp1 , sp2 , idp1 and idp2 .
b. Register Core service and LDAP service for each of these sub organization.
c. Create service template for the registered services.
d. Create a sample user for each of these sub organizations. These sample
users will be created with user id as sp1User , sp2User , idp1User
and idp2User for the sub organizations sp1 , sp2 , idp1 and idp2
respectively. All the passwords are the same as the user id (i.e.
sp1User 's password is sp1User ).
- Update the
subOrgRequests.xml (available in <sample3_dir> ).
The following assumptions are made in this XML file.
a. Access Manager's root suffix is "dc=example,dc=com" (attribute "DN"
for elements "OrganizationRequests" and "PeopleContainerRequests")
b. Access Manager (AM) is running in HTTP mode.
c. AM services are deployed under the URI: amserver
d. The four virtual servers fully qualified host names are www.sp1.com,
www.sp2.com, www.idp1.com and www.idp2.com.
Update the above values in subOrgRequests.xml as your
deployment requirement.
- Load
subOrgRequests.xml using the following command.
<begin_dir>/bin/amadmin -u amadmin -w <amadmin's password>
-t <path>/subOrgRequests.xml
B. Upload the meta data:
This sample scenario requires four hosted providers. The metaData.xml
available under <sample3_dir> creates these hosted providers and configures
the meta data for all the providers.
- Update the
metaData.xml (available in <sample3_dir> ).
The following assumptions are made in this xml file.
a. Access Manager's root suffix is "dc=example,dc=com" (attribute "DN"
for elements "OrganizationRequests")
b. Access Manager(AM) is running in HTTP mode.
c. AM is running on port 58080
d. AM services are deployed under URI : amserver
e. Four virtual servers fully qualified host names are www.sp1.com,
www.sp2.com, www.idp1.com and www.idp2.com.
f. SP1 Certificate Alias is SP1_SECURITY_KEY
g. SP2 Certificate Alias is SP2_SECURITY_KEY
h. IDP1 Certificate Alias is IDP1_SECURITY_KEY
i. IDP2 Certificate Alias is IDP2_SECURITY_KEY
j. SP1 metaAlias is www.sp1.com
k. SP2 metaAlias is www.sp2.com
l. IDP1 metaAlias is www.idp1.com
m. IDP2 metaAlias is www.idp2.com
n. SP1's associated realm is sp1, associated organization is
"o=sp1org,dc=example,dc=com".
o. SP2's associated realm is sp2, associated organization is
"o=sp2org,dc=example,dc=coma".
p. IDP1's associated realm is idp1, associated organization is
"o=idp1org,dc=example,dc=com".
q. IDP2's associated realm is idp2, associated organization is
"o=idp2org,dc=example,dc=com".
r. Common domain service is installed on
"http://www.sp1.com:58080/amcommon/" (If it is installed on a
different machine, default port number will be 80)
Update the above values in the metaData.xml as your
deployment scenario.
Note: In the given metaData.xml common domain URL's host name is entered
as virtual host name (www.sp1.com ), in this case edit
FSIntroConfig.properties (located inside the
common domain WAR /WEB-INF/classes directory.
For SJS web server 6.1, by default it could be found at
<ws6_install_dir>/SUNWwbsvr/https-<host_name>/is-web-apps/common/WEB-INF/classes
directory)
to change the cookie domain value to ".sp1.com" .
For example set is as following :
com.sun.identity.federation.services.introduction.cookiedomain=.sp1.com
Alternatively use the original host name in the common domain URLs so
that you need not change the cookie domain value (it will be set for
the original host)
- Load the
metaData.xml using following command.
<begin_dir>/bin/amadmin -u amadmin -w <amadmin's password>
-t <path>/metaData.xml
- Login to console as admin.
- click "sp1" under Realms.
- click "Data Stores" tab.
- click "amSDK1" link.
- set o=sp1org,<root_suffix> in the "Access Manager Organization"
field, and click "Save" button.
- repeat 3-7 for "sp2", "idp1" and "idp2", use "o=sp2org", "o=idp1org"
and "o=idp2org" for corresponding "Access Manager Organization" field.
C. Create SP1 virtual server and Deploy SP1
This sample scenario requires four virtual servers. Urlhosts for these
virtual servers will be assumed as www.sp1.com , www.sp2.com ,
www.idp1.com and www.idp2.com .
- Update
SP1Config.properties (available in
<sp3_sample_dir> /sp1/WEB-INF/classes/ )
The following assumptions are made in this xml file.
a. Fully qualified host name for the SP1 virtual server is www.sp1.com
b. Access Manager (AM) is running in HTTP mode.
c. AM is running on port 58080
d. AM services are deployed under URI - amserver
e. SP1 metaAlias is www.sp1.com
Update the above values in the SP1Config.properties as per your
deployment scenario.
- Repate 1 for
SP2 , IDP1 and IDP2 .
- Login to web server as administrator.
- Click
<Manage> button to Manage server (In this case, it is
https-<fullhostname>).
- Click on Virtual Server Class.
- Click on Manage for the
"vsclass1"
- Click Add Virtual Server
- Name the "Name" to
sp1VS
- Select connections(In this case it is the default one)
- Add urlhosts entry to the domain for which the virtual server runs
on. For
sp1VS use www.sp1.com
- Click OK
- Repeat 6-11 for
SP2 , IDP1 and
IDP2 , create Virtual Server sp2VS ,
idp1VS and idp2VS for
www.sp2.com , www.idp1.com and
www.idp2.com respectively.
- Click Apply and Click Apply Changes. The server will be restarted.
- Click Virtual Server Class "vsclass1" and Click "sp1VS" under Tree View of
the Server.
- Click Web Applications
- On Server machine, create war file for
SP1
cd <sp1_sample_dir/sp1>
jar -cvf sp1.war
- War File On - Choose Server Machine and click Go
- War File Path - Enter the full patch that the war file we just
created.
- Application URI -
/sp1
- Installation Directory - accept default, modify if needed.
- Click OK. Virtual server created.
- Repeat 14-21, select
sp2VS , idp1VS and
idp2VS virtual server, deploy URI /sp2 ,
/idp1 and /idp2 for SP2 ,
IDP1 and IDP2 respectively
- Click Apply and Click Apply Changes. The server will be restarted.
- Edit server.xml (located at
<ws6_install_dir>/SUNWwbsvr/https-<host_name>/config directory for SJS web server),
copy service, console(legacy mode only), password and common domain web
application from default virtual server (https-<host_name>) to
sp1VS virtual server. For example, for SJS web server 6.1,
sp1VS will looks like this:
<VS id="sp1VS" state="on" connections="ls1" urlhosts="www.sp1.com" mime="mime1" aclids="acl1">
<USERDB id="default" database="default"/>
<WEBAPP uri="/amserver" path="/opt/SUNWwbsvr/https-host.sun.com/is-web-apps/services" enabled="true"/>
<WEBAPP uri="/ampassword" path="/opt/SUNWwbsvr/https-host.sun.com/is-web-apps/password" enabled="true"/>
<WEBAPP uri="/amcommon" path="/opt/SUNWwbsvr/https-host.sun.com/is-web-apps/common" enabled="true"/>
<WEBAPP uri="/sp1" path="/opt/SUNWwbsvr/https-host.sun.com/webapps/sp1VS/sp1" enabled="true"/>
</VS>
- Repeat step 24 for
sp2VS , idp1VS and
idp2VS
- Retsart Web Server.
D. Configure Access Manager for SP1 virtual server:
- Login to the Access Manager as amadmin and go to the Configuration tab.
- Click on Platform service under System Properties section.
- Click "New" under "Instance Name".
- Enter "<protocol>://www.sp1.com:<port>" in Server field,
enter "02" in Instance Name.
- Click OK
- Repeat step 3-5 for <protocol>://www.sp2.com:<port> with
03, <protocol>://www.idp1.com:<port> with 04,
<protocol>://www.idp2.com:<port> with 05.
- In Cookie Domains field, add ".sp1.com", ".sp2.com", ".idp1.com"
and ".idp2.com"
- Click Save.
- Add
fqdnMap entry for SP1 virtual server in
/etc/opt/SUNWam/config/AMConfig.properties :
com.sun.identity.server.fqdnMap[www.sp1.com]=www.sp1.com
The FQDN Map is a simple map that enables Access Manager Authentication
service to take corrective action in the case where the users may have
typed in an incorrect URL such as by specifying partial hostname or
using an IP address to access protected resources. This property can be
used for creating a mapping for more than one hostnames. This may be the
case when the applications hosted on this server are accessible by more
than one hostnames.
- Repeat step 9 for
SP2 , IDP1
and IDP2 , use www.sp2.com ,
www.idp1.com and www.idp2.com respectively.
- Restart the web server and the Access Manager.
E. Federate user account at SP1 with an account at IDP1 :
- Access the following url in a web browser
SERVER_PROTO://SERVER_HOST:SERVER_PORT/sp1/index.jsp
This index.jsp has following three links:
a. Federate - will initiate the federation process.
b. Logout - will initiate the single logout process.
c. Terminate Federation - will initiate the federation termination
process.
Here index.jsp is a protected page which includes _head.jsp . The
_head.jsp will check for valid user session and if session is invalid
it will redirect to preLogin service. The preLogin service will try to
do Single Sign On, since it is a first time access, Single Sign On will
fail and the preLogin service will redirect to the common login page.
- On the common login page click on "Local Login" link, you will be
redirected to the
SP1 's login page.
- After successful authentication at
SP1 , you will be redirected to
the index.jsp where you can choose Federate/Logout/Terminate Federation.
- If you choose to federate, you will be taken to the Federate page
where you can select your preferred Identity Provider to federate with.
Select
IDP1 as the preferred Identity Provider.
- Now you will be taken to
IDP1 's login page where you need to
provide authentication credentials (user-id/password) for the IDP1
account (in this case idp1User/idp1User ). If the authentication is
successful, you will be shown the FederationDone page.
- At this point you have successfully federated your account between
SP1 and IDP1 .
Note: When an account is already federated, the you will be redirected
to the IDP1 Login page first, assuming the common domain service is
properly configured. If the common domain service is not configured
properly then you will see the commonLogin page where you can click on
the IDP1 's link with which you have federated your SP1 account.
- Repeat step 1-6 to federate your
SP2 account (sp2User ) with the
IDP1 account (idp1User ).
F. Single Sign On:
- After successful federation start a new browser session and try to
access
SP1 protected page (index.jsp ):
SERVER_PROTO://SERVER_HOST:SERVER_PORT/sp1/index.jsp
For example
http://www.sp1.com :58080/sp1/index.jsp
Note: If the earlier session is still valid in the new browser, then
single logout should be done first. See section H for this.
- Now you will be taken to
IDP1 's login page (Again assuming that
the common domain is configured properly). You need to provide
authentication credentials for the user account at IDP1 . If
authentication is successful you will be directly taken to the initially
accessed SP1 protected page without being asked for SP1 authentication
credentials.
- Now in the same browser try to access
SP2 's protected page
(http://www.sp2.com:58080/sp2/index.jsp ), you will be allowed to access
this protected page without being asked for authentication at SP2
(Assuming that you have federated your SP2 account with the account at
IDP1 ). Again, if common domain is not configured you will see
commonLogin page where you can select a preferred IDP , with which you
federated your account. After clicking on the IDP 's link you will be
able to see the SP2 's initially accessed protected page.
- Similarly you can demonstrate federation and single sign on with an
account at
IDP2 by repeating all the steps in section F and section
G by selecting IDP2 as the preferred IDP .
G. Single Logout:
- On
SP1 's protected page (index.jsp ) click on "Logout" link.
- You will be logged out from all the valid sessions (in this case
SP1 ,
SP2 and IDP1 )s and will be shown a LogoutDone page.
- Alternatively, you can start the logout process from the
IDP protected
page (index.jsp ) as well and accomplish the same.
H. Federation Termination:
- On the
SP1 's protected page (index.jsp ) click on
"Terminate Federation" link.
- You will be taken to a page where you can select a provider to
terminate the federation. For example select
IDP1 for federation
termination.
- On successful federation termination you will be taken to
TerminationDone page.
- Alternatively, you can initiate federation termination from the
IDP
side also and get the same result.
I. Name ID Mapping:
- For the encryption to work, you need to download JCE
provider and set it up in your JDK and web container, if these
were not previously done yet:
a. Download, for example, bouncy castle JCE provider from
"ftp://ftp.bouncycastle.org/pub/release1.28". For JDK 1.5, select
bcprov-jdk15-128.jar; for JDK 1.4, select bcprov-jdk14-128.jar.
b. Copy the above jar file to <jdk_root>/jre/lib/ext directory
c. For domestic version of JDK, download JCE Unlimited Strength Jurisdiction
Policy Files from Sun site (http://java.sun.com) for your version of JDK.
For WebSphere, please go to corresponding IBM site to download.
d. Copy downloaded US_export_policy.jar and local_policy.jar to
<jdk_root>/jre/lib/security directory.
e. Edit <jdk_root>/jre/lib/security/java.security file, add bouncy
castle as one of the provider, for example:
security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider
f. Restart your container.
- This test requires that there are an existing federation between
sp1User and idp1User , and another existing federation between
sp2User and idp1User .
- To perform this test, some preparation on encryption is needed if
encryption is turned on, i.e., if "Enable Mapped Name Identifier
Encryption" attribute for
IDP1 (on IDP1 's administration
console, Federation Management->Entity Provider->www.idp1.com)
is "true" which is the default value.
- Request and Install an encryption certificate on the
SP2 site, the
procedure is the same as installing a certificate for XML signature, see
the Readme file under .../SUNWam/samples/saml/xmlsig for details. If
there is a signature certificate already installed, then it can be
shared by encryption, and this step can be omitted.
- Then go to
SP2 's administration console to specify the alias of this
certificate under "Encryption Key Alias", the key size under
"Encryption Key Size" (e.g. 256), and the encryption method under
"Encryption method" (e.g., AES).
- Now install the above certificate in
IDP1 's key store.
- Then go to
IDP1 's administration console, and go to
Federation Management->Entity Provider->www.sp2.com
and specify those three attributes with the same values as above. Now
the preparation is done, and the actual test can begin.
- On
SP1 's protected page (index.jsp ) click on "Name ID Mapping"
link.
- Two text fields "Target Name Space" and "Target Decryption URL" will
show up to be filled in. "Target Name Space" will be
SP2 's provider ID;
In the case of this sample, it would be http://www.sp2.com . "Target
Decryption URL" will be the URL for DecryptNameID.jsp which is deployed
on SP2 ; In the context of this sample, it will be
"http://www.sp2.com/sp2/DecryptNameID.jsp" . If your server
is not running on port 80, you need to add your port number after
www.sp2.com in the URL.
- After those two fields are correctly filled in and
"send NameIDMappingRequest" button is clicked, the desired name ID will
appear in a browser page.
Here is what really happens: First, SP1 sends the Name ID Mapping request
to IDP; Then IDP encrypts the Name ID with SP2's public key, and sends the
encrypted Name ID to SP1 through Name ID Mapping response; Finally, SP1
sends the encrypted Name ID to SP2, and then SP2 decrypts the Name ID.
|