Skip Headers

Oracle® Containers for J2EE Security Guide 10g Release 3 (10.1.3) B14429-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 6 Oracle Identity Management Security Provider

In Oracle Application Server, Oracle Identity Management with Oracle Internet Directory and (optionally) OracleAS Single Sign-On is the LDAP-based security provider.

This chapter is for those who use or plan to use Oracle Identity Management as the security provider, and covers the integration of Oracle Identity Management with OC4J. It begins with some overview of LDAP realm management, then discusses configuration and use of these features, covering the following topics:

- Realm Management in LDAP-Based Environments

- Overview of Oracle Identity Management Key Components

- Prerequisites: Oracle Application Server Infrastructure

- Steps to Use the Oracle Identity Management Security Provider

- LDAP-Based Provider Settings in OC4J Configuration Files

Notes: Beginning with the OC4J 10.1.3 implementation, the LDAP-based provider is supported in standalone OC4J as well as in an Oracle Application Server environment. B e aware that with the LDAP-based provider, role comparisons for authorization are not case-sensitive. Managing users and roles in Oracle Internet Directory is beyond the scope of this document. Consult the Oracle Identity Management Guide to Delegated Administration. After you add or modify a user account in Oracle Internet Directory, you should be able to log in without restarting OC4J, assuming you have associated Oracle Internet Directory with OC4J as described in "Associate Oracle Internet Directory with OC4J". OC4J provides a login module, `LDAPLoginModule`, for use with non-Oracle LDAP servers. Do not configure this login module for use with Oracle Internet Directory. Doing so would result in the loss of optimizations and integrations that are otherwise available. The only login module for use with Oracle Internet Directory is `RealmLoginModule`.

## Realm Ma nagement in LDAP-Based Environments

A realm is a collection of users and roles. In the OC4J 10.1.3 implementation, manage users and roles in an LDAP-based (Oracle Internet Directory) realm by using administrative features of the Oracle Delegated Administration Services (DAS).

This section discusses the following topics for realm management in Oracle Internet Directory:

- LDAP-Based Realm Types

- LDAP-Based Realm Data Storage

### LDAP-Based Realm Types

The OracleAS JAAS Provider supports the identity management realm for LDAP-based environments. (The external realm and application realm are deprecated.) A realm provides different user and role management capabilities.

A realm type consists of:

- A role manager for role management

- A user manager for user management

The identity management realm:

- Is created through provisioning tools.

- Is used in hosting environments, and is well suited for a hosting environment in which multiple customers or companies subscribe to shared services.

- Supports external, read-only user and role management.

When you use Oracle Internet Directory with OracleAS Single Sign-On, you must use the identity management realm.

Notes: Specifically, regarding external and application realms: in package `oracle.security.jazn.realm`, `APPLICATION_REALM` and `EXTERNAL_REALM` are deprecated in the `RealmType` class; `_extRealm` and `_appRealm` are deprecated in the `InitRealmInfo` class. External realms and application realms will be desupported in future releases. Use the DAS tool for user and role management with Oracle Internet Directory.

Figure 6-1 shows a sample LDAP DIT containing an identity management realm that is registered as an instance with the OracleAS JAAS Provider. The realm type is created below a realms container.

Figure 6-1 Simplified Directory Information Tree for the Identity Management Realm

Description of "Figure 6-1 Simplified Directory Information Tree for the Identity Management Realm"

Table 6-1 describes the user and role management responsibilities of the identity management realm.

Table 6-1 Identity Management Realm Responsibilities

Identity Management Realm Name | Role Management | User Management
--- | --- | ---
`BestCOMRealm` | Retrieves external, read-only roles of a subscriber | Retrieves external, read-only users

### About Distin guished Names

The term distinguished name, or DN, is used frequently in this chapter. This is a standard LDAP concept. A DN comprises a set of one or more relative distinguished names (RDNs) separated by commas. An RDN can be any of the following:

- DC (domain component)

- CN (common name)

- OU (organizational unit name)

- O (organization name)

- STREET (street address)

- L (locality name)

- ST (state or province)

- C (country)

- UID (user ID)

RDNs most often consist of common names or domain components in the discussion in this chapter. A common name could be something like "Jeff Smith" or "Oracle", for example.

See Also: The next section, "LDAP-Based Realm Data Storage"

### LDAP-Ba sed Realm Data Storage

The realm framework provides a means for registering realm instances with the OracleAS JAAS Provider and managing their information.

By default, Oracle Internet Directory has one default identity management realm. OracleAS JAAS Provider creates a corresponding realm that it linked to it. For example (a typical scenario), an OracleAS JAAS Provider realm called "`us`" is linked to the default identity management realm in Oracle Internet Directory, which has the distinguished name "`dc=us,dc=oracle,dc=com`". Each time you create a new identity management realm in Oracle Internet Directory, a corresponding OracleAS JAAS Provider realm is created to link to it.

A realms container object is created under the site-wide JAAS context. For each registered realm instance, a corresponding realm entry is created under the realms container that stores the realm attributes. This directory hierarchy is known to the OracleAS JAAS Provider, which enables it to create new realm instances in the desirable directory location and find all the registered realms in runtime.

