REST Catalog User Identity

A typical Iceberg REST catalog configuration uses fixed client credentials. Every user who accesses the data lake through VeloDB Enterprise appears to the REST catalog as the same service account, making user-level authorization and auditing difficult.

User identity mode stores the OIDC access token in the VeloDB Enterprise session and forwards it to the REST catalog. The catalog can identify the user, authorize access based on users or groups, and issue short-lived storage credentials.

Note:

Supported since VeloDB Enterprise 4.1.4.

How it works

User identity mode involves three components:

1. The IdP issues a user access token intended for both VeloDB Enterprise and the REST catalog.
2. VeloDB Enterprise validates the token, establishes a session, and controls whether the user can access the target catalog.
3. The REST catalog uses the forwarded token to authorize access to namespaces, tables, or views, and issues temporary storage credentials when needed.

OIDC access token
        |
        v
VeloDB Enterprise user session
        |
        v
Iceberg REST catalog
        |
        v
Catalog authorization and temporary storage credentials

Both authorization layers apply:

VeloDB Enterprise	REST catalog	Result
Allows	Allows	Access succeeds.
Denies	Allows	Access fails.
Allows	Denies	Access fails.
Denies	Denies	Access fails.

VeloDB Enterprise can manage access to the catalog, while the REST catalog centrally manages fine-grained privileges on external data lake objects.

Prerequisites

• OIDC authentication is configured, and users can log in to VeloDB Enterprise with access tokens.
• The frontend (FE) and backend (BE) use the same VeloDB Enterprise version.
• The REST catalog supports OAuth 2.0 user authentication and can map token claims to catalog principals.
• The REST catalog has namespace, table, and view privileges configured for the users or groups.
• To obtain object storage credentials from the catalog, it must support credential vending.

Warning:

In production, use TLS for communication between the IdP, VeloDB Enterprise, and the REST catalog. Do not configure long-lived, highly privileged credentials for business queries in catalog properties.

1. Configure REST catalog identities and privileges

These examples use two users to demonstrate isolation:

• oidc_alice: A Finance user who can access only the finance namespace.
• oidc_bob: A Marketing user who can access only the marketing namespace.

Create principals in the REST catalog that correspond to the OIDC users, and configure the following privileges:

Principal	Role	Accessible objects
oidc_alice	finance_reader	finance.finance_orders, finance.finance_budget
oidc_bob	marketing_reader	marketing.campaign_spend, marketing.lead_score

The exact procedure depends on your REST catalog. Ensure that:

• Principal names or mapping rules match the token's user claims.
• Roles can list their target namespaces and tables.
• Roles can read table properties and data.
• Roles have no access to other namespaces or tables.

2. Create an OIDC integration

Use an account with ADMIN_PRIV to create the integration in VeloDB Enterprise:

CREATE AUTHENTICATION INTEGRATION corp_oidc
PROPERTIES (
    'type' = 'oidc',
    'enable_jit_user' = 'true',
    'oidc.issuer' = 'https://idp.example.com/realms/doris',
    'oidc.jwks_uri' = 'https://idp.example.com/realms/doris/protocol/openid-connect/certs',
    'oidc.allowed_audiences' = 'doris',
    'oidc.username_claim' = 'preferred_username',
    'oidc.subject_claim' = 'sub',
    'oidc.groups_claim' = 'doris_groups',
    'oidc.allowed_algorithms' = 'RS256',
    'oidc.required_scopes' = 'doris.query'
);

Replace the IdP endpoints, audience, and claim configuration with values for your deployment. The token must also be accepted by the REST catalog.

Add the integration to the FE authentication chain in fe.conf:

authentication_chain = corp_oidc

If you use other authentication methods, retain their entries in the required order. Restart the FE after changing fe.conf.

3. Create a catalog in user identity mode

Use an account with catalog management privileges:

CREATE CATALOG lakehouse PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'rest',
    'iceberg.rest.uri' = 'https://polaris.example.com/api/catalog',
    'iceberg.rest.security.type' = 'oauth2',
    'iceberg.rest.session' = 'user',
    'iceberg.rest.session-timeout' = '0',
    'iceberg.rest.oauth2.delegated-token-mode' = 'access_token',
    'iceberg.rest.vended-credentials-enabled' = 'true',
    'warehouse' = 'enterprise_lakehouse'
);

Replace the REST endpoint and warehouse value with your catalog configuration.

