Skip Headers
Oracle® Application Server Single Sign-On Administrator's Guide
10g Release 2 (10.1.2)
B14078-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

2 Basic Administration

This chapter introduces you to the tasks involved in administering single sign-on. The chapter contains the following topics:

2.1 The Single Sign-On Administrator's Role

When the single sign-on server is accessed for the first time, only one single sign-on administrator exists: orcladmin, the OracleAS super user. The person installing OracleAS selects the password for this user at install time. The orcladmin account is used to create other accounts, including accounts for iASAdmins, the group that administers single sign-on.

As a single sign-on administrator, you can use the administration pages to do the following:

2.2 Granting Administrative Privileges

To exercise your privileges as a single sign-on administrator, you must be a member of the administrative group iASAdmins. This means that an existing member of this group must add you to it.

To assign a user to iASAdmins:

  1. Start Oracle Directory Manager. To learn how to start this tool, see Oracle Internet Directory Administrator's Guide.

  2. Log in as cn=orcladmin, the directory super user. You must use the password that was assigned to this user when Oracle Internet Directory was installed.


    Note:

    The directory superuser cn=orcladmin is not the same as the OracleAS super user orcladmin. These are separate, hierarchically unequal accounts.

  3. In the System Objects frame, click in succession the following entries:

    • Entry Management

    • dc=default_identity_management_realm

    • cn=OracleContext

    • cn=Groups

    • cn=iASAdmins

    For example:

    cn=iASAdmins,cn=Groups,cn=OracleContext,dc=oracle,dc=com
    
    

    Where dc=oracle,dc=com is the default identity management realm. In reality, the default is likely the domain name of your installation.

  4. In the uniquemembers text box of the iASAdmins tab, add an entry for the user. uniquemembers is an attribute of the entry iASAdmins. As such it defines members of the group iASAdmins. Be sure to add the user's full DN. In Figure 2-1 the user cn=gbhatia,cn=users,dc=oracle,dc=com has been added.

  5. Click Apply.

Figure 2-1 iASAdmins Tab of Oracle Directory Manager

Description of Figure 2-1  follows
Description of "Figure 2-1 iASAdmins Tab of Oracle Directory Manager"

To create new users, use Oracle Delegated Administration Services. See the chapter about the Oracle Internet Directory Self-Service Console in Oracle Identity Management Guide to Delegated Administration.

2.3 Changing the Single Sign-On Administration Group

By default, the single sign-on server uses the directory entry cn=iASAdmins,cn=Groups,cn=OracleContext,default_realm_dn to determine whether a user has administrative privileges for OracleAS Single Sign-On. You can create a different default administration group by following these steps:

  1. Create a new group in the directory relative to the default realm DN. If, for example, your default realm is dc=us,dc=acme,dc=com, and you want the default administration group to be called sso_admins, create this entry:

    cn=sso_admins,dc=us,dc=acme,dc=com
    
    

    Use either Oracle Directory Manager or LDAP command line tools to create the entry.

  2. In the file ORACLE_HOME/sso/admin/plsql/sso/ssooidi.pks update the IASADMINSGROUP constant with the RDN that you created in step 1. Following the example given earlier, you would edit the line that contains this constant to look like this:

    IASADMINSGROUP CONSTANT VARCHAR2(1024) := 'cn=sso_admins';
    
    

    You do not have to include the default realm (dc=us,dc=acme,dc=com in the example). The single sign-on server appends the realm when it checks for group membership.

  3. Save the file.

  4. Load the file into the orasso schema:

    sql> connect orasso/password
    sql> @ssooidi.pks
    sql> @ssooidi.pkb
    
    

Once you complete these steps, all users in the group cn=sso_admins,dc=us,dc=acme,dc=com can administer the single sign-on server. You may include groups as members too.

2.4 policy.properties

policy.properties is a multipurpose configuration file for OracleAS Single Sign-On. This file contains basic parameters required by the single sign-on server. The default values of these parameters are adequate for most installations. Hence the file requires no modification out of the box.