For example, the distinguished name for a realm called `oracle` can be `"cn=oracle,cn=realms,cn=JAZNContext,cn=site root"`.

During runtime, the OracleAS JAAS Provider finds all the registered realms and their attributes (name, user manager implementation class, role manager implementation class, and their properties) from Oracle Internet Directory and instantiates the realm implementation class with the properties for initialization.

#### Realm Hierarchy

As Figure 6-2 illustrates, the OracleAS JAAS Provider stores its entries within the product container `cn=JAZNContext`. Beneath `cn=JAZNContext` is a `cn=Realms` container, which stores realm entries, and a `cn=Policy` container, which stores global OracleAS JAAS Provider policies. The `cn=Policy` container in turn stores two types of entries, `cn=Permissions` and `cn=Grantees`.

Note that the OracleAS JAAS Provider has its own `Groups` and `Users` containers. The `Groups` container contains the role `JAZNAdminGroup`. The `Users` container contains the users that populate this role.

Figure 6-2 Global JAZNContext Subtree

Description of "Figure 6-2 Global JAZNContext Subtree"

Figure 6-3 shows the directory entries that are placed under the example realm `cn=sampleRealm`. The entry `cn=usermgr` stores information related to user management while the entry `cn=rolemgr` stores information related to role management. The policy-related entries under `cn=sampleRealm` store realm-specific policies.

Figure 6-3 Realm-Specific Subtree

Description of "Figure 6-3 Realm-Specific Subtree"

In an identity management-based environment, a subscriber is registered as a realm. Using the subscriber DN, the OracleAS JAAS Provider locates the subscriber-specific Oracle context and creates a `cn=JAZNContext` subtree. In this case, the OracleAS JAAS Provider stores the entries `cn=usermgr` and `cn=rolemgr` and policy-related entries under the subscriber's `JAZNContext`.

In Figure 6-4, `cn=oracle` is a subscriber.

Figure 6-4 Subscriber JAZNContext Subtree

Description of "Figure 6-4 Subscriber JAZNContext Subtree"

#### Access Control Lists and OracleAS JAAS Provider Directory Entries

OracleAS JAAS Provider directory entries are protected by access control lists (ACLs) at the root of the product subtree. These ACLs grant the role `JAZNAdminGroup` and the OracleAS JAAS Provider superuser `JAZNAdminUser` full privileges (read, write) for OracleAS JAAS Provider directory objects. Non-superusers who are not `JAZNAdminGroup` members are denied access to OracleAS JAAS Provider entries.

Because identity management `JAZNContext` subtrees are mirror images of their site-wide parents, the security measures that they use to protect entries are the same.

## Overview of Oracle Identity Management Key Components

Oracle Identity Management provides an enterprise infrastructure for securing distributed enterprise applications. It is an integrated package that includes the LDAP-based Oracle Internet Directory, Oracle Application Server Single Sign-On, and additional security and user management functionality.

To use Oracle Identity Management as your security provider, you must consider the underlying Oracle Internet Directory and OracleAS Single Sign-On. This section provides an overview of these features:

- Overview of Oracle Internet Directory

- Overview of Oracle Application Server Single Sign-On

- SSO-Enabled J2EE Environment: Typical Scenario

See Also: Oracle Identity Management Administrator's Guide

### Overview of Oracle Internet Directory

Oracle Internet Directory provides Windows integration, password policy options, partial replication, and other important security features, including the following.

- Windows integration capabilities: Provides a preconfigured directory synchronization solution for Windows Active Directory Services. This feature allows users to have a single identity and password credential across Oracle and Windows environments. It also includes directory plug-ins that support mastering and changing passwords stored in the Windows environment, relieving customers of overhead and potential security concerns associated with synchronizing passwords across the two environments.

- Flexible password policy: Supports password policy options. In addition, Oracle Internet Directory plug-in support allows customers to implement an almost unlimited variety of site-specific password policies.

- Partial replication: Supports replication models, enabling improved scalability and performance in large network configurations.

- Other features include support for dynamic groups, an expanded Oracle Internet Directory Self-Service Console, easy synchronization of directory data with database tables, and features to permit user identity synchronization with the Oracle e-Business Suite Release 11i.

When using Oracle Internet Directory with the OC4J 10.1.3 implementation, the basic, digest, client-cert, username token, X.509 token, and SAML token authentication methods are supported.

See Also: Oracle Internet Directory Administrator's Guide

### Ove rview of Oracle Application Server Single Sign-On

OracleAS Single Sign-On supports multilevel authentication. This allows customers to establish more than one authentication mechanism, and indicates the way in which a user is authenticated to single sign-on enabled applications. Applications can take advantage of this to grant different degrees of privilege to users, depending on how they authenticated.

For example, users may get partial privileges if they authenticate using a password, but more complete privileges if they use stronger authentication, such as X.509v3.

See Also: Oracle Application Server Single Sign-On Administrator's Guide

### S SO-Enabled J2EE Environment: Typical Scenario

OracleAS Single Sign-On lets a user access multiple applications with a single set of login credentials. Figure 6-5 shows JAAS integration in an application running in an SSO-enabled J2EE environment.

Figure 6-5 OracleAS Single Sign-On and J2EE Environments

