5.8 Set Up the Spring Boot Application

In this section, you clone the sample application, review its dependencies, and configure the application properties and environment variables.

Topics:

5.8.1 Get the Application Source Code

The sample application is part of the Oracle JDBC Extensions project. Clone the repository and navigate to the sample application directory.

cd $HOME
git clone https://github.com/oracle/ojdbc-extensions.git
cd ojdbc-extensions/ojdbc-provider-spring/samples/employee-records-api

This directory is referred to as APP_DIR throughout the rest of this chapter. Here are the key files within it:

Path Description

APP_DIR/pom.xml

Maven build file

APP_DIR/.env

Environment variables (copy from .env.example)

APP_DIR/src/main/resources/application.properties

Spring Boot configuration

5.8.2 Install the JDBC Driver

The core Oracle JDBC driver is required for database connectivity. For this sample application, the driver dependency is already included in pom.xml.

If you are using a different application, add the following dependency to your pom.xml file: 

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

5.8.3 Install the Provider

The Oracle JDBC Spring provider automates end-user security context payload propagation through the JDBC Service Provider Interface (SPI). For this sample application, the provider dependencies are already included in pom.xml.

If you are using a different application, add the following dependencies. These artifacts are part of the Oracle JDBC Extensions project:
<!-- Propagate end-user security context to Oracle Database -->
<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc-provider-spring</artifactId>
    <version>${ojdbc.provider.version}</version>
</dependency>

The ojdbc-provider-spring library handles the end-user security context payload propagation automatically. Oracle JDBC discovers the library on the class path and invokes it on every connection; no additional code is required in your application.

5.8.4 Review Additional Dependencies

The following additional dependencies are also required and are already included in the sample application’s pom.xml.

If you are using a different application, add each of these manually:
<!-- Azure token provider for JDBC (authenticates the connection pool to Oracle via Entra ID) -->
<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc-provider-azure</artifactId>
    <version>1.0.6</version>
</dependency>

<!-- Oracle Wallet/SSL support (reads cwallet.sso for TCPS certificate validation) -->
<dependency>
    <groupId>com.oracle.database.security</groupId>
    <artifactId>oraclepki</artifactId>
    <version>${oracle.security.version}</version>
</dependency>

<!-- OAuth 2.0 Resource Server (validates incoming user JWTs in the Authorization header) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

<!-- JPA (Hibernate) with HikariCP -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<!-- AOP (for @RunWithDataRoles privilege elevation) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

<!-- Actuator for health/info endpoints -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

5.8.5 Configure the Application

Now that the dependencies are in place, configure the application to connect to your Oracle AI Database and Entra ID tenant.

The application uses two configuration files that work together:
  • application.properties: The primary Spring Boot configuration file. It defines application-level settings (such as connection pools, security providers, and OAuth 2.0 settings) using ${VARIABLE} placeholders to keep sensitive and environment-specific data out of the source code.
  • .env: A key-value file that stores the actual environment variables (such as client credentials and database URLs). When sourced at runtime, Spring Boot uses these values to dynamically resolve the placeholders in application.properties.

Note:

Spring Boot does not read .env files automatically. Use the set -a && source .env && set +a command to export the variables into the current shell session.

Review application.properties

The sample application includes a pre-configured application.properties file with all required settings. If you are configuring a different application or if the file is missing after cloning, create it using the following commands:
mkdir -p APP_DIR/src/main/resources
vi APP_DIR/src/main/resources/application.properties

Verify that the file contains the following configuration sections, and add any that are missing.

JWT validation

Configures the application to validate incoming end-user tokens.
spring.security.oauth2.resourceserver.jwt.issuer-uri=${JWT_ISSUER_URI}

Database connection

Configures the connection pool for TCPS with token authentication using your environment variables.
spring.datasource.url=${ORACLE_JDBC_URL}
spring.datasource.driver-class-name=oracle.jdbc.OracleDriver
spring.datasource.hikari.data-source-properties.oracle.jdbc.clientId=${HRAPP_CLIENT_ID}
spring.datasource.hikari.data-source-properties.oracle.jdbc.clientSecret=${HRAPP_CLIENT_SECRET}
spring.datasource.hikari.data-source-properties.javax.net.ssl.trustStore=${ORACLE_WALLET_TRUSTSTORE}
spring.datasource.hikari.data-source-properties.javax.net.ssl.trustStoreType=SSO