policy.properties is also used to implement advanced single sign-on features such as multilevel authentication. Appendix C, "policy.properties" contains a copy of the file. policy.properties is also in the single sign-on configuration directory at ORACLE_HOME/sso/conf.


Note:

When editing policy.properties, take care not to insert blank space at the end of each line. After editing the file, restart the single sign-on server. See the section immediately following for instructions.

2.5 Stopping and Starting Single Sign-On Components

You can use either the command line or the Oracle Enterprise Manager Application Server Control console to start and stop single sign-on components. The console offers the benefit that you can stop or start several components at once. The command line requires several commands for the same tasks.

2.5.1 Using the Application Server Control Console

Use these steps to stop and start single sign-on components with the console:

  1. Go to the standalone console for the infrastructure instance of Oracle Enterprise Manager that you want to administer. This is effected by entering the host name of the computer hosting the OracleAS instance and the port number of Oracle Enterprise Manager. The default port number is 1810, but it may be configured in increments of one, up to 1816.

  2. Log in using the credentials of an OracleAS administrator.

  3. From the Standalone Instances section of the Farm page, choose the appropriate OracleAS instance.

  4. From the System Components list of the Application Server page, select the check boxes for the components that you want to stop, start, or restart; then click the appropriate button at the top of the list. Figure 2-2 shows the single sign-on middle tier being restarted. To stop or restart the entire identity management infrastructure, click Stop All or Restart All at the top of the page.

Figure 2-2 Using the Console to Restart the Single Sign-On Middle Tier

Description of Figure 2-2  follows
Description of "Figure 2-2 Using the Console to Restart the Single Sign-On Middle Tier"

2.5.2 Using the Command Line

You can issue separate commands to stop and start just the Oracle HTTP Server or the entire single sign-on middle tier. Another command stops and starts just the OC4J_SECURITY instance. Still another command stops and starts all infrastructure components.

2.5.2.1 Stopping and Starting the Oracle HTTP Server

Issue these two commands to stop and then start the Oracle HTTP Server:

ORACLE_HOME/opmn/bin/opmnctl stopproc process-type=HTTP_Server
ORACLE_HOME/opmn/bin/opmnctl startproc process-type=HTTP_Server

You can also stop and start the server by issuing this command:

ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server

2.5.2.2 Stopping and Starting the OC4J_SECURITY Instance

Issue these two commands to stop and then start the OC4J_SECURITY instance:

ORACLE_HOME/opmn/bin/opmnctl stopproc process-type=OC4J_SECURITY
ORACLE_HOME/opmn/bin/opmnctl startproc process-type=OC4J_SECURITY

You can also stop and start the OC4J_SECURITY instance by issuing this command:

ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=OC4J_SECURITY

2.5.2.3 Stopping and Starting the Single Sign-On Middle Tier

To stop and then start the single sign-on middle tier, stop and start both the Oracle HTTP Server and the OC4J_SECURITY instance:

ORACLE_HOME/opmn/bin/opmnctl stopproc process-type=HTTP_Server
ORACLE_HOME/opmn/bin/opmnctl startproc process-type=HTTP_Server

ORACLE_HOME/opmn/bin/opmnctl stopproc process-type=OC4J_SECURITY
ORACLE_HOME/opmn/bin/opmnctl startproc process-type=OC4J_SECURITY

You can also stop and start the single sign-on middle tier by issuing these commands:

ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server
ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=OC4J_SECURITY

2.5.2.4 Stopping and Starting All Components

Issue the following commands to stop and then start the Oracle HTTP Server, the single sign-on server, OC4J, and Oracle Internet Directory:

ORACLE_HOME/opmn/bin/opmnctl stopall
ORACLE_HOME/opmn/bin/opmnctl startall

This command assumes that infrastructure components are all in the same Oracle home.

2.5.2.5 Stopping and Starting the Database

If the database needs to be shut down, use the following steps to stop and start affected components including the database:

  1. Stop the Oracle HTTP Server, the single sign-on server, OC4J, and Oracle Internet Directory:

    ORACLE_HOME/opmn/bin/opmnctl stopall
    
    
  2. Shut down the database.

  3. Start the database.

  4. Start the Oracle HTTP Server, the single sign-on server, OC4J, and Oracle Internet Directory:

    ORACLE_HOME/opmn/bin/opmnctl startall
    