Description of "Figure 6-5 OracleAS Single Sign-On and J2EE Environments"

The following steps describe the responsibilities of Oracle components when an HTTP client request is initiated in a J2EE environment with OracleAS Single Sign-On enabled.

1. An HTTP client attempts to access a Web application, WebApp A1, hosted by OC4J (the Web container for executing servlets). Oracle HTTP Server (using an Apache listener) handles the request.

2. Oracle HTTP Server/`mod_osso` receives the request and:

   - Determines that WebApp A1 application requires Web-based OracleAS Single Sign-On for authenticating HTTP clients.

   - Redirects the HTTP client request to the Web-based OracleAS Single Sign-On (because it has not yet been authenticated).

3. The HTTP client is authenticated by OracleAS Single Sign-On through a user name and password or through a user certificate. OracleAS Single Sign-On then:

   - Validates the user's stored login credentials.

   - Sets the OracleAS Single Sign-On cookie (including the user's distinguished name and realm).

   - Redirects back to the WebApp A1 application (in OC4J).

4. The security provider retrieves the OracleAS Single Sign-On user.

Note: For full details on OracleAS Single Sign-On, see the Oracle Application Server Single Sign-On Administrator's Guide.

## Prerequisites: Oracle Application Server Infrastructure

Oracle Identity Management is part of the Oracle Application Server infrastructure. Using Oracle Identity Management as security provider requires the 10.1.2 or 9.0.4 infrastructure to be installed. This is in a separate `ORACLE_HOME` from OC4J.

For information about installing Oracle Application Server infrastructure, refer to the appropriate Oracle Application Server Installation Guide for your platform.

The rest of this section provides additional information, organized as follows:

- Supported Versions for Oracle Internet Directory and OracleAS Single Sign-On

- Considerations for 9.0.4.x Infrastructure: Access Control List Settings

### Sup ported Versions for Oracle Internet Directory and OracleAS Single Sign-On

For using Oracle Identity Management (with Oracle Internet Directory) as the security provider under OracleAS JAAS Provider in the OC4J 10.1.3 implementation, the supported versions of the Oracle Application Server infrastructure are 10.1.2.0.2, 10.1.2.0.1, and 9.0.4.x.

Using OracleAS Single Sign-On as well, however, requires version 10.1.2.0.1 or 9.0.4.3 of the infrastructure. You must upgrade to the appropriate version if you want to use SSO and are currently using 10.1.2.0.0, or 9.0.4.2 or prior.

### Consi derations for 9.0.4.x Infrastructure: Access Control List Settings

Prior to the Oracle Internet Directory 10.1.2 implementation, access control list (ACL) features were not set up properly for `JAZNAdminGroup`. To use the Oracle Internet Directory 9.0.4 implementation with a 10.1.x OracleAS JAAS Provider implementation, place the following contents into a file, replacing `%s_MgmtRealmDN%` with the appropriate ID management realm (for example, `dc=us,dc=oracle,dc=com`), then execute the steps that follow.

    dn: cn=JAZNContext,cn=Products,cn=OracleContext,%s_MgmtRealmDN%
    changetype: modify
    replace: orclaci
    orclaci: access to entry
       by group= "cn=JAZNAdminGroup,cn=Groups,cn=JAZNContext,cn=Products,cn=OracleContext"
    (browse, add, delete)
       by group= "cn=IASAdmins,cn=Groups,cn=OracleContext,%s_MgmtRealmDN%
    added_object_constraint=(objectclass=orclApplicationEntity) (add, delete, browse)
       by * (none)
    orclaci: access to attr=(*)
       by group= "cn=JAZNAdminGroup,cn=Groups,cn=JAZNContext,cn=Products,cn=OracleContext"
    (search, read, write, compare)
       by group= "cn=IASAdmins,cn=Groups,cn=OracleContext,%s_MgmtRealmDN%"
    (read, search, write, compare)
       by * (none)

1. Name the file with the `.ldif` extension, such as `jaznacl.ldif`.

2. Run the `ldapmodify` utility with the newly created file as input, specifying `oidport`, `oidhost`, `adminuser_dn`, `password`, and `filename`, as appropriate:

       % ldapmodify -c -a -p oidport -h oidhost -D adminuser_dn -w password \
                    -f filename.ldif

Note: The `ldapmodify` tool is a standard LDAP utility and is provided with Oracle Internet Directory in `ORACLE_HOME``/bin` in your Oracle Application Server infrastructure installation.

See Also: "Access Control Lists and OracleAS JAAS Provider Directory Entries"

## Steps to Use the Oracle Identity Management Security Provider

This section documents the steps involved in setting up Oracle Identity Management as your security provider, optionally using OracleAS Single Sign-On for authentication:

1. Associate Oracle Internet Directory with OC4J

2. Configure Oracle Identity Management as the Security Provider

3. Configure SSO (Optional)

See Also: For additional information about installing and using Oracle Application Server infrastructure: Oracle Application Server Installation Guide (appropriate version for your platform) Oracle Application Server Administrator's Guide

### Associate Oracle Internet Directory with OC4J

This section discusses the step of associating an Oracle Internet Directory instance with your OC4J instance, which you must do before you can specify Oracle Identity Management as the security provider. It also shows the corresponding XML configuration. The following subtopics are covered:

- Associating Oracle Internet Directory with OC4J

- Changing the Oracle Internet Directory Association

- Required OC4J Accounts Created in Oracle Internet Directory

- Oracle Internet Directory Association in jazn.xml

- Associating the OC4J System Application with Oracle Internet Directory

#### Associating Oracle Internet Directory with OC4J

Use the Application Server Control Console to associate your OC4J instance with an instance of the LDAP-based Oracle Internet Directory, the repository for Oracle Identity Management. Here are the steps:

1. In the OC4J Home page for your instance, choose the Administration tab.

2. In the resulting Administration page, choose the Identity Management task (one of the Security tasks).

3. In the resulting Identity Management page, choose Configure. (This assumes no Oracle Internet Directory instance was previously associated with the OC4J instance, so that the Oracle Internet Directory host name and port are listed as "not configured". If a different Oracle Internet Directory instance was previously associated with this OC4J instance, see the next section, "Changing the Oracle Internet Directory Association".)

4. In the resulting Configure Identity Management: Connection Information page, do the following:

   - Specify the fully qualified host name for the Oracle Internet Directory instance (`myoid.oracle.com`, for example).

   - Specify the distinguished name for the Oracle Internet Directory user, such as `cn=orcladmin` (see note below). The user specified here must belong to the `iASAdmins` role in the Oracle Internet Directory instance.

   - Specify the password for the Oracle Internet Directory user. This will also be set as the default password for the `oc4jadmin` user created in Oracle Internet Directory (unless the `oc4jadmin` account had previously been created, due to associating a different OC4J instance with the Oracle Internet Directory instance).

   - Spec ify whether to use SSL connections or non-SSL connections to the Oracle Internet Directory instance, and the appropriate port to use. The port for SSL is typically 636; for non-SSL it is typically 389. (To change the SSL or port setting later, you would have to redo the OC4J-OID association, as described in the next section, "Changing the Oracle Internet Directory Association".)

   - When you are done, go to the next page.

5. In the Configure Identity Management: Application Server Control page, you can specify whether Application Server Control uses Oracle Identity Management as its security provider. (If you do this, only users and roles defined in the Oracle Internet Directory instance will be able to access Application Server Control.)

   When you are done, go to the next page.

6. In the Configure Identity Management: Deployed Applications page, you can optionally specify Oracle Internet Directory, with or without SSO, as the security provider for each deployed application in the OC4J instance.

   When you are done, choose Configure. This completes the OC4J-OID association process and takes you back to the Identity Management page.

Notes: Because Oracle Internet Directory is associated at OC4J instance level, OracleAS JAAS Provider picks up the Oracle Internet Directory host, port, password, and SSL settings only from the `jazn.xml` file of a given OC4J instance, not from any application-level configuration. Each user in a directory must have a unique distinguished name.

#### Changing the Oracle Internet Directory Association

This section describes the steps to change the OC4J-OID association to use a different Oracle Internet Directory instance, or to change the port or SSL configuration. A new `JAZNAdminUser` account is created in Oracle Internet Directory.

1. As in the previous section, "Associating Oracle Internet Directory with OC4J", navigate to the Identity Management page.

2. In the Identity Management page, choose Change. (This is in the same place as Configure would be if there had been no previous OC4J-OID association.)

3. In the Change Identity Management page, as for the Configure Identity Management page in the previous section, specify the Oracle Internet Directory host name, the distinguished name and password of the Oracle Internet Directory user, whether to use SSL connections, and the port number for connections.

4. Choose OK. This completes the OC4J-OID reassociation process and brings you back to the Identity Management page.

#### Required OC4J Accounts Created in Oracle Internet Directory

The Oracle Internet Directory 10.1.2 implementation does not by default include certain accounts that are required by OC4J and Application Server Control 10.1.3 implementations. Therefore, the accounts listed below are created automatically as default accounts in Oracle Internet Directory, under the default identity management realm, as part of the OC4J-OID association process. This occurs the first time an OC4J instance is associated with the Oracle Internet Directory instance. On any subsequent associations of the same or any other OC4J instance with the same Oracle Internet Directory instance, these accounts are not changed.

- `oc4jadmin` user

- `oc4j-administrators` role

- `oc4j-app-administrators` role

(Also during OC4J-OID association, the `ascontrol_admin`, `ascontrol_appadmin`, and `ascontrol_monitor` roles are created for Application Server Control.)

Note: The file `oidConfigForOc4j.sbs` in directory `ORACLE_HOME``/j2ee/home/jazn/install` contains the OC4J accounts and permissions for default users and roles that are created in Oracle Internet Directory the first time an OC4J instance is associated with that Oracle Internet Directory instance. Do not modify or delete this file, as these accounts are required for normal OC4J operations. Also, do not modify or delete any of these default accounts or their permissions once they are created.

See Also: "Predefined OC4J Accounts" for additional information about the OC4J accounts "Activation of the oc4jadmin Account"

#### Oracle Internet Directory Association in jazn.xml

OC4J-OID association is effective at the level of the OC4J `home` instance. After you have associated OC4J with Oracle Internet Directory, the location, user, password, and LDAP protocol configurations are reflected in the bootstrap `jazn.xml` file. Here is a sample entry:

    <jazn provider="LDAP" location="ldap://myoid.oracle.com:389" default-realm="us" >
       <property
          name="ldap.user"
          value="orclApplicationCommonName=jaznadmin1,cn=JAZNContext,cn=products,
                 cn=OracleContext"/>
       <property name="ldap.password"
                 value="{903}3o4PTHbgMzVlzbVfKITIO5Bgio6KK9kD"/>
       <property name="ldap.protocol" value="no-ssl"/>
    </jazn>

The default realm "`us`" corresponds to the default identity management realm in Oracle Internet Directory. Supported `ldap.protocol` settings are "`ssl`" or "`no-ssl`", according to whether you use SSL connections. The default is to use SSL, so if you specify SSL when you use Application Server Control, this does not actually result in any `ldap.protocol` setting.

Note: In runtime, the LDAP-based provider connects as user `jaznadmin` to Oracle Internet Directory. This user is a member of `JAZNAdminGroup`.

See Also: "Configuring LDAP User and SSL Properties"

#### Associating the OC4J System Application with Oracle Internet Directory

There may be situations where, after associating OC4J with Oracle Internet Directory, you also need to specifically associate the OC4J `system` application with Oracle Internet Directory. This would be the case, for example, if you want to perform operations on your application (such as startup and shutdown) with `admin_client.jar`, which executes through the `system` application, and have `admin_client.jar` be aware of Oracle Internet Directory user accounts. This requires the following manual steps:

1. Copy the `<jazn>` element from the instance-level `jazn.xml` file (discussed in the preceding section, "Oracle Internet Directory Association in jazn.xml") to the `system-application.xml` file, overwriting the existing `<jazn>` element in `system-application.xml`. This results in the `system` application using Oracle Identity Management (instead of the default file-based provider) as its security provider.

2. Map or create an anonymous user in Oracle Internet Directory. You have two choices:

   - Map an anonymous user to an existing Oracle Internet Directory user.

   - Create an anonymous Oracle Internet Directory user.

   These procedures are described immediately below.

See Also: "OC4J System Application"

##### Map an Anonymous User

You can map an anonymous user to an existing Oracle Internet Directory user through a `<property>` element under the `<jazn>` element in the instance-level `jazn.xml` file, for the `anonymous.user` property. For example, assuming there is a user `myoiduser` in Oracle Internet Directory: You can map an anonymous user to an existing Oracle Internet Directory user through a `<property>` element under the `<jazn>` element in the instance-level `jazn.xml` file, for the `anonymous.user` property. For example, assuming there is a user `myoiduser` in Oracle Internet Directory:

    <jazn ... >
       <property name="anonymous.user" value="myoiduser" />
       ...
    </jazn>

##### Cre ate an Anonymous User

You can use the `ldapmodify` utility to create an anonymous user account in Oracle Internet Directory.

First, create an LDIF (lightweight directory interchange format) file to use as input for `ldapmodify`. Here is an example of an appropriate LDIF file:

    dn: cn=anonymous, cn=Users, yourDistinguishedName
    changetype: add
    uid: anonymous
    givenName: anonymous
    cn: anonymous
    sn: anonymous
    description: This entry is used as the identification for unauthenticated users.
    orclisenabled: disabled
    objectClass: top
    objectclass: person
    objectclass: organizationalPerson
    objectClass: inetorgperson
    objectClass: orcluser
    objectClass: orcluserV2

Note that you must replace `yourDistinguishedName` by the distinguished name of the default identity management realm in Oracle Internet Directory.

After you have created the `anony.ldif` file, use `ldapmodify` to add the anonymous user, as follows:

    % ORACLE_HOME/bin/ldapmodify -D cn=orcladmin -w password -h hostname -p port \
                                 -f anony.ldif

When you issue this command, replace `password`, `hostname`, and `port` with the password, host name, and port for your installation.

Notes: The `anonymous` account is a special user account created in the Oracle Internet Directory server for OC4J server usage purpose only. Because this account is created without a password, this account cannot be used by an end user to log in to the applications. The `ldapmodify` tool is a standard LDAP utility and is provided with Oracle Internet Directory in `ORACLE_HOME``/bin` in your Oracle Application Server infrastructure installation.

### Configure Oracle Identity Management as the Security Provider

This section covers the step of specifying Oracle Identity Management as the security provider for your application, using the Application Server Control Console. The following subtopics are covered:

- Specifying Oracle Identity Management during Deployment

- Changing to Oracle Identity Management after Deployment

- Notes: Procedures discussed throughout this section assume you are logged in to Application Server Control as a user with required administrative permissions (as `oc4jadmin`, for example). To enable fat client access to EJBs using RMI, you must grant RMI permission "login" to your user or role. When using the Oracle Identity Management security provider, you can accomplish this through the OracleAS JAAS Provider Admintool. For example:
      % java -jar jazn.jar -grantperm myrealm -role myrole \
           com.evermind.server.rmi.RMIPermission login

#### Specifying Oracle Identity Management during Deployment

Assuming you have satisfied appropriate requirements discussed earlier, in "Steps to Use the Oracle Identity Management Security Provider", you can specify Oracle Identity Management (the LDAP-based provider) when you deploy an application through Application Server Control.

From the Deploy: Deployment Settings page (see "Deploying an Application through Application Server Control" for how to get to this page):

1. Go to the Select Security Provider task.

2. In the resulting Deployment Settings: Select Security Provider page, choose Oracle Identity Management from the Security Provider dropdown list.

3. Under "Configuration of Oracle Identity Management Security Provider" (which appears after you choose Oracle Identity Management from the dropdown), do the following:

   - Confirm the Oracle Internet Directory host and port are correct, as established earlier when you associated the Oracle Internet Directory instance with your OC4J instance.

   - Optionally enable SSO authentication. This results in the configuration `auth-method="SSO"` in `orion-application.xml` for your application, as discussed in "Configuring OC4J for OracleAS Single Sign-On".

4. Choose OK to finish the security provider selection.

5. Back in the Deploy: Deployment Settings page, choose Deploy to complete the deployment, or choose another task, as desired. The list of tasks is noted in "Deploying an Application through Application Server Control".

Notes: Specifying Oracle Identity Management as the security provider for your application results in the setting `provider="LDAP"` in the `<jazn>` element in `orion-application.xml`. During deployment, there is no need to specify the Oracle Internet Directory location, since this was already specified when you associated OC4J with Oracle Internet Directory (and is reflected in the `<jazn>` element in `jazn.xml`). The default realm is the default Oracle Identity Management realm. This is determined when Oracle Internet Directory is installed.

#### Changing to Oracle Identity Management after Deployment

You can select a security provider for your application at deployment time, as described above. You can also change to a different security provider after deployment. Assuming you have completed the prerequisites outlined in "Steps to Use the Oracle Identity Management Security Provider", you can change to Oracle Identity Management as follows:

1. Go to the Security Provider page for your application, as described in "Navigating to the Security Provider Page for Your Application".

2. In the Security Provider page, choose "Change Security Provider".

3. In the Change Security Provider page, select Oracle Identity Management Security Provider from the Security Provider Type dropdown.

4. Under "Security Provider Attributes: Oracle Identity Management Security Provider" (which appears after you select Oracle Identify Management in the dropdown):

   - Confirm the Oracle Internet Directory host and port are correct, as established earlier when you associated the Oracle Internet Directory instance with your OC4J instance.

   - Optionally enable SSO authentication. This results in the configuration `auth-method="SSO"` for your application, as discussed in "Configuring OC4J for OracleAS Single Sign-On".

5. Choose OK to finish the change.

This takes you back to the Security Provider page, where you can examine the settings.

### Configure SSO (Optional)

This step is required only if you want to use OracleAS Single Sign-On functionality with Oracle Identity Management. The following subtopics are covered:

1. Run the SSO Registration Tool

2. Transfer the osso.conf File to the OC4J Instance

3. Run the osso1013 Script

4. Synchronization of OracleAS JAAS Provider User Context with Servlet Sessions

5. Restart the Oracle HTTP Server and OC4J Instances

See Also: Oracle Application Server Administrator's Guide, which also documents these steps

#### Run the SSO Registration Tool

The first task in configuring OracleAS Single Sign-On is to register your application as a partner application with the single sign-on server in your infrastructure. This is a post-installation step. Accomplish this by running the `ssoreg` utility in your infrastructure installation (the SSO server system) to create an (obfuscated) `osso.conf` file.

The `ssoreg` utility is `ORACLE_HOME``/sso/bin/ssoreg.sh` in a Linux installation or `ORACLE_HOME``\sso\bin\ssoreg.bat` in a Windows installation.

Here is the 10.1.2.0.2 syntax for `ssoreg` options required for this usage, with options described in Table 6-2:

    -oracle_home_path path
    -site_name name
    -config_mod_osso TRUE
    -mod_osso_url url
    -remote_midtier
    -config_file path

Table 6-2 Key ssoreg Options

Option | Description
--- | ---
`oracle_home_path` | The absolute path to the `ORACLE_HOME` location in your infrastructure installation.
`site_name` | Name of the Web site, such as `www.example.com`.
`config_mod_osso` | A `TRUE` setting (which is what you want) indicates that `mod_osso`, the Apache mod for OracleAS Single Sign-On, is effectively the application being registered. (Actually, your application is being registered through `mod_osso`.) This results in an obfuscated `osso.conf` file being generated.
`mod_osso_url` | A URL consisting of the host name and port where your application will run:
    http://www.example.com:7777
`remote_midtier` | When present on the command line, specifies that the application being registered is on a remote middle tier. Because your OC4J installation is on a different tier (with a different `ORACLE_HOME`) than your infrastructure, including OracleAS Single Sign-On, you must include this option.
`config_file` | Desired location of the `osso.conf` file, typically something like:
    ORACLE_HOME/Apache/Apache/conf/osso/osso.conf

Here is a Linux example (assume that `$ORACLE_HOME` has been set properly).

    % $ORACLE_HOME/sso/bin/ssoreg.sh -oracle_home_path $ORACLE_HOME \
      -site_name myhost.mydomain.com -config_mod_osso TRUE \
      -mod_osso_url http://myhost.mydomain.com:7777 -remote_midtier \
      -config_file $ORACLE_HOME/Apache/Apache/conf/osso/osso.conf

- Important: To use OracleAS Single Sign-On with Oracle Identity Management as the security provider under OracleAS JAAS Provider in a 10.1.2.0.x infrastructure, you must upgrade to 10.1.2.0.1 or higher. In a 9.0.4.x infrastructure, you must upgrade to 9.0.4.3. (This is also noted in "Supported Versions for Oracle Internet Directory and OracleAS Single Sign-On".) Older versions do not support the `-remote_midtier` option, and ignoring this option may cause unintended changes in Oracle Application Server Distributed Configuration Management (DCM) on the host where you run the command. In a 9.0.4 infrastructure, the utility is `ossoreg.jar`, but the functionality is essentially the same. You must still have a version that supports `-remote_midtier`. In a 9.0.4 infrastructure, you must include a `-u` setting for `ssoreg`, to set the user ID to start the Apache process:
      -u SYSTEM        (for Windows)
      -u root          (for Linux)

See Also: Oracle Application Server Single Sign-On Administrator's Guide for additional information about the `ssoreg` utility, including options not mentioned here

#### Transfer the osso.conf File to the OC4J Instance

Transfer, such as by FTP, the `osso.conf` file produced during SSO registration (at your infrastructure installation, after installation) to a desired location on the OC4J middle tier.

#### Run the osso1013 Script

At your OC4J installation, run a script called `osso1013` to complete the SSO registration process, specifying the location where you placed the `osso.conf` file.

    % osso1013 path/osso.conf

This script is located in the `ORACLE_HOME``/Apache/Apache/bin` directory.

On Windows, you may have to run it through Perl:

    % perl osso1013 path/osso.conf

#### Syn chronization of OracleAS JAAS Provider User Context with Servlet Sessions

For situations where a Web application is used with the Oracle Identity Management security provider and with OracleAS Single Sign-On (acting as the login, timeout, and logout service), the OC4J 10.1.3 implementation supports synchronization between the OracleAS JAAS Provider user context and the servlet session.

With this synchronization, if there is an SSO logout or timeout, after which the user tries to access a protected resource, he or she receives the SSO login prompt again. (This does not occur if the user is only trying to access a public resource.)

This synchronization is disabled by default. You can enable it (or explicitly disable it) through the property `sso.session.synchronize` under the `<jazn-web-app>` element in the `orion-application.xml` file. The following example enables it:

    <orion-application ... >
       ...
       <jazn ... >
          ...
          <jazn-web-app ... >
             <property name="sso.session.synchronize" value="true" />
          </jazn-web-app>
          ...
       </jazn>
       ...
    </orion-application>

Notes: The `orion-web.xml` file, used to configure a single Web application, also supports the `<jazn-web-app>` element, as a subelement of `<orion-web-app>`. In the event of competing settings, the `orion-web.xml` setting takes precedence for the particular Web application. For SSO timeout to work, you must enable the SSO timeout header in OracleAS Single Sign-On. Refer to the Oracle Application Server Single Sign-On Administrator's Guide for details.

#### Restart the Oracle HTTP Server and OC4J Instances

You must restart Oracle HTTP Server and OC4J for the registration to take effect.

## LDAP-Based Provider Settings in OC4J Configuration Files

This section describes how to configure aspects of the LDAP-based Oracle Internet Directory, covering the following topics:

- Configuring LDAP User and SSL Properties

- Configuring LDAP Connection Properties

- Configuring LDAP Caching Properties

Se e Also: Oracle Identity Management Guide to Delegated Administration for information about creating users and roles, through the Oracle Delegated Administration Services (DAS), when using Oracle Identity Management

### Configuring LD AP User and SSL Properties

Table 6-3 summarizes LDAP user and SSL properties, supported through `<property>` subelements under the `<jazn>` element in the bootstrap `jazn.xml` file. These parameters are set as appropriate through your configuration in Application Server Control Console when you associate OC4J with Oracle Internet Directory, described earlier in this chapter.

The resulting configuration is as follows:

    <jazn ... >
       ...
       <property name="propname" value="propvalue" />
       ...
    </jazn>

You must restart OC4J for the changes to take effect.

Table 6-3 LDAP SSL Properties and Related Properties

Property Name | Property Definition
--- | ---
`ldap.user` | LDAP user name or distinguished name. This element is populated automatically; you should not change the contents. For example:
    orclApplicationCommonName=jaznadmin1,cn=JAZNContext,
    cn=products,cn=OracleContext
`ldap.password` | Obfuscated password for the LDAP user name. For example: `{903}oZZYqmGc/iyCaDrD4qs2FHbXf3LAWtMN` See Also: "Password Obfuscation in OC4J Configuration Files" for details on obfuscation.
`ldap.protocol` | Deter mines whether to use SSL. (By default, SSL is used.) Supported settings are "`ssl`" (typically used with port 636) or "`no-ssl`" (typically used with port 389). Note: As an alternative to the "`ssl`" setting, you can use the protocol "`ldaps://`" in the LDAP URL.

Oracle Internet Directory supports NULL authentication for SSL communication. Data are encrypted with the Anonymous Diffie-Hellman cipher suite, but no certificates are used for authentication.

See Also: Table 12-1, "Cipher Suites Supported by OracleSSL" for a list of supported cipher suites

Here is a sample configuration:

    <?xml version = '1.0' encoding = 'UTF-8'?>
    <jazn provider="LDAP" location="ldap://www.example.com:389" default-realm="us">
       <property name="ldap.protocol" value="no-ssl"/>
    </jazn>

See Also: Oracle Internet Directory Administrator's Guide

### Configuring LD AP Con nection Properties

Table 6-4 summarizes LDAP connection properties. Table 6-5 summarizes properties for the LDAP JNDI connection pool. You can set these properties in `<property>` subelements under the `<jazn>` element in the instance-level `jazn.xml` file, as follows:

    <jazn ... >
       ...
       <property name="propname" value="propvalue" />
       ...
    </jazn>

You must restart OC4J for the changes to take effect.

Table 6-4 LDAP Connection Properties

Property Name | Property Definition | Default Value
--- | --- | ---
`ldap.connect.max.retry` | Number of times the security provider attempts to create an LDAP connection before giving up | 5
`ldap.connect.sleep.time` | Number of milliseconds the security provider waits before retrying a failed LDAP connection attempt | 5000

Table 6-5 LDAP JNDI Connection Pool Properties

Property Name | Property Definition | Default Value
--- | --- | ---
`jndi.ctx_pool.init_size` | Initial size for the LDAP JNDI connection pool | 5
`jndi.ctx_pool.inc_size` | Pool increment size for the LDAP JNDI connection pool—number of connections added to pool whenever the supply of connections in the pool is exhausted | 10

Note: The configurations discussed here must be performed manually; there is currently no support for these in Application Server Control.

### Configuring LDAP Caching Properties

Oracle Internet Directory supports caching, providing improved performance and scalability. There are three separate caches:

- Policy cache, which stores grantees and permissions

- Realm cache, which stores realms, users and roles, and a role graph

- Session cache, which stores users and role graphs in an HTTP session object (available only to Web-based clients with cookies enabled)

The caching service maintains a global hashmap `(java.util.HashMap` instance) that is used to store and retrieve cached objects. Expired objects in the hashmap are periodically invalidated and cleaned up automatically, as appropriate. Objects in the cache expire based on a time-to-live algorithm; expiration time can be set through the cache properties described below.