OAuth 2.0 client registration

Defines the OAuth 2.0 client used to acquire tokens for the database connection.
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}
spring.security.oauth2.client.registration.hrapp.scope=${HRAPP_SCOPE}
spring.security.oauth2.client.registration.hrapp.authorization-grant-type=client_credentials
spring.security.oauth2.client.provider.hrapp.token-uri=${HRAPP_TOKEN_URI}
spring.security.oauth2.client.provider.hrapp.authorization-uri=${HRAPP_AUTH_URI}

End-user security context propagation

Enables the Oracle JDBC Spring Boot Provider to propagate the user's JWT to the database. These properties are mandatory for Oracle Deep Data Security (Deep Sec) to function.
# End-user security context provider — propagates the user's JWT to Oracle
spring.datasource.hikari.data-source-properties.oracle.jdbc.provider.endUserSecurityContext=ojdbc-provider-spring-end-user-security-context
spring.datasource.hikari.data-source-properties.oracle.jdbc.provider.endUserSecurityContext.registrationId=hrapp

Note:

The registrationId value (hrapp) must exactly match the client name used in the OAuth 2.0 client registration section above.

Configure environment variables

You manage the application’s environment variables using a .env file located in the application directory.

Navigate to the directory, copy the example template provided with the sample application, and open the new .env file for editing. 

cd APP_DIR
cp .env.example .env
vi .env

Update the variables in the .env file using the values from your Entra ID application registrations. See Create Application Registrations in Microsoft Entra ID. Use the following table as a reference.

Variable Description Example / Format

JWT_ISSUER_URI

Entra ID token issuer URI for JWT validation.

The value must be exactly the same as the iss claim from the Microsoft Entra ID access token.

https://sts.windows.net/[TENANT_ID]/

ORACLE_JDBC_URL

Oracle TCPS connection string.

See format after the table.

ORACLE_WALLET_TRUSTSTORE

Path to the server wallet for TLS.

/u01/app/oracle/wallets/server/cwallet.sso

HRAPP_CLIENT_ID

Application (Client) ID of EmployeeRecordsAPI.

[EMP_RECORDS_APP_ID]

b821ac28-11aa-2222-c3c3-5b3e31c8cb8e

HRAPP_CLIENT_SECRET

Client secret generated for EmployeeRecordsAPI.

[CLIENT_SECRET]

Jkk8Q~F4t0Hof6~2SecRETe14SHRYtQ.i7wwwcC0

HRAPP_SCOPE

Scope that the application requests through the client credentials flow.

[DB_APP_ID_URI]/.default

https://supremo.onmicrosoft.com/fe58febf-0724-4d8f-9b14-598a0d2f4662/.default

HRAPP_TOKEN_URI

Entra ID token endpoint.

https://login.microsoftonline.com/[TENANT_ID]/oauth2/v2.0/token

HRAPP_AUTH_URI

Entra ID authorization endpoint.

https://login.microsoftonline.com/[TENANT_ID]/oauth2/v2.0/authorize

HRAPP_DELEGATED_SCOPE

Delegated scope for Auth Code + PKCE (user login).

api://[EMP_RECORDS_APP_ID]/access_as_user

ORACLE_JDBC_URL Format

Construct your JDBC URL using the following format. Ensure that you replace the placeholder values ([your-vm-fqdn], [DB_APP_ID_URI], [TENANT_ID], and [your-pdb-service]) with your specific environment details.
jdbc:oracle:thin:@(DESCRIPTION=
    (ADDRESS=(PROTOCOL=tcps)(HOST=[your-vm-fqdn])(PORT=2484))
    (SECURITY=
        (TLS_SERVER_CERT_DN="CN=[your-vm-fqdn],O=Oracle,C=US")
        (TOKEN_AUTH=AZURE_SERVICE_PRINCIPAL)
        (AZURE_DB_APP_ID_URI=[DB_APP_ID_URI])
        (TENANT_ID=[TENANT_ID]))
    (CONNECT_DATA=(SERVICE_NAME=[your-pdb-service])))