10/11

# 7 Customizing Oracle Database Mobile Server Security

Managing the provided security within Oracle Database Mobile Server is described in Chapter 9, "Configuring Security in the Oracle Database Mobile Server" in the Oracle Database Mobile Server Administration and Deployment Guide. This chapter describes how to customize authentication to provide your own mechanisms to be used within Oracle Database Mobile Server.

The following section details security issues for Oracle Database Mobile Server:

- Section 7.1, "Providing Your Own Authentication Mechanism for Authenticating Users for the Mobile Server"

## 7.1 Providing Your Own Authentication Mechanism for Authenticating Users for the Mobile Server

You can provide an external authenticator for the mobile server to authenticate users with passwords as well as their access privileges to applications. For example, in an enterprise environment, you may have your user data, such as employee information, stored in a LDAP-based directory service. The mobile server can retrieve the user information from the LDAP directory—or from any custom User Management System—if configured with your own implementation of an external authenticator. The mobile server links the external user information to the mobile server repository.

The following sections describe how to implement and use an external authentication method for Oracle Database Mobile Server:

- Section 7.1.1, "Implementing Your External Authenticator"

- Section 7.1.2, "Registering External Authenticator"

- Section 7.1.3, "User Initialization Scripts"

### 7.1.1 Implementing Your External Authenticator

In order to use an external authenticator, you must implement the `oracle.lite.provider.Authenticator` Java interface and configure the implementation in the `mobile.ora` file.

Note:

Samples `SampleAuthenticator.java` and `OIDAuthenticator.java` demonstrate how to implement an external authenticator. These samples can be found in the `<ORACLE_HOME>``\Mobile\Server\demos\devmgr\java\` directory.

Implement the following methods in your external authenticator. The mobile server invokes each of these methods as appropriately.

- Section 7.1.1.1, "Initialization for the External Authenticator"

- Section 7.1.1.2, "Destruction of the External Authenticator"

- Section 7.1.1.3, "The Authentication Method for the External Authenticator"

- Section 7.1.1.4, "The User Instantiation Method for the External Authenticator"

- Section 7.1.1.5, "Retrieve the User Name or the User Global Unique ID"

- Section 7.1.1.6, "Log Off User"

- Section 7.1.1.7, "Change User Password"

#### 7.1.1.1 Initialization for the External Authenticator

The mobile server invokes the `initialize` method before calling any other method of provider class. This method be called only once when the provider is initialized.

    Method: void initialize (String metaData) throws Exception
    Parameter: String metaData (Reserved for future use)

#### 7.1.1.2 Destruction of the External Authenticator

The mobile server invokes the `destroy` method when the system shutdowns. Provider implementation should implement all the cleanup code in this method.

    Method: void destroy() throws Exception
    Parameter: None

#### 7.1.1.3 The Authentication Method for the External Authenticator

Authenticate a user and return a session handle with the `authenticate` method. The returned session handle is passed to the `logOff` method when the user logs off from the system. Note that the `logOff` method may not be called for each successful `authenticate` method call. Some of the mobile server clients may use the `authenticate` method to verify the user credential and not for logging on to the system.

    Method: Object authenticate (String uid, String pwd) throws SecurityException
    Parameter: User Id (or User Name) and password string
    Return: Session handle or NULL

You can pass error and warning information, as follows:

- Failure: Pass along any error information, such as why the authentication failed. Use the `AuthException` class, available in the package `oracle.lite.provider.auth`, to pass along failure information.

- Warning: Pass along any warnings, such as the situation when the user's password is about to expire. Use the `ExtAuthResult` class, available in the package `oracle.lite.provider.auth`, to pass along warning information.

Refer to the Oracle Database Mobile Server API Specification for more details on these exception classes.

#### 7.1.1.4 The User Instantiation Method for the External Authenticator

If the user has not been instantiated in the mobile server repository, then the mobile server invokes the `getInitializationScripts` method—after authenticating the user—to retrieve the initialization scripts for the user. The mobile server uses the initialization scripts to instantiate the user in the mobile server and assign access rights to applications and data. See Section 7.1.3, "User Initialization Scripts" for more information.

    Method: StringBuffer getInitializationScripts (Object sid)
    Parameter: Session handle returned by 'authenticate' method
    Return: 'StringBuffer' containing User's initialization scripts

#### 7.1.1.5 Retrieve the User Name or the User Global Unique ID

Return the user name or GUID (Globally Unique Id) of the user if there is one. Usually, LDAP-based User Management systems maintain a GUID for each user. In case your authentication mechanism does not support GUID, then the `getUserGUID` method returns `NULL`.

    Method: String getFullName (Object sid)
    Parameter: Session handle returned by 'authenticate' method
    Return: User's full name

    Method: String getUserGUID (Object sid)
    Parameter: Session handle returned by 'authenticate' method
    Return: User's GUID or NULL

#### 7.1.1.6 Log Off User

Log off the User from the back-end system. Note that the `logOff` method may not be called for each successful `authenticate` method call. Some of the mobile server clients may use the `authenticate` method to verify the user credential and not for logging on to the system.

    Method: void logOff (Object sid) throws SecurityException
    Parameter: Session handle returned by 'authenticate' method

#### 7.1.1.7 Change User Password

    Method: void changePassword (Object sid, String pwd) throws SecurityException
    Parameter: Session handle returned by the authenticate method and new password string

### 7.1.2 Registering External Authenticator

The `EXTERNAL_AUTHENTICATION` section in the `mobile.ora` file facilitates the authentication of existing external users with the specified external authenticator class. To register your external authenticator class, modify the `mobile.ora` file and set your external `Authenticator` JAVA class name in the `EXTERNAL_AUTHENTICATION` section, as follows:

    [EXTERNAL_AUTHENTICATION]
    CLASS  = SampleAuthenticator
    EXPIRATION = 1800

The mobile server caches the user instantiated through the external authenticator for a period of time in order to improve efficiency. The default expiration time for the cached user object is 30 minutes (or 1800 seconds). Customize this value by setting a new value for the `EXPIRATION` parameter.

In addition, you must configure the `EXTERNALUSER` parameter in the `WSH.INI` script, which notifies the server that the user being created is external and does not require a password in the `WSH.INI` script. Instead, the new user be authenticated by the external authenticator specified in the `mobile.ora` file. For more information on `EXTERNALUSER` parameter, see Appendix B, "Write Scripts for the Mobile Server with the WSH Tool" in the Oracle Database Mobile Server Administration and Deployment Guide.

Alternatively, you can create the external user with the `ResourceManager` APIs, which notifies the server that the user being created does not require a password. Instead, the new user be authenticated by the external authenticator specified in the `mobile.ora` file.

### 7.1.3 User Initialization Scripts

The mobile server invokes the `getInitializationScripts` method to retrieve the user initialization script that instantiates user-specific objects in the mobile server repository. The external authenticator can perform the following actions during the initialization process:

1. Assign access rights to applications

2. Set data subscription parameters.

3. Optionally, add the user to a user group.

The syntax of the initialization script is based on the `INI` format. The first section in the script is as follows.

    [MAIN]
    VERSION=2

The following example performs these actions for a user whose id is `USER1`.

1. Assigning access rights to applications.

   Assign access rights to `Application1` and `Application2` for `USER1`, where `Application1` has two publication items and three subscription parameters.

       # List the applications we want access to
       #
       [ACL]
       Application1
       Application2
       # List Access details for 'Application1'
       #
       [ACL.Application1]
       NAME=USER1
       TYPE=USER
       DATA=LOCATION, ITEMS
       # List Access details for 'Application2'
       #
       [ACL.Application2]
       NAME=USER1
       TYPE=USER

2. Setting data subscription parameters.

       [SUBSCRIPTION.USER1.Application1.LOCATION]
       NAME=ZIP, USR_ID
       VALUE=12345, USER1
       [SUBSCRIPTION.USER1.Application1.ITEMS]
       NAME=WEIGHT
       VALUE=20

3. Adding a User to a User Group

       [GROUP]
       User's Group
       [GROUP.User's Group]
       USER=USER1