Configuring Oracle Database Proxy Authentication

You can configure a database login to use Oracle Database proxy authentication with an Oracle Database platform in JSE applications and JEE applications using OC4J native or managed data sources with Oracle JDBC driver release 10.1.0.2.0 or later and external connection pools only.

There is no TopLink Workbench support for this feature. To configure TopLink to use Oracle Database proxy authentication, you must use Java (see "Using Java").

For more information, see "Oracle Database Proxy Authentication".

You can use TopLink support for Oracle Database proxy authentication in the following ways:

Server Session Uses Main Connection and Client Session Uses Nonexclusive Proxy Connection
Server Session Uses Main Connection and Client Session Uses Pooled Nonexclusive Proxy Connection
Server Session Uses Main Connection and Each Client Session Uses a Separate Pooled Nonexclusive Proxy Connection
Server Session uses Main Connection and Client Session uses Exclusive Proxy Connection
Server Session (or DatabaseSession) uses Proxy Connection

Server Session Uses Main Connection and Client Session Uses Nonexclusive Proxy Connection

In this configuration, the client Session connects using a nonpooled connection defined by ConnectionPolicy's login.

Outside of a (non-JTA) transaction, the client Session performs reads through the Server session read pool, and therefor through the main connection. Inside a (non-JTA) transaction, the client Session performs both reads and writes through the client Session proxy connection associated with transaction.

Server Session Uses Main Connection and Client Session Uses Pooled Nonexclusive Proxy Connection

In this configuration, the client Session uses pooled connections from the original writing pool.

Server Session Uses Main Connection and Each Client Session Uses a Separate Pooled Nonexclusive Proxy Connection

In this configuration, each client Session uses the same proxy properties. For example, clientSession1 and clientSession2 use "sarah" and clientSession3 and clientSession4 use "sarah2".

Server Session uses Main Connection and Client Session uses Exclusive Proxy Connection

In this configuration, the client Session is an isolated client session (see "Isolated Client Sessions") that uses an exclusive proxy connection.

Both outside and inside of a (non-JTA) transaction, the client Session performs reads and writes through its exclusive proxy connection.

If you are using Oracle Private Virtual Database (VPD) (see "Isolated Client Sessions and Oracle Virtual Private Database (VPD)"), use this configuration to set up VPD support entirely in the database. That is, rather than making the isolated client session execute SQL (see "PostAcquireExclusiveConnection Event Handler" and "PreReleaseExclusiveConnection Event Handler"), the database performs the required set up in an after login trigger using the proxy session_user.

Server Session (or DatabaseSession) uses Proxy Connection

In this configuration, multiple Server session objects (or DatabaseSession objects) share the same main connection (sample user "scott") but each obtains a different proxy connection from it.

Outside of a (non-JTA) transaction, the client Session performs reads through the Server session read pool, and therefore through the main connection. Inside of a (non-JTA) transaction, the client Session performs both reads and writes through its proxy connection associated with transaction.

Using Java

You configure Oracle Database proxy authentication by implementing session event handlers (see "Managing Session Events With the Session Event Manager") to wrap the TopLink DatasourceLogin JNDIConnector with a TopLink proxy connector instance (from oracle.toplink.platform.database.oracle) appropriate for your JDBC driver and to configure proxy authentication properties.

If you are using the Oracle JDBC OCI driver, use the OracleOCIProxyConnector and property constants defined in oracle.jdbc.pool.OracleOCIConnectionPool.

If you are using the Oracle JDBC Thin driver, use the OracleJDBC10_1_0_2ProxyConnector and the property constants defined in oracle.jdbc.OracleConnection.

The properties to set are shown in Tables a through d.

Note:

Property constant names and values are consistent between the two classes except for PROXYTYPE_ constants (such as PROXYTYPE_USER_NAME). In OracleOCIConnectionPool these are of type String and in OracleConnection they are of type int. If you are using the Oracle JDBC Thin driver and OracleJDBC10_1_0_2ProxyConnector, you must always set these properties as a String. For example:

login.setProperty(
    "proxytype", Integer.toString(OracleConnection.PROXYTYPE_USER_NAME)
);

To configure TopLink to use Oracle Database proxy authentication, do the following:

Decide on the proxy type you want to use and create appropriate users and roles.

User Name Authentication:

To authenticate a proxy user sarah by user name only, create the user account on the Oracle Database using the following:
```
alter user sarah grant connect through dbadminuser
    with roles clerk, reports;
```
In this case, you will need to set the proxy properties shown in Table 86-2.

Table 86-2 Proxy Properties for User Name Authentication

Property Name Property Value

"proxytype"

PROXYTYPE_USER_NAME

PROXY_USER_NAME

"sarah"

PROXY_ROLES

String[] {"role1", "role2", ...}
User Name and Password Authentication:

To authenticate a proxy user sarah by user name and password, create the user account on the Oracle Database using the following:
```
alter user sarah grant connect through dbadminuser
    authenticated using password
    with roles clerk, reports;
```
In this case, you will need to set the proxy properties shown in Table 86-3.

Table 86-3 Proxy Properties for User Name and Password Authentication

Property Name Property Value

"proxytype"

PROXYTYPE_USER_NAME

PROXY_USER_NAME

"sarah"

PROXY_PASSWORD

"passwordforsarah"

PROXY_ROLES

String[] {"role1", "role2", ...}

Property Name	Property Value
"proxytype"	PROXYTYPE_USER_NAME
PROXY_USER_NAME	"sarah"
PROXY_ROLES	String[] {"role1", "role2", ...}

Property Name	Property Value
"proxytype"	PROXYTYPE_USER_NAME
PROXY_USER_NAME	"sarah"
PROXY_PASSWORD	"passwordforsarah"
PROXY_ROLES	String[] {"role1", "role2", ...}

Distinguished Name Authentication:

To authenticate a proxy user sarah by globally unique distinguished name, create the user account on the Oracle Database using the following:

create user sarah identified globally as
    'CN=sarah,OU=americas,O=oracle,L=city,ST=ca,C=us';
alter user sarah grant connect through dbadminuser
    authenticated using distinguished name
    with roles clerk, reports;

In this case, you will need to set the proxy properties shown in Table 86-4.

Table 86-4 Proxy Properties for Distinguished Name Authentication

Property Name	Property Value
"proxytype"	PROXYTYPE_DISTINGUISHED_NAME
PROXY_DISTINGUISHED_NAME	"CN=sarah,OU=americas,O=oracle,L=city,ST=ca,C=us"
PROXY_ROLES	String[] {"role1", "role2", ...}

Certificate Authentication:

To authenticate a proxy user sarah by encrypted distinguished name, create the user account on the Oracle Database using the following:
```
alter user sarah grant connect through dbadminuser
    authenticated using certificate
    with roles clerk, reports;
```
In this case, you will need to set the proxy properties shown in Table 86-2.

Table 86-5 Proxy Properties for User Name Authentication

Property Name Property Value

"proxytype"

PROXYTYPE_CERTIFICATE

PROXY_CERTIFICATE

byte[] {<EncryptedCertificate>}

PROXY_ROLES

String[] {"role1", "role2", ...}

Property Name	Property Value
"proxytype"	PROXYTYPE_CERTIFICATE
PROXY_CERTIFICATE	byte[] {<EncryptedCertificate>}
PROXY_ROLES	String[] {"role1", "role2", ...}

Implement a session event handler for the preLoginEvent session event.

This event handler wraps the JNDIConnector with the appropriate TopLink connector.

Login login = event.getSession().getDatasourceLogin();
// Make sure that external connection pooling is used
login.setUsesExternalConnectionPooling(true);
// Wrap JNDIConnector with either
// OracleOCIProxyConnector or OracleJDBC10_1_0_2ProxyConnector
login.setConnector(
    new OracleOCIProxyConnector(
        ((JNDIConnector)login.getConnector()).getName()
    )
);

Create additional session event handlers depending on how you intend to use proxy authentication.