2.6 Troubleshooting an Inaccessible Server

Occasionally OracleAS applications are inaccessible because the single sign-on server is inaccessible. Use these steps to diagnose the problem:

  1. Follow the instructions in "Accessing the Monitoring Pages" in Chapter 10 to access the Application Server page of the Application Server Control console.

  2. Verify that the single sign-on server is indeed down by examining the System Components table on the Application Server page. A down-facing red arrow signifies that the server is down, an up-facing green arrow that the server is up.

  3. Check the table to determine whether the Oracle HTTP Server is down.

  4. If the Oracle HTTP Server is down, restart it using either the command line or the Application Server Control console. See "Stopping and Starting Single Sign-On Components".

  5. If the Oracle HTTP Server fails to start, check the log files for the server to determine the problem. The files are found in ORACLE_HOME/opmn/logs and in ORACLE_HOME/Apache/Apache/logs/error_log.

  6. Check the status and configuration of the database access descriptor (DAD) for the single sign-on server. You do this by examining the DAD table on the mod_plsql Services page of the Application Server Control console. to access this table, select HTTP Server from the System Components table; then click Administration and then PL/SQL Properties. If the DAD arrow points up, continue to step 7. If the DAD arrow points down, click the DAD name and verify that the DAD is properly configured. For help, see the chapter about modules in Oracle HTTP Server Administrator's Guide. The section about mod_plsql explains how to configure a DAD.

  7. Check the status of the OracleAS metadata repository:

    1. Start the Oracle Enterprise Manager Database Control console:

      ORACLE_HOME/bin/emctl start dbconsole
      
      
    2. In your browser, enter the URL for Oracle Enterprise Manager Database Control:

      http://host_name.domain:port/em
      
      

      In the URL, host_name is the name of the computer on which the metadata repository is installed. port is the port number reserved for Database Control during installation. You can find this number by examining the file ORACLE_HOME/install/portlist.ini. Look for this line:

      Enterprise Manager Console HTTP Port(database_name) = port_number
      
      

      The port number is a value in the range 5500–5519.

  8. Log in to the Database Control page with the SYSaccount; then connect as SYSDBA.

  9. On the Database Home page, examine the status indicator in the General section. If the database is up, continue to step 10. If the database is down, click the Startup button—or, when appropriate—the Perform Recovery button.

    If the database starts, restart the Application Server Control console, the Database Control console, the infrastructure middle tier, and middle tiers associated with the metadata repository installation. If you need help, see the chapter about starting and stopping in Oracle Application Server Administrator's Guide.

    If the database fails to start, consult Oracle Database Administrator's Guide.

  10. Determine whether the OC4_SECURITY instance is running by examining the System Components table on the Application Server page of the Application Server Control Console. Or use the command line for this purpose:

    opmnctl status
    
    

    If the OC4J_SECURITY instance is down, restart it by using the Application Server Control console. If OC4J_SECURITY starts successfully, see if the single sign-on server is accessible. If OC4J_SECURITY fails to start, check the OC4J_Security logs for errors. See "Viewing the Log Files" in Appendix A for more about these logs.

  11. Check the status of Oracle Internet Directory, using the same procedures that you used to check the status of the OC4J_SECURITY instance in step 10. Use the Application Server Control console to start the directory if necessary. If the directory fails to start, check directory error logs.

2.7 Setting Browser Preferences for OracleAS Single Sign-On

Logging in and out of OracleAS Single Sign-On successfully requires that the following browser settings be in place:

Cache Settings

To enable the correct cache settings:

  1. Go to the cache settings dialog box by clicking the following in succession:

    • Internet Explorer:

      • Tools

      • Internet Options

      • General

      • Settings

    • Netscape Communicator:

      • Edit

      • Preferences

      • Advanced

      • Cache

  2. Select Every visit to the page in Internet Explorer or Every time in Netscape Communicator.

Image Settings

