本页尚未翻译

本页内容仍为英文原文，源自官方文档 enterprise/authentication。中文翻译正在分批进行中。

Authentication

Authentication modes for LanceDB Enterprise: API keys and OAuth credentials.

Applies to: Embedded ❌, Enterprise ✅

A deployment authenticates each request over a db:// connection before authorization decides what it may do. Choose one of these methods:

• 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. Load the key from an environment variable or secret manager.

import os
db = lancedb.connect(
    uri="db://your-database-uri",
    api_key=os.environ["LANCEDB_API_KEY"],
    region="us-east-1",
    host_override="https://your-enterprise-endpoint.com",
)

import * as lancedb from "@lancedb/lancedb";

const apiKey = process.env.LANCEDB_API_KEY;
if (!apiKey) throw new Error("LANCEDB_API_KEY is required");

const db = await lancedb.connect("db://your-database-uri", {
  apiKey,
  region: "us-east-1",
  hostOverride: "https://your-enterprise-endpoint.com",
});

let api_key = std::env::var("LANCEDB_API_KEY")?;

let db = lancedb::connect("db://your-database-uri")
    .api_key(&api_key)
    .region("us-east-1")
    .host_override("https://your-enterprise-endpoint.com")
    .execute()
    .await?;

For Rust, enable the remote feature on the lancedb dependency to use API key or OAuth authentication.

See Database for the connection options.

OAuth

The async Python, TypeScript, and Rust clients 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.

A deployment accepts these tokens only when its administrator has configured it with your identity provider. Ask them for the issuer URL, client ID, scopes, and any resource or audience required by the provider. For Authorization Code, register the loopback redirect URI with the provider. For Device Code, enable the provider's device authorization grant for your application.

说明

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. In Rust, use .oauth_config(config) on the connection builder.

Supported flows

OAuthFlowType (Python and TypeScript) or OAuthFlow (Rust) selects how the client acquires tokens:

Flow	Python value	TypeScript value	Rust value	When to use
Client Credentials	OAuthFlowType.CLIENT_CREDENTIALS	OAuthFlowType.ClientCredentials	OAuthFlow::ClientCredentials	Service-to-service / machine-to-machine. Requires a client ID and client secret registered with your identity provider.
Authorization Code	OAuthFlowType.AUTHORIZATION_CODE	OAuthFlowType.AuthorizationCode	OAuthFlow::AuthorizationCode(AuthorizationCodeOptions::new())	Interactive user sign-in through a browser and local callback server. Uses S256 PKCE by default.
Device Code	OAuthFlowType.DEVICE_CODE	OAuthFlowType.DeviceCode	OAuthFlow::DeviceCode(DeviceCodeOptions::new())	CLI or headless sign-in. The client displays a verification URL and user code for the user to enter on another device.
Azure Managed Identity	OAuthFlowType.AZURE_MANAGED_IDENTITY	OAuthFlowType.AzureManagedIdentity	OAuthFlow::AzureManagedIdentity { client_id: None }	Azure workloads with access to the IMDS endpoint. Tokens are fetched from IMDS, so no client secret is stored on the client.

Configure OAuth

Build an OAuth config and pass it on connect. Use oauth_config in Python and Rust, and oauthConfig in TypeScript.

import os
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=os.environ["LANCEDB_OAUTH_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,
)

import * as lancedb from "@lancedb/lancedb";
import { OAuthConfig, OAuthFlowType } from "@lancedb/lancedb";

const clientSecret = process.env.LANCEDB_OAUTH_CLIENT_SECRET;
if (!clientSecret) throw new Error("LANCEDB_OAUTH_CLIENT_SECRET is required");

// Client Credentials (service-to-service)
const oauthConfig: OAuthConfig = {
  issuerUrl: "https://login.microsoftonline.com/{tenant}/v2.0",
  clientId: "your-application-client-id",
  clientSecret,
  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,
});

use lancedb::remote::{OAuthConfig, OAuthFlow};

// Client Credentials (service-to-service)
let oauth_config = OAuthConfig {
    issuer_url: "https://login.microsoftonline.com/{tenant}/v2.0".into(),
    client_id: "your-application-client-id".into(),
    client_secret: Some(std::env::var("LANCEDB_OAUTH_CLIENT_SECRET")?),
    scopes: vec!["api://lancedb-api/.default".into()],
    flow: OAuthFlow::ClientCredentials,
    client_auth_method: None,
    resource: None,
    audience: None,
    refresh_buffer_secs: None,
    token_cache: None,
};

let db = lancedb::connect("db://your-database-uri")
    .region("us-east-1")
    .host_override("https://your-enterprise-endpoint.com")
    .oauth_config(oauth_config)
    .execute()
    .await?;

