test

Sun Java System SAML v2 Plug-in for Federation Services User's Guide

Chapter 2 Installing the SAML v2 Plug-in for Federation Services

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:

Installation Process

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.

  1. 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.

  2. 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.

  3. Create an installation configuration properties file based on the included saml2silent template.

    For more information, see Creating an Installation Configuration Properties File.

  4. 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.

  5. 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.

  6. 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.

Supported Software Products

This section covers information you should know about the supported software products. It includes the following topics:

Supported Server Products

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.

Installing on Sun Java System Access Manager 7 2005Q4

This 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 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.

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 Services

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.

Caution – 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 2005Q4

This section contains information on a Federation Manager installation and preparing it for the SAML v2 Plug-in for Federation Services installation.

Installing Federation Manager

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.

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 Services

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:

Supported Web Containers

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 

The saml2setup Command-line Reference

saml2setup 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 update -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.

-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.

Creating an Installation Configuration Properties File

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 ###############
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

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 – 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.

Installing the SAML v2 Plug-in for Federation Services

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.

Note –

saml2setup takes as input an installation configuration properties file. See Creating an Installation Configuration Properties File for more information.

ProcedureTo Install the SAML v2 Plug-in for Federation Services

Before You Begin

Create an installation configuration properties file as described in Creating an Installation Configuration Properties File.

Note –

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.

  1. Log in as root.

    You must have system administrator privileges to run the SAML v2 Plug-in for Federation Services installer.

  2. Create a new directory.


    # mkdir saml2bits


    # cd saml2bits

  3. 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.

  4. 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.

  5. 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.

  6. 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.

ProcedureTo 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.

  1. 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.

  2. 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/.

  3. Deploy idpdiscovery.war according to the instructions in Appendix A, Deploying the SAML v2 Plug-in for Federation Services Generated WAR.

  4. 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:

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 – 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.

ProcedureTo Enable the SAML v2 Authentication Module in Legacy Mode

  1. Log in to Access Manager as the top-level administrator, by default, amadmin.

  2. Select the Identity Management tab.

  3. Select Services from the View drop down box.

  4. Click Add Service.

  5. Select SAML2 and click OK.

  6. Log out of the Access Manager console.

ProcedureTo 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.

  1. Save the following XML code to a file.


    <Requests>
<OrganizationRequests DN="<root_suffix>">
   <RegisterServices>
       <Service_Name>sunAMAuthSAML2Service</Service_Name>
   </RegisterServices>
</OrganizationRequests>
</Requests>

  2. 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.

ProcedureTo 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.

  1. Log in to Access Manager as the top-level administrator, by default, amadmin.

  2. Select the Access Control tab.

  3. Select the appropriate realm.

  4. Click the Authentication tab.

  5. Click New under Module Instances.

  6. Enter SAML2 as a name.

  7. Select the SAML2 radio button.

  8. Click Create.

  9. Click Save.

  10. 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.

ProcedureTo Enable the SAML v2 Authentication Module

  1. Log in to Federation Manager as the top-level administrator, by default, amadmin.

  2. Select the Organization tab.

  3. Select the Authentication tab.

  4. Click Edit next to the Core service.

  5. Select SAML2 in the Organization Authentication Modules attribute list and click Save.

  6. 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.