Property	Description
iceberg.rest.session	Set to user to maintain separate REST catalog sessions for different VeloDB Enterprise users.
iceberg.rest.session-timeout	Controls how long REST catalog user sessions can be reused. Set to 0 to reduce reuse when verifying privilege changes. In production, choose a value that balances security and performance.
iceberg.rest.oauth2.delegated-token-mode	Set to access_token to forward the current VeloDB Enterprise session's access token to the REST catalog.
iceberg.rest.vended-credentials-enabled	Controls whether to use temporary object storage credentials issued by the REST catalog.

Do not also configure iceberg.rest.oauth2.credential shared by all business users. Otherwise, the REST catalog might identify only a fixed service account and be unable to authorize the current user.

4. Grant access to the catalog

Create a shared role that allows OIDC users to access the lakehouse catalog:

CREATE ROLE lakehouse_user;
GRANT SELECT_PRIV ON lakehouse.*.* TO ROLE lakehouse_user;

CREATE ROLE MAPPING corp_oidc_lakehouse_mapping
ON AUTHENTICATION INTEGRATION corp_oidc
RULE (
    USING CEL 'has_scope("doris.query")'
    GRANT ROLE lakehouse_user
);

This role grants VeloDB Enterprise query privileges across lakehouse. It does not distinguish Finance from Marketing. The REST catalog further restricts which external objects each user can access.

5. Verify user isolation

Replace <fe-host> with the FE hostname and the example paths with your CA certificate and token files. Restrict access to the token files.

Verify the Finance user

Save the access token for oidc_alice in a local file, and connect with MySQL Shell 9.x:

mysqlsh --sql --sqlc --ssl-mode=VERIFY_IDENTITY \
  --ssl-ca=/path/to/ca.pem \
  -h <fe-host> -P 9030 -u oidc_alice \
  --authentication-openid-connect-client-id-token-file=/path/to/oidc_alice.access_token

Run:

SWITCH lakehouse;
SHOW DATABASES;

USE finance;
SHOW TABLES;

oidc_alice should see the finance namespace and its authorized tables. Attempts to access marketing should be rejected by the REST catalog, or unauthorized objects should be filtered from results.

Verify the Marketing user

Connect with the access token for oidc_bob:

mysqlsh --sql --sqlc --ssl-mode=VERIFY_IDENTITY \
  --ssl-ca=/path/to/ca.pem \
  -h <fe-host> -P 9030 -u oidc_bob \
  --authentication-openid-connect-client-id-token-file=/path/to/oidc_bob.access_token

Run:

SWITCH lakehouse;
SHOW DATABASES;

USE marketing;
SHOW TABLES;

oidc_bob should see only the marketing namespace and its authorized tables.

Troubleshoot unexpected access

If both users see the same objects, check that:

• The catalog has iceberg.rest.session set to user.
• The catalog is not still using fixed OAuth 2.0 credentials.
• The REST catalog correctly identifies the principal in the token.
• REST catalog roles and object privileges are associated with the correct principals.
• The users' local roles allow access to the target catalog.

For connection or token validation failures, see OIDC common errors.

Handle role and organizational changes

When a user's business role changes, update authorization in the REST catalog's centralized privilege model. For example, changing oidc_bob from marketing_reader to finance_reader does not require modifying the VeloDB Enterprise catalog or duplicating privileges for every external table.

When changes take effect depends on where you make them:

• Changes to REST catalog roles or object privileges apply to subsequent catalog requests. Reused catalog sessions can be affected by iceberg.rest.session-timeout.
• Changes to IdP claims, such as groups, department, or scopes, require refreshing the access token or logging in again before VeloDB Enterprise and the REST catalog can read the new claims.

In production, choose token lifetimes and REST catalog session timeouts according to your security and performance requirements.

Security recommendations

• Configure a dedicated audience for VeloDB Enterprise and validate it with oidc.allowed_audiences.
• Restrict client IDs, scopes, and JWT signature algorithms.
• Use short-lived access tokens and establish a reliable refresh and revocation process.
• Use credential vending to issue short-lived storage credentials with the minimum required privileges.
• Retain audit logs from both VeloDB Enterprise and the REST catalog to trace the complete access path.
• Grant only the required local catalog privileges. Manage namespace, table, and view privileges centrally in the REST catalog.

See also

• OIDC Authentication
• Iceberg REST Catalog API
• CREATE CATALOG