To ensure that images are automatically loaded:

  1. Click the following in succession:

    • Internet Explorer:

      • Tools

      • Internet Options

      • Advanced

    • Netscape Communicator:

      • Edit

      • Preference

      • Advanced

  2. Select Show pictures in Internet Explorer or Automatically load images in Netscape Communicator.

2.8 Accessing the Administration Pages

You can use the administration pages within the single sign-on UI to set the single sign-on session length and to enable the server to verify IP addresses. You can also use these pages to administer partner applications and external applications.

To access the administration pages:

  1. Enter a URL of the following form:

    http://host:port/pls/orasso
    
    

    where host is the name of computer on which the server is located, port is the port number of the server, and orasso is the database access descriptor for the single sign-on schema. If the server is enabled for SSL, https must be substituted for http. The port number may be omitted if it is 80 or 443 (SSL) because these numbers are the defaults.

    The Access Partner Applications page appears.

  2. Click Login in the upper right corner of the Access Partner Applications page.

    The login page appears.

  3. Enter the administrator's user name and password; then click Login.

  4. The home page appears. To perform administrative functions, click SSO Server Administration.

Figure 2-3 shows the SSO Server Administration page.

Figure 2-3 SSO Server Administration Page

Description of Figure 2-3  follows
Description of "Figure 2-3 SSO Server Administration Page"

2.9 Using the Edit SSO Server Page to Configure the Server

Use the Edit SSO Server page to fix the length of single sign-on sessions and to verify IP addresses. To access the Edit SSO Server page, click Edit SSO Server Configuration on the SSO Server Administration page.

The Edit SSO Server page contains the following heading and fields:

Table 2-1 SSO Session Policy

Field Description

Single sign-on session duration

Enter the number of hours users can be logged in to the server before their session expires. The default is eight hours.

Verify IP addresses for requests made to the single sign-on server

Select to verify that the IP address of the browser is the same as the IP address in the authentication request. This check box is not selected by default.


If you change either of these parameters, restart the OC4J_SECURITY instance:

ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=OC4J_SECURITY

2.10 Configuring Globalization Support

You can enable the single sign-on UI to be rendered in any language that the user's browser is configured for. English and the language of the operating system are installed when OracleAS is installed. To install additional languages, click the Product Languages button on the Select a Product to Install screen. If you forget to install additional languages during the installation of OracleAS, you can still enable the single sign-on UI for additional languages by running the ossoca.jar tool.

