Installing, Configuring, and Deploying Sun Java System Access Manager the Simple Way

Sun Java System Access Manager 7.1 (henceforth, Access Manager) integrates authentication and authorization services, policy agents, identity management, and identity federation for protecting network resources. Subsequently, you can secure access to resources and manage the identities of the users who access them.

You can deploy Access Manager on most platforms on most containers—that is, most Web servers or application servers—that comply with the Java Servlet 2.3 API Specification. Such was not always the case; see the appendix.

This article describes a simple and efficient way to install, configure, and deploy Access Manager on Sun Java System Application Server (henceforth, Application Server), which is also an open-source project called GlassFish. On average, the entire process takes less than 10 minutes to complete and so is especially handy for prototypes.

First, download the following software:

• Sun Application Server Platform Edition 9.0 or a later release, derived from GlassFish
  
  
• Access Manager
  
  The ZIP file contains the Java Development Kit (JDK) version-specific Web archive (WAR) files, the application for Distributed Authentication, administrative command-line interface (CLI) tools, session failover tools, legal files, and procedures for running the samples. Unzip the file to a directory of your choice, referred to as Access_Manager_install_dir in the rest of this article. Figure 1 shows this directory's file structure.
  
  

  Figure 1: File Structure of Access Manager

   
  The main difference between the jdk14 and jdk15 binaries is size. Sun's JDK 1.5.x includes most of the Java archive (JAR) files for Java Web Services Developer Pack (Java WSDP), but those files are not part of Access Manager for the containers that run under Sun's JDK 1.5.x. The example in this article uses the amserver.war file under Access_Manager_install_dir /applications/jdk15.

If you have enabled Security Manager in the Java virtual machine, add the Access Manager-related permissions to Application Server's server.policy file, as follows.

// ADDITIONS FOR Access Manager
grant codeBase "file:\${com.sun.aas.instanceRoot}/applications/j2ee-modules/amserver/-" {
    permission java.net.SocketPermission "*", "connect,accept,resolve";
    permission java.util.PropertyPermission "*", "read, write";
    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 "getLoginConfiguration";
    permission javax.security.auth.AuthPermission "setLoginConfiguration";
    permission javax.security.auth.AuthPermission "modifyPrincipals";
    permission javax.security.auth.AuthPermission "createLoginContext.*";
    permission java.io.FilePermission "<<ALL FILES>>", "execute,delete";
    permission java.util.PropertyPermission "java.util.logging.config.class", "write";
    permission java.security.SecurityPermission "removeProvider.SUN";
    permission java.security.SecurityPermission "insertProvider.SUN";
    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 java.util.PropertyPermission "user.language", "write";
    permission javax.security.auth.kerberos.ServicePermission "*", "accept";
    permission javax.net.ssl.SSLPermission "setHostnameVerifier";
    permission java.security.SecurityPermission "putProviderProperty.IAIK";
    permission java.security.SecurityPermission "removeProvider.IAIK";
    permission java.security.SecurityPermission "insertProvider.IAIK";
};
// END OF ADDITIONS FOR Access Manager

Note: If you deploy Access Manager 7.1 with a name other than amserver, change the amserver string in the grant statement correspondingly. Alternatively, just cite grant {...} for testing.

Note: If your container of choice is IBM WebSphere, set the following two Java virtual machine options in the container's server.xml file:

-DamCryptoDescriptor.provider=IBMJCE
-DamKeyGenDescriptor.provider=IBMJCE

For example:

genericJvmArguments="-DamCryptoDescriptor.provider=IBMJCE -DamKeyGenDescriptor.provider=IBMJCE"

Afterward, restart Application Server for the changes to take effect.

Now deploy the Access Manager WAR file on any Web container that is supported by Sun Java Enterprise System 5. Three steps are involved:

• Deploy the WAR file.
• Configure Access Manager.
• Verify the configuration.

Deploying the WAR File
To deploy the WAR file:

1. Log in to the Application Server Administration Console at http://localhost:4848.
   
   The default user name is admin; the default password is adminadmin.
   
   
2. On the left pane, select Web Applications under Applications. On the right pane, specify the location of the Access Manager WAR file ( Access_Manager_install_dir /applications/jdk15/amserver.war) and click Deploy.
   
   Once deployment is successful, Application Server displays amserver under Deployed Web Applications, as shown in Figure 2.
   
   

   Figure 2: Successful Deployment of Access Manager on Application Server (Click image for larger view.)

    
   