For Azure workloads with access to IMDS, use a managed identity instead of a client secret:

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,
    # Set only for a user-assigned managed identity:
    # managed_identity_client_id="your-user-assigned-identity-client-id",
)

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,
  // Set only for a user-assigned managed identity:
  // managedIdentityClientId: "your-user-assigned-identity-client-id",
};

use lancedb::remote::{OAuthConfig, OAuthFlow};

let oauth_config = OAuthConfig {
    issuer_url: "https://login.microsoftonline.com/{tenant}/v2.0".into(),
    client_id: "your-application-client-id".into(),
    client_secret: None,
    scopes: vec!["api://lancedb-api/.default".into()],
    flow: OAuthFlow::AzureManagedIdentity {
        // Set to Some("your-user-assigned-identity-client-id".into())
        // only for a user-assigned managed identity.
        client_id: None,
    },
    client_auth_method: None,
    resource: None,
    audience: None,
    refresh_buffer_secs: None,
    token_cache: None,
};

managed_identity_client_id / managedIdentityClientId selects a user-assigned identity. Omit it for a system-assigned identity. The required client_id / clientId field does not select the Azure managed identity. In Rust, set the client_id inside OAuthFlow::AzureManagedIdentity to Some(...) for a user-assigned identity, or None for a system-assigned identity. The top-level OAuthConfig::client_id is the application client ID.

For interactive sign-in, configure Authorization Code or Device Code. The authorization URL or device verification instructions are written to standard error. Authorization Code also tries to open a browser and listens for the callback at http://127.0.0.1:8400/callback by default. Register that redirect URI with your identity provider. Public clients can omit client_secret; request a refresh token from your provider (often by including offline_access) if you want to reuse the session.

from lancedb.remote import OAuthConfig, OAuthFlowType, TokenCacheOptions

# Use DEVICE_CODE for a CLI without a local browser or callback server.
oauth_config = OAuthConfig(
    issuer_url="https://your-issuer.example.com",
    client_id="your-public-client-id",
    scopes=["openid", "offline_access", "lancedb.read"],
    flow=OAuthFlowType.AUTHORIZATION_CODE,
    token_cache=TokenCacheOptions(),
)

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,
)

import * as lancedb from "@lancedb/lancedb";
import { OAuthFlowType, type OAuthConfig } from "@lancedb/lancedb";

// Use OAuthFlowType.DeviceCode for a CLI without a local browser or callback server.
const oauthConfig: OAuthConfig = {
  issuerUrl: "https://your-issuer.example.com",
  clientId: "your-public-client-id",
  scopes: ["openid", "offline_access", "lancedb.read"],
  flow: OAuthFlowType.AuthorizationCode,
  tokenCache: {},
};

const db = await lancedb.connect("db://your-database-uri", {
  region: "us-east-1",
  hostOverride: "https://your-enterprise-endpoint.com",
  oauthConfig,
});

use lancedb::remote::{AuthorizationCodeOptions, OAuthConfig, OAuthFlow, TokenCacheOptions};

// Use OAuthFlow::DeviceCode(Default::default()) for a CLI without a local browser or callback server.
let oauth_config = OAuthConfig {
    issuer_url: "https://your-issuer.example.com".into(),
    client_id: "your-public-client-id".into(),
    client_secret: None,
    scopes: vec![
        "openid".into(),
        "offline_access".into(),
        "lancedb.read".into(),
    ],
    flow: OAuthFlow::AuthorizationCode(AuthorizationCodeOptions::new()),
    client_auth_method: None,
    resource: None,
    audience: None,
    refresh_buffer_secs: None,
    token_cache: Some(TokenCacheOptions::new()),
};

let db = lancedb::connect("db://your-database-uri")
    .region("us-east-1")
    .host_override("https://your-enterprise-endpoint.com")
    .oauth_config(oauth_config.clone())
    .execute()
    .await?;

With DEVICE_CODE / DeviceCode / OAuthFlow::DeviceCode(DeviceCodeOptions::new()), the same configuration and connection calls apply; only the flow value changes.

Device Code sends no PKCE parameters by default. For a provider that requires S256 PKCE on device grants, Rust callers can select OAuthFlow::DeviceCode(DeviceCodeOptions::new().use_pkce(true)) (import DeviceCodeOptions from lancedb::remote). This option is currently Rust-only. Enable it only when the provider supports the extension; a failed PKCE request is not retried without PKCE.

Reuse an interactive session