To enable the single sign-on server for additional languages after installation:

  1. Copy the desired language files from the CD home for the Repository Configuration Assistant (REPCD_HOME) to the Oracle home for OracleAS Single Sign-On:

    cp REPCD_HOME/portal/admin/plsql/nlsres/ctl/lang/*.* ORACLE_HOME/sso/nlsres/ctl/lang/
    
    

    where lang is the desired language code. For example, this value would be ja for Japanese. Note that you must create the lang directory in the single sign-on home before running ossoca.jar.

  2. Add ORACLE_HOME/lib to the library path environment variable.

  3. Issue the following commands:

    • UNIX:

      $ORACLE_HOME/sso/bin/ssoca -jar $ORACLE_HOME/sso/lib/ossoca.jar langinst
      lang make_lang_avail $ORACLE_HOME
      
      
    • Windows:

      set PATH=%ORACLE_HOME%/bin;%PATH%
      
      %ORACLE_HOME%\jdk\bin\java -Dwindir=SYSTEM_ROOT -jar %ORACLE_
      HOME%\sso\lib\ossoca.jar langinst lang make_lang_avail %ORACLE_HOME
      
      

      SYSTEM_ROOT denotes the system root directory for Windows. Written as an environment variable, the system root is %SystemRoot%. By default, the value for this variable is C:\winnt.

    For the variable lang, substitute the code for the language to be installed. For the variable make_lang_avail, substitute 1 if you want to make the language available.

    In the following UNIX example, the Korean language is installed:

    $ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoca.jar langinst ko 1
    $ORACLE_HOME
    
    

For a complete list of the language codes supported, see Appendix A in Oracle Application Server Globalization Guide.

2.11 Configuring the Global User Inactivity Timeout

Before reading this section, read "Global User Inactivity Timeout" in Chapter 1, "Components and Processes: an Overview."

The global user inactivity timeout is applicable to one domain only. This means that computers enabled for the timeout must reside within the same cookie domain. The applications on these computers use the domain cookie to track user activity. If, for example, you use login.acme.com for the single sign on server, other computers in the system must have the .acme.com domain in their host name. One of these computers might be host1.acme.com. Another might be host2.acme.com. In addition, clocks on all of these computers, including the single sign-on server computer, must be synchronized with 10 seconds of one another.

The global user inactivity timeout is not configured by default. You must enable it by running the ssogito.sql script. The script is found at ORACLE_HOME/sso/admin/plsql/sso. The steps that follow include an example of ssogito.sql.

To configure the global user inactivity timeout:

  1. Log in to SQL*Plus, using the single sign-on schema name and password. The default schema name is orasso. To obtain the password, see Appendix B.

  2. Run ssogito.sql by entering the following command:

    SQL> @ssogito.sql
    
    

    A list of fields appears.

  3. In the Enter value for timeout_cookie_domain field, enter a domain name that is common to all of the applications enabled by the single sign-on server. Be sure to place a period before the domain name.


    Note:

    If this field is left blank, the domain name defaults to the host name of the single sign-on server.

  4. In the Enter value for inactivity period field, enter the length of the desired inactivity period in minutes.

  5. To enable the new settings, press the Return or Enter key. To cancel the transaction, press the Return or Enter key twice.

    Once you have completed a transaction, the script provides you with a summary of the new timeout settings. Here is an example of ssogito.sql:

    SQL> @ssogito
    =============================================
    SSO Server Inactivity Timeout Configuration
    =============================================
    Timeout          : DISABLED
    Cookie name      : OSSO_USER_CTX
    Cookie domain    :
    Inactivity period: 15 minutes
    Encryption key   : 093D678526DAA66D
    Note: timeout cookie domain will be defaulted
    to the SSO Server hostname
    -------------------------------------------
    To disable timeout set inactivity period to 0, (zero)
    Press return key twice if you do not want
    to change timeout configuration.
    
    PL/SQL procedure successfully completed.
    
    Enter value for timeout_cookie_domain: .oracle.com
    Enter value for inactivity_period: 15
    Timeout                  : ENABLED
    New timeout cookie domain: .oracle.com
    New inactivity period    : 15 minutes
    
    PL/SQL procedure successfully completed.
    
    No errors.
    
    
  6. Restart the single sign-on middle tier:

    ORACLE_HOME/opmn/bin/opmnctl stopproc process-type=HTTP_Server
    ORACLE_HOME/opmn/bin/opmnctl startproc process-type=HTTP_Server
    
    ORACLE_HOME/opmn/bin/opmnctl stopproc process-type=OC4J_SECURITY
    ORACLE_HOME/opmn/bin/opmnctl startproc process-type=OC4J_SECURITY
    
    
  7. On the application middle tiers where the inactivity timeout is to be enabled, edit the mod_osso.conf file. Make sure that the OssoIdleTimeout parameter exists and that it is set to on. The file is at ORACLE_HOME/Apache/Apache/conf. Here is an example file with the correct setting:

    LoadModule osso_module libsexec/mod_osso.so
    <IfModule mod_osso.c>
      OssoIpCheck off
      OssoIdleTimeout on
      OssoConfigFile /u01/oracleas10g/Apache/Apache/conf/osso/osso.conf
    #
    #Insert Protected Resources
    #
    .
    .
    .
    </IfModule>
    
    
  8. Restart the Oracle HTTP Server on the application middle tiers.

    ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server
    
    

If Oracle Delegated Administration Services and the single sign-on server are located on the same middle tier, and you want the global user inactivity timeout to apply to the former, perform steps seven and eight on the single sign-on middle tier.

2.12 Obtaining the Sample Files

The ipassample.jar file contains sample code for single sign-on features such as certificate-enabled sign-on and deployment-specific pages. Use this command to extract the file:

ORACLE_HOME/jdk/bin/jar -xvf ORACLE_HOME/sso/lib/ipassample.jar