From b7673ab454d0a8f00f85421cb8298af6189e7712 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 29 Jun 2026 19:39:30 +0000 Subject: [PATCH 1/2] docs: document OAuth authentication for Enterprise remote connections --- docs/docs.json | 1 + docs/enterprise/authentication.mdx | 102 +++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 docs/enterprise/authentication.mdx diff --git a/docs/docs.json b/docs/docs.json index 7d1519f7..7690f85b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -50,6 +50,7 @@ "enterprise/quickstart", "enterprise/architecture", "enterprise/security", + "enterprise/authentication", "enterprise/benchmarks", { "group": "Deployment", diff --git a/docs/enterprise/authentication.mdx b/docs/enterprise/authentication.mdx new file mode 100644 index 00000000..7ffd5309 --- /dev/null +++ b/docs/enterprise/authentication.mdx @@ -0,0 +1,102 @@ +--- +title: "Authentication" +sidebarTitle: "Authentication" +description: "Authenticate to LanceDB Enterprise with an API key or OAuth credentials." +icon: "key" +keywords: ["authentication", "oauth", "api key", "azure managed identity", "client credentials"] +--- + +LanceDB Enterprise supports two ways for clients to authenticate against a `db://` remote table: + +- **API keys** — a long-lived shared secret passed as `api_key` on connect. Works in every SDK. +- **OAuth 2.0** — short-lived bearer tokens obtained from your identity provider, refreshed automatically by the client. + +OAuth is the recommended option when you want to rotate credentials centrally, plug into an existing identity provider, or run on Azure with managed identities so no secret material lives on the client. + +## API key + +Pass the API key from your Enterprise tenant on `connect`. This works with both the synchronous and asynchronous Python clients, as well as TypeScript and Rust. + +```python Python icon="python" +import lancedb + +db = lancedb.connect( + uri="db://your-database-uri", + api_key="your-api-key", + region="us-east-1", + host_override="https://your-enterprise-endpoint.com", +) +``` + +## OAuth + +The async Python client can obtain bearer tokens from an OIDC issuer and attach them to every request. Token acquisition, caching, and refresh are handled inside the client — your application code only provides the configuration. + + +OAuth is currently supported through `lancedb.connect_async`. The synchronous `connect` entry point continues to use API key authentication for `db://` URIs. + + +### Supported flows + +`OAuthFlowType` selects how the client acquires tokens: + +| Flow | Value | When to use | +| --- | --- | --- | +| Client Credentials | `CLIENT_CREDENTIALS` | Service-to-service / machine-to-machine. Requires a client ID and client secret registered with your identity provider. | +| Azure Managed Identity | `AZURE_MANAGED_IDENTITY` | Workloads running on Azure compute (VMs, AKS, App Service, Container Apps). Tokens are fetched from the Azure IMDS endpoint, so no client secret is stored on the client. | + +### Configure OAuth + +Build an `OAuthConfig` and pass it to `connect_async` via the `oauth_config` parameter. + +```python Python icon="python" +import lancedb +from lancedb.remote import OAuthConfig, OAuthFlowType + +# Client Credentials (service-to-service) +oauth_config = OAuthConfig( + issuer_url="https://login.microsoftonline.com/{tenant}/v2.0", + client_id="your-application-client-id", + client_secret="your-application-client-secret", + scopes=["api://lancedb-api/.default"], + flow=OAuthFlowType.CLIENT_CREDENTIALS, +) + +db = await lancedb.connect_async( + uri="db://your-database-uri", + region="us-east-1", + host_override="https://your-enterprise-endpoint.com", + oauth_config=oauth_config, +) +``` + +For workloads running on Azure compute, use a managed identity instead of a client secret: + +```python Python icon="python" +from lancedb.remote import OAuthConfig, OAuthFlowType + +oauth_config = OAuthConfig( + issuer_url="https://login.microsoftonline.com/{tenant}/v2.0", + client_id="your-application-client-id", + scopes=["api://lancedb-api/.default"], + flow=OAuthFlowType.AZURE_MANAGED_IDENTITY, + # Optional: required only for user-assigned managed identities. + managed_identity_client_id="your-user-assigned-identity-client-id", +) +``` + +### Configuration reference + +| Field | Required | Description | +| --- | --- | --- | +| `issuer_url` | Yes | OIDC issuer URL or OAuth authority URL. For Azure, use `https://login.microsoftonline.com/{tenant_id}/v2.0`. | +| `client_id` | Yes | Application / client ID registered with your identity provider. | +| `scopes` | Yes | List of OAuth scopes to request. For Azure managed identity, provide exactly one scope or resource, for example `["api://your-app-id/.default"]`. | +| `flow` | No | `OAuthFlowType.CLIENT_CREDENTIALS` (default) or `OAuthFlowType.AZURE_MANAGED_IDENTITY`. | +| `client_secret` | Conditional | Required for `CLIENT_CREDENTIALS`. Redacted from the config's `repr` so it does not leak into logs. | +| `managed_identity_client_id` | No | Client ID of a user-assigned managed identity. Only used with `AZURE_MANAGED_IDENTITY`; omit for system-assigned identities. | +| `refresh_buffer_secs` | No | How many seconds before token expiry to proactively refresh. Defaults to 300. Keep this well below the token TTL — setting it greater than or equal to the TTL forces a refresh on every request. | + + +Treat `client_secret` like any other production credential. Load it from a secret manager or environment variable rather than committing it to source control. The dataclass deliberately omits `client_secret` from its `repr` so accidental log lines do not expose the value. + From d46c48dcf6594dc4082276ffb124d3033b68fd4d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 29 Jun 2026 23:58:15 +0000 Subject: [PATCH 2/2] docs: add TypeScript OAuth examples to Enterprise authentication page --- docs/enterprise/authentication.mdx | 69 +++++++++++++++++++++++------- 1 file changed, 54 insertions(+), 15 deletions(-) diff --git a/docs/enterprise/authentication.mdx b/docs/enterprise/authentication.mdx index 7ffd5309..52566e2a 100644 --- a/docs/enterprise/authentication.mdx +++ b/docs/enterprise/authentication.mdx @@ -30,25 +30,26 @@ db = lancedb.connect( ## OAuth -The async Python client can obtain bearer tokens from an OIDC issuer and attach them to every request. Token acquisition, caching, and refresh are handled inside the client — your application code only provides the configuration. +The async Python client and the TypeScript client can obtain bearer tokens from an OIDC issuer and attach them to every request. Token acquisition, caching, and refresh are handled inside the client — your application code only provides the configuration. -OAuth is currently supported through `lancedb.connect_async`. The synchronous `connect` entry point continues to use API key authentication for `db://` URIs. +In Python, OAuth is supported through `lancedb.connect_async`. The synchronous `connect` entry point continues to use API key authentication for `db://` URIs. In TypeScript, `lancedb.connect` accepts `oauthConfig` directly. ### Supported flows `OAuthFlowType` selects how the client acquires tokens: -| Flow | Value | When to use | -| --- | --- | --- | -| Client Credentials | `CLIENT_CREDENTIALS` | Service-to-service / machine-to-machine. Requires a client ID and client secret registered with your identity provider. | -| Azure Managed Identity | `AZURE_MANAGED_IDENTITY` | Workloads running on Azure compute (VMs, AKS, App Service, Container Apps). Tokens are fetched from the Azure IMDS endpoint, so no client secret is stored on the client. | +| Flow | Python value | TypeScript value | When to use | +| --- | --- | --- | --- | +| Client Credentials | `OAuthFlowType.CLIENT_CREDENTIALS` | `OAuthFlowType.ClientCredentials` | Service-to-service / machine-to-machine. Requires a client ID and client secret registered with your identity provider. | +| Azure Managed Identity | `OAuthFlowType.AZURE_MANAGED_IDENTITY` | `OAuthFlowType.AzureManagedIdentity` | Workloads running on Azure compute (VMs, AKS, App Service, Container Apps). Tokens are fetched from the Azure IMDS endpoint, so no client secret is stored on the client. | ### Configure OAuth -Build an `OAuthConfig` and pass it to `connect_async` via the `oauth_config` parameter. +Build an OAuth config and pass it on connect. Use `oauth_config` in Python and `oauthConfig` in TypeScript. + ```python Python icon="python" import lancedb from lancedb.remote import OAuthConfig, OAuthFlowType @@ -70,8 +71,30 @@ db = await lancedb.connect_async( ) ``` +```typescript TypeScript icon="square-js" +import * as lancedb from "@lancedb/lancedb"; +import { OAuthConfig, OAuthFlowType } from "@lancedb/lancedb"; + +// Client Credentials (service-to-service) +const oauthConfig: OAuthConfig = { + issuerUrl: "https://login.microsoftonline.com/{tenant}/v2.0", + clientId: "your-application-client-id", + clientSecret: "your-application-client-secret", + scopes: ["api://lancedb-api/.default"], + flow: OAuthFlowType.ClientCredentials, +}; + +const db = await lancedb.connect("db://your-database-uri", { + region: "us-east-1", + hostOverride: "https://your-enterprise-endpoint.com", + oauthConfig, +}); +``` + + For workloads running on Azure compute, use a managed identity instead of a client secret: + ```python Python icon="python" from lancedb.remote import OAuthConfig, OAuthFlowType @@ -85,18 +108,34 @@ oauth_config = OAuthConfig( ) ``` +```typescript TypeScript icon="square-js" +import { OAuthConfig, OAuthFlowType } from "@lancedb/lancedb"; + +const oauthConfig: OAuthConfig = { + issuerUrl: "https://login.microsoftonline.com/{tenant}/v2.0", + clientId: "your-application-client-id", + scopes: ["api://lancedb-api/.default"], + flow: OAuthFlowType.AzureManagedIdentity, + // Optional: required only for user-assigned managed identities. + managedIdentityClientId: "your-user-assigned-identity-client-id", +}; +``` + + ### Configuration reference -| Field | Required | Description | +The same configuration is available in both SDKs. Python uses `snake_case` field names; TypeScript uses `camelCase`. + +| Python field / TypeScript field | Required | Description | | --- | --- | --- | -| `issuer_url` | Yes | OIDC issuer URL or OAuth authority URL. For Azure, use `https://login.microsoftonline.com/{tenant_id}/v2.0`. | -| `client_id` | Yes | Application / client ID registered with your identity provider. | +| `issuer_url` / `issuerUrl` | Yes | OIDC issuer URL or OAuth authority URL. For Azure, use `https://login.microsoftonline.com/{tenant_id}/v2.0`. | +| `client_id` / `clientId` | Yes | Application / client ID registered with your identity provider. | | `scopes` | Yes | List of OAuth scopes to request. For Azure managed identity, provide exactly one scope or resource, for example `["api://your-app-id/.default"]`. | -| `flow` | No | `OAuthFlowType.CLIENT_CREDENTIALS` (default) or `OAuthFlowType.AZURE_MANAGED_IDENTITY`. | -| `client_secret` | Conditional | Required for `CLIENT_CREDENTIALS`. Redacted from the config's `repr` so it does not leak into logs. | -| `managed_identity_client_id` | No | Client ID of a user-assigned managed identity. Only used with `AZURE_MANAGED_IDENTITY`; omit for system-assigned identities. | -| `refresh_buffer_secs` | No | How many seconds before token expiry to proactively refresh. Defaults to 300. Keep this well below the token TTL — setting it greater than or equal to the TTL forces a refresh on every request. | +| `flow` | No | Selects the OAuth flow. Defaults to Client Credentials. | +| `client_secret` / `clientSecret` | Conditional | Required for Client Credentials. Redacted from the config's `repr` (Python) and `Debug` output (TypeScript native binding) so it does not leak into logs. | +| `managed_identity_client_id` / `managedIdentityClientId` | No | Client ID of a user-assigned managed identity. Only used with Azure Managed Identity; omit for system-assigned identities. | +| `refresh_buffer_secs` / `refreshBufferSecs` | No | How many seconds before token expiry to proactively refresh. Defaults to 300. Keep this well below the token TTL — setting it greater than or equal to the TTL forces a refresh on every request. | -Treat `client_secret` like any other production credential. Load it from a secret manager or environment variable rather than committing it to source control. The dataclass deliberately omits `client_secret` from its `repr` so accidental log lines do not expose the value. +Treat the client secret like any other production credential. Load it from a secret manager or environment variable rather than committing it to source control. Both SDKs deliberately omit the secret from their debug/repr output so accidental log lines do not expose the value.