Note: Only Oracle Internet Directory supports these caches. The file-based provider defaults to caching the entire XML document.

Table 6-6 describes LDAP caching properties and their default values. You can set these properties in `<property>` subelements under the `<jazn>` element in the instance-level `jazn.xml` file, as follows:

    <jazn ... >
       ...
       <property name="propname" value="propvalue" />
       ...
    </jazn>

Table 6-6 LDAP Cache Properties

Property | Description | Default
--- | --- | ---
`ldap.cache.policy.enable` | If set to `true`, enables policy cache; if set to `false`, disables cache. | `true`
`ldap.cache.realm.enable` | If set to `true`, enables realm cache; if set to `false`, disables cache. | `true`
`ldap.cache.session.enable` | If set to `true`, enables session cache; if set to `false`, disables cache. | `true`
`ldap.cache.initial.capacity` | Initial capacity for the hashmap. This property affects performance; it is important to not set it too low. | 20
`ldap.cache.load.factor` | Load factor for the hashmap. This is a measure of how full to allow the cache to get before the capacity is automatically increased. This property affects performance; it is important to not set it too high. | 0.7
`ldap.cache.purge.initial.delay` | String containing an integer that represents the number of milliseconds the daemon thread waits before it starts checking for expired objects. | 3600000 (one hour)
`ldap.cache.purge.timeout` | The string representation of an integer that represents the number of milliseconds an object remains in cache before being invalidated and removed. It is also the sleep time for the daemon thread between each run looking for expired objects. | 3600000 (one hour)

