Sun ONE logo      Previous      Contents      Index      Next     

Sun ONE Identity Server Customization and API Guide

Chapter 2
The Identity Server Console

The Sun ONE Identity Server console is a web-based interface for creating, managing, and monitoring the identities, web services, and enforcement policies configured throughout an Identity Server deployment. It is built with Sun ONE Application Framework, a Java™ 2 Enterprise Edition (J2EE) framework used to help developers build functional web applications. XML files, JavaServer Pages™ (JSP) and Cascading Style Sheets (CSS) are used to define the look of the HTML pages. This chapter explains the console, its pluggable architecture, and how to customize it. It contains the following sections:


Overview

The Identity Server console is a web interface that allows administrators with different levels of access to, among other things, create organizations, create (and delete) users to (and from) those organizations, and establish enforcement policies that protect and limit access to the organization’s resources. In addition, administrators can view and terminate current user sessions and manage their federation configurations (create, delete and modify authentication domains and providers). Users without administrative privileges, on the other hand, can manage personal information (name, e-mail address, telephone number, etc.), change their password, subscibe and unsubscribe to groups, and view their roles. All of these functionalities are accomplished using a web browser.


Note

The client web browser accessing the console must support JavaScript, version 1.2 and cookies.


The console ships with four modules: Identity Management (including user and policy management), Service Configuration, Current Sessions (including session management) and Federation Management. Customization of these modules and the Identity Server console can be achieved, in varying degrees, by modifying the JSP and XML files that define the interface as well as extending the Sun ONE Application Framework ViewBeans.


Note

A ViewBean is a Java class written specifically for rendering display. In Identity Server, each identity object has its own profile ViewBean. For example, the user profile has the UMUserProfileViewBean.


Console Interface

The console is divided into three frames as pictured in Figure 2-1: 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 Identity Server 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 2-1  The Identity Server Console

Identity Server console has three frames: Header, Navigation and Data.

Generating The Console Interface

When the Identity Server console receives an HTTP(S) request, it first determines whether the requesting user has been authenticated. If not, the user is redirected to the Identity Server 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. Information on how to define a module tab can be found in "To Add A Module Tab".

Accessing The Console

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

http://identity_server_host.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 as discussed in "The User Interface Login URL" of Chapter 3, "Authentication Service." The default successful login URL is http(s)://identity_server_host.domain_name:port/amconsole/base/AMAdminFrame.


Customizing The Console

The Identity Server 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 JSP and CSS. All of these files can be found in the IdentityServer_base/SUNWam/web-apps/applications/console directory. The files in this directory provide the default Sun ONE interface. Out of the box, it contains the following sub-directories:

Creating Custom Organization Files

To customize the console for use by a specific organization, the IdentityServer_base/SUNWam/web-apps/applications/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 IdentityServer_base/SUNWam/web-apps/applications/custom_directory directory.

To Create Custom Organization Files

  1. Change to the directory where the default templates are stored:
  2. cd IdentityServer_base/SUNWam/web-apps/applications

  3. Make a new directory at that level.
  4. The directory name can be any arbitrary value. For this example, it is named IdentityServer_base/SUNWam/web-apps/applications/custom_directory/.

  5. Copy all the JSP files from the console directory into the new directory.
  6. IdentityServer_base/SUNWam/web-apps/applications/console contains the default JSP for Identity Server. Ensure that any image files are also copied into the new directory.

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

  9. Modify the AMBase.jsp file.
  10. In our example, this file is found in IdentityServer_base/SUNWam/web-apps/applications/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 Code Example 2-1.

    Code Example 2-1  The AMBase.jsp File 

    <!--

    Copyright 2002 Sun Microsystems, Inc. All rights reserved.

    Use is subject to license terms.

    -->

    <% String console = "../console";

    String consoleUrl = console + "/";

    String consoleImages = consoleUrl + "images";

    %>

  11. Change the value of the JSP Directory Name attribute in the Administration Service to match that of the directory created in Step 2.
  12. 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 Chapter 6, "Service Management" in this manual or the Sun ONE Identity Server 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 IdentityServer_base/SUNWam/web-apps/applications/custom_directory directory, the user would need need to login to that organization using the URL http://server_name.domain_name:port/service_deploy_uri/UI/Login?org=custom_directory_organization.


Note

More information on this login URL and authentication URL parameters can be found in Chapter 3, "Authentication Service" in this manual.


Alternate Customization Procedure

The console can also be modified by simply replacing the default images in IdentityServer_base/SUNWam/web-apps/applications/console/images, with new, similarly named images.

Miscellaneous Customizations

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

To Modify The Service Configuration Display

A service is a group of attributes that are managed together by the Identity Server console. Out-of-the-box, Identity Server 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 Identity Server console, while code implementations within Identity Server use the attribute values to run the service. There is a defined procedure for adding Identity Server services to the console. For information on this procedure, see "Defining A Custom Service" of Chapter 6, "Service Management." Chapter 6 also contains information on how to extend existing services, add or remove a service name from the Navigation frame using the "serviceHierarchy Attribute" and change the default service display using the "propertiesViewBeanURL Attribute"

To Modify The User Profile View

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


Note

Attributes defined as User attributes in each service’s specific XML file can also be displayed in the User Service. More information on how this is done can be found in "Customizing User Pages" of Chapter 6, "Service Management" in this manual.


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://Identity Server_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 IdentityServer_base/SUNWam/web-apps/applications/console/user directory and the ViewBean 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. More information on this procedure can be found in "Console Samples".

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 Sun ONE Identity Server 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 IdentityServer_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 Identity Server console. More information on this attribute can be found in "any Attribute" of Chapter 6, "Service Management" in this manual.

To Customize Interface Colors

All the colors of the console are configurable using the Identity Server style sheet adminstyle.css located in the IdentityServer_base/SUNWam/web-apps/applications/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. Code Example 2-2 details the tag in adminstyle.css.

Code Example 2-2  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. As documented in "The sms.dtd Structure" in Chapter 6, "Service Management" in this manual, 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. Code Example 2-3 illustrates this concept.

Code Example 2-3  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>

Table 2-1 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 2-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

"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 IdentityServer_base/SUNWam/locale/. To add label information for a new module, add a key and value pair similar to module105_NewTab=My New Tab. Code Example 2-4 illustrates the default pairs in the file.

Code Example 2-4  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 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 Identity Server, a new tab will be displayed with the name My New Tab. For information on the sample that explains how to add a new tab, see "Console Samples".

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 Sun ONE Identity Server Administration Guide.


Console API

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:

  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.

Identity Server includes a sample implementation of the ConsoleEventListener. See "ConsoleEventListener" for more information. The Identity Server Javadocs 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 IdentityServer_base/SUNWam/web-apps/applications

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


Console Samples

Sample files have been included to help understand how the Identity Server 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. Figure 2-2 contains a screenshot of a tabbed user profile. It is in the UserProfile directory.

Figure 2-2  Console With Three Tabs

Identity Server console Data frame divided with three tabs.

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 IdentityServer_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 Identity Server is installed on the Solaris™ operating system.




Previous      Contents      Index      Next     


Copyright 2003 Sun Microsystems, Inc. All rights reserved.