Best Practices for Using Database Tools

This section describes procedures and practices that can help you to use Database Tools more easily and efficiently.

Topics:

Using Compartments

Database connections are a useful feature when granting access to database to a specific user or defined groups of users. To help isolate these connections, use policies to grant access to specific connections based on a user's role, as demonstrated in the following example:

For an Autonomous Data Warehouse that is used for reporting, create a shared database connection named ReportingDataAccess. Assign this connection to a specific set of end users in a group called Data Scientists. The users in this group now have access to the details of the database connection, but are limited to using only this connection and the roles and privileges inherited by the user that the connection is using to access the database.

You can also create an administrator connection to the data warehouse, and assign a different set of users to that connection with a group called DatabaseAdministrators. Using compartments and policies, you can separate the access to these connections as follows:

Data Scientists group:

  1. Create a compartment called Reporting.
  2. Create a group in this compartment called DataScientists.
  3. Create a database connection in the Reporting compartment called ReportingDataAccess.
  4. Create a policy that gives access to the connection in the Reporting compartment to the DataScientists group:
    • Allow group DataScientists to read database-tools-family in compartment Reporting
    • Allow group DataScientists to use database-tools-connections in compartment Reporting

Database Administrators group:

  1. Create a compartment called DBA.
  2. Create a group in this compartment called DatabaseAdministrators.
  3. Create a database connection called DatabaseAdmin in the DBA compartment.
  4. Create a policy that gives access to the connection in the DBA compartment to that group:
    • Allow group DatabaseAdministrators to read database-tools-family in compartment DBA
    • Allow group DatabaseAdministrators to use database-tools-connections in compartment DBA

These groups and compartment-specific database connections help isolate which users can access which databases and determine the access they have.

Using Private Endpoints

When creating database connections to an Autonomous Database that is using a private endpoint, create a network security group to provide access from Database Tools to that database. When creating the network security group, you define specific access rules that limit which IPs or CIDR blocks can be used, and the ports or port ranges.

For the SQL worksheet

To configure the minimum set of network security group rules needed to provide access from the Database Tools SQL Worksheet in the OCI Console:

  1. On the Private Endpoint Details page, locate the Reverse Connection Source IPs field in the Private Endpoint Information section. There are two IP addresses.
  2. Edit the network security group and add rules for the two IP addresses, with access to destination port 1522 using TCP/IP. For example, given two IP addresses, 10.0.1.6 and 10.0.1.8, the two rules have the CIDR blocks 10.0.1.6/32 and 10.0.1.8/32 with access to destination port 1522, using TCP/IP.

For SQLcl and Bastions

To configure the minimum set of network security group rules needed to provide access from the Database Tools SQLcl using a bastion in the OCI Console:

  1. On the Bastion details page, locate the private endpoint IP address item in the Private endpoint IP address field. Only one IP address shown.
  2. Edit the network security group and add rules for this IP address with access to the destination port of 1522 using TCP/IP. For example, if given an IP address 10.0.1.9, then the rule has the CIDR block of 10.0.1.7/32 with access to the destination port of 1522 using TCP/IP.

These rules ensure that Database Tools has access to only the selected Autonomous Database through the network security group from these specific IP addresses, and only on port 1522 for bastion access using SQLcl and SQL Worksheet access on the OCI Console.

Auditing

You can extend the Oracle Database unified audit trail to capture application attributes by configuring auditing for application context values. The application context namespace is populated with the required attributes, and those values are captured in the unified audit trail.

The application attributes provided by Database Tools can be used to:

  • Identify the authenticated IAM principal that initiated the database access using the Database Tools service.
  • Correlate a unified audit trail record with an OCI audit event.

Identify the Authenticated IAM Principal

To capture the application context attributes in the unified audit trail, you must first run the AUDIT CONTEXT command specifying the additional attributes that you want to include in the audit record.

For example, the following statement captures the values of namespace CLIENTCONTEXT attributes IAM_PRINCIPAL_OCID to RESOURCE_COMPARTMENT_OCID in all audit records.

AUDIT CONTEXT NAMESPACE CLIENTCONTEXT ATTRIBUTES IAM_PRINCIPAL_OCID,IAM_PRINCIPAL_TYPE, 
IAM_PRINCIPAL_SUB_TYPE,IAM_PRINCIPAL_RESOURCE_TYPE,IAM_PRINCIPAL_TENANCY_OCID, 
OPC_REQUEST_ID,RESOURCE_OCID,RESOURCE_COMPARTMENT_OCID

After you have added the attributes, you can use the following statement to check the application context attributes that are captured in the unified audit trail.

SELECT * FROM AUDIT_UNIFIED_CONTEXTS;

Audit records populated in the UNIFIED_AUDIT_TRAIL by the Database Tools service provide information for the following columns.

Table 7-1 Audited Columns

Column Value
OS_USERNAME IAM authenticated principal identifier possibly truncated
CLIENT_IDENTIFIER Remaining characters of the IAM authenticated principal identifier
USERHOST Middle-tier hostname
TERMINAL Unknown
CLIENT_PROGRAM_NAME Database Tools ORDS
EXECUTION_ID opc-request-id truncated at 64 characters
APPLICATION_CONTEXTS See Table 7-2

The APPLICATION_CONTEXTS column is populated with the values of the following CLIENTCONTEXT attributes, which enables you to identify the authenticated IAM principal that initiated the database operation.

Table 7-2 Application_Contexts Column

Context Attribute Description
CLIENTCONTEXT IAM_PRINCIPAL_OCID IAM prinicipal id
IAM_PRINCIPAL_TENANCY_OCID IAM prinicipal tenancy id
IAM_PRINCIPAL_TYPE

IAM prinicipal type

  • user
  • resource
  • instance
  • service
IAM_PRINCIPAL_SUB_TYPE

IAM principal sub-type

  • natv (native user)
  • natf (native federated user)
  • fed (federated user)
  • none
IAM_PRINCIPAL_RESOURCE_TYPE IAM principal resource type
OPC_REQUEST_ID OPC request id
RESOURCE_OCID Resource id
RESOURCE_COMPARTMENT_OCID Resource compartment id

Correlate a Unified Audit Trail Record with an OCI Audit Event

Using the OPC_REQUEST_ID and RESOURCE_COMPARTMENT_OCID attributes provided in the APPLICATION_CONTEXTS column and the EVENT_TIMESTAMP, it is possible to find the audit event matching the unified audit trail record.

Using the Oracle Cloud Infrastructure Console

  1. In the Console, open the navigation menu and click Observability & Management, select Logging, and then select Audit.
  2. In the left pane, select the Compartment.
  3. In the right pane, in Filters, enter data.request.id= '<opc-request-id value>'.
  4. In Filter by time, select the time interval from the drop-down list.
  5. Click Apply.

    The results appear in the Explore Events tab.

Using the Command Line Interface (CLI)

Enter the <REGION ID>, <RESOURCE_COMPARTMENT_OCID>, and <OPC_REQUEST_ID> in the following script to find the audit event matching the unified audit trail record.

#!/bin/sh
 
read -r -d '' body <<EndOfBody
{
  "searchQuery": "search \"<RESOURCE_COMPARTMENT_ID>/_Audit\" | (data.request.id='<OPC_REQUEST_ID>') | sort by datetime desc",
  "timeStart":"2024-07-19T11:03:56.167Z",
  "timeEnd":"2024-07-19T14:03:56.167Z",
  "isReturnFieldInfo":false
}
EndOfBody
 
oci raw-request --target-uri https://logging.<REGION_ID>.oci.oraclecloud.com/20190909/search --http-method POST --request-body "${body}"