Contained Within
Find More DocumentationFeatured Support Resources |  Download this book in PDF (1229 KB)
Chapter 2 Installing the SAML v2 Plug-in for Federation ServicesThe Sun Java System SAML v2 Plug-in for Federation Services installs into an instance of Sun Java System Access Manager 7 2005Q4 or Sun Java System Federation Manager 7. Once deployed, it extends the functionality of the server product to include SAML v2–based interactions. This chapter contains the following topics: Installation ProcessWhen the SAML v2 Plug-in for Federation Services is installed, the SAML v2 package is integrated into either the existing Access Manager or Federation Manager web archive (WAR). This modified WAR is then redeployed to add SAML v2 functionality to the existing application. Following is an overview of the process to install the SAML v2 Plug-in for Federation Services.
After completing the installation, see Chapter 3, Administration and Chapter 4, Configuring Specialized Interactions for instructions on how to use the SAML v2 Plug-in for Federation Services for SAML v2 interactions. Supported Software ProductsThis section covers information you should know about the supported software products. It includes the following topics: Supported Server ProductsThe SAML v2 Plug-in for Federation Services can only be installed in a running instance of either Sun Java System Access Manager 7 2005Q4 or Sun Java System Federation Manager 7 2005Q4. These products can be installed on versions of the Solaris™ Operating System (OS), Red Hat™ Linux, or Microsoft Windows. The following sections contain information regarding installation of the SAML v2 Plug-in for Federation Services on these server products. Installing on Sun Java System Access Manager 7 2005Q4This section contains information on an Access Manager installation and preparing it for the SAML v2 Plug-in for Federation Services installation. Note – The SAML v2 Plug-in for Federation Services works in either the realm or legacy mode of Access Manager. Installing Access ManagerAccess Manager can be installed on versions of the Solaris™ Operating System (OS), Red Hat™ Linux, or Microsoft Windows. The default installation directories for Solaris and Linux are /opt/SUNWam/ and /opt/sun/identity/, respectively. /opt is the root installation directory. SUNWam and sun/identity are the product directories. Note – /opt is the default root installation directory for Access Manager. When specified in a path, /AccessManager-base will be used as a generic placeholder. /SUNWam and /sun/identity are the default product directories for Access Manager. When specified in a path, /product-directory/ will be used as a generic placeholder. See the Sun Java System Access Manager 7 2005Q4 Deployment Planning Guide for more information on the product's installed layout. For information on installing Access Manager, see the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX. Preparing Access Manager for SAML v2 Plug-in for Federation ServicesBefore installing the SAML v2 Plug-in for Federation Services into an instance of Sun Java System Access Manager, you need to copy the amserver.war (located in /AccessManager-base/product-directory/) into a new directory and extract its contents using the following command: jar —xvf amserver.war This new directory is referred to as the staging directory and contains the original contents for your Access Manager application. Any modifications to the application must be made to the files in this directory. These files are then repackaged into a new WAR and redeployed into your web container. The path to this directory is the value used for the STAGING_DIR variable in your installation file.  Caution – If your instance of Access Manager has been customized, be sure to copy and extract the updated WAR. For more information on Linux and Windows installations of the SAML v2 Plug-in for Federation Services, see the following:
Installing on Sun Java System Federation Manager 7 2005Q4This section contains information on a Federation Manager installation and preparing it for the SAML v2 Plug-in for Federation Services installation. Installing Federation ManagerFederation Manager can be installed on the Solaris OS, Red Hat Linux, or Microsoft Windows. The default root installation directory for the Solaris OS is /opt. Note – /opt is the default root installation directory for Federation Manager. When specified in a path, /FederationManager-base will be used as a generic placeholder. Unlike in Access Manager, the SUNWam directory in Federation Manager cannot be modified so references to this directory will remain static. See the Sun Java System Federation Manager 7.0 User’s Guide for more information on the default installation directory and the default runtime directory. For information on installing Federation Manager, see the Sun Java System Federation Manager 7.0 User’s Guide. Additional information on Linux and Windows installations of Federation Manager can be found in the following:
Preparing Federation Manager for SAML v2 Plug-in for Federation ServicesBefore installing the SAML v2 Plug-in for Federation Services into an instance of Sun Java System Federation Manager, backup your staging directory. For more information on Linux and Windows installations of the SAML v2 Plug-in for Federation Services, see the following:
Supported Web ContainersA WAR modified with the SAML v2 Plug-in for Federation Services can be deployed in any of the following web containers. CPU and memory requirements are based on the needs of the web container. See your product's documentation for installation information. Table 2–1 Supported Web Containers
The saml2setup Command-line Referencesaml2setup is the command-line installer for the SAML v2 Plug-in for Federation Services. By default, it:
The saml2setup syntax is: saml2setup install [-p] -s installation-configuration-properties-file saml2setup uninstall -s installation-configuration-properties-file saml2setup configure -s installation-configuration-properties-file saml2setup unconfigure -s installation-configuration-properties-file saml2setup -V saml2setup -? Note – saml2setup takes as input an installation configuration properties file. See Creating an Installation Configuration Properties File for more information.
The subcommands of saml2setup are:
Creating an Installation Configuration Properties FileTo install the SAML v2 Plug-in for Federation Services you must have an installation configuration properties file based on the template saml2silent. The saml2silent template is included with the installation binaries and can be modified based on your deployment. The saml2silent template can be found on the top-level of the directory to which the binaries were unpacked. Following is a sample installation configuration properties file that might be used to install the SAML v2 Plug-in for Federation Services on an instance of Federation Manager. Descriptions of the properties themselves can be found in Table 2–2. ############### START OF VARIABLE DEFINITIONS ############### STAGING_DIR=/var/opt/SUNWam/fm/war_staging ADMINPASSWD=11111111 DEPLOY_SAMPLES=true SYSTEM=FM AM_INSTANCE= LOAD_SCHEMA=true DS_DIRMGRDN="cn=Directory Manager" DS_DIRMGRPASSWD=22222222 IDPDISCOVERY_ONLY=false COMMON_COOKIE_DOMAIN= COOKIE_ENCODE=true ############### END OF VARIABLE DEFINITIONS ############### Note – Your modified installation file is used as input to the installer utility, saml2setup. More information on the installer utility can be found in Installing the SAML v2 Plug-in for Federation Services. Table 2–2 saml2silent Installation File Property Definitions
Installing the SAML v2 Plug-in for Federation ServicesTo install the SAML v2 Plug-in for Federation Services packages and create an updated WAR, run the saml2setup installer as described in The saml2setup Command-line Reference. Note – saml2setup takes as input an installation configuration properties file. See Creating an Installation Configuration Properties File for more information.
|
# mkdir saml2bits |
# cd saml2bits |
Download the file-name.tar.gz file into the new directory.
See the Sun Java System SAML v2 Plug-in for Federation Services Release Notes for the download URL.
Unpack the product binaries by typing:
# gunzip —dc file-name.tar.gz | tar -xvof - |
where file-name.tar.gz is the name of the downloaded file.
Run the saml2setup installer as follows:
# saml2setup install -s installation-file-name |
where installation-file-name is the name of the installation configuration properties file described in Creating an Installation Configuration Properties File.
The installer will install the packages, configure the plug-in, and create an updated WAR using the service deployment identifier specified in the AMConfig.properties file of the specific server product.
-
When installed into an instance of Access Manager, the new WAR is located in /AccessManager-base/product-directory/ and is called service-deploy-uri.war as in, for example, amserver.war.
Note –AMConfig.properties is located in the /etc/opt/product-directory/config directory.
-
When installed into an instance of Federation Manager, the new WAR is located in the staging directory defined in the installation configuration properties file and is called FM-deploy-uri.war as in, for example, federation.war
Note –AMConfig.properties is located in the /staging-directory/web-src/WEB-INF/classes directory.
Follow the instructions in Appendix A, Deploying the SAML v2 Plug-in for Federation Services Generated WAR to deploy the modified WAR and complete the installation.
Next Steps
Restart Federation Manager if you installed the SAML v2 Plug-in for Federation Services on that server product.
Installing the SAML v2 IDP Discovery Service
In deployments having more than one identity provider, the SAML v2 IDP Discovery Service allows service providers to determine which identity provider a principal uses with the Web Browser SSO profile. The SAML v2 IDP Discovery Service relies on a cookie written in a domain common to all identity providers and service providers in a circle of trust. The SAML v2 Plug-in for Federation Services can install a standalone instance of the SAML v2 IDP Discovery Service in this predetermined domain, also known as the common domain.
Note –
Information on configuring SAML v2 IDP Discovery Service is in The SAML v2 IDP Discovery Service.
To Install the SAML v2 IDP Discovery Service
Before You Begin
Download and unpack the SAML v2 Plug-in for Federation Services binaries as described in Installing the SAML v2 Plug-in for Federation Services.
-
Create an installation configuration properties file.
Be sure to set the IDPDISCOVERY_ONLY, COMMON_COOKIE_DOMAIN, and COOKIE_ENCODE properties as described in Creating an Installation Configuration Properties File.
-
Run the saml2setup command.
# saml2setup install -s installation-file-name
where installation-file-name is the name of the installation configuration properties file described in Creating an Installation Configuration Properties File.
The installer will create a SAML v2 IDP Discovery Service WAR named idpdiscovery.war in /AccessManager-base/product-directory/saml2/ or /FederationManager-base/SUNWam/saml2/.
-
Deploy idpdiscovery.war according to the instructions in Appendix A, Deploying the SAML v2 Plug-in for Federation Services Generated WAR.
-
Restart your web container.
Next Steps
See The SAML v2 IDP Discovery Service to configure the SAML v2 IDP Discovery Service.
Postinstallation
This section contains postinstallation tasks specific to the product on which you are installing the SAML v2 Plug-in for Federation Services. It includes the following topics:
After completing these tasks, see Chapter 3, Administration to begin configuring your instance of the SAML v2 Plug-in for Federation Services.
Access Manager Postinstallation
The following sections contain some procedures to perform after installing Access Manager.
Adding the sunFMSAML2NameIdentifier Object Class
If installing the SAML v2 Plug-in for Federation Services on an instance of Access Manager that uses an LDAPv3-compliant directory for a user data store, you must add the sunFMSAML2NameIdentifier object class to all existing users. This object class contains two attributes:
-
sun-fm-saml2–nameid-info-key is used for searching purposes. The attribute's value takes the form hosted-entity-id|remote-entity-id|idp-nameid.
-
sun-fm-saml2–nameid-info is used to store all information related to the name identifier. The attribute's value takes the form hosted-entity-id|remote-entity-id|idp-nameid|idp-nameid-qualifier|idp-nameid-format|sp-nameid|sp-nameid-qualifier|hosted-entity-role|is-affiliation.
Note –
The values in these attributes are defined in the SAML v2 specifications. For example, hosted-entity-role takes a value of IDPRole or SPRole (based on the configuration of the provider) and is-affiliation specifies whether the federation is affiliation-based (taking a value of true or false). For explanations on the other attributes, see the Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 specification.
To add sunFMSAML2NameIdentifier to the default amadmin entry, you would run ldapmodify (available in the bin directory) using the following LDIF as input:
DN: uid=amadmin,ou=people,dc=sun,dc=com changetype: modify add: objectclass objectclass: sunFMSAML2NameIdentifier
This task is not required for installations of Access Manager 7.1. It is also not required for installations of Federation Manager that use an LDAPv3-compliant directory as a user data store because the object class is automatically added if not found.
Caution – Be sure to set your class path correctly before using ldapmodify.
Enabling the SAML v2 Authentication Module
If installing the SAML v2 Plug-in for Federation Services on an instance of Access Manager, you might have to enable the SAML v2 authentication module using the Access Manager console. The following sections explain the procedure to do this in both legacy and realm mode.
Note –
This is only necessary for instances of Access Manager acting as service providers.
To Enable the SAML v2 Authentication Module
in Legacy Mode
-
Log in to Access Manager as the top-level administrator, by default, amadmin.
-
Select the Identity Management tab.
-
Select Services from the View drop down box.
-
Click Add Service.
-
Select SAML2 and click OK.
-
Log out of the Access Manager console.
To Enable the SAML v2 Authentication Module
in Legacy Mode Using amadmin
You can also enable the SAML v2 authentication module using the amadmin command line tool.
-
Save the following XML code to a file.
<Requests> <OrganizationRequests DN="<root_suffix>"> <RegisterServices> <Service_Name>sunAMAuthSAML2Service</Service_Name> </RegisterServices> </OrganizationRequests> </Requests> -
Load the XML file using the amadmin command line tool to register the SAMLv2 authentication module.
For information on the amadmin command line tool, see Chapter 1, The amadmin Command Line Tool, in Sun Java System Access Manager 7.1 Administration Reference.
To Enable the SAML v2 Authentication Module
in Realm Mode
The SAML v2 Authentication Module is enabled during installation of Access Manager in Realm mode. The following procedure is for informational purposes.
-
Log in to Access Manager as the top-level administrator, by default, amadmin.
-
Select the Access Control tab.
-
Select the appropriate realm.
-
Click the Authentication tab.
-
Click New under Module Instances.
-
Enter SAML2 as a name.
-
Select the SAML2 radio button.
-
Click Create.
-
Click Save.
-
Log out of the Access Manager console.
Federation Manager Postinstallation
If installing the SAML v2 Plug-in for Federation Services on an instance of Federation Manager, you must enable the SAML v2 authentication module using the Federation Manager console.
To Enable the SAML v2 Authentication Module
-
Log in to Federation Manager as the top-level administrator, by default, amadmin.
-
Select the Organization tab.
-
Select the Authentication tab.
-
Click Edit next to the Core service.
-
Select SAML2 in the Organization Authentication Modules attribute list and click Save.
-
Log out of the Federation Manager console.
Uninstalling the SAML v2 Plug-in for Federation Services
To uninstall the SAML v2 Plug-in for Federation Services, run the following command using the same installation configuration properties file for input that was used as input during installation.
# saml2setup uninstall -s installation-file-name |
This command removes the SAML v2 Plug-in for Federation Services and its packages.