Configure Java Applications

The Oracle JDBC driver supports two approaches for propagating the end-user security context payload from your Java application to the database: API extension methods and a configuration-driven Service Provider Interface (SPI). API calls take precedence over provider-based configurations.

Topics:

Use the API Extension Methods

If you want to supply the end-user security context payload directly in your application code, use the API extension methods.

This approach involves interacting directly with the oracle.jdbc.OracleConnection interface within your Java code to manually set and clear the security context payload.

Build the security context payload.

Use the createWithToken or createWithName method of oracle.jdbc.EndUserSecurityContext to create the security context object, with the end-user or application identity and optional data roles. For example, you can create a security context payload named mySecurityContext.

The following example illustrates a two-token end-user security context payload attachment with the createWithToken method:

System.out.println("Attaching End-User Security Context");

String userToken = getUserToken();
String dbAccessToken = getDbAccessToken();

OracleJsonObject attrs = new OracleJsonFactory().createObject();
attrs.put("service_center_id", 52);
attrs.put("region_id", "EMEA");

try (Connection connection = DriverManager.getConnection(sslURL, props)) {
    EndUserSecurityContext mySecurityContext =
        EndUserSecurityContext.createWithToken(dbAccessToken, userToken)
            .withDataRoles(Set.of("hcm_role"))
            .withAttributes(Map.of("HR.HCM", attrs));

    connection.unwrap(OracleConnection.class)
        .setEndUserSecurityContext(mySecurityContext);

    try {
        query(connection);
    }
    finally {
        connection.unwrap(OracleConnection.class)
            .clearEndUserSecurityContext();
    }
}

To build a payload containing only a database-access token, use createWithToken with that token as its only argument. This requires Oracle JDBC 23.26.0.0.4 (October RU) or later. In the following example, getDatabaseAccessToken() returns the database-access token as a char[]. Clear the array in a finally block after constructing the payload. Use the resulting mySecurityContext object in steps 2 through 4.

char[] databaseAccessToken = getDatabaseAccessToken();
EndUserSecurityContext mySecurityContext;
try {
    mySecurityContext = EndUserSecurityContext.createWithToken(
        java.nio.CharBuffer.wrap(databaseAccessToken));
} finally {
    java.util.Arrays.fill(databaseAccessToken, (char) 0);
}

The following example illustrates a security context payload attachment with the createWithName method (for cases where the application manages end users in its own user store). Data roles, end-user context attributes, and the lookup key are optional:

String userName = "Emma";
String lookupKey = "key1";

EndUserSecurityContext mySecurityContext =
    EndUserSecurityContext.createWithName(DB_ACCESS_TOKEN, userName, lookupKey)
        .withDataRoles(Set.of("hcm_role"))
        .withAttributes(ctxAttrs);

Set the security context payload.

Before executing SQL statements, attach the security context payload to the database connection. If your connection object is a java.sql.Connection (as is typical when obtained from a DataSource or connection pool), you must first cast or unwrap it to OracleConnection and then attach the payload.
```
OracleConnection oracleConnection =
    connection instanceof OracleConnection
        ? (OracleConnection) connection
        : connection.unwrap(OracleConnection.class);

oracleConnection.setEndUserSecurityContext(mySecurityContext);
```
Perform database operations.

Clear the security context payload.

Always clear the security context payload before returning the connection to a pool to prevent data leakage. Use a finally block to ensure the security context payload is cleared even if an exception occurs during database operations.

OracleConnection oracleConnection =
    connection instanceof OracleConnection
        ? (OracleConnection) connection
        : connection.unwrap(OracleConnection.class);

oracleConnection.setEndUserSecurityContext(mySecurityContext);
try {
    executeSqlAsEndUser(connection);
}
finally {
    oracleConnection.clearEndUserSecurityContext();
}

Use the Service Provider Interface

The Service Provider Interface (SPI) approach enables your Java application to supply the end-user security context payload without requiring modifications to your core application code.

