Design and Coding Considerations

Search Order

In addition to Native Directory, multiple user directories can be configured in Oracle Hyperion Shared Services. A default search order position is assigned to all configured user directories. You can modify the search order from Oracle Hyperion Shared Services Console. Excepting Native Directory, you can remove configured user directories from the search order. Oracle Enterprise Performance Management System does not use the user directories that are not included in the search order. See the Oracle Enterprise Performance Management System User Security Administration Guide.

The search order determines the order in which EPM System cycles through the user directories to authenticate users. If the user is authenticated in a user directory, EPM System stops the search and returns the user. EPM System denies authentication and returns an error if the user cannot be authenticated against user directories in the search order.

Impact of Custom Authentication on Search Order

Custom authentication affects how EPM System security interprets the search order.

If the custom authentication module returns a user name, EPM System locates the user only in a user directory that is enabled for custom authentication. At this stage, EPM System ignores user directories that are not configured for custom authentication.

Understanding the Custom Authentication Flow

The following use case scenarios are used to explore custom authentication flow:

Use-Case Scenario 1

The following table details the EPM System user directory configuration and search order used in this scenario. This scenario assumes that the custom authentication module uses an RSA infrastructure to authenticate users.

Table 5-1 Setup for Scenario 1

User Directory Type and Name Search Order Custom Authentication Sample User Names Password^Foot 1

User Directory Type and Name	Search Order	Custom Authentication	Sample User Names	Password^Foot 1
Native Directory	1	Disabled	`test_user_1` `test_user_2` `test_user_3`	`password`
LDAP-Enabled SunONE_West	2	Disabled	`test_ldap1` `test_ldap_2` `test_user_3` `test_ldap_4`	`ldappassword`
LDAP-Enabled SunONE_East	3	Enabled	`test_ldap1` `test_ldap_2` `test_user_3`	`ldappassword` on SunONE and `RSA PIN` in custom module

Native Directory

1

Disabled

test_user_1

test_user_2

test_user_3

password

LDAP-Enabled

SunONE_West

2

Disabled

test_ldap1

test_ldap_2

test_user_3

test_ldap_4

ldappassword

LDAP-Enabled

SunONE_East

3

Enabled

test_ldap1

test_ldap_2

test_user_3

ldappassword on SunONE and

RSA
                                    PIN

in custom module

^Footnote 1 For simplicity, it is assumed that all users use the same user directory password.

To initiate the authentication process, a user enters a user name and password in the logon screen of an EPM System product. In this scenario, the custom authentication module performs the following actions:

Accepts a user name and RSA PIN as the user credentials
Returns a user name in username@providername format; for example, test_ldap_2@SunONE_East, to EPM System security

Table 5-2 User interaction and results

User Name and Password	Authentication Result	Login User Directory
`test_user_1/password`	Success	Native Directory
`test_user_3/password`	Success	Native Directory
`test_user_3/ldappassword`	Success	SunONE_West (search order 2)^Foot 2
`test_user_3/RSA PIN`	Success	SunONE_East (search order 3)^Foot 3
`test_ldap_2/ldappassword`	Success	SunONE_West (search order 2)
`test_ldap_4/RSA PIN`	Failure EPM System displays an authentication error.^Foot 4

^Footnote 2

The custom authentication cannot authenticate this user because the user entered EPM System credentials. EPM System can identify this user only in a user directory that is not enabled for custom authentication. The user is not in Native Directory (search order number 1) but is identified in SunONE West (search order number 2).

^Footnote 3

EPM System does not find this user in Native Directory (search order number 1) or SunONE West (search order number 2). The custom authentication module validates the user against RSA Server and returns test_user_3@SunONE_EAST to EPM System. EPM System locates the user in SunONE East (search order number 3), which is a custom authentication–enabled user directory.

^Footnote 4

Oracle recommends that all users authenticated by the custom module be present in a custom authentication–enabled user directory included in the search order. Login fails if the user name that is returned by the custom authentication module is not present in a custom authentication–enabled user directory included in the search order.

Use-Case Scenario 2

The following table details the EPM System user directory configuration and search order used in this scenario. This scenario assumes that the custom authentication module uses an RSA infrastructure to authenticate users.

In this scenario, the custom authentication module performs the following actions:

Accepts a user name and RSA PIN as the user credentials
Returns a user name, for example, test_ldap_2, to EPM System security

Table 5-3 A sample search order

User Directory Search Order Custom Authentication Sample User Names Password^Foot 5

User Directory	Search Order	Custom Authentication	Sample User Names	Password^Foot 5
Native Directory	1	Disabled	`test_user_1` `test_user_2` `test_user_3`	`password`
LDAP-Enabled, for example, SunONE	2	Enabled	`test_ldap1` `test_ldap2` `test_user_3`	`ldappassword` on SunONE and `RSA PIN` in custom module

Native Directory

1

Disabled

test_user_1

test_user_2

test_user_3

password

LDAP-Enabled, for example, SunONE

2

Enabled

test_ldap1

test_ldap2

