Sun Java System Access Manager 7.1 Developer's Guide

Chapter 11 Customizing the Administration Console

The Sun JavaTM System Access Manager 7.1 console is a web-based interface for creating, managing, and monitoring the identities, web services, and enforcement policies configured throughout an Access Manager deployment. It is built with Sun Java System Application Framework, a Java 2 Enterprise Edition (J2EE) framework used to help developers build functional web applications. XML files, JavaServer PagesTM (JSP) and Cascading Style Sheets (CSS) define the look of the Access Manager HTML pages.

This chapter describes the Access Manager administration console, its pluggable architecture, and how to customize the Legacy mode user interface. The chapter contains the following sections:


Note –

At this time, no documentation or code samples exist for modifying the Realm mode user interface. For customized information on modifying the Realm mode user interface in your environment, contact your Sun Sales Representative.


About the Administration Console

The console is divided into three frames: Header, Navigation and Data. The Header frame displays corporate branding information as well as the first and last name of the currently logged-in user as defined in their profile. It also contains a set of tabs to allow the user to switch between the management modules, a hyperlink to the Access Manager Help system, a Search function and a Logout link. The Navigation frame on the left displays the object hierarchy of the chosen management module, and the Data frame on the right displays the attributes of the object selected in the Navigation frame.

Figure 11–1 Legacy Mode Administration Console

The Legacy Mode administration console consists
of three frames: header, navigation, and data.

For information about what the Console does and about the differences between the Realm mode and Legacy mode console interfaces, see Chapter 1, The Access Manager Console, in Sun Java System Access Manager 7.1 Administration Guide.

Generating The Console Interface

When the Access Manager console receives an HTTP(S) request, it first determines whether the requesting user has been authenticated. If not, the user is redirected to the Access Manager login page supplied by the Authentication Service. After successful authentication, the user is redirected back to the console which reads all of the user’s available roles, and extracts the applicable permissions and behaviors. The console is then dynamically constructed for the user based on this information. For example, users with one or more administrative roles will see the administration console view while those without any administrative roles will see the end user console view. Roles also control the actions a user can perform and the identity objects that a user sees. Pertaining to the former, the organization administrator role allows the user read and write access to all objects within that organization while a help desk administrator role only permits write access to the users’ passwords. With regards to the latter, a person with a people container administrator role will only see users in the relevant people container while the organization administrator will see all identity objects. Roles also control read and write permissions for service attributes as well as the services the user can access.

Plug-In Modules

An external application can be plugged-in to the console as a module, gaining complete control of the Navigation and Data frames for its specific functionality. In this case, a tab with the name of the custom application needs to be added to the Header frame. The application developer would create the JSPs for both left and right frames, and all view beans, and models associated with them.

Accessing the Console

The Naming Service defines URLs used to access the internal services of Access Manager. The URL used to access the Administration Console web application is:

http://AcceessManager-HostName.domain_name:port/
		amconsole

The first time Administration Console (amconsole) is accessed, it brings the user to the Authentication web application (amserver) for authentication and authorization purposes. After login, amserver redirects the user to the configured success login URL. The default successful login URL is:

http(s)://AcceessManager-HostName.domain_name:port/
		amconsole/base/AMAdminFrame

Customizing The Console

The Access Manager Legacy mode console uses JSP and CSS to define the look and feel of the pages used to generate its frames. A majority of the content is generated dynamically—based on where, and at what, the user is looking. In that regard, the modification of the content is somewhat restricted. Within the Navigation frame, the layout of the controls (the view menu), the action buttons, and the table with current objects in each JSP can be changed. In the Data frame, the content displayed is dynamically generated based on the XML service file being accessed but the layout, colors, and fonts are controlled by the adminstyle.css style sheet.

The Default Console Files

An administrator can modify the console by changing tags in the JSPs and CSS's. All of these files can be found in the AccessManager-base/SUNWam/web-src/services/console directory. The files in this directory provide the default Sun Java System interface. Out of the box, it contains the following subdirectories:


Note –

