UC HTTP Connections

Governing External Service Access

Pillar 4: Tool & API Governance

Agenda

What we’ll cover

The problem — credential sprawl and no centralized on/off switch for agent-to-API calls

What — the UC connection proxy model and four authentication methods

Why — centralized credential storage, instant revocation, defense in depth

How — setup steps, provider prerequisites, GRANT/REVOKE USE CONNECTION, common gotchas

The Challenge

Your agents call external APIs. Who controls that traffic?

Credential sprawl

API keys scattered across env vars, app code, and CI pipelines. Every rotation means redeploying every consumer. No single inventory of who holds what credential, or when it expires.

Authorization gap

Any agent that can reach the network can call any external API. There is no centralized on/off switch. Revoking access means hunting down every place the credential was copied.

Core Concept

Application code never touches credentials

Agent / AppCalls connection

→

UC Connection ProxyUSE CONNECTION check

→

Inject CredentialServer-side only

→

External ServiceGitHub, Slack, etc.

App never holds the credential. Databricks injects it at proxy time. REVOKE USE CONNECTION = instant removal. No redeployment needed.

Overview

Four authentication methods, one governance model

Method	External Identity	Credential Lifecycle	Best For
Bearer Token	Shared (static token)	Manual rotation	Simple APIs
OAuth M2M	Shared (service/app)	Auto-refresh	Service-to-service
OAuth U2M Shared	Shared (one user’s token)	Auto-refresh	OAuth without M2M support
OAuth U2M Per User	Per user (individual token)	Auto-refresh per user	User-scoped data

All four enforce USE CONNECTION on the Databricks side. The auth method determines how the external credential is obtained; USE CONNECTION determines who is allowed to use it. All OAuth methods require RFC 6750 compliance from the external service. DCR and U2M Per User cannot use the SQL http_request() function; use the Python SDK or a proxy endpoint instead.

Auth Method 1

Bearer Token: simple, static, shared

How it works

Store an API key or static token in the connection
All callers with USE CONNECTION share the same credential
Databricks injects the token into the Authorization header at proxy time
Rotation is manual; requires connection update

Trade-offs

+ Simple setup
+ Works with any API that accepts static tokens
- No auto-refresh
- No per-user identity at external service
- Manual rotation on expiration

Expiration requires manual intervention. Prefer OAuth methods when the external service supports them. Monitor token lifecycle closely.

Auth Method 2

OAuth M2M: service-to-service, auto-refresh

How it works

Uses client_credentials grant type
Databricks stores the Client ID and Client Secret
Tokens are refreshed automatically before expiration
All callers share the same service identity at the external provider

Trade-offs

+ Auto-refresh, no manual rotation
+ Standard OAuth, widely supported
+ No user interaction required
- Shared identity, no per-user tracking at external service
- External service must support client_credentials

Recommended over Bearer Token when the external service supports OAuth. Eliminates manual rotation entirely.

Auth Method 3

OAuth U2M Shared: one user authorizes for all

How it works

One user completes the OAuth consent flow
Their refresh token is stored in the connection
All callers with USE CONNECTION share this single user’s token
Databricks auto-refreshes using the stored refresh token

Risk

Single point of failure. If the authorizing user leaves the organization, revokes consent, or changes their password, the connection breaks for every consumer. Recovery requires a new user to re-authorize.

When to use

External service supports OAuth but does not support the client_credentials grant. U2M Shared is a fallback when M2M is unavailable.

Auth Method 4

OAuth U2M Per User: true end-to-end identity

Flow

1

User triggers action

Query, tool call, or agent step

2

Proxy checks the grant

USE CONNECTION grant for current_user()

3

First-time consent

User completes OAuth consent at the external provider

4

Per-user token stored

Subsequent calls auto-refresh

5

Individual identity at the service

External service receives the individual user’s token

Why it matters

Databricks side	`current_user()` identity preserved
External side	Individual user’s OAuth token
User leaves	Only their access breaks, others unaffected
Audit	Per-user attribution at both layers

Supported providers: Google (Drive, Docs, Gmail, Calendar), GitHub, Glean, Microsoft 365, and custom OAuth providers. For many providers, Databricks manages OAuth credentials in the backend — no manual app registration required.

Advanced: Dynamic Client Registration (RFC 7591) — when the external OAuth server supports it, you provide only the host URL and Databricks discovers the OAuth endpoints, registers the client, and manages per-user consent automatically. This is the recommended auth method for MCP servers that support DCR. Zero manual OAuth setup required.

Why it matters

The business case for the proxy model

Operational velocity

REVOKE USE CONNECTION removes access instantly, no redeployment needed. Without it, revoking a leaked credential means hunting down every place it was copied and redeploying every consumer.

Risk reduction

The credential never leaves storage — it’s injected server-side at proxy time. Serverless Network Perimeter (SNP) and USE CONNECTION are two independent layers: reachability and authorization. Neither alone is sufficient.

Audit and compliance

SHOW GRANTS ON CONNECTION gives a queryable inventory of exactly who can use which connection — centralized credential storage, per-identity authorization, instant revocation.

Decision Framework

Choosing the right method

Condition	Method
Need per-user identity at the external service?	U2M Per User
External service supports OAuth `client_credentials`?	OAuth M2M
External service supports OAuth but no `client_credentials`?	U2M Shared
Static API key only?	Bearer Token

Start from the top. The first “Yes” is your method. U2M Per User gives the strongest governance posture but requires external OAuth support and per-user consent.

