test

Deployment Example 2: Federation Using SAML v2

Chapter 8 Installing the SAMLv2 Plug-in on Access Manager Servers

This chapter provides information about the following groups of tasks:

Note –

The following instructions are designed to be used on an Identity Provider Site that is already deployed and running. See 1.2 System Architecture in this manual for information about deploying the Identity Provider Site. See also 2.12 Obtaining Instructions for Deploying the Identity Provider Site in this manual.

8.1 Installing the SAMLv2 Plug-In on the Access Manager Servers

You must obtain the Sun Java System SAMLv2 Plug-in for Federation Services 1.0.

The SAMLv2 Plug-in is an auxiliary program that works with either Sun Java System Access Manager or Sun Java System Federation Manager. The plug-in incorporates a subset of features based on the Security Assertion Markup Language (SAML) version 2 specifications. When installed, the plug-in allows support for interactions based on those specifications.

You can download the plug-in from the following Sun Microsystems URL:http://sunsolve.sun.com/search/document.do?assetkey=1-21-122983-02-1.

Caution – Caution –

If you have configured an Access Manager site, be sure to remove the site ID from the Access Manager instances before installing the SAMLv2 plug-in. If the site ID exists in the Access Manager instances, SAMLv2 installation may fail.

Use the following as your checklist for installing the SAMLv2 Plug-In:

  1. Install the SAMLv2 Plug-In and the SAMLv2 Patch on Access Manager 1.

  2. Install the SAMLv2 Plug-In and the SAMLv2 Patch on Access Manager 2.

ProcedureTo Install the SAMLv2 Plug-In and the SAMLv2 Patch on Access Manager 1

  1. As a root user, log in to the host Access Manager 1.

    Change to the directory where you unpacked the SAMLv2 installation files. Example:


    # cd /tmp/saml2
# ls
../                            
ENTITLEMENT.TXT                saml2silent
LICENSE.TXT                    samlv2-1.0-solaris-sparc.tar
README.TXT                     version
SUNWsaml2/

  2. Modify the saml2silent file to reflect the location of the deployed Access Manager WAR file.

    Make a backup copy of the saml2silent file before making any changes to it.

    See changes in boldface in the following example:


    ############### START OF VARIABLE DEFINITIONS ###########################
 
STAGING_DIR=/opt/SUNWwbsvr/https-AccessManager-1.example.com/
is-web-apps/services
ADMINPASSWD=4m4dmin1
DEPLOY_SAMPLES=true
 
#
# SYSTEM
# AM  if SAML2 will be deployed on Access Manager
# FM  if SAML2 will be deployed on Federation Manager
# installer will auto detect if not specified.
#
 
SYSTEM=AM
 
# AM_INSTANCE
# SAML2 will be deployed on the specified AM instance.
# If it is not specified, SAML2 will be configured on the first AM instance.
#
 
AM_INSTANCE=
 
 
#
# LOAD_SCHEMA if true will load SAML2 SDS/AD schema
# DS_DIRMGRDN is the DN (distinguished name) of the directory manager,
#             the user who has unrestricted access to Directory Server.
# DS_DIRMGRPASSWD is the password for the directory manager
#
LOAD_SCHEMA=true
DS_DIRMGRDN="cn=Directory Manager"
DS_DIRMGRPASSWD=dirm4n4ger
 
 
#
# IDPDISCOVERY_ONLY set to true will only configure idpdiscovery service
# COMMON_COOKIE_DOMAIN IDP Discovery service cookie domain
# COOKIE_ENCODE  set to true, common domain cookie will be encoded.
IDPDISCOVERY_ONLY=false
COMMON_COOKIE_DOMAIN=
COOKIE_ENCODE=true
 
############### END OF VARIABLE DEFINITIONS ################################

  3. Run the SAMLv2 installer.


    # ./saml2setup install -s saml2silent

    When installation is complete, you will see the following message:


    Hosted entity descriptor for realm "/" was written to file 
"idpMeta.xml" successfully.
Hosted entity config for realm "/" was written to file
"idpExtended.xml" successfully.
Hosted entity descriptor for realm "/" was written to file
"spMeta.xml successfully.
Hosted entity config for realm "/" was written to file
"spExtended.xml" successfully.
Meta data created !!!

