Main Page
Achieving Single Sign On using SAML profile
1. Introduction
This sample illustrates how to achive Single Sign On using Web/Artifact
and Web/POST profiles.
2. Single Sign On using SAML Web/Artifact profile
This sample application aims to demonstrate and explain how to achieve
SSO between two different Access Manager installations using
SAML's Web Artifact profile. In brief Web Artifact profile is something
like follows:
A web user authenticates to a source site. The web user then uses a
secured resource at a destination site, without directly authenticating to
the destination site. The following assumptions are made about this
scenario for the purpose of this profile:
a. The user is using a standard commercial browser and has
authenticated to a source site by some means outside the scope
of SAML . In Access Manager, Authentication service
is used by the SAML Service to achieve this
authentication.
b. The source site has some from of security engine in place that can
track locally authenticated users. This typically takes the form of
a session represented by an encrypted cookie or an encoded URL or
some other technology. Access Manager SAML Service uses the
SSOToken object stored as a cookie to track this piece of
information.
At some point, the user attempts to access a target resource available
from the destination site, and subsequently, through one or more steps
(for example, redirection), arrives at an inter-site transfer service (which
may be associated with one or more URIs) at the source site. Starting from
this point, the web browser SSO profiles describe a canonical
sequence of HTTP exchanges that transfer the user browser to an assertion
consumer service at the destination site. Information about the SAML
assertions provided by the source site and associated with the user, and
the desired target, is conveyed from the source to the destination site by
the protocol exchange. The assertion consumer service at the destination
site can examine both the assertions and the target information and
determine whether to allow access to the target resource, thereby
achieving web SSO for authenticated users originating
from a source site.
Step 1: Accessing the Inter-Site Transfer Service
In step 1, the user's browser accesses the inter-site transfer service,
with information about the desired target at the destination site attached
to the URL.
http://<inter-site transfer host name and path>?TARGET=<Target>
where
<inter-site transfer host name and path>
This provides the host name, port number, and path components of an
inter-site transfer URL at the source site. This is
<protocol>:<servername>:<port>/amserver/SAMLAwareServlet
in Access Manager Server.
Target=<Target>
This name-value pair occurs in the <searchpart> and is used to convey
information about the desired target resource at the destination site.
Step 2: Redirecting to the Destination Site
In step 2, the source site's inter-site transfer service responds and
redirects the user's browser to the assertion consumer service at the
destination site.
http://<artifact receiver host name and path>?<SAML searchpart>
where
< artifact receiver host name and path>
This provides the host name, port number, and path components of an
artifact receiver URL associated with the assertion consumer service
at the destination site. In Access Manager Server terms we call it the
Partner URL i.e. the URL of the partner which receives the Artifact in
the query string, with who we are trying to achieve the SSO.
<SAML searchpart>= ?TARGET=<Target>?SAMLart=<SAML artifact> ?
A single target description MUST be included in the <SAML searchpart>
component.
Step 3: Accessing the Artifact Receiver URL
In step 3, the user's browser accesses the artifact receiver URL, with
a SAML artifact representing the user's authentication information attached
to the URL. This is actually a redirection which happens internally between
inter site service and the artifact receiver of the partner.
Internally a HTTP Get is made to
http://<artifact receiver host name and path>?<SAML searchpart>
where
<artifact receiver host name and path>
This provides the host name, port number, and path components of an
artifact receiver URL associated with the assertion consumer service
at the destination site.
<SAML searchpart>= ?TARGET=<Target>?SAMLart=<SAML artifact> ?
Steps 4 and 5: Acquiring the Corresponding Assertions
In steps 4 and 5, the destination site, in effect, dereferences the one
or more SAML artifacts in its possession in order to acquire the SAML
authentication assertion that corresponds to each artifact.
These steps MUST utilize a SAML protocol binding for a SAML
request-response message exchange between the destination and source
sites. The destination site functions as a SAML requester and the
source site functions as a SAML responder.
The destination site MUST send a <samlp:Request> message
to the source site, requesting assertions by supplying assertion artifacts
in the <samlp:AssertionArtifact> element. The request is sent using
SOAP over HTTP(s) to the SOAP responder of the source
site. In Access Manager this is the
<protocol>:<servername>:<port>/amserver/SAMLSOAPReceiver
Step 6: Responding to the User's Request for a Resource
In step 6, the user's browser is sent an HTTP response that either allows
or denies access to the desired resource.
3. Single Sign On using SAML Web Browser/POST profile
The web browser/POST profile of SAML allows authentication information
to be supplied to a destination site without the use of an artifact.
There are three parties involved in the browser/POST profile. They are:
Browser, Source Site, and Destination Site. The browser/POST profile
consists of a series of two interactions, the first between a user
equipped with a browser and a source site, and the second directly
between the user and the destination site. The following section
elucidates the four steps involved in browser/POST profile.
Step 1: Accessing the Inter-Site Transfer Service
The user's browser accesses the inter-site transfer service, with
information about the desired target at the destination site attached
to the URL.
Step 2: Generating and Supplying the Response
The source site generates HTML form data containing a SAML Response
which contains an SSO assertion.
Step 3: Posting the Form Containing the Response
The browser submits the form containing the SAML response to the
destination site.
Step 4: Responding to the User's Request for a Resource
The user's browser is sent an HTTP response that either allows or denies
access to the desired resource.
4. Sun Car Rental Sample Application
This Sample Application demonstrates Single Sign On between 2 Access
Manager installations. A user is setup on one machine with email address
of username@sun.com (amadmin here) and the postaladdress attribute (Home
Address on administration console) is used as the membership level of the
user either gold , silver or bronze . Once the user logs
into the source site, web browser/Artifact profile or web browser/POST
profile is used to achieve SSO . Some user specific attributes
are also sent along with the SSO Assertion as Attribute Statements. This
is determined by the siteAttributeMapper plugin
(TestSiteAttributeMapper.java as bundled with the sample and present in
com.iplanet.am.samples.saml.sso package) It is located under
<INSTALL_DIR>/SUNWam/samples/saml/sso/ directory. When the SAML
Service performs the SSO it calls this configured plugin (This
configuration is per partner as configured in the trusted site list and
explained in the next section), which returns a list of Attributes which
are then sent back as Attribute Statements as part of the SSO Assertion.
The destination site receives this Assertion and looks up the POST to target
URLs configured on its site; if it finds the TARGET its supposed to
redirect to in the list, along with redirecting to TARGET it also does a
FORM POST of the Assertion to the TARGET (which is demo/app_artifact.jsp
or demo/app_postprofile.jsp in this case). app_artifact.jsp
/app_postprofile.jsp reads the Assertion POSTed and redirects the user to
gold , silver or bronze page based on the membership level. It
also displays some pertinent information from the Assertion in a small
window on the left like:
Authentication authority, email address, user id, membership level.
Links on left allow user to access other pages, with access control
enforced based on user's membership level. For example if the user has
silver member level, then on clicking on link meant for "gold members"
an error message is displayed. Link "Visit Inter Site Service" takes
the user to the site's inter site service from where the user can again
do a SSO with the other machine.
Access Manager SAML Service Configuration
Now, let's get down to doing the configuration needed in the Access
Manager server to make this SSO happen.
The current sample is for achieving SSO between 2 machines
arth.red.iplanet.com (lets call it A) and greed.sun.com (B). For
achieving SSO between any other machines make machine names changes as the
situation demands. Also in this example configuration it has been assumed
that the deployment URI is amserver and the port is 58080 and the protocol
is http . This configuration will have to be changed accordingly if the
configuration scenario is different. Example if the port is 444 then
wherever I have mentioned 58080 replace that with 444.
The following configuration steps need to be followed, as user amadmin . Go
to http://servername:port/amconsole
- On machine B go into
Service Management->SAML->SiteID and issuer name
where there is an entry like:
instanceID=greed.sun.com:58080|siteid=Yl1KZ1qcHktuAdSDBSAO4Wkcz6c=|
issuerName=greed.sun.com:58080
copy the siteID string which is Yl1KZ1qcHktuAdSDBSAO4Wkcz6c=
here and use it as specified in step 3.
- Get the
IP address of machine B (say 192.12.12.34)
- On machine A go to
Service Management->SAML->trusted partner sites add
the following entry for machine B (a trusted partner with who we wish to
achieve SSO ).
sourceID=Yl1KZ1qcHktuAdSDBSAO4Wkcz6c=
SAMLUrl=http://greed.sun.com:58080/amserver/SAMLAwareServlet
POSTUrl=http://greed.sun.com:58080/amserver/SAMLPOSTProfileServlet
target=greed.sun.com
hostlist=192.12.12.34
siteattributemapper=com.iplanet.am.samples.saml.sso.TestSiteAttributeMapper
SOAPUrl=http://greed.sun.com:58080/amserver/SAMLSOAPReceiver
issuer=greed.sun.com:58080
where the source ID is as saved in 1 and hostlist=<IP address> is IP
address of machine B.
- On A, go to
ServiceManagement->SAML->POST to Target URLs and add
http://arth.red.iplanet.com:58080/demo/app_artifact.jsp then add
another one http://arth.red.iplanet.com:58080/demo/app_postprofile.jsp
- On machine A go into
Service Management->SAML->SiteID and issuer name
where there is an entry like:
instanceID=arth.red.iplanet.com:58080|
siteid=VoKyj7WH9TJjfl/sX31iakdFKQA=|issuerName=arth.red.iplanet.com:58080
copy the siteID string which is here VoKyj7WH9TJjfl/sX31iakdFKQA= and use
it as specified in step 7.
- Get the
IP address of machine A (say 192.12.12.33)
- On machine B go to
Service Management->SAML->trusted partner sites
add the following entry for machine A (a trusted partner with who we
wish to achieve SSO ).
sourceID=VoKyj7WH9TJjfl/sX31iakdFKQA=
SAMLUrl=http://arth.red.iplanet.com:58080/amserver/SAMLAwareServlet
POSTUrl=http://arth.red.iplanet.com:58080/amserver/SAMLPOSTProfileServlet
target=arth.red.iplanet.com
hostlist=192.12.12.33
siteattributemapper=com.iplanet.am.samples.saml.sso.TestSiteAttributeMapper
SOAPUrl=http://arth.red.iplanet.com:58080/amserver/SAMLSOAPReceiver.
issuer=arth.red.iplanet.com:58080
- On machine B, go to
ServiceManagement->SAML->POST to Target URLs and
add http://greed.sun.com:58080/demo/app_artifact.jsp , then add another
one http://greed.sun.com:58080/demo/app_postprofile.jsp
The rest of the instructions need to be followed for both machines.
- cd
/<INSTALL_DIR>/SUNWam/samples/saml/sso/ as root and run
gmake . In the build environment its in /tools/ns/bin/gmake . For Windows
machines go to where the product has been installed SunONE/SunONEIS by
default, so for default go to /SunONE/SunONEIS/samples/sso/ and run
make.bat .
- cp
SAMLSampleApp.jar /<INSTALL_DIR>/SUNWam/lib for Solaris.
For Windows, this file gets copied automatically in the installation's
lib directory.
- Change web server's classpath. In
<WEB_SERVER_INSTALL_DIR>/https-<servername>/config/server.xml add
/<INSTALL_DIR>/SUNWam/lib/SAMLSampleApp.jar to the serverclasspath
- Deploy the application per the web container Access Manager is
deployed on. For example on Sun Java System Web Server 6.1 the deploy
location will be
<WEB_SERVER_INSTALL_DIR>/docs .
cp -r <INSTALL_DIR>/SUNWam/samples/saml/sso/demo
<WEB_SERVER_INSTALL_DIR>/docs/demo/.
In case of Windows use the appropriate means available to copy
directory recursively. Ensure that directory
<WEB_SERVER_INSTALL_DIR>/docs/demo/ gets created and has following
structure:
<WEB_SERVER_INSTALL_DIR>/docs/demo/
|- app_artifact.jsp
|- demo_artifact.jsp
|- reserve.html
|- app_postprofile.jsp
|- demo_postprofile.jsp
|- silver.jsp
|- bronze.jsp
|- gold.jsp
|- contact.html
|- images
|- corp-main-smp-screen.jpg
|- sunOne.gif
|- corp-main-smp-shirtback.jpg
- cd
/<INSTALL_DIR>/docs/demo/ . For Windows machines
go to where the product has been installed SunONE/SunONEIS by default,
so for default go to /SunONE/SunONEIS/docs/demo/ . As install user
(root here for Solaris), in file demo_artifact.jsp and
demo_postprofile.jsp on machine B replace both <PARTNER_HOST> occurences
by machine A's name. For example, in demo_artifact.jsp , in the lines
looking like this:
<td><a>PARTNER_HOST</a></td>
<td><a href="<%= reqBase%>/amserver/SAMLAwareServlet?
TARGET=http://PARTNER_HOST:58080/demo/app_artifact.jsp">
Car Rental Application</a></td>
On machine B changes to
<td><a>arth.red.iplanet.com</a></td>
<td><a href="<%= reqBase%>/amserver/SAMLAwareServlet?
TARGET=http://arth.red.iplanet.com:58080/demo/app_artifact.jsp">
Car Rental Application</a></td>
For example, in demo_postprofile.jsp , in the lines looking like this:
<td><a>PARTNER_HOST</a></td>
<td><a href="<%= reqBase%>/amserver/SAMLPOSTProfileServlet?
TARGET=http://PARTNER_HOST:58080/demo/app_postprofile.jsp">
Car Rental Application</a></td>
On machine B changes to
<td><a>arth.red.iplanet.com</a></td>
<td><a href="<%= reqBase%>/amserver/SAMLPOSTProfileServlet?
TARGET=http://arth.red.iplanet.com:58080/demo/app_postprofile.jsp">
Car Rental Application</a></td>
For machine A put machine B's name for the above string.
- cd
/<WEB_SERVER_INSTALL_DIR>/docs/demo/ . For Windows machines go
to where the product has been installed SunONE/SunONEIS by default, so
for default go to /SunONE/SunONEIS/docs/demo/ . In files reserve.html
and contact.html replace
PROTOCOL by the protocol (http in this sample)
SERVERHOST by server name being used (arth.red.iplanet.com on machine
A and greed.sun.com on B in this sample)
SERVERPORT by the port the Access Manager server is running on (58080
in this sample).
If the deployment URI is different from amserver please replace
amserver by the URI in these two files after editing them manually.
- To test web browser/post profile, the user has to set up an
keyentry
in a keystore . For details, please refer to
<INSTALL_DIR>/SUNWam/samples/saml/xmlsig/keytool.txt (on Solaris) or
<INSTALL_DIR>/samples/saml/xmlsig/keytool.txt (on Windows).
- Start the Sun Java System web server.
- Log in as
amadmin , to http://servername:port/amconsole
Go to Identity Management->Users->amadmin
Add email address as amadmin@sun.com and "Home Address" as "gold" or
"silver" or "bronze". (For sample purposes we are trying to use the
attribute postaladdress to represent membership level of user.)
- Log in as
amadmin , to http://servername:port/amconsole
Go to Identity Management->Services->Add
Add 'SAML' authentication module service under Authentication Service.
Create and save template for this SAML authentication module service.
Click on 'Core' under Authentication Service.
Select / highlight 'SAML' in the 'Organization Authentication Modules' list.
Save the changes and Logout.
Now we are all set.
To test web browser/Artifact profile, go to
http://arth.red.iplanet.com:58080/demo/demo_artifact.jsp ,
log in as amadmin , Click on "Sun Car Rental" next to the greed.sun.com
you should be able to SSO to machine B as see the sample Application.
Depending on the entry you specified in the postaladdress attribute
gold/silver/bronze you should see different pages.
To test web browser/POST profile, go to
http://arth.red.iplanet.com:58080/demo/demo_postprofile.jsp , log in as
amadmin , Click on "Sun Car Rental" next to the greed.sun.com you should be
able to SSO to machine B as see the sample Application. Depending on the
entry you specified in the postaladdress attribute gold/silver/bronze you
should see different pages.
Now can go the other way around, do SSO from B to A, after choosing
"Visit Inter Site Service".
NOTE: if <INSTALL_DIR>/lib/AMConfig.properties has debug=message , debug
logs can be found at /var/opt/SUNWam/debug/samlSample and
/var/opt/SUNWam/debug/amSAML for Solaris and /SunONE/SunONEIS/debug
directory on Windows.
5. Configure with SSL with client Authentication Enabled
If the Access Manager is running SSL with client authentication on (which
is the recommended one for SAML Service), one needs to do the following
steps in addition to the above mentioned configuration.
- Assuming docs to turn
SSL on from administration guide have been
followed and the access manager is already running SSL with client
authentication successfully.
- In the above configuration replace all instances of
"http" in the URLs
with "https" , including the the protocol in "POST to target URLs"
parameter. In addition under "Service Configuration" - > SAML -> site ID
and site issuer name, replace the protocol in the instance ID attribute
to "https" too.
- In the points 3 and 7 in the above section add one more attribute to
the trusted partner configuration.
authtype=SSL
The point is that the server whose configuration is being defined in
trusted partner list is running in SSL then this attribute needs to be
specified. If only one server is running SSL and the other is not then
this attribute will be set on the non SSL server for trusted partner
info. of the server running SSL .
- For machine A (
arth ) import the client certificate of machine B
(greed ) into the certdb by running the following command as root.
For Solaris
setenv LD_LIBRARY_PATH <WEB_SERVER_INSTALL_DIR>/bin/https/lib
cd <WEB_SERVER_INSTALL_DIR>/bin/https/admin/bin
./certutil -A -n greed -t P -d <WEB_SERVER_INSTALL_DIR>/alias -P
https-arth.red.iplanet.com-arth- -f /etc/opt/SUNWam/config/.wtpass
-i infile
where:
-d is the com.iplanet.am.admin.cli.certdb.dir parameter from
<INSTALL_DIR>/SUNWam/lib/AMConfig.properties
-P is the com.iplanet.am.admin.cli.certdb.prefix parameter from
<INSTALL_DIR>/SUNWam/lib/AMConfig.properties
-f is the com.iplanet.am.admin.cli.certdb.passfile parameter from
<INSTALL_DIR>/SUNWam/lib/AMConfig.properties
-i is the client certificate of B (greed).
For Windows
Assuming product is installed in c:\sunone\sunoneis directory
cd to c:\sunone\sunoneis\bin\https\admin\bin
certutil -A -n greed -t P -d c:\sunone\sunoneis\alias
-P -P https-arth.red.iplanet.com-arth- -f \sunone\sunoneis\config\.wtpass
-i infile
where:
-d is the com.iplanet.am.admin.cli.certdb.dir parameter from
c:\sunone\sunoneis\lib\AMConfig.properties
-P is the com.iplanet.am.admin.cli.certdb.prefix parameter from
c:\sunone\sunoneis\lib\AMConfig.properties
-f is the com.iplanet.am.admin.cli.certdb.passfile parameter from
c:\sunone\sunoneis\lib\AMConfig.properties
-i is the client certificate of B (greed).
-n is the nickname of the certificate.
- For machine B (
greed ) import the client certificate of machine A
(arth ) into the certdb by running the following command
For Solaris
as user "root"
setenv LD_LIBRARY_PATH <WEB_SERVER_INSTALL_DIR>/bin/https/lib
cd <WEB_SERVER_INSTALL_DIR>/bin/https/admin/bin
./certutil -A -n arth -t P -d <WEB_SERVER_INSTALL_DIR>/alias -P
https-greed.sun.com-greed- -f /etc/opt/SUNWam/config/.wtpass
- i infile
where:
-d is the com.iplanet.am.admin.cli.certdb.dir parameter from
<INSTALL_DIR>/SUNWam/lib/AMConfig.properties
-P is the com.iplanet.am.admin.cli.certdb.prefix parameter from
<INSTALL_DIR>/SUNWam/lib/AMConfig.properties
-f is the com.iplanet.am.admin.cli.certdb.passfile parameter from
<INSTALL_DIR>/SUNWam/lib/AMConfig.properties. If this file does
not exist it needs to be created first and the password put there,
in cleartext.
-i is the client certificate of B (arth).
For Windows
Assuming product is installed in c:\sunone\sunoneis directory
Add c:\sunone\sunoneis\bin\https\lib to the PATH environment variable.
cd c:\sunone\sunoneis\bin\https\admin\bin
certutil -A -n arth -t P -d c:\sunone\sunoneis\alias
-P -P https-greed.red.iplanet.com-greed
-f \sunone\sunoneis\config\.wtpass
-i infile
where:
-dg is the com.iplanet.am.admin.cli.certdb.dir parameter from
c:\sunone\sunoneis\lib\AMConfig.propertiesg
-Pg is the com.iplanet.am.admin.cli.certdb.prefix parameter from
c:\sunone\sunoneis\lib\AMConfig.propertiesg
-fg is the com.iplanet.am.admin.cli.certdb.passfile parameter from
c:\sunone\sunoneis\lib\AMConfig.propertiesg. If this file does
not exist it needs to be created first and the password put there
in cleartext.
-ig is the client certificate of B (greed).
-ng is the nickname of the certificate.
- On machine A change the
hostlist parameter in the partner configuration
to include the nickname of machine B's client cert so replace
hostlist=192.12.12.34 by hostlist = 192.12.12.34 , greed
in Service Management -> SAML-> trusted partner sites.
- On machine B change the
hostlist parameter in the partner
configuration to include the nickname of machine A's client cert so
replace hostlist=192.12.12.33 by hostlist = 192.12.12.34 , arth
in Service Management -> SAML-> trusted partner sites
- Restart server.
|