The 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:
When 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.
Install Sun Java System Access Manager 7 2005Q4 or Sun Java System Federation Manager 7 2005Q4 into one of the supported web containers.
For more information, see Supported Server Products and Supported Web Containers.
Download and unpack the SAML v2 Plug-in for Federation Services bits.
See the Sun Java System SAML v2 Plug-in for Federation Services Release Notes for the download URL.
Create an installation configuration properties file based on the included saml2silent template.
For more information, see Creating an Installation Configuration Properties File.
Run saml2setup to install the plug-in packages and create a new Access Manager or Federation Manager WAR.
For more information, see Installing the SAML v2 Plug-in for Federation Services.
Deploy the modified WAR to your web container and restart it.
For more information, see Appendix A, Deploying the SAML v2 Plug-in for Federation Services Generated WAR.
Make any postinstallation modifications to your instance of Access Manager or Federation Manager.
For more information, see Postinstallation.
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.
This section covers information you should know about the supported software products. It includes the following topics:
The 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.
This section contains information on an Access Manager installation and preparing it for the SAML v2 Plug-in for Federation Services installation.
The SAML v2 Plug-in for Federation Services works in either the realm or legacy mode of Access Manager.
Access 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.
/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.
Before 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.
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:
Technical Note: Sun Java System SAML v2 Plug-in for Federation Services on Linux
Technical Note: Sun Java System SAML v2 Plug-in for Federation Services on Windows
This section contains information on a Federation Manager installation and preparing it for the SAML v2 Plug-in for Federation Services installation.
Federation 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.
/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:
Technical Note: Sun Java System Federation Manager 7.0 on Linux
Technical Note: Sun Java System Federation Manager 7.0 on Windows
Before 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:
Technical Note: Sun Java System SAML v2 Plug-in for Federation Services on Linux
Technical Note: Sun Java System SAML v2 Plug-in for Federation Services on Windows
A 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
Web Container |
Minimum Version |
---|---|
Sun Java System Web Server |
6.1sp4 |
Sun Java System Application Server |
8.1 |
BEA WebLogic® Server |
8.1 |
WebSphere® Application Server |
5.1 |
saml2setup is the command-line installer for the SAML v2 Plug-in for Federation Services. By default, it:
Installs the SAML v2 Plug-in for Federation Services packages on an instance of supported versions of Access Manager or Federation Manager.
Configures the plug-in and generates a modified WAR for redeployment.
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 update -s installation-configuration-properties-file
saml2setup -V
saml2setup -?
saml2setup takes as input an installation configuration properties file. See Creating an Installation Configuration Properties File for more information.
-p |
Specifies that the SAML v2 Plug-in for Federation Services packages will be installed only. The plug-in will not be configured and the modified WAR will not be generated. |
-s or --silent |
Specifies the name of the installation configuration properties file used as input to the script. See Creating an Installation Configuration Properties File |
-V |
Displays version information. |
-? |
Displays help information. |
The subcommands of saml2setup are:
install |
Installs the SAML v2 Plug-in for Federation Services packages, configures the plug-in, and generates a WAR. Note – The function of this subcommand will change when run using the -p option. |
uninstall |
Removes the SAML v2 Plug-in for Federation Services and its packages. |
configure |
Configures the plug-in and generates a WAR only. |
unconfigure |
Removes a configured SAML v2 Plug-in for Federation Services and WAR but leaves the packages, allowing for future reconfiguration using the configure subcommand. |
update |
Updates a previously configured staging directory with new files from a patch installation directory and then regenerates a WAR file for deployment. Note – Use the update option after you install a new SAML v2 plug-in patch or Access Manager 7.x patch, so you can avoid the unconfigure and configure routine, which will remove your existing metadata. |
To 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 ###############
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.
Property |
Definition |
---|---|
STAGING_DIR |
Defines the staging directory for the SAML v2 Plug-in for Federation Services WAR.
|
ADMINPASSWD |
Specifies the password chosen for the underlying product's administrator; by default, amadmin. |
DEPLOY_SAMPLES |
Defines whether the included sample will be deployed as part of the installation. The default value is true. |
SYSTEM |
Defines the server product into which the plug-in will be installed. It takes a value of AM if installing into an instance of Access Manager or FM if installing into an instance of Federation Manager. If no value is specified, the installer will automatically detect the server product. |
AM_INSTANCE |
Used if there are multiple instances of Access Manager. The value would be the name of the particular instance. If no value is specified, the installer will automatically detect the first instance of Access Manager. Note – This variable has no relevance when installing into an instance of Federation Manager. |
LOAD_SCHEMA |
Defines whether or not to automatically load the LDAP schema. The default value is true. There are instances when you might load the LDAP schema manually. For example, if ldapmodify is not available, you might set LOAD_SCHEMA to false. |
DS_DIRMGRDN |
Defines the distinguished name (DN) of the user that has permissions to bind to the LDAP directory. This is required when LOAD_SCHEMA is true. |
DS_DIRMGRPASSWD |
Defines the password associated with the user DN that will bind to the LDAP directory. This is required when LOAD_SCHEMA is true. Caution – The value of this property is very sensitive. Be sure to protect the password after installation by removing it entirely from the file, or protect the file itself by setting the appropriate permissions. |
IDPDISCOVERY_ONLY |
Defines whether the installer will configure the SAML v2 Plug-in for Federation Services or the SAML v2 IDP Discovery Service only. If true, only the SAML v2 IDP Discovery Service will be configured. If false, the full SAML v2 Plug-in for Federation Services will be configured. The default value is false. Note – For more information on the SAML v2 IDP Discovery Service, see Installing the SAML v2 IDP Discovery Service and The SAML v2 IDP Discovery Service. |
COMMON_COOKIE_DOMAIN |
Defines the common domain for the SAML v2 IDP Discovery Service. The value of this property must be set to .cookie-domain-name as in .sun.com. |
COOKIE_ENCODE |
Defines whether the common domain cookie will be URL encoded before setting and URL decoded before reading. If set to true the SAML v2 IDP Discovery Service will encode the cookie before setting and decode it before reading. If set to false, the SAML v2 IDP Discovery Service will not encode or decode the cookie. It will be set and received as is. |
To 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.
saml2setup takes as input an installation configuration properties file. See Creating an Installation Configuration Properties File for more information.
Create an installation configuration properties file as described in Creating an Installation Configuration Properties File.
For instances of Access Manager and Federation Manager using an LDAPv3–compliant directory, the new schema file is loaded only if the LOAD_SCHEMA variable in the installation configuration properties file is set to true.
Log in as root.
You must have system administrator privileges to run the SAML v2 Plug-in for Federation Services installer.
Create a new directory.
# 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.
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
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.
Restart Federation Manager if you installed the SAML v2 Plug-in for Federation Services on that server product.
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.
Information on configuring SAML v2 IDP Discovery Service is in The SAML v2 IDP Discovery Service.
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.
See The SAML v2 IDP Discovery Service to configure the SAML v2 IDP Discovery Service.
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.
The following sections contain some procedures to perform after installing Access Manager.
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.
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.
Be sure to set your class path correctly before using ldapmodify.
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.
This is only necessary for instances of Access Manager acting as service providers.
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.
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.
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.
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.
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.
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.