Circle of trus "samplecot" is created successfully.


Loading SAML2 schema...
The new AM server war /opt/SUNWam/amserver.war is ready for deploy!

    In this deployment example, complete proceeding steps before deploying the WAR file.

  4. Load the SAMLv2 users schema into the Access Manager users instance.


    #cd /opt/SUNWam/saml2/ldif
# ldapmodify -h LoadBalancer-2.example.com -p 489 -D "cn=Directory Manager" 
-w dirm4n4ger -f saml2_sds_schema.ldif
modifying entry CN=schema

  5. Go to the directory where you downloaded and unpacked the SAMLv2 patch installation file.


    # cd /temp/saml2patch/122983-02
# ls
LEGAL_LICENSE.TXT
LICENSE.TXT
patchinfo
postbackout
postpatch
prebackout
prepatch
README.122983-01
rel_notes.html
SUNWsaml2

  6. Run the SAMLv2 patch installer. 


    # cd /temp/saml2patch
# patchadd -G 122983-02

    When installation is complete, you will see the following message:


    Patch packages installed:
					SUNWsaml2

  7. Go to the directory where the SAMLv2 update script is located.


    # cd /opt/SUNWam/saml2/bin

  8. Run the update script.


    # ./saml2setup update -s saml2silent

    Any updates required because of the newly-installed patch are made in SAMLv2.

  9. Restart Access Manager 1.


    # cd /opt/SUNWwbsvr/https-AccessManager-1.example.com
# ./stop;./start

    This deployment uses Sun Java System Web Server which does not require you to redeploy the Access Manager WAR file at this point. If you are using any other web container, you must redeploy the Access Manager WAR file before restarting the Access Manager 1 server.

Troubleshooting

If you must uninstall and then re-install the SAMLv2 patch for any reason, when you run the update script the script may fail. Search the saml2silent file for the string -- and delete all occurrences. The script may have inadvertently added the extraneous strings to the file.

ProcedureTo Install the SAMLv2 Plug-In and the SAMLv2 Patch on Access Manager 2

  1. As a root user, log in to the host Access Manager 2.

    Change to the directory where you unpacked the SAMLv2 installation files. Example:


    # cd /tmp/saml2
# ls
../                            
ENTITLEMENT.TXT                saml2silent
LICENSE.TXT                    samlv2-1.0-solaris-sparc.tar
README.TXT                     version
SUNWsaml2/

  2. Modify the saml2silent file to reflect the location of the deployed Access Manager WAR file.

    Make a backup copy of the saml2silent file before making any changes to it.

    See changes in boldface in the following example:


    ############### START OF VARIABLE DEFINITIONS ###########################
 
STAGING_DIR=/opt/SUNWwbsvr/https-AccessManager-2.example.com/
is-web-apps/services
ADMINPASSWD=4m4dmin1
DEPLOY_SAMPLES=true
 
#
# SYSTEM
# AM  if SAML2 will be deployed on Access Manager
# FM  if SAML2 will be deployed on Federation Manager
# installer will auto detect if not specified.
#
 
SYSTEM=AM
 
# AM_INSTANCE
# SAML2 will be deployed on the specified AM instance.
# If it is not specified, SAML2 will be configured on the first AM instance.
#
 
AM_INSTANCE=
 
 
#
# LOAD_SCHEMA if true will load SAML2 SDS/AD schema
# DS_DIRMGRDN is the DN (distinguished name) of the directory manager,
#             the user who has unrestricted access to Directory Server.
# DS_DIRMGRPASSWD is the password for the directory manager
#
LOAD_SCHEMA=true
DS_DIRMGRDN="cn=Directory Manager"
DS_DIRMGRPASSWD=dirm4n4ger
 
 
#
# IDPDISCOVERY_ONLY set to true will only configure idpdiscovery service
# COMMON_COOKIE_DOMAIN IDP Discovery service cookie domain
# COOKIE_ENCODE  set to true, common domain cookie will be encoded.
IDPDISCOVERY_ONLY=false
COMMON_COOKIE_DOMAIN=
COOKIE_ENCODE=true
 
