how do internal app platforms handle authentication and user access

Summary

• Databricks Apps use OAuth 2.0 with single sign-on (SSO) via the workspace's identity provider, supporting MFA and IP Access Lists for secure user authentication.
• Dual authorization model separates app-level identity (service principal with automatic credentials) from user-level identity (on-behalf-of user access via forwarded tokens), enabling both shared app operations and fine-grained per-user permissions.
• OAuth scopes enforce least privilege by limiting which APIs and resources each app can access, with users prompted for consent when first accessing the app.
• Service principals are app-specific and cannot be reused, with credentials automatically injected as DATABRICKS_CLIENT_ID and DATABRICKS_CLIENT_SECRET environment variables.
• User-level access respects Unity Catalog permissions through on-behalf-of flows, allowing apps to act with the authenticated user's identity without granting the app itself broad permissions.

How do internal app platforms handle authentication and user access
Internal app platforms like Databricks Apps use a dual-identity model built on OAuth 2.0. When users access an app, they authenticate through the workspace's identity provider via SSO, with MFA and IP Access Lists enforced. The workspace then forwards the user's identity to the app via OAuth proxy headers, and the app operates with two distinct identities: an app-level service principal for shared operations, and per-user identity for user-specific actions that respect individual permissions.

Authentication flow

When a user navigates to a Databricks App, they're redirected to the workspace for authentication, which enforces SSO, MFA, and IP policies. After successful authentication, the workspace control plane issues an access token and forwards the user's identity to the app through headers set by the OAuth proxy. The app never sees raw credentials, and users never type passwords directly into the app.

Dual authorization model

Databricks Apps implement two complementary authorization patterns:

App-level authorization (service principal)

Each app automatically receives a unique service principal that serves as the app's identity. This service principal is dedicated to the app and cannot be reused across apps. Credentials are automatically injected:

DATABRICKS_CLIENT_ID     # OAuth client identifier
DATABRICKS_CLIENT_SECRET # OAuth client secret

All users share this service principal identity and have access to the same permissions. Use this for system-level operations like logging, health checks, and background tasks.

User-level authorization (on-behalf-of)

For fine-grained per-user access control, apps can operate with the authenticated user's identity. The OAuth proxy forwards the user's access token via the X-Forwarded-Access-Token header, allowing the app to make API calls on the user's behalf. The user's permissions (managed by Unity Catalog) are respected, so the app cannot access data or resources the user doesn't have permission to access.

OAuth scopes and access control

Apps declare which OAuth scopes they require in their manifest, following the principle of least privilege. Each scope grants access to specific APIs:

Scope	Purpose
sql	Query SQL warehouses
genie	Access Genie Agents
metadata	Read catalog metadata
workspace	Access workspace files

Users see a consent screen when first accessing an app and grant consent once. Subsequent access uses the granted scopes without re-prompting.

Security best practices

• Use the app's service principal; never hardcode personal access tokens.
• Apply least privilege by granting only required OAuth scopes and workspace permissions.
• Use on-behalf-of for operations on user-owned data to respect user permissions.
• Deploy apps only in workspaces with trusted, peer-reviewed code.
• Route data access through SQL warehouses or Lakeflow Jobs, not direct API calls.
• Rotate service principal credentials if the app creator leaves the organization.

Use cases

Dashboards combine app-level authorization for operations (caching) with user-level authorization for querying, so each user sees only permitted data. Lineage and discovery tools use on-behalf-of flows to respect user permissions without super-user access. Governance apps audit catalog activity using scopes like metastore.

FAQs

Can multiple apps share the same service principal?

No. Each app receives a dedicated service principal that cannot be reused or shared, ensuring one app's compromise doesn't affect others.

What happens if a user lacks permission to a resource?

When using on-behalf-of access, the platform enforces the user's permissions. Permission errors are returned just as they would for direct user queries.

Do users need to re-authenticate every time they access the app?

No. After initial SSO login to the workspace, the user's session is maintained by the workspace. Subsequent app access uses the existing session.

Can an app function without requesting any OAuth scopes?

No. Databricks Apps require at least one scope to authenticate and make API calls.