Oracle JDBC defines a Java interface named oracle.jdbc.spi.EndUserSecurityContextProvider. This interface is designed to work as a standard service provider interface that is dynamically loaded by Java’s java.util.ServiceLoader class. This design allows you to implement the interface by integrating with different Java security technologies to provide a security context payload to Oracle JDBC.

By simply installing and configuring a provider implementation, you can enable your application to automatically propagate the security context payload to the database before each SQL operation. The SPI approach also allows you to integrate with different IAM-specific providers without changing how your application interacts with the JDBC driver.

To supply the security context payload using the SPI approach, perform the following tasks.

Install the driver.

Ensure the core Oracle JDBC driver is included in your project dependencies by adding the following block to your pom.xml file.

<!-- Oracle JDBC driver -->
     <dependency>
         <groupId>com.oracle.database.jdbc</groupId>
         <artifactId>ojdbc11</artifactId>
         <version>23.26.4.0.0</version>
     </dependency>

Install a provider implementation.

Add an implementation of oracle.jdbc.spi.EndUserSecurityContextProvider to your application’s class path. You can use a pre-built provider published to a repository such as Maven Central, or implement the interface yourself to integrate with your security framework. For a pre-built provider that integrates with Spring Security, see Use the JDBC Spring Boot Provider (The SPI Approach).
Configure the data source to use the provider.

Configure the application’s data-source connection properties to use the installed provider. The specific properties depend on the provider implementation. See your provider’s documentation for the required configuration.

Use the JDBC Spring Boot Provider (The SPI Approach)

The JDBC Spring Boot provider is an out-of-the-box (OOTB) security context payload provider for the Oracle JDBC driver. It automates the propagation of the end-user security context payload from Spring Security (OAuth 2.0) to the database through the JDBC connection. In most cases, no application code changes are necessary.

Spring Boot runtime components

Spring Boot is built on the Spring Framework and uses declarative configuration to assemble applications from modular components. For Spring Boot applications that access Oracle AI Database and use Oracle Deep Data Security (Deep Sec), the following Spring components are most relevant:

Spring Web: Simplifies REST API development by handling request mapping, input validation, and HTTP-to-Java object conversion.
Spring Security: Handles authentication and authorization. It supports OAuth 2.0 token acquisition and validation, populates the Spring security context with the authenticated end-user identity and token claims, and propagates the security context information using the Spring filter chain.
Spring Data: Manages database persistence and transactions transparently using repository interfaces. Spring Data JPA (Java Persistence API) maps Java entities to database tables, while Spring Boot auto-configures a connection pool with the Oracle JDBC driver to support Spring Data.

This image displays the Spring Boot runtime components.

How the JDBC Spring Boot provider works

In a typical Spring Boot application, Spring Security establishes the Spring security context from OAuth 2.0 tokens issued by the IAM system. Spring’s persistence layer, together with the configured data source and connection pool, manages JDBC connections. Application code usually interacts with the database through repositories, transactions, or persistence APIs rather than holding the JDBC connection directly. Requiring application code to access the JDBC connection to pass the security context information violates Spring Framework’s module-level contracts.

Oracle JDBC addresses this type of cross-layer integration through its Service Provider Interface (SPI). The SPI provides an extension point that allows the JDBC driver to obtain the security context information from an external provider instead of requiring application code to pass that information directly to the database connection. The JDBC Spring Boot provider is the Spring Boot-specific provider that plugs into this SPI. It retrieves the security context information from Spring Security and supplies it to the JDBC driver as an end-user security context payload. For each SQL request from the application, the driver retrieves the security context payload from the provider and attaches it to the SQL payload sent to the database. Deep Sec then uses the propagated end-user security context payload to enforce data authorization in the database.

This image displays how the JDBC Spring Boot provider facilitates the flow of security context information from the Spring Boot application to Oracle AI Database.

Note: A sample Spring Boot application that you can use with the JDBC Spring Boot provider is available in the Oracle JDBC Extensions repository, under ojdbc-extensions/ojdbc-provider-spring/samples. For an end-to-end walkthrough that uses this application, see Configure Oracle Deep Data Security for a Sample Application.

To configure the provider in a Spring Boot application, perform the following tasks.