Prerequisites

Can your provider support U2M?

Six requirements, service-agnostic. If all six are yes, it works with UC HTTP connections.

Mandatory requirements

RFC 6750 compliance	OAuth responses must use standard fields: `access_token`, `expires_in`, `token_type`. Non-compliant services will fail.
Authorization Code Grant	RFC 6749 Section 4.1. User redirected to consent, provider redirects back with auth code.
Refresh tokens	Provider must issue `refresh_token`. Include required scope per provider: Google (`offline_access`), Microsoft (`offline_access`).
Custom redirect URIs	Must allow registering `<workspace>/login/oauth/http.html` as a redirect URI.
Confidential client	Client ID + Client Secret (not public/PKCE-only clients).
HTTPS endpoints	All authorization and token endpoints must be HTTPS.

Credential exchange methods

`header_and_body`	Default. Google, most providers.
`body_only`	Some custom OAuth servers.
`header_only`	Okta, some enterprise IdPs.

Common blockers: Non-standard OAuth responses, no auth code grant, no refresh tokens, proprietary extensions, admin policies blocking third-party apps, redirect URI restrictions.

Implementation

Setting up a U2M connection

External OAuth Provider

1

Create an OAuth client (application registration)

2

Add redirect URI: <workspace-url>/login/oauth/http.html

3

Enable required APIs and scopes (include offline_access)

4

Configure consent screen (internal or external)

Databricks

1

Create HTTP connection (Catalog Explorer or SQL)

2

Enter host, authorization endpoint, token endpoint

3

Enter Client ID and Client Secret from the OAuth provider

4

Click “Sign in with HTTP” to complete the consent flow

Redirect URI pattern: <workspace-url>/login/oauth/http.html. Must match exactly, no trailing slash.

Deep Dive

The redirect URI handshake

1

User clicks “Sign in with HTTP” in Databricks connection UI

2

Databricks redirects browser to the external provider’s authorization endpoint

3

User reviews and grants consent at the external provider’s consent screen

4

External provider redirects back to <workspace>/login/oauth/http.html with an auth code

5

Databricks exchanges the auth code for access + refresh tokens (server-side)

6

Connection is active. Subsequent calls auto-refresh using the stored refresh token.

The offline_access scope is required to obtain a refresh token. Without it, the connection works for approximately one hour, then fails silently when the access token expires.

Gotchas

Common setup errors and fixes

`redirect_uri_mismatch`

URI must exactly match the provider’s expectation. No trailing slash, no extra spaces. Check error details for the exact value received.

`offline_access` scope

Required for refresh tokens. Without it, the connection works ~1 hour then fails silently. Verify the scope is enabled and requested.

`admin_policy_enforced`

Org admin blocks unauthorized apps. Allowlist the Client ID in the provider’s admin console before attempting consent.

Immutable name

Connection name cannot be changed post-creation. Choose carefully. Consumers reference it by name in SQL and tool configurations.

Owner irrevocable access

Creator has permanent USE CONNECTION. Transfer ownership to a service principal for full GRANT/REVOKE control.

MCP flag locked

isMcpConnection flag is immutable. If you need to change it, delete and recreate the connection.

Governance

GRANT USE CONNECTION: the on/off switch

SQL Examples

-- Grant access
GRANT USE CONNECTION
  ON CONNECTION my_github_conn
  TO `data-engineering`;

-- Revoke access
REVOKE USE CONNECTION
  ON CONNECTION my_github_conn
  FROM `data-engineering`;

-- Audit grants
SHOW GRANTS
  ON CONNECTION my_github_conn;

Defense in Depth

Layer 1: Network (SNP)

Serverless Network Perimeter controls which FQDNs are reachable at the network layer. Blocks egress regardless of caller.

Layer 2: Credential (USE CONNECTION)

Even if the host is reachable, the caller needs a USE CONNECTION grant to get credentials injected. No grant = 403, credential never leaves storage.

Combined: SNP controls which destinations are reachable. USE CONNECTION controls which identities can authenticate. Neither alone is sufficient; together they form a complete egress governance layer.

Reference: docs.databricks.com, learn.microsoft.com/en-us/azure/databricks/

ONE PROXY. FOUR METHODS. ZERO EXPOSED CREDENTIALS.

The credential never leaves storage. USE CONNECTION is the only switch.

Databricks Applied AI Governance Series · UC Connections

→ / Space	Next slide
←	Previous slide
Home	First slide
End	Last slide
Swipe	Touch navigation

Navigation

UC HTTP Connections

What we’ll cover

Your agents call external APIs. Who controls that traffic?

Credential sprawl

Authorization gap

Application code never touches credentials

Four authentication methods, one governance model

Bearer Token: simple, static, shared

OAuth M2M: service-to-service, auto-refresh

OAuth U2M Shared: one user authorizes for all

OAuth U2M Per User: true end-to-end identity

The business case for the proxy model

Operational velocity

Risk reduction

Audit and compliance

Choosing the right method

Can your provider support U2M?

Setting up a U2M connection

The redirect URI handshake

Common setup errors and fixes

redirect_uri_mismatch

offline_access scope

admin_policy_enforced

Immutable name

Owner irrevocable access

MCP flag locked

GRANT USE CONNECTION: the on/off switch

Layer 1: Network (SNP)

Layer 2: Credential (USE CONNECTION)

`redirect_uri_mismatch`

`offline_access` scope

`admin_policy_enforced`