Console-related JSP contain HTML and custom library tags. The tags are defined in tag library descriptor files (.tld) found in the AccessManager-base/SUNWam/web-src/WEB-INF directory. Each custom tag corresponds to a view component in its view bean. While the tags in the JSP can be removed, new tags can not be added. For more information, see the Sun Java System Application Framework at http://docs.sun.com/app/docs/coll/S1_appframe20_en.


console.war

The console.war contains files used by the Access Manager administration console.

Files You Can Modify

You can modify the following console.war files:

Files You Must Not Modify

Do not modify the following console.war files. Modifying these files may cause unintended Access Manager behaviors.

Creating Custom Organization Files

To customize the console for use by a specific organization, the AccessManager-base/SUNWam/web-src/services/console directory should first be copied, renamed and placed on the same level as the default directory. The files in this new directory can then be modified as needed.


Note –

There is no standard to follow when naming the new directory. The new name can be any arbitrarily chosen value.


For example, customized console files for the organization dc=new_org, dc=com might be found in the AccessManager-base/SUNWam/web-src/services/custom_directory directory.

ProcedureTo Create Custom Organization Files

  1. Change to the directory where the default templates are stored:

    cd AccessManager-base/SUNWam/web-src/services

  2. Make a new directory at that level.

    The directory name can be any arbitrary value. For this example, it is named AccessManager-base/SUNWam/web-src/services/custom_directory/.

  3. Copy all the JSP files from the console directory into the new directory.

    AccessManager-base/SUNWam/web-src/services/console contains the default JSP for Access Manager. Ensure that any image files are also copied into the new directory.

  4. Customize the files in the new directory.

    Modify any of the files in the new directory to reflect the needs of the specific organization.

  5. Modify the AMBase.jsp file.

    In our example, this file is found in AccessManager-base/SUNWam/web-src/services/custom_directory/base. The line String console = "../console"; needs to be changed to String console = "../new_directory_name ";. The String consoleImages tag also needs to be changed to reflect a new image directory, if applicable. The contents of this file are copied in Creating Custom Organization Files.


    <!--
     Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
     Use is subject to license terms.
    -->
    
    <% String console = "../console";
       String consoleUrl = console + "/";
       String consoleImages = consoleUrl + "images";
    %>
    
    
                      
  6. Change the value of the JSP Directory Name attribute in the Administration Service to match that of the directory created in Creating Custom Organization Files.

    The JSP Directory Name attribute points the Authentication Service to the directory which contains an organization’s customized console interface. Using the console itself, display the services registered to the organization for which the console changes will be displayed. If the Administration Service is not visible, it will need to be registered. For information on registering services, see the Administration Guide.

    Once the new set of console files have been modified, the user would need to log into the organization where they were made in order to see any changes. Elaborating on our example, if changes are made to the JSP located in the AccessManager-base/SUNWam/web-src/services/custom_directory directory, the user would need to login to that organization using the URL:

    http:// server_name.domain_name:port//
    		service_deploy_uri/UI/Login?org=
    			custom_directory_organization.

Alternate Customization Procedure

The console can also be modified by simply replacing the default images in AccessManager-base/SUNWam/web-src/services/console/images , with new, similarly named images.

Miscellaneous Customizations

Included in this section are procedures for several specific customizations available to administrators of the Access Manager console.

To Modify The Service Configuration Display

A service is a group of attributes that are managed together by the Access Manager console. Out-of-the-box, Access Manager loads a number of services it uses to manage its own features. For example, the configuration parameters of the Logging Service are displayed and managed in the Access Manager console, while code implementations within Access Manager use the attribute values to run the service.

To Modify The User Profile View

The Access Manager console creates a default User Service view based on information defined in the amUser.xml service file.

A modified user profile view with functionality more appropriate to the organization’s environment can be defined by creating a new ViewBean and/or a new JSP. For example, an organization might want User attributes to be formatted differently than the default vertical listing provided. Another customization option might be to break up complex attributes into smaller ones. Currently, the server names are listed in one text field as:

protocol://Access Manager_host. domain:port

Instead, the display can be customized with three text fields:

protocol_chooser_field://server_host_field :port_number_field

