LakeBase JDBC Driver: Identity Provider Integration

The Onehouse LakeBase JDBC driver (ai.onehouse.jdbc.OnehouseDriver) extends the standard PostgreSQL JDBC driver with built-in browser-based authentication support. It enables seamless SSO integration with your corporate identity provider (IdP) so end users authenticate with their existing credentials rather than managing static passwords.

info

The LakeBase JDBC driver is required when your LakeBase Cluster uses Lake Formation access control. For clusters without Lake Formation, the standard PostgreSQL JDBC driver is sufficient.

How It Works

When browserAuth=true is set in the connection properties, the driver:

1. Detects the configured identity provider from the connection properties
2. Opens a browser window to begin the authentication flow
3. Starts a local HTTP server (default port 8888) to receive the OAuth/SAML callback
4. Exchanges the authentication response for credentials and passes them to the underlying PostgreSQL driver

JDBC URL Format

jdbc:onehouse:postgresql://host:port/database?param=value...

The driver also accepts standard PostgreSQL URLs when browserAuth=true is present in the properties:

jdbc:postgresql://host:port/database

Supported Identity Providers

1. OIDC Device Flow (Okta, Auth0, and any OIDC-compliant IdP)

Uses the OAuth 2.0 Device Authorization Grant (RFC 8628). The browser displays a user code and activation URL; no local callback server is needed.

Connection properties:

Property	Required	Description
browserAuth	Yes	Set to true to enable browser authentication
oidcClientId	Yes	OAuth2 client ID from your IdP application
oidcIssuerUrl	Yes	OIDC issuer URL (e.g., https://dev-12345.okta.com)
oidcIamRole	Yes	AWS IAM role ARN to assume after authentication
oidcClientSecret	No	Client secret (omit for public clients)

OIDC endpoints used:

• Device authorization: {oidcIssuerUrl}/oauth2/v1/device/authorize
• Token: {oidcIssuerUrl}/oauth2/v1/token
• Scopes requested: openid profile offline_access groups

Example (Java):

Properties props = new Properties();
props.setProperty("browserAuth", "true");
props.setProperty("oidcClientId", "0oa1b2c3d4e5f6g7h8i9");
props.setProperty("oidcIssuerUrl", "https://dev-12345.okta.com");
props.setProperty("oidcIamRole", "arn:aws:iam::123456789012:role/onehouse-lakebase-role");
// props.setProperty("oidcClientSecret", "optional-client-secret");

Connection conn = DriverManager.getConnection(
    "jdbc:onehouse:postgresql://cluster-host:5432/postgres",
    props
);

---

2. Azure AD OAuth2 (Authorization Code Flow)

Uses the OAuth 2.0 Authorization Code flow with Microsoft Azure AD (login.microsoftonline.com). The driver opens a browser for interactive login and receives an authorization code at the local callback server.

Connection properties:

Property	Required	Description
browserAuth	Yes	Set to true to enable browser authentication
azureOAuthTenantId	Yes	Azure AD tenant ID (GUID)
azureOAuthClientId	Yes	Azure application (client) ID
azureOAuthClientSecret	Yes	Azure client secret value
azureOAuthScope	No	OAuth scope (default: openid)
azureOAuthIamRole	No	AWS IAM role ARN to assume after federation
authCallbackPort	No	Local callback server port (default: 8888)
authCallbackPath	No	Callback path (default: /lakebase)

Azure AD endpoints used:

• Authorization: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
• Token: https://login.microsoftonline.com/{tenantId}/oauth2/token

Example (Java):

Properties props = new Properties();
props.setProperty("browserAuth", "true");
props.setProperty("azureOAuthTenantId", "12345678-1234-1234-1234-123456789abc");
props.setProperty("azureOAuthClientId", "your-application-client-id");
props.setProperty("azureOAuthClientSecret", "your-client-secret");
props.setProperty("azureOAuthIamRole", "arn:aws:iam::123456789012:role/onehouse-lakebase-role");

Connection conn = DriverManager.getConnection(
    "jdbc:postgresql://cluster-host:5432/postgres",
    props
);

---

3. Azure Entra ID (SAML 2.0)

Uses SAML 2.0 HTTP POST binding with Microsoft Entra ID. The driver generates a SAML AuthnRequest, redirects the browser to Entra, and receives the SAML assertion at the local callback server.

Connection properties:

Property	Required	Description
browserAuth	Yes	Set to true to enable browser authentication
azureTenantId	Yes	Azure tenant ID (GUID)
azureEntityId	Yes	Entity ID configured in your Entra enterprise application
authCallbackPort	No	Local callback server port (default: 8888)
authCallbackPath	No	Callback path (default: /lakebase)

SAML AuthnRequest details:

• Destination: https://login.microsoftonline.com/{tenantId}/saml2
• AssertionConsumerServiceURL: http://localhost:{port}{callbackPath}
• ProtocolBinding: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
• NameIDPolicy format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Example (Java):

Properties props = new Properties();
props.setProperty("browserAuth", "true");
props.setProperty("azureTenantId", "12345678-1234-1234-1234-123456789abc");
props.setProperty("azureEntityId", "urn:your-org:lakebase:jdbc");
props.setProperty("authCallbackPort", "8888");

Connection conn = DriverManager.getConnection(
    "jdbc:postgresql://cluster-host:5432/postgres",
    props
);

---

4. External Redirect (Generic OAuth / SAML)

For any IdP that can be configured to redirect back to a local URL. Use this for custom SAML providers, Okta SAML apps, or any OAuth/OIDC flow not covered by the built-in handlers.

Connection properties:

Property	Required	Description
browserAuth	Yes	Set to true to enable browser authentication
authRedirectUrl	Yes	The URL to open in the browser. Use {callback} as a placeholder for the local callback URL
authCallbackPort	No	Local callback server port (default: 8888)
authCallbackPath	No	Callback path (default: /lakebase)

The local callback server accepts the following parameters from your IdP:

Accepted Parameter Name	Used For
username, user, login, email	Username
password, pass, access_token, token	Password / token
SAMLResponse	SAML assertion (Base64-encoded XML)
code	OAuth authorization code (forwarded with all query params)

Example (Java):

Properties props = new Properties();
props.setProperty("browserAuth", "true");
props.setProperty("authRedirectUrl",
    "https://your-okta-domain.okta.com/app/amazon_aws/exk1234567890/sso/saml" +
    "?RelayState={callback}");
props.setProperty("authCallbackPort", "5001");
props.setProperty("authCallbackPath", "/auth/acs");

Connection conn = DriverManager.getConnection(
    "jdbc:postgresql://cluster-host:5432/postgres",
    props
);

---

5. Built-in Form (Username / Password)

Falls back to a simple HTML form served by the local callback server when no IdP-specific properties are set. Useful for testing or environments with basic authentication.

Connection properties:

Property	Required	Description
browserAuth	Yes	Set to true to enable browser authentication
authCallbackPort	No	Local callback server port (default: 8888)

The browser opens http://localhost:{port}/auth, where the user enters their username and password. The form POSTs to http://localhost:{port}/submit.

---

IAM Role Specification

All identity providers support optional IAM role federation. When a role is configured (via oidcIamRole, azureOAuthIamRole, or the JDBC URL options parameter), the driver passes it to LakeBase as a PostgreSQL connection option:

options=-c onehouse.lakebase_iam_role=arn:aws:iam::account-id:role/role-name

If no role is specified, LakeBase uses the first IAM role present in the authentication token by default.

To specify a role explicitly in the JDBC URL:

jdbc:postgresql://host:5432/postgres?options=-c onehouse.lakebase_iam_role=arn:aws:iam::123456789012:role/role-name

To specify a role in DBeaver:

1. Open your connection settings
2. Go to Driver Properties
3. Add property options with value -c onehouse.lakebase_iam_role=arn:aws:iam::123456789012:role/role-name

---

Driver Registration

// Register the driver (required once per JVM)
Class.forName("ai.onehouse.jdbc.OnehouseDriver");

// Or use DriverManager directly
DriverManager.registerDriver(new ai.onehouse.jdbc.OnehouseDriver());

The driver extends org.postgresql.Driver, so it is fully compatible with tools and frameworks that accept a PostgreSQL-compatible JDBC driver.

---