Caching is enabled by default. You should disable the caches when performing management and administrative tasks. In particular:

- Disable the policy cache when managing policy. If the policy cache is enabled, calling `Policy.grant()` or `Policy.revoke()` causes an `UnsupportedOperationException.`

- Disable the realm cache when managing realms. This includes adding realms, dropping realms, granting roles, and revoking roles.

- Disable the session cache when you disable HTTP session cookies.

The following example disables all three caches:

    <jazn provider="LDAP" location="ldap://myhost.example.com:636" >
       ...
       <property name="ldap.cache.session.enable" value="false" />
       <property name="ldap.cache.realm.enable" value="false" />
       <property name="ldap.cache.policy.enable" value="false" />
       ...
    </jazn>

Or, as startup parameter settings:

    -Dldap.cache.session.enable=false
    -Dldap.cache.realm.enable=false
    -Dldap.cache.policy.enable=false

The following example leaves all caches enabled, and sets a cache size of 100 and a 10,000-millisecond timeout:

    < jazn provider="LDAP" location="ldap://myhost.example.com:636" >
       < property name="ldap.cache.initial capacity" value="100" />
       < property name="ldap.cache.purget.timeout" value="10000" />
    </jazn>

Notes: The OracleAS JAAS Provider Admintool automatically disables caching while it is in operation, then reenables caching when it finishes. The configurations discussed here must be performed manually; there is currently no support for these in Application Server Control.