Configuring Access Manager
To configure Access Manager:

1. Click Launch.
   
   Alternatively, go to http:// hostname.domain_name .com: portnumber /amserver, where:
   
   
   • hostname.domain_name .com is the name of the host on which Access Manager is deployed.
   • portnumber is the number of the port from which Access Manager will be listening for incoming requests.
   
   The Access Manager Configurator page is displayed, as shown in Figure 3.
   
   

   Figure 3: Configurator Page in Application Server (Click image for larger view.)

    
   
2. Specify the amAdmin password (for example, admin123) and the configuration directory (for example, /amconfig).
   
   
3. Optional. To specify Sun Java System Directory Server as a configuration store, ensure that the Directory Server instance is installed and running and then do the following.
   
   
   1. Under Configuration Store Settings, select Directory Server.
      
      
   2. Under Server Settings, fill in the Name, Port, and "Suffix to store configuration data" fields.
      
      
   3. Under Directory Server Administration, fill in the Password and Retype Password fields.
   
   
4. Click Configure.
   
   Access Manager displays the status of the configuration process.

In this example, File System is the default for storing service configuration data. That is, all the service configuration files are under the config_dir / deploy_URI /sms directory, /amconfig/amserver/sms in this case.

After successful configuration, Access Manager displays the login screen, as shown in Figure 4.

Figure 4: Access Manager Login Screen (Click image for larger view.)

Verifying the Configuration
Finally, verify the configuration by logging in. The Access Manager Administration Console is displayed, as shown in Figure 5.

Figure 5: Access Manager Administration Console (Click image for larger view.)

As soon as configuration is complete, Access Manager creates the following files in your system:

1. Configuration files — These files reside in the directory specified in the Configurator page (General Settings > Configuration Directory). In this example, that directory is called /amconfig. See its file structure in Figure 6.
   
   

   Figure 6: File Structure in the Configuration Directory

    
   
2. Bootstrap files — These files are required for locating configuration information in specific Access Manager instances. At a given point, depending on the number of the configured instances on the same host machine, multiple bootstrap files might apply. Do not delete those files.
   
   By default, a bootstrap file resides under the user.home directory. You can change that location as desired. For details on the procedure, see "Deploying Access Manager as a Single WAR File" in the Sun Java System Access Manager 7.1 Postinstallation Guide.
   
   Access Manager constructs the file name by editing the real path from Servlet Context and replacing the \ and / symbols with the _ symbol. For example, if the user running Application Server is root, the bootstrap file in this example is /AccessManager/AMConfig_opt_SUNWappserver_domains_domain1_applications_j2ee-modules_amserver_.

Access Manager offers no scripts for undeploying configured instances. To undeploy Access Manager:

1. Undeploy with container-specific commands.
   
   
2. Delete the configuration files and bootstrap file.
   
   See the preceding section.
   
   
3. Optional. Undo the server policy changes.
   
   If you would like to redeploy Access Manager, skip this step.
   
   
4. Restart the Web container.

To test with various configuration values without undeploying Access Manager:

1. Delete the configuration files and bootstrap file.
   
   
2. Restart the Web container.
   
   
3. Go to http:// hostname.domain_name .com: portnumber /amserver.
   
   The Configurator page is displayed.

In its earlier versions, the installer deployed Access Manager as packages. They were a collection of JAR files along with supporting XML, JavaServer Pages (JSP), HTML, and GIF files; also locale files and properties in the AMConfig.properties and serverconfig.xml files, the latter for directory configurations. That approach led to a number of problems, as follows:

• The installer was container-aware.
• The installer had operating system-related dependencies.
• Reverting to original configurations was complicated.
• Wide distribution of Access Manager was not feasible.

Consequently, the Access Manager engineering team set a goal to repackage the components to be deployable as J2EE applications. That goal became a reality in Access Manager 7.1: You can now conveniently deploy it as a single Web application, hassle free.

• Sun Java System Access Manager
• • Main page
  • Developer home
  • Software Forum
  • Related documentation: "Deploying Access Manager as a Single WAR File"
  
  
• Sun developer services
  • Support
  • Training and certification