############### END OF VARIABLE DEFINITIONS ################################

  3. Run the SAMLv2 installer.


    # ./saml2setup install -s saml2silent

    When installation is complete, you will see the following message:


    Hosted entity descriptor for realm "/" was written to file 
"idpMeta.xml" successfully.
Hosted entity config for realm "/" was written to file
"idpExtended.xml" successfully.
Hosted entity descriptor for realm "/" was written to file
"spMeta.xml successfully.
Hosted entity config for realm "/" was written to file
"spExtended.xml" successfully.
Meta data created !!!

Circle of trus "samplecot" is created successfully.


Loading SAML2 schema...
The new AM server war /opt/SUNWam/amserver.war is ready for deploy!

    In this deployment example, complete proceeding steps before deploying the WAR file.

  4. Load the SAMLv2 users schema into the Access Manager users instance.


    #cd /opt/SUNWam/saml2/ldif
# ldapmodify -h LoadBalancer-2.example.com -p 489 -D "cn=Directory Manager" 
-w dirm4n4ger -f saml2_sds_schema.ldif
modifying entry CN=schema

  5. Go to the directory where you downloaded and unpacked the SAMLv2 patch installation file.


    # cd /temp/saml2patch/122983-02
# ls
LEGAL_LICENSE.TXT
LICENSE.TXT
patchinfo
postbackout
postpatch
prebackout
prepatch
README.122983-01
rel_notes.html
SUNWsaml2

  6. Run the SAMLv2 patch installer. 


    # cd /temp/saml2patch
# patchadd -G 122983-02

    When installation is complete, you will see the following message:


    Patch packages installed:
					SUNWsaml2

  7. Go to the directory where the SAMLv2 update script is located.


    # cd /opt/SUNWam/saml2/bin

  8. Run the update script.


    # ./saml2setup update -s saml2silent

    Any updates required because of the newly-installed patch are made in SAMLv2.

  9. Restart Access Manager 2.


    # cd /opt/SUNWwbsvr/https-AccessManager-2.example.com
# ./stop;./start

    This deployment uses Sun Java System Web Server which does not require you to redeploy the Access Manager WAR file at this point. If you are using any other web container, you must redeploy the Access Manager WAR file before restarting the Access Manager 1 server.

Troubleshooting

If you must uninstall and then re-install the SAMLv2 patch for any reason, when you run the update script the script may fail. Search the saml2silent file for the string -- and delete all occurrences. The script may have inadvertently added the extraneous strings to the file.

8.2 Configuring the Access Manager Load Balancer for the SAMLv2 Protocols

Follow the instructions that come with your load balancer hardware and software for installing and setting up the load balancer. Set up Load Balancer 3 using the following settings:

Table 8–1 Access Manager Load Balancer Settings

Setting 

Value 

Load Balancing Method 

Round Robin 

Persistence 

Active HTTP cookie with insert value 

SSL Termination 

Enabled 

8.3 Configuring the Access Manager Servers to Use SAMLv2 User Schema

The final task in configuring the Access Manager servers is to configure them to use SAMLv2 user schema.

ProcedureTo Reconfigure the LDAPv3 Plug-In on the Access Manager User Instances

  1. Log in to the Access Manager console:

    User Name:

    amadmin

    Password:

    4m4dmin1

  2. On the Realms page, click the users realm name.

  3. Click the Data Stores tab.

    On the Data Stores tab, click the usersLDAP Data Store name.

  4. On the “LDAPv3 Repository Plugin” page, make the following changes:

    1. Add a new LDAP User Object Class.

      In the Add box for LDAP User Object Class, enter the following and then click Add:


      sunFMSAML2NameIdentifier

    2. Add a new LDAP User Attribute.

      In the Add box for LDAP User Attributes, enter the following and then click Add:


      sun-fm-saml2-nameid-infokey

    3. Add a second new LDAP User Attribute.

      In the Add box for LDAP User Attributes, enter the following and then click Add:


      sun-fm-saml2-nameid-info

  5. Click Save.