A third customization option might be to add JavaScript to the ViewBean to dynamically update attribute values based on other defined input. The custom JSP would be placed in the following directory: AccessManager-base/SUNWam/web-src/services/console/user. The ViewBean is placed in the classpath com.iplanet.am.console.user. The value of the attribute User Profile Display Class in the Administration Service (iplanet-am-admin-console-user- profile-class in the amAdminConsole.xml service file) would then be changed to the name of the newly created ViewBean. The default value of this attribute is com.iplanet.am.console.user.UMUserProfileViewBean.

Display Options For The User Profile Page

There are a number of attributes in the Administration Service that can be selected to display certain objects on the User Profile page. Display User’s Roles, Display User’s Groups and User Profile Display Options specify whether to display the roles assigned to a user, the groups to which a user is a member and the schema attributes, respectively. More information on these service attributes can be found in the Administration Guide.

To Localize The Console

All textual resource strings used in the console interface can be found in the amAdminModuleMsgs.properties file, located in AccessManager-base/SUNWam/locale/. The default language is English (en_US). Modifying this file with messages in a foreign language will localize the console.

To Display Service Attributes

Service attributes are defined in XML service files based on the sms.dtd . In order for a particular service attribute to be displayed in the console, it must be configured with the any XML attribute. The any attribute specifies whether the service attribute for which it is defined will display in the Access Manager console.

To Customize Interface Colors