By default, tokens stay in process memory. Set token_cache / tokenCache for Authorization Code or Device Code to keep refresh tokens across process restarts. Only refresh tokens are persisted; access tokens and client secrets are not written to the cache. Set cache_dir / cacheDir to choose the directory, or leave it unset to use the platform cache directory. Your identity provider must issue a refresh token for a later process to sign in without prompting again.

Use OAuthSession with the same config to log in before connecting, inspect whether a refresh token is cached, or remove the local cached credential:

from lancedb.remote import OAuthSession

session = OAuthSession(oauth_config)
status = await session.login()
print(status.refreshable)
status = await session.status()  # Does not contact the provider.
print(status.refreshable)
logout = await session.logout()
print(logout.removed)

import { OAuthSession } from "@lancedb/lancedb";

const session = new OAuthSession(oauthConfig);
const status = await session.login();
console.log(status.refreshable);
const current = await session.status(); // Does not contact the provider.
console.log(current.refreshable);
const logout = await session.logout();
console.log(logout.removed);

use lancedb::remote::OAuthSession;

let session = OAuthSession::new(oauth_config)?;
let status = session.login().await?;
println!("{}", status.refreshable);
let status = session.status().await?; // Does not contact the provider.
println!("{}", status.refreshable);
let logout = session.logout().await?;
println!("{}", logout.removed);

login() runs the interactive flow even when a session is cached. logout() removes the local cache entry; it does not revoke the provider's token or end a browser sign-in. OAuthSession requires a persistent cache and supports only Authorization Code and Device Code. A cache is unused for Client Credentials and rejected for Azure Managed Identity.

Configuration reference

The shared configuration below is available in all three SDKs; device-code PKCE is a Rust-only option through DeviceCodeOptions. Python and Rust use snake_case field names; TypeScript uses camelCase. In Rust, set optional OAuthConfig fields to Some(value) or None. Configure redirect_uri, callback_port, and use_pkce through the builder methods on AuthorizationCodeOptions, and select a managed identity through OAuthFlow::AzureManagedIdentity { client_id: ... }.

Python field / TypeScript field	Required	Description
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	Yes in Rust; otherwise no	Selects the OAuth flow. Defaults to Client Credentials in Python and TypeScript; Rust requires an explicit OAuthFlow.
client_secret / clientSecret	Conditional	Required for Client Credentials; only required for Authorization Code and Device Code when the provider registers a confidential client. Redacted from the config's repr (Python) and Debug output (Rust and TypeScript native binding).
client_auth_method / clientAuthMethod	No	Token endpoint authentication: ClientAuthMethod.NONE / ClientAuthMethod.None for a public client, ClientAuthMethod.CLIENT_SECRET_BASIC / ClientAuthMethod.ClientSecretBasic, or ClientAuthMethod.CLIENT_SECRET_POST / ClientAuthMethod.ClientSecretPost. Defaults to Basic when a client secret is set and no client authentication otherwise. The secret methods require client_secret / clientSecret. Omit for Azure Managed Identity.
redirect_uri / redirectUri	No	Authorization Code loopback callback URI. Defaults to http://127.0.0.1:{callback_port}/callback; register it with the provider.
callback_port / callbackPort	No	Authorization Code callback server port (default 8400). If redirect_uri / redirectUri has an explicit port, the two ports must match.
use_pkce / usePkce	No	Enable S256 PKCE for Authorization Code (default true).
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.
resource	No	RFC 8707 resource indicator, an absolute URI without a fragment. Sent to authorization and token endpoints, including refresh requests. Not supported for Azure Managed Identity.
audience	No	Provider-specific audience sent to authorization and token endpoints, including refresh requests. Not supported for Azure Managed Identity.
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.
token_cache / tokenCache	No	Opt in to a persistent refresh-token cache for Authorization Code or Device Code. Use TokenCacheOptions() in Python, {} in TypeScript, or Some(TokenCacheOptions::new()) in Rust. Defaults to an in-memory session.

TokenCacheOptions also accepts cache_dir / cacheDir to select a cache directory and lock_timeout_secs / lockTimeoutSecs to set the wait for a cross-process refresh lock (default 30 seconds). In Rust, use the TokenCacheOptions::cache_dir(...) and TokenCacheOptions::lock_timeout_secs(...) builder methods. Token endpoint authentication uses Some(ClientAuthMethod::None), Some(ClientAuthMethod::ClientSecretBasic), or Some(ClientAuthMethod::ClientSecretPost); None selects the default.

注意

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. All three SDKs deliberately omit the secret from their debug/repr output so accidental log lines do not expose the value.

LanceDB Embedded has nothing to authenticate to: your process opens the files directly, and the object store's own credentials are the only gate.