test_user_3

ldappassword on SunONE and

RSA
                                    PIN

in custom module

^Footnote 5 For simplicity, it is assumed that all users use the same user directory password.

To initiate the authentication process, a user enters a user name and password on the login screen of an EPM System product.

Table 5-4 User interaction and results

User Name and Password	Login Result	Login User Directory
`test_user_1/password`	Success	Native Directory
`test_user_3/password`	Success	Native Directory
`test_user_3/ldappassword`	Failure	SunONE^Foot 6
`test_user_3/RSA PIN`	Success	SunONE^Foot 7

^Footnote 6

Authentication of user against Native Directory fails because of password mismatch. Authentication of user using the custom authentication module fails because the password used is not a valid RSA PIN. EPM System does not try to authenticate this user in SunONE (search order 2), because custom authentication settings override EPM System authentication in this directory.

^Footnote 7

Authentication of user against Native Directory fails because of password mismatch. The custom authentication module authenticates the user and returns the user name test_user_3 to EPM System.

Use-Case Scenario 3

The following table details the EPM System user directory configuration and search order used in this scenario. This scenario assumes that the custom authentication module uses an RSA infrastructure to authenticate users.

For clarity in such scenarios, Oracle recommends that your custom authentication module return the user name in username@providername format; for example, test_ldap_4@SunONE.

Table 5-5 A sample search order

User Directory Search Order Custom Authentication Sample User Names Password^Foot 8

User Directory	Search Order	Custom Authentication	Sample User Names	Password^Foot 8
Native Directory	1	Enabled	`test_user_1` `test_user_2` `test_user_3`	`RSA_PIN`
LDAP-Enabled, for example, MSAD	2	Disabled	`test_ldap1` `test_ldap4` `test_user_3`	`ldappassword`
LDAP-Enabled, for example, SunONE	3	Enabled	`test_ldap1` `test_ldap4` `test_user_3`	`ldappassword` on SunONE and `RSA PIN` in custom module

Native Directory

1

Enabled

test_user_1

test_user_2

test_user_3

RSA_PIN

LDAP-Enabled, for example, MSAD

2

Disabled

test_ldap1

test_ldap4

test_user_3

ldappassword

LDAP-Enabled, for example, SunONE

3

Enabled

test_ldap1

test_ldap4

test_user_3

ldappassword on SunONE and

RSA
                                    PIN

in custom module

^Footnote 8 For simplicity, it is assumed that all users use the same user directory password.

To initiate the authentication process, a user enters a user name and password in the logon screen of an EPM System product.

Table 5-6 User interaction and results

User Name and Password	Authentication Result	Login User Directory
`test_user_1/password`	Success	Native Directory
`test_user_3/RSA_PIN`	Success	Native Directory
`test_user_3/ldappassword`	Success	MSAD (search order 2)
`test_ldap_4/ldappassword`	Success	MSAD (search order 2)
`test_ldap_4/RSA PIN`	Success	SunONE (search order 3)

User Directories and Custom Authentication Module

To use the custom authentication module, user directories that contain EPM System user and group information can be individually configured to delegate authentication to the custom module.

EPM System users who are authenticated using a custom module must be present in one of the user directories included in the search order (see Search Order). Also, the user directory must be configured to delegate authentication to the custom module.

The identity of the user in the custom provider (for example, 1357642 in RSA SecurID infrastructure) may be different from the user name in the user directory (for example, jDoe in an Oracle Internet Directory) configured in Shared Services. After authenticating the user, the custom authentication module must return the user name jDoe to EPM System.

Note:

As a best practice, Oracle recommends that the user name in the user directories configured in EPM System be identical to those available on the user directory used by the custom authentication module.

CSSCustomAuthenticationIF Java Interface

The custom authentication module must use the CSSCustomAuthenticationIF Java interface to integrate with EPM System security framework. It must return a user name string if custom authentication is successful or an error message if authentication is unsuccessful. For the authentication process to be completed, the user name returned by the custom authentication module must be present in one of the user directories included in Shared Services search order. EPM System security framework supports the username@providerName format.

Note:

Ensure that the user name that the custom authentication module returns does not contain an * (asterisk), because EPM System security framework interprets it as a wildcard character while searching for users.

See Sample Code 1 for CSSCustomAuthenticationIF interface signature.

Your custom authentication module (can be a class file) must be included in CustomAuth.jar. The package structure is unimportant.

For detailed information about the CSSCustomAuthenticationIF interface, see Security API documentation.

The authenticate method of CSSCustomAuthenticationIF supports custom authentication. The authenticate method accepts credentials (user name and password) that the user entered while trying to access the EPM System as input parameters. This method returns a string (user name) if custom authentication is successful. It throws a java.lang.Exception if authentication is unsuccessful. The user name returned by the method should uniquely identify a user in one of the user directories included in Shared Services search order. EPM System security framework supports the username@providerName format.

Note:

To initialize resources, for example, a JDBC connection pool, use the class constructor. Doing so improves performance by not loading resources for every authentication.