Server Session Uses Main Connection and Client Session Uses Non-Exclusive Proxy Connection:

Implement a session event handler for the postAcquireClientSession session event to configure a clone of the server session's login with the properties appropriate for your chosen type of proxy authentication (see Tables a through d).

ClientSession cs = (ClientSession)event.getSession();
cs.getConnectionPolicy().setLogin((Login)serverSession.getLogin().clone());
Login login = cs.getConnectionPolicy().getLogin();
//set proxy properties into connection policy's login
login.setProperty(
    "proxytype" , OracleOCIConnectionPool.PROXYTYPE_USER_NAME
);
login.setProperty(
    OracleOCIConnectionPool.PROXY_USER_NAME ,"sarah"
);

Server Session Uses Main Connection and Client Session Uses Pooled Non-Exclusive Proxy Connection:

Implement a session event handler for the postAcquireClientSession session event to cache the client Session.

// Cache the Client Session
ClientSession cs = (ClientSession)event.getSession();

Implement a session event handler for the postAcquireConnection session event to configure the accessor's login with the properties appropriate for your chosen type of proxy authentication (see Tables a through d).

if(cs == null) {
    return;
}
DatasourceAccessor dsAccessor = (DatasourceAccessor)event.getResult();
if(dsAccessor==cs.getWriteConnection() {
    Login login = dsAccessor.getLogin();
    //set proxy properties into dsAccessor's login
    login.setProperty(
        "proxytype" , OracleOCIConnectionPool.PROXYTYPE_USER_NAME
    );
    login.setProperty(
        OracleOCIConnectionPool.PROXY_USER_NAME ,"sarah"
    ); 
}

Server Session Uses Main Connection and Each Client Session Uses a Separate Pooled Non-Exclusive Proxy Connection:

String proxy_user_name = "sarah";
 
ClientSession cs = (ClientSession)event.getSession();
ConnectionPolicy policy = cs.getConnectionPolicy();
 
// The Client Session will connect using the pool with the same name as proxy user
policy.setPoolName(proxy_user_name);
 
ServerSession ss = cs.getParent();
 
// if the pool doesn't exist, create and start up it
ConnectionPool pool = ss.getConnectionPool(proxy_user_name);
if(pool == null) {
    // Clone serverSession's login - the clone will be used by the new connection pool
    Login login = (Login)ss.getLogin().clone();
    // set proxy properties in the login
    login.setProperty(
        "proxytype", OracleOCIConnectionPool.PROXYTYPE_USER_NAME
    );
    login.setProperty(
        OracleOCIConnectionPool.PROXY_USER_NAME, proxy_user_name
    );
    // create the new pool    
    pool = new ExternalConnectionPool(proxy_user_name, login, ss);
    ss.getConnectionPools().put(proxy_user_name, pool);
    // start it up
    pool.startUp();
}

Server Session uses Main Connection and Client Session uses Exclusive Proxy Connection:

Implement a session event handler for the postAcquireExclusiveConnection session event to configure the accessor's login with the properties appropriate for your chosen type of proxy authentication (see Tables a through d).

ClientSession cs = (ClientSession)event.getSession();
 
DatasourceAccessor dsAccessor = (DatasourceAccessor)event.getResult();
if(dsAccessor == cs.getWriteConnection() {
    Login login = dsAccessor.getLogin();
    //set proxy properties into dsAccessor's login
    login.setProperty(
        "proxytype", OracleOCIConnectionPool.PROXYTYPE_USER_NAME
    );
    login.setProperty(
        OracleOCIConnectionPool.PROXY_USER_NAME, "sarah"
    ); 
}

Server Session uses Proxy Connection:

Add the following code to the preLoginEvent handler created in step 2 to configure the session's login with the properties appropriate for your chosen type of proxy authentication (see Tables a through d).
```
login.setProperty(
    "proxytype", OracleOCIConnectionPool.PROXYTYPE_USER_NAME
);
login.setProperty(
    OracleOCIConnectionPool.PROXY_USER_NAME, "sarah"
);
```