Configure MCP Deep Data Security

Oracle Deep Data Security (Deep Sec) enables Oracle Database authorize access through ORDS MCP using an application identity and, when configured, the authenticated end-user identity. Database policies can then limit which rows, columns, and operations are available to each user and application.

If you choose to use Oracle Deep Data Security with ORDS MCP, configure the database and identity-provider resources as described in the following sections.

Configure Database and Identity Provider Prerequisites

Before you configure an ORDS MCP database pool for Deep Sec, configure the required database and identity-provider resources.

For a local end-user pool using password authentication, the database administrator must create the local user, assign local data roles, and grant the required data privileges.

For an application-token pool configured to use authenticated end-user context, the database and identity administrators must:

Register the application with the identity provider
Create the database application identity
Assign application roles to end users in the identity provider
Create Deep Sec data roles that correspond to application roles
Create data grants that define permitted database rows, columns, and operations

ORDS establishes the database connection and, when required, propagates the authenticated MCP user’s context. It does not create or manage identity-provider users or roles, database data roles, or database data grants.

Configure an ORDS MCP Deep Sec Database Pool

Use the db.authentication pool setting to choose the database authentication mode.

Value	Description
`PASSWORD`	Specifies a fixed database identity using the configured `db.username` and secure `db.password`, including a database-managed local end user. This is the default and does not propagate the individual MCP identity of the caller.
`APP_TOKEN`	Specifies how ORDS obtains a database access token for the configured application and connects using that identity of the application. It does not propagate the individual MCP identity of the caller identity.
`APP_TOKEN_WITH_END_USER_TOKEN`	Specifies that ORDS obtains a database access token for the configured application and attaches the authenticated MCP token of the user as the Oracle Database end-user security context.

Use a Database-Managed Local End User with Password Authentication

Use PASSWORD authentication when the ORDS MCP database pool connects with a database-managed local end-user account.

Configure the Local End-User Credentials in the Database Pool

ords --config /path/to/conf config --db-pool mcp-hr set db.authentication PASSWORD
ords --config /path/to/conf config --db-pool mcp-hr set db.username mcp_hr_end_user
ords --config /path/to/conf config --db-pool mcp-hr secret db.password

PASSWORD is the default value for db.authentication.

Every connection borrowed from the pool uses the database principal identified by db.username and db.password. As a result, all MCP callers authorized to use the pool, access the database as the same local end user.

Create a Local End User and Grant Data Access

The following example creates a database-managed local end user, grants the database session privilege required for direct logon, and grants a Deep Sec data role. The data grant permits the role to query selected columns of the HR.EMPLOYEES table.

CREATE END USER mcp_hr_end_user IDENTIFIED BY <password>;

CREATE ROLE direct_logon_role;
GRANT CREATE SESSION TO direct_logon_role;
GRANT direct_logon_role TO mcp_hr_end_user;

CREATE DATA ROLE hrapp_employees;
GRANT DATA ROLE hrapp_employees TO mcp_hr_end_user;
GRANT direct_logon_role TO hrapp_employees;

CREATE OR REPLACE DATA GRANT hr.hrapp_employee_access
  AS SELECT (first_name, last_name, email)
  ON hr.employees
  TO hrapp_employees;

Run the following query to verify the data-role assignments:

SELECT data_role, role_type, grantee, grantee_type
FROM dba_data_role_grants
WHERE grantee IN ('MCP_HR_END_USER', 'HRAPP_EMPLOYEES');

Configure Application Token Authentication

Use APP_TOKEN when the database authorizes access using only the application identity. Use APP_TOKEN_WITH_END_USER_TOKEN when the database must authorize each authenticated MCP user individually through the end-user security context.

For either mode, configure the following pool settings:

Setting	Description
`db.authentication`	Specifies the authentication mode for the MCP pool. `PASSWORD` is the default. `APP_TOKEN` uses a database access token for the configured application identity. `APP_TOKEN_WITH_END_USER_TOKEN` uses the application token and propagates the authenticated MCP user token as the Oracle Database end-user security context.
`db.access.token.endpoint`	Specifies the trusted HTTPS OAuth token endpoint that issues the application database access token.
`db.access.client.id`	The OAuth client identifier for the application.
`db.access.client.secret`	The secure OAuth client secret for the application.
`db.access.scope`	One or more OAuth scopes requested for the database access token. Separate multiple scopes with spaces.

For example, run the following ORDS CLI commands:

ords --config /path/to/conf config --db-pool mcp-hr set db.authentication APP_TOKEN_WITH_END_USER_TOKEN
ords --config /path/to/conf config --db-pool mcp-hr set db.access.token.endpoint https://idp.example.com/oauth2/v1/token
ords --config /path/to/conf config --db-pool mcp-hr set db.access.client.id mcp-hr-application
ords --config /path/to/conf config --db-pool mcp-hr set db.access.scope https://database.example.com/.default
ords --config /path/to/conf config --db-pool mcp-hr secret db.access.client.secret

Stores db.access.client.secret as an ORDS secure configuration value. Configure only a trusted HTTPS identity-provider endpoint.
For APP_TOKEN_WITH_END_USER_TOKEN, ORDS authenticates the MCP request, obtains a separate database access token for the configured application, and attaches the authenticated MCP user token as the Oracle JDBC end-user security context. ORDS clears that context before returning the connection to the pool.

Configure Data Roles and Data Grants

Deep Sec data roles represent database authorization assigned to the application users. For externally managed users, create data roles that correspond to the roles issued by the identity provider. Then, create data grants to define the permitted data access.

The following example maps a Microsoft Entra ID application role to a Deep Sec data role. Mapping syntax depends on the configured identity provider.

CREATE DATA ROLE employee_role MAPPED TO 'AZURE_ROLE=EMPLOYEE';

The following data grant permits users with the employee_role data role to query only the row that matches their end-user identity. It prevents access to the ssn column.

CREATE OR REPLACE DATA GRANT hr.employees_own_record
  AS SELECT (ALL COLUMNS EXCEPT ssn)
  ON hr.employees
  WHERE email = ORA_END_USER_CONTEXT.username
  TO employee_role;

Data grants are database security policies. Design and test them according to your organization’s authorization requirements. For complete syntax and privilege requirements, see CREATE DATA GRANT.

Verify the End-User Security Context

For an APP_TOKEN_WITH_END_USER_TOKEN request, use the sql_run tool to verify that the database receives the expected end-user identity and the data roles.

SELECT ORA_END_USER_CONTEXT.username AS end_user
FROM dual;

Query V$END_USER_DATA_ROLE only when the configured database identity has the required database privilege:

SELECT role_name
FROM v$end_user_data_role;

Use these queries and representative application queries to verify that:

The expected end-user identity is present.
The expected data roles are enabled.
Row-level filtering returns only authorized rows.
Protected columns are unavailable or masked as intended.

If the configured database identity cannot query the dynamic performance view, a database administrator can use the Deep Sec administrative views to validate security-context and data-role state. For additional runtime diagnostics, see End-User Security Context Views.