This document describes the OAuth2 and OpenID Connect (OIDC) authentication implementation for Docling Pipelines.
The authentication system supports:
The following packages are already included in requirements.txt:
httpx>=0.28.1 - HTTP client for OAuth2 requestspython-jose[cryptography] - JWT token handlingpydantic-settings>=2.12.0 - Configuration managementfastapi>=0.128.8 - Web frameworkCopy .env.oauth2.example to .env and configure:
cp .env.oauth2.example .env
OAUTH2_ENABLED=true
OAUTH2_PROVIDER=google
OAUTH2_CLIENT_ID=your-client-id.apps.googleusercontent.com
OAUTH2_CLIENT_SECRET=your-client-secret
OAUTH2_REDIRECT_URI=http://localhost:8000/auth/oauth2/callback
JWT_SECRET_KEY=your-jwt-secret-key
Setup Steps:
http://localhost:8000/auth/oauth2/callbackOAUTH2_ENABLED=true
OAUTH2_PROVIDER=azure
AZURE_TENANT_ID=your-tenant-id
OAUTH2_CLIENT_ID=your-application-id
OAUTH2_CLIENT_SECRET=your-client-secret
OAUTH2_REDIRECT_URI=http://localhost:8000/auth/oauth2/callback
JWT_SECRET_KEY=your-jwt-secret-key
Setup Steps:
http://localhost:8000/auth/oauth2/callbackOAUTH2_ENABLED=true
OAUTH2_PROVIDER=generic
OAUTH2_DISCOVERY_URL=https://your-provider.com/.well-known/openid-configuration
OAUTH2_CLIENT_ID=your-client-id
OAUTH2_CLIENT_SECRET=your-client-secret
OAUTH2_REDIRECT_URI=http://localhost:8000/auth/oauth2/callback
OIDC_ISSUER=https://your-provider.com
OIDC_AUDIENCE=your-client-id
JWT_SECRET_KEY=your-jwt-secret-key
GET /auth/oauth2/authorize?provider=google
Redirects to OAuth2 provider’s authorization page.
Query Parameters:
provider (optional): Provider name (google, azure, generic)redirect_after (optional): URL to redirect after successful loginGET /auth/oauth2/callback?code=xxx&state=xxx&provider=google
Handles OAuth2 callback and exchanges code for token.
Response:
{
"access_token": "ey...",
"token_type": "bearer"
}
GET /auth/oauth2/providers
Returns list of configured OAuth2 providers.
GET /auth/oauth2/discovery/{provider}
Returns OIDC discovery document for a provider.
GET /auth/me
Authorization: Bearer <token>
Returns current authenticated user information.
GET /protected
Authorization: Bearer <token>
Example protected endpoint requiring authentication.
import httpx
# Step 1: Redirect user to authorization URL
auth_url = "http://localhost:8000/auth/oauth2/authorize?provider=google"
# Step 2: User completes OAuth2 flow in browser
# User is redirected to /auth/oauth2/callback with code and state
# Step 3: Use the returned access token
token = "eyJ..."
# Step 4: Make authenticated requests
async with httpx.AsyncClient() as client:
response = await client.get(
"http://localhost:8000/auth/me",
headers={"Authorization": f"Bearer {token}"}
)
user = response.json()
print(f"Logged in as: {user['username']}")
# Step 1: Get authorization URL (open in browser)
curl http://localhost:8000/auth/oauth2/authorize?provider=google
# Step 2: After OAuth2 flow, you'll receive a token
TOKEN="your-access-token-here"
# Step 3: Use token to access protected endpoints
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8000/auth/me
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8000/protected
oauth2_config.py)
oauth2_provider.py)
oauth2_routes.py)
dependencies.py)
1. User → GET /auth/oauth2/authorize
2. Server → Redirect to OAuth2 Provider
3. User → Authenticates with Provider
4. Provider → Redirect to /auth/oauth2/callback?code=xxx&state=xxx
5. Server → Exchange code for tokens
6. Server → Validate ID token
7. Server → Extract user info
8. Server → Create JWT token
9. Server → Return JWT to user
10. User → Use JWT for API requests
OAUTH2_REDIRECT_URI=https://your-domain.com/auth/oauth2/callback
python -c "import secrets; print(secrets.token_urlsafe(32))"
State Storage: Use Redis or database for state storage in production
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
OAUTH2_SESSION_EXPIRE_MINUTES=60
CORS_ORIGINS=https://your-frontend.com