Sun Java System Federation Manager 7.0 User's Guide

Installation Sequence

This sequence of steps needs to be followed to complete your installation of Federation Manager. For more information, click the appropriate link.

  1. Create a silent installation file based on your deployment.

    See The Silent Installation File.

  2. Select an installation option for instructions on how to download and unpack the Federation Manager binary, add the Federation Manager packages to your server and generate the Federation Manager web archive (WAR) from the added packages.

    See Federation Manager Installation Options.

  3. Deploy the generated WAR to a web container.

    See Deploying Your Federation Manager WAR.

The Silent Installation File

Before installing Federation Manager you must have a silent installation file for use as input to the installer. Included with the Federation Manager application is a template called fmsilent-template. After installation, fmsilent-template is located in the /FederationManager-base/SUNWam/fm/ directory. It is reproduced below and can be modified to create a silent installation file based on your deployment.


Example 2–1 fmsilent-template Silent Installation File Template

XML_ENCODING=iso-8859-1
BASEDIR=/opt 
IS_INSTALL_VARDIR=/var/opt/SUNWam/fm 
COOKIE_ENCODE=false 
SERVER_PROTOCOL=http 
SERVER_DEPLOY_URI=/federation 
DEPLOY_SAMPLES=true

# The following entries contain sample values!
# These should be modified for your specific installation
# and then uncommented (remove the # from the line)
#

#FM_PROCESS_USER=sample_user
#FM_PROCESS_GROUP=sample_group
#INST_ORGANIZATION=dc=sun,dc=com
#SERVER_HOST=sample.sun.com
#SERVER_PORT=58080
#ADMINPASSWD=11111111

Delete the # before the variables you want to modify and enter the appropriate values. Save the file and install Federation Manager according to the instructions in Federation Manager Installation Options. Following are definitions of the variables in the fmsilent-template file.

Table 2–1 Silent Installation File Variable Definitions

Silent Installation File Variable 

Definition 

XML_ENCODING

Defines how the XML parser will read your character set. ISO 8859-1 defines the Latin 1 character set.

BASEDIR

Defines the default installation directory for Federation Manager. By default, this is /opt. See Default Installation Directories for additional information.

IS_INSTALL_VARDIR

Defines the default runtime directory for Federation Manager. This directory is created by fmwar with the contents assigned the user and group ownership specified by the values in FM_PROCESS_USER and FM_PROCESS_GROUP. For more information, see Default Installation Directories.

COOKIE_ENCODE

Defines whether the cookie should be encoded or not. By default, this value should be set to false. This attribute will update the com.iplanet.am.cookie.encode property in AMConfig.properties.


Caution – Caution –

The value of this property is dependent on the web container in which Federation Manager is deployed. For all currently supported web containers, the value must be left false.


SERVER_PROTOCOL

Defines the protocol used by the web container on which Federation Manager will be deployed. 

SERVER_DEPLOY_URI

Defines the Federation Manager WAR deployment URI. It is also used as the name of the generated .WAR file by default.

DEPLOY_SAMPLES

Defines whether the Liberty and SAML samples will be deployed as part of the Federation Manager installation. 

FM_PROCESS_USER

Defines the user under which Federation Manager runs. 


Note –

It is recommended that FM_PROCESS_USER specifies a user ID that is different from the super user like root. Typically this user is the same as the user under which the underlying web container runs.


FM_PROCESS_GROUP

Defines the group to which the FM_PROCESS_USER belongs.

INST_ORGANIZATION

Defines the root node for the Federation Manager configuration data. The value of this variable is written as dc=orgname,dc=com. If Federation Manager uses an LDAP directory to store its configuration, this becomes the root suffix. If Federation Manager uses a flat file to store its configuration, this value becomes the top level directory name of the file system by inverting the sequence and using the comma as a delimiter. Using the values from the template in Example 2–1, the flat file directory structure would be /var/opt/SUNWam/fm/federation/dc=com/dc=orgname.

SERVER_HOST

Defines the host of the web container on which Federation Manager will be deployed. 

SERVER_PORT

Defines the port of the web container on which Federation Manager will be deployed. 

ADMINPASSWD

