Databricks · AI Governance

UC HTTP
Connections

Governing External Service Access

Pillar 4: Tool & API Governance
Arrow keys or Space to navigate
01 / 15
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.

02 / 15
Core Concept

Application code never touches credentials

Agent / App
Calls connection
→
UC Connection Proxy
USE CONNECTION check
→
Inject Credential
Server-side only
→
External Service
GitHub, Slack, etc.
App never holds the credential. Databricks injects it at proxy time. REVOKE USE CONNECTION = instant removal. No redeployment needed.
03 / 15
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.
04 / 15
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 requires updating the connection and is manual
Trade-offs
+ Simple setup
+ Works with any API that accepts a static token
- No auto-refresh
- No per-user identity at the external service
- Token expiration requires manual intervention
Token expiration requires manual intervention. Use OAuth methods when the external service supports them.
05 / 15
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.
06 / 15
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.

07 / 15
Auth Method 4

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

Flow
1
User triggers action (query, tool call, agent step)
2
Proxy checks USE CONNECTION grant for current_user()
3
First time: user completes OAuth consent at external provider
4
Per-user refresh token stored, subsequent calls auto-refresh
5
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, SharePoint, and custom OAuth providers.
08 / 15
Decision Framework

Choosing the right method

Need per-user identity at the external service?
Yes
U2M Per User
External service supports OAuth client_credentials?
Yes
OAuth M2M
External service supports OAuth but no client_credentials?
Yes
U2M Shared
Static API key only?
Yes
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.
09 / 15
Prerequisites

Can your provider support U2M?

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

Mandatory requirements
Authorization Code GrantRFC 6749 Section 4.1. User redirected to consent page, provider redirects back with auth code.
Refresh tokensProvider must issue a refresh_token. Scope varies: Google (offline_access), Microsoft (offline_access), Salesforce (refresh_token).
Custom redirect URIsMust allow registering <workspace>/login/oauth/http.html as a redirect URI.
Confidential clientClient ID + Client Secret (not public/PKCE-only clients).
Standard token endpointgrant_type=authorization_code for initial exchange, grant_type=refresh_token for renewal.
HTTPS endpointsAll authorization and token endpoints must be HTTPS.
Credential exchange methods
header_and_bodyDefault. Google, most providers.
body_onlySome custom OAuth servers.
header_onlyOkta, some enterprise IdPs.
Common blockers: No auth code grant (M2M only), no refresh tokens, proprietary auth extensions, admin policy blocking third-party apps, redirect URI domain restrictions.
10 / 15
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.
11 / 15
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.
12 / 15
Gotchas

Common setup errors and fixes

redirect_uri_mismatch
URI must exactly match what the provider expects. No trailing slash. Check the error details page for the exact value the provider received.
admin_policy_enforced
Org admin blocks unauthorized OAuth apps. Allowlist the Client ID in the provider's admin console before attempting consent.
offline_access scope
Required for a refresh token. Without it, the connection works for ~1 hour then fails silently. Always include this scope.
Immutable name
Connection name cannot be changed after creation. Choose carefully. Consumers reference it by name in SQL and tool configs.
Owner access
The creator has irrevocable USE CONNECTION. Transfer ownership to a service principal if you need to control access fully.
MCP flag locked
isMcpConnection cannot be toggled after creation. If you need to change it, delete the connection and recreate it.
13 / 15
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.
14 / 15
Summary

Quick Reference

Details
Auth Methods Bearer Token, OAuth M2M, OAuth U2M Shared, OAuth U2M Per User
Governance Primitive GRANT / REVOKE USE CONNECTION
Redirect URI <workspace-url>/login/oauth/http.html
Provider Prerequisites Authorization code grant, refresh tokens, custom redirect URIs, confidential client, standard token endpoint, HTTPS
Common Gotchas redirect_uri_mismatch, admin_policy_enforced, offline_access scope, immutable name, owner access, MCP flag locked
Network Layer Serverless Network Perimeter (SNP) for FQDN allowlisting
Credential Layer USE CONNECTION for per-identity authorization
UC Connections: centralized credential storage, per-identity authorization, instant revocation.
Reference: github.com/bhavink/applied-ai-governance
15 / 15