All the colors of the console are configurable using the Access Manager style sheet adminstyle.css located in the AccessManager-base/SUNWam/web-src/services/console/css directory. For instance, to change the background color for the navigation frame, modify the BODY.navFrame tag; or to change the background color for the data frame, modify the BODY.dataFrame. The tags take either a text value for standard colors (blue, green, red, yellow, etc.) or a hexadecimal value (#ff0000, #aadd22, etc.). Replacing the default with another value will change the background color of the respective frame after the page is reloaded in the browser. Miscellaneous Customizations details the tag in adminstyle.css.


Example 11–1 BODY.navFrame Portion of adminstyle.css


BODY.navFrame   {
                color: black;
                background: #ffffff;
                }


                  

To Change The Default Attribute Display Elements

The console auto-generates Data frame pages based on the definition of a service’s attributes in an XML service definition file. Each service attribute is defined with the XML attributes type, uitype and syntax. Type specifies the kind of value the attribute will take. uitype specifies the HTML element displayed by the console. syntax defines the format of the value. The values of these attributes can be mixed and matched to alter the HTML element used by the console to display the values of the attributes. For example, by default, an attribute of the single_choice type displays its choices as a drop down list in which only one choice can be selected. This list can also be presented as a set of radio buttons if the value of the uitype attribute is changed to radio. Miscellaneous Customizations illustrates this concept.


Example 11–2 uitype XML Attribute Sample


 <AttributeSchema name="test-attribute"
                    type="single_choice"
                    syntax="string"
                    any="display"
                    uitype="radio"
                    i18nKey="d105">
                    <ChoiceValues>
 <ChoiceValue i18nKey="u200">Daily</ChoiceValue>
 <ChoiceValue i18nKey="u201">Weekly</ChoiceValue>
 <ChoiceValue i18nKey="u202">Monthly</ChoiceValue>
                    </ChoiceValues>
                    <DefaultValues>
                        <Value>Daily</Value>
                    </DefaultValues>
                </AttributeSchema>


                  

Miscellaneous Customizations is a listing of the possible values for each attribute, and the corresponding HTML element that each will display based on the different groupings.

Table 11–1 Service Attribute Values and Corresponding Display Elements

type Value 

syntax Value 

uitype Value 

Element Displayed In Console 

single_choice 

string 

No value defined 

pull-down menu choices 

   

radio 

radio button choices 

Single 

boolean 

No value defined 

checkbox 

   

radio 

radio button 

 

string 

No value defined 

text field 

   

link 

hyperlink 

   

button 

clickable button 

 

password 

No value defined 

text field 

 

paragraph 

No value defined 

scrolling text field 

list 

string 

No value defined 

Add/Delete name list 

   

name_value_list

Add/Edit/Delete name list 

multiple_choice

string 

No value defined 

choice list 

To Add A Module Tab

The section “Plug-In Modules” mentions the capability to plug-in external applications as modules. Once this is accomplished, the module needs to be accessible via the console by adding a new module tab. Label information for module tabs are found in the amAdminModuleMsgs.properties console properties file located in AccessManager-base/SUNWam/locale/. To add label information for a new module, add a key and value pair similar to module105_NewTab=My New Tab. Miscellaneous Customizations illustrates the default pairs in the file.


Example 11–3 Module Tab Key And Value Pairs


module101_identity=Identity Management
module102_service=Service Configuration
module103_session=Current Sessions
module104_federation=Federation Management
                  

The module name and a URL for the external application also need to be added to the View Menu Entries attribute in the Administration Service (or iplanet-am-admin-console-view-menu in the amAdminConsole.xml service file). When a module tab in the Header frame is clicked, this defined URL is displayed in the Navigation frame. For example, to define the display information for the tab sample, an entry similar to module105_NewTab|/amconsole/custom_directory /custom_NavPage would be added to the View Menu Entries attribute in the Administration Service.


Note –

The console retrieves all the entries from this attribute and sorts them by i18n key. This determines the tab display order in the Header frame.


After making these changes and restarting Access Manager, a new tab will be displayed with the name My New Tab.

To Display Container Objects

In order to create and manage LDAP organizational units (referred to as containers in the console), the following attributes need to be enabled (separately or together) in the Administration Service.

Viewing any of these display options is also dependent on whether the Enable User Management attribute is selected in the Administration Service. (This attribute is enabled by default after a new installation.) More information on these attributes can be found in the Administration Guide.

Console APIs

The public console API package is named com.iplanet.am.console.base.model . It contains interfaces that can be used to monitor and react to events that occur in the console. This listener can be called when the user executes an action on the console that causes an event. An event can have multiple listeners registered on it. Conversely, a listener can register with multiple events. Events that might be used to trigger a listener include:

When a listener is created all the methods of that interface must be implemented thus, the methods in the AMConsoleListener interface must be implemented. The AMConsoleListenerAdapter class provides default implementations of those methods and can be used instead. Creating a console event listener includes the following:

ProcedureTo Create a Console Event Listener

  1. Write a console event listener class or implement the default methods in the AMConsoleListenerAdapter class.

  2. Compile the code.

  3. Register the listener in the Administration Service.

    Access Manager includes a sample implementation of the ConsoleEventListener. The Sun Java System Access Manager 7.1 Java API Reference also contains more detailed information on the listener interfaces and class.

Precompiling the Console JSP

Each JSP is compiled when it is first accessed. Because of this, there is a delay when displaying the HTML page on the browser. To avoid this delay, the system administrator can precompile the JSP by running the following command:

WebServer_install_directory/servers/bin/https/bin/jspc -webapp AccessManager-base/SUNWam/web-src/services

where, by default, WebServer_install_directory is /opt/SUNWwbsvr.

Console Samples

Sample files have been included to help understand how the Access Manager console can be customized. The samples include instructions on how to:

Modify User Profile Page

This sample modifies the user interface by adding a hyperlink that allows an existing user to change their configured password. It is in the ChangeUserPassword directory.

Create A Tabbed Identity Management Display

This sample creates a custom user profile which displays the profile with three tabs. The sample is in the UserProfile directory.

ConsoleEventListener

This sample displays the parameters passed to AMConsoleListener class in the amConsole debug file. It is in the ConsoleEventListener directory.

Add Administrative Function

This sample adds functionality to the Identity Management module that allows an administrator to move a user from one organization to other. It is in the MoveUser directory.

Add A New Module Tab

This sample adds a new tab into the Header frame. This tab will connect to an external application and can be configured using the console. It is in the NewTab directory.

Create A Custom User Profile View

This sample creates a custom user profile view to replace the default user profile view. A different user profile view can be created for each configured organization. A custom class would need to be written that extends the default user profile view bean. This class would then be registered in the User Profile Display Class attribute of the Administration Service. There is an example of how to do this in the samples directory. This sample is in the UserProfile directory.

These samples are located in AccessManager-base/SUNWam/samples/console. Open the README file in this directory for general instructions. Each specific sample directory also contains a README file with instructions relevant to that sample.


Note –

The console samples are only available when Access Manager is installed on the SolarisTM operating system.