Defines the password for the Federation Manager administrator. The default administrator is amadmin.

Federation Manager Installation Options

There are two different options that can be used to accomplish the actual installation step defined in the Installation Sequence. The first option, standard installation, is completed in two steps. First, you add the Federation Manager packages to your machine using fmsetup and then you create a WAR from these packages using fmwar. The second option, self-extracting installation, uses fmsetup and a tar.gz file to add the packages to your machine and create a WAR in one step. For instructions, see:


Tip –

It is recommended that you use the Self-Extracting Installation procedure.


After completing either of these installation procedures, the Federation Manager WAR must still be deployed in your web container. For instructions, see Deploying Your Federation Manager WAR.

Self-Extracting Installation

The Federation Manager self-extracting installation option installs the packages, and creates the Federation Manager WAR in one procedure. After completing the self-extracting installation option, see Deploying Your Federation Manager WAR for further instructions.

ProcedureTo Add Federation Manager Packages and Create a WAR

  1. Log in as root.

  2. Create a new directory.


    # mkdir fm1.0
    

    # cd fm1.0
    
  3. Download the file-name.tar.gz file into the new directory.

    Go to http://www.sun.com/download/products.xml?id=44a5bbb5 to download Federation Manager.

  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 fmsetup to add the Federation Manager packages and create a WAR.


    #fmsetup install -s silent-installation-file
    

    where silent-installation-file is the name of the file created from the silent installation template discussed in The Silent Installation File. See Detailing the fmsetup Syntax for more information.


    Caution – Caution –

    fmsetup only installs shared packages if they are not already present. If an older package is detected, the installer script will quit and display an error message identifying the older package name. To continue, you must manually remove that package using pkgrm(1M) and run fmsetup again.


  6. Follow the instructions in Deploying Your Federation Manager WAR to complete the deployment.

Standard Installation

The Federation Manager standard installation option encompasses two separate procedures.

  1. The first procedure adds the Federation Manager packages to your server. See To Add Federation Manager Packages.

  2. The second procedure creates the Federation Manager WAR from the added packages. See To Archive the Federation Manager Packages.

ProcedureTo Add Federation Manager Packages

This section details the first part of the standard installation procedure in which the Federation Manager packages are added to a directory on your machine. Following the package add, you must still create a staging directory and the WAR. See To Archive the Federation Manager Packages.

  1. Log in as root.

  2. Create a new directory.


    # mkdir fm1.0
    

    # cd fm1.0
    
  3. Paste the download URL into a browser window to download the installation bundle into the new directory.

    Go to http://www.sun.com/download/products.xml?id=44a5bbb5 to download Federation Manager.

  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. Edit the silent installation file template as described in The Silent Installation File.

  6. Run fmsetup to add the Federation Manager packages using the -p option.

    The -p option is used for package installations only.


    # fmsetup install -p -s silent-installation-file
    

    where silent-installation-file is the name of the file created from the silent installation template discussed in The Silent Installation File. See Detailing the fmsetup Syntax for more information.


    Caution – Caution –

    fmsetup only installs shared packages if they are not already present. If an older package is detected, the installer script will quit and display an error message identifying the older package name. To continue, you must manually remove that package using pkgrm(1M) and run fmsetup again.


  7. Follow the instructions in To Archive the Federation Manager Packages to complete the standard installation option.

ProcedureTo Archive the Federation Manager Packages

This section details the second part of the standard installation option: how to create a staging directory and archive the packages added to your machine in To Add Federation Manager Packages. This procedure will create the WAR used to deploy Federation Manager. After generating a WAR, see Deploying Your Federation Manager WAR.

  1. Log in as root.

  2. Run fmwar to archive the Federation Manager packages into a WAR file.


    # /FederationManager-base/SUNWam/fm/bin/fmwar -n name-for-WAR 
    -d staging-directory -s silent-installation-file -g
    

    where:

    name-for-WAR

    Defines the name given to the created WAR. 

    staging-directory

    Defines the path to the directory which contains the files that will be used to generate the WAR. 


    Caution – Caution –

    The -g option in the example above is used only when creating a Federation Manager WAR for the first time. In these cases, the -g option must be specified and the -d option must point to a directory which does not yet exist. This directory will be the staging directory. A recommended path is /var/opt/SUNWam/FM/war_staging. If the -g option is not specified, -d must point to an existing staging directory to regenerate the WAR. See Detailing the fmwar Syntax for more information.


    silent-installation-file

    Defines the name of the file created in The Silent Installation File.

  3. Follow the instructions in Deploying Your Federation Manager WAR to complete the product installation.