For Spring Boot applications, both the IAM client-registration settings and the data-source driver configuration are supplied in the application.properties file. You must link the data source to the OAuth registration using the registrationId.

Install the provider.

Add the Oracle JDBC Spring provider dependency to your pom.xml. This artifact is part of the Oracle JDBC Extensions project hosted on GitHub: https://github.com/oracle/ojdbc-extensions.
```
<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc-provider-spring</artifactId>
    <version>${ojdbc.provider.version}</version>
</dependency>
```

Add IAM credentials and endpoints.

In your application.properties file, add the following properties to configure the application with your application’s IAM registration details.

Note: The registration name used below (for example, hrapp) acts as the identifier for the next step.

# Spring OAuth2 Configuration
spring.security.oauth2.client.registration.hrapp.client-name=hrapp
spring.security.oauth2.client.registration.hrapp.client-id=<HRAPP_CLIENT_ID>
spring.security.oauth2.client.registration.hrapp.client-secret=<HRAPP_CLIENT_SECRET>

# Endpoint Configuration
spring.security.oauth2.client.provider.hrapp.token-uri=<HRAPP_TOKEN_URI>
spring.security.oauth2.client.provider.hrapp.authorization-uri=<HRAPP_AUTH_URI>
spring.security.oauth2.client.registration.hrapp.redirect-uri=<REDIRECT_URI>

# Scope Configuration
spring.security.oauth2.client.registration.hrapp.scope=<DB_APP_ID_URI>/.default

# --- SELECT ONE GRANT TYPE BELOW ---

# OPTION A: OBO Flow (User assertion)
spring.security.oauth2.client.registration.hrapp.authorization-grant-type=urn:ietf:params:oauth:grant-type:jwt-bearer

# OPTION B: Client Credentials Flow (Service assertion)
# spring.security.oauth2.client.registration.hrapp.authorization-grant-type=client_credentials

Enable the provider.

Next, enable the provider in your connection pool’s data-source configuration. The connection pool setup (data source URL, SSL wallet, pool sizing, and so on) is standard and is not covered here. Ensure the registrationId matches the name used in step 2 (hrapp). For the complete connection pool configuration details, see Configure Oracle Deep Data Security for a Sample Application.
```
# Enable the Spring Security Context provider
spring.datasource.hikari.data-source-properties.oracle.jdbc.provider.endUserSecurityContext=ojdbc-provider-spring-end-user-security-context

# Link to the OAuth2 Registration ID configured in Step 2
spring.datasource.hikari.data-source-properties.oracle.jdbc.provider.endUserSecurityContext.registrationId=hrapp
```

Set additional data roles and context attributes.

Optionally, you can set additional data roles and end-user context attributes in the Spring security context. The provider attaches these to the end-user security context payload and propagates them with every database operation.

# (Optional) Configure default Data Roles or Attributes to pass with every connection
spring.datasource.hikari.data-source-properties.oracle.jdbc.provider.endUserSecurityContext.dataRoles=COMPENSATION_ANALYST
spring.datasource.hikari.data-source-properties.oracle.jdbc.provider.endUserSecurityContext.endUserContextAttribute={"HR_APP_NAMESPACE":{"APP":"HR"}}

Handle privilege elevation (Java code).

For scenarios requiring temporary elevated permissions (for example, generating a compensation summary), use the sample @RunWithDataRoles annotation in your Java code. This adds specific data roles to the end-user security context payload for the duration of a method’s execution. After the method finishes, the user’s original security context is restored.
1. Define a unique prefix for data roles through your application code (default is ORACLE_DATA_ROLE_).
2. Annotate your service method.
```
@RunWithDataRoles(
            dataRoles = {"COMPENSATION_ANALYST"}
    )
    @Transactional(readOnly = true)
    public SalarySummaryDto getSalarySummary()
```

Note: The OOTB JDBC Spring Boot provider may not support custom or non-standard authentication and authorization workflows. If the provider doesn’t meet your requirements, you can build a custom provider. See Advanced: Implement a Security Context Provider.