Deploying Your Federation Manager WAR

There are four web containers in which Federation Manager can be deployed. They are:

Instructions for deploying the Federation Manager WAR in each of these web containers can be found in the following sections.

Deploying Federation Manager in Sun Java System Web Server

Sun Java System Web Server has the wdeploy command line utility to deploy a WAR file. The syntax is:

wdeploy deploy -u /deployment-URI -i instance-name -v vs-id -d deployment-directory WAR-file-location 

where:

deployment-URI

Defines the URI for the application. This value must be the same as that defined for the SERVER_DEPLOY_URI property in The Silent Installation File.


Note –

Note the inclusion of the leading slash.


instance-name

Defines the instance of Web Server to which you are deploying the web application. 

vs-id

Defines the virtual server ID of the instance of Web Server to which you are deploying the web application. 

deployment-directory

Defines the directory to which the WAR will be deployed. 

WAR-file-location

Defines the full path to the WAR file being deployed. 

When you execute wdeploy, a web application with the defined URI and directory is added to the server.xml file. The WAR file is also extracted from its location and deployed in the deployment directory.


Note –

More information on the wdeploy utility can be found in the Sun ONE Web Server 6.1 Programmer’s Guide to Web Applications.


This section contains the following procedures:

ProcedureTo Deploy an Instance of Federation Manager in Web Server

  1. Type the following command replacing the variables with information regarding your deployment and hit Enter.


    # WebServer-base/SUNWwbsvr/bin/https/httpadmin/bin/wdeploy deploy 
    -u /deployment-URI -i instance-name -v vs-id 
    -d WebServer-base/instance-name/deployment-URI war-file-location
    

    For example:


    # /WebServer-base/SUNWwbsvr/bin/https/httpadmin/bin/wdeploy deploy -
    u /federation -i niceday.red.sun.com -v https-niceday.red.sun.com 
    -d /opt/SUNWwbsvr/https-niceday.red.sun.com/federation 
    /var/opt/SUNWam/fm/fedx/fedx.war
    
  2. Restart the Web Server.

ProcedureTo View the Federation Manager Java API Specifications

  1. To view the Federation Manager Java API Specifications when it is deployed in Web Server, you must first create a symbolic link by typing:


    # ln -s /FederationManager-base/SUNWam/fm/docs /Web Server-doc-root/javadocs
    

    where:

    FederationManager-base

    Defines the Federation Manager installation directory. 

    Web Server-doc-root

    Defines the Web Server directory in which you store publicly available documentation files. 

  2. Once the symbolic link is defined, you can access the Java API Reference via a web browser by typing a URL in the format protocol://host:port/javadocs. For example, http://host1.sun.com:81/javadocs.

ProcedureTo Delete an Instance of Federation Manager from Web Server

  1. Type the following command replacing the variables with information regarding your deployment:


    # /WebServer-base/bin/https/httpadmin/bin/wdeploy delete -u /deployment-URI 
    -i instance-name -v vs-id -n hard
    

    where:

    WebServer-base

    Defines the Web Server installation directory. 

    deployment-URI

    Defines the Federation Manager URI (with leading slash). 

    instance-name

    Defines the instance of Web Server to which the web application is deployed. 

    vs-id

    Defines the virtual server ID of the instance of Web Server to which you are deploying the web application. 

    For example:


    # /WebServer-base/SUNWwbsvr/bin/https/httpadmin/bin/wdeploy delete -u /federation 
    -i https-niceday.red.sun.com -v https-niceday.red.sun.com -n hard
    
  2. Hit Enter.

Deploying Federation Manager in Sun Java System Application Server

With Sun Java System Application Server, you can use the deploy subcommand of the asadmin utility to deploy a WAR file. The syntax is:

# asadmin deploy --user admin-user --passwordfile filename --port port 
--contextroot deployment-URI --name deployment-URI 
--target instance-name WAR-file-location

where:

admin-user

Defines the ID of the Application Server administrator. 

filename

Defines the full path to the file that stores the password of the Application Server administrator. You must manually edit this file so it can be understood by the asadmin utility. The password must be in the form: AS_ADMIN_PASSWORD=password where password is the password in text used during the installation of Application Server.

port

Defines the port for the Application Server Domain Administration Server. The default is 4849. 

deployment-URI

Defines the URI for the application. This value must be the same as that defined for the SERVER_DEPLOY_URI property in The Silent Installation File.

instance-name

Defines the instance of Application Server to which the WAR will be deployed. 

WAR-file-location

Defines the full path to the WAR file being deployed. 


Note –

The asadmin options listed above are those relevant to deploying Federation Manager. For more information (including the full set of options), see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.


This section contains the following procedures:

ProcedureTo Deploy an Instance of Federation Manager in Application Server

  1. Type the following command replacing the variables with information regarding your deployment and hit Enter.


    # ApplicationServer-base/bin/asadmin deploy --user AS-administrator 
    --passwordfile filename --port port-number 
    --contextroot  deployment-URI --name deployment-URI 
    --target instance-name war-file-location
    

    For example:


    # /opt/SUNWappserver/appserver/bin/asadmin deploy --user admin 
    --passwordfile /tmp/pwdfile --port 4849 --contextroot fm --name fm 
    --target server1 /var/opt/SUNWam/fm/war_staging/fm.war
    
  2. Following the deployment, modify the Application Server server.policy file.

    By default, server.policy is located in the /var/opt/SUNWappserver/domains/domain-name/ directory. In the server.policy sample below, all of the capitalized contents (except WEB-INF) must be replaced with information applicable to your deployment.

    // Federation Manager RELATED ADDITIONS
       grant {
         permission java.util.PropertyPermission "user.language", "write";
       };
       grant codeBase "file:${BASEDIR}/${PROD_DIR}/fm/web-src/WEB-INF/lib/am_sdk.jar" {
         permission java.net.SocketPermission "*", "connect,accept,resolve";
       };
       grant codeBase "file:${BASEDIR}/${PROD_DIR}/fm/web-src/WEB-INF/lib/am_services.jar" {
            permission java.net.SocketPermission "*", "connect,accept,resolve";
       };
       grant codeBase "file:$AS81_VARDIR/domains/$AS81_DOMAIN/applications/
       j2ee-modules/${DEPLOY_WARPREFIX}/-" {
            permission java.net.SocketPermission "*", "connect,accept,resolve";
       };
       grant {
        permission java.lang.RuntimePermission "modifyThreadGroup";
        permission java.lang.RuntimePermission "setFactory";
        permission java.lang.RuntimePermission "accessClassInPackage.*";
        permission java.util.logging.LoggingPermission "control";
        permission java.lang.RuntimePermission "shutdownHooks";
        permission javax.security.auth.AuthPermission "insertProvider.Mozilla-JSS";
        permission java.security.SecurityPermission "putProviderProperty.Mozilla-JSS";
        permission javax.security.auth.AuthPermission "getLoginConfiguration";
        permission javax.security.auth.AuthPermission "setLoginConfiguration";
        permission javax.security.auth.AuthPermission "modifyPrincipals";
        permission javax.security.auth.AuthPermission "createLoginContext.*";
        permission java.security.SecurityPermission "insertProvider.Mozilla-JSS";
        permission javax.security.auth.AuthPermission "putProviderProperty.Mozilla-JSS";
        permission java.io.FilePermission "ALL FILES", "execute,delete";
        permission java.io.FilePermission "$VAR_SUBDIR/logs/*", "delete,write";
        permission java.util.PropertyPermission "java.util.logging.config.class", "write";
        permission java.security.SecurityPermission "removeProvider.SUN";
        permission java.security.SecurityPermission "insertProvider.SUN";
        permission java.security.SecurityPermission "removeProvider.Mozilla-JSS";
        permission javax.security.auth.AuthPermission "doAs";
        permission java.util.PropertyPermission "java.security.krb5.realm", "write";
        permission java.util.PropertyPermission "java.security.krb5.kdc", "write";
        permission java.util.PropertyPermission "java.security.auth.login.config", "write";
        permission javax.security.auth.kerberos.ServicePermission "*", "accept";
        permission javax.net.ssl.SSLPermission "setHostnameVerifier";
       };

    Post installation modifications to server.policy are made as follows:

    Replaceable Content 

    Default Value 

    $BASEDIR

    /opt

    $PROD_DIR

    SUNWam

    $AS81_VARDIR

    /var/opt/SUNWappserver

    $AS81_DOMAIN

    domain1

    $VAR_SUBDIR

    /var/opt/SUNWam

    $DEPLOY_WARPREFIX

    federation

  3. Restart the Application Server.

ProcedureTo View the Federation Manager Java API Specifications

  1. To view the Federation Manager Java API Specifications when it is deployed in Application Server, you must first create a symbolic link by typing:


    # ln -s /FederationManager-base/SUNWam/fm/docs /Application Server-doc-root/javadocs
    

    where:

    FederationManager-base

    Defines the Federation Manager installation directory. 

    Application Server-doc-root

    Defines the Application Server directory in which you store publicly available documentation files. 

  2. Once the symbolic link is defined, you can access the Java API Reference via a web browser by typing a URL in the format protocol://host:port/javadocs. For example, http://host1.sun.com:81/javadocs.

ProcedureTo Delete an Instance of Federation Manager from Application Server

  1. Type the following command replacing the variables with information regarding your deployment:


    # ApplicationServer-base/bin/asadmin undeploy --user AS-administrator 
    --passwordfile filename --host host --port port
     --target instance-name deployment-URI
    

    where:

    ApplicationServer-base

    Defines the Application Server installation directory. 

    AS-administrator

    Defines the administrator of the Application Server 

    filename

    Defines the file that holds the Application Server administrator password. 

    host

    Defines the server that is hosting Federation Manager. 

    port

    Defines the port number used. 

    instance-name

    Defines the instance of Application Server to which the application is deployed. 

    deployment-URI

    Defines the Federation Manager URI (with leading slash). 

    For example:


    # /opt/SUNWappserver/appserver/bin/asadmin undeploy --user admin 
    --passwordfile /tmp/pwdfile --host samplehost.sun.com 
    --port 4849 --target server1 /fm
    
  2. Hit Enter.

Deploying Federation Manager in BEA WebLogic Server

With BEA WebLogic Server 8.1 (minimum version supported), you can use the weblogic.Deployer utility on the command line to deploy a WAR file. More information on this utility can be found in the BEA WebLogic Server documentation.

This section contains the following procedures:

ProcedureTo Deploy an Instance of Federation Manager in BEA WebLogic Server

  1. Type the following command replacing the variables with information regarding your deployment and hit Enter.


    # WebLogic-base/bin/java -classpath WebLogic-classpath weblogic.Deployer 
    -adminurl http://server-host:server-port -name deployment-URI 
    -username WebLogic-admin -password WebLogic-admin-password -target instance-name 
    -deploy WAR-file-location
    

    where:

    WebLogic-base

    Defines the WebLogic Server installation directory. 

    WebLogic-classpath

    Includes the JDK path and weblogic.jar. 

    server-host

    Defines the WebLogic Server host to which Federation Manager will be deployed. 

    server-port

    Defines the port of the WebLogic Server host to which Federation Manager will be deployed. 

    deployment-URI

    Defines the URI for the application. This value must be the same as that defined for the SERVER_DEPLOY_URI property in The Silent Installation File.

    WebLogic-admin

    Defines the ID of the WebLogic Server super user (weblogic, by default). 

    WebLogic-admin-password

    Defines the password of the WebLogic Server super user. 

    instance-name

    Defines the instance of WebLogic Server to which the WAR will be deployed. 

    WAR-file-location

    Defines the full path to the WAR file being deployed. 

    For example:


    /export/bea8/jdk142_06/bin/java -classpath /export/bea8/weblogic8/lib/weblogic.jar:. 
    weblogic.Deployer -adminurl http://samplehost.sun.com:7001 -name /fm 
    -username weblogic -password 11111111 -target myserver 
    -deploy /var/opt/SUNWam/fm/war_staging/fm.war
  2. Restart the WebLogic Server.

ProcedureTo Delete an Instance of Federation Manager from BEA WebLogic Server

  1. Type the following command replacing the variables with information regarding your deployment:


    # WebLogic-base/bin/java -classpath WebLogic-classpath weblogic.Deployer -undeploy 
    -adminurl http://server-host:server-port -name deployment-URI 
    -username WebLogic-admin -password WebLogic-admin-password 
    -target WebLogic-Server 
    

    where:

    WebLogic-base

    Defines the WebLogic Server installation directory. 

    WebLogic-classpath

    Includes the JDK path and weblogic.jar. 

    server-host

    Defines the WebLogic Server host to which Federation Manager is deployed. 

    server-port

    Defines the port of the WebLogic Server host to which Federation Manager is deployed. 

    deployment-URI

    Defines the Federation Manager URI. 

    WebLogic-admin

    Defines the ID of the WebLogic Server super user (weblogic, by default). 

    WebLogic-admin-password

    Defines the password of the WebLogic Server super user. 

    WebLogic-Server

    Defines the instance of WebLogic Server in which Federation Manager is deployed. 

    For example:


    /export/bea8/jdk142_06/bin/java -classpath /export/bea8/weblogic8/lib/weblogic.jar:. 
    weblogic.Deployer -undeploy -adminurl http://samplehost.sun.com:7001 
    -name /fm -username weblogic -password 11111111 -target myserver
  2. Hit Enter.

Deploying Federation Manager in WebSphere Application Server

Before deploying an application or deleting an instance in WebSphere Application Server 5.1 (minimum version supported), you must modify the Jacl (Java Action Command Language) descriptor file. Following this you may run the wsadmin.sh file from the command line. More information on both of these steps can be found in the WebSphere Application Server documentation.

This section contains the following procedures:

ProcedureTo Deploy an Instance of Federation Manager in WebSphere Application Server

  1. Create a Jacl descriptor (for example, fmsetup.jacl) with the following content:


    # $AdminApp install WAR-file-location {-contextroot 
    deployment-URI -usedefaultbindings -nopreCompileJSPs -distributeApp 
    -nouseMetaDataFromBinary -node WebSphereAS-node 
    -cell WebSphereAS-cell -server WebSphereAS-instance 
    -nodeployejb -appname deployment-URI -createMBeansForResources 
    -noreloadEnabled -reloadInterval 0 -nodeployws}
    

    where:

    WAR-file-location

    Defines the full path to the WAR file being deployed. 

    deployment-URI

    Defines the Federation Manager URI. This is generally the name of the WAR file without the .WAR suffix.

    WebSphereAS-node

    Defines the node under which the Application Server instance is configured. 

    WebSphereAS-cell

    Defines the cell under which the Application Server node is configured. 

    WebSphereAS-instance

    Defines the instance of the Application Server to which Federation Manager will be deployed. 

  2. Save the configuration with the following command:


    # $AdminConfig save
    
  3. After editing the Jacl descriptor, run the following command to deploy the WAR:


    # WebSphereAS-base/bin/wsadmin.sh -f Jacl-descriptor-file
    

    where:

    Jacl-descriptor-file

    Defines the full path to the Jacl descriptor previously created. 

ProcedureTo Delete an Instance of Federation Manager from WebSphere Application Server

  1. Edit the Jacl descriptor by adding the following:

    \$AdminApp uninstall deploy-tag {-node WebSphereAS-node -cell WebSphereAS-cell -server WebSphereAS-instance}

    where:

    deploy-tag

    Defines the Federation Manager URI. This is generally the name of the WAR file without the .WAR suffix.

    WebSphereAS-node

    Defines the node under which the Application Server instance is configured. 

    WebSphereAS-cell

    Defines the cell under which the Application Server node is configured. 

    WebSphereAS-instance

    Defines the instance of the Application Server to which Federation Manager will be deployed. 

  2. After editing the Jacl descriptor, run the following command to delete the instance:


    # WebSphereAS-base/bin/wsadmin.sh -f Jacl-descriptor-file