Configure GitHub and Microsoft Entra ID authentication.
Flux Orchestrator supports optional OAuth authentication via GitHub or Microsoft Entra (Azure AD). This guide walks through the setup process for both providers.
OAuth authentication is optional and disabled by default. When disabled, the application runs in open mode with no authentication required. When enabled, users must authenticate with the configured OAuth provider before accessing the application.
┌─────────┐ ┌──────────────┐ ┌─────────────┐
│ Browser │─────▶│ Flux Orch. │─────▶│ OAuth │
│ │◀─────│ Backend │◀─────│ Provider │
└─────────┘ └──────────────┘ └─────────────┘
(Session Store) (GitHub/Entra)
Flow:
http://localhost:8080 (or your production URL)http://localhost:8080/api/v1/auth/callback# Enable OAuth
OAUTH_ENABLED=true
OAUTH_PROVIDER=github
# GitHub OAuth credentials
OAUTH_CLIENT_ID=your_github_client_id_here
OAUTH_CLIENT_SECRET=your_github_client_secret_here
OAUTH_REDIRECT_URL=http://localhost:8080/api/v1/auth/callback
# Scopes (GitHub)
OAUTH_SCOPES=read:user,user:email
# Optional: Restrict to specific users
OAUTH_ALLOWED_USERS=user1@example.com,user2@example.com
http://localhost:8080/api/v1/auth/callbackUser.Read (allows reading basic user profile)email (allows reading user email)openid (OpenID Connect sign-in)profile (allows reading basic profile)# Enable OAuth
OAUTH_ENABLED=true
OAUTH_PROVIDER=entra
# Entra OAuth credentials
OAUTH_CLIENT_ID=your_entra_application_id_here
OAUTH_CLIENT_SECRET=your_entra_client_secret_here
OAUTH_REDIRECT_URL=http://localhost:8080/api/v1/auth/callback
# Scopes (Entra)
OAUTH_SCOPES=openid,profile,email
# Optional: Restrict to specific users
OAUTH_ALLOWED_USERS=user1@contoso.com,user2@contoso.com
OAUTH_REDIRECT_URL to use https://.env files with real credentials to version controlOAUTH_ALLOWED_USERS to limit access to specific usersapiVersion: v1
kind: Secret
metadata:
name: flux-orchestrator-oauth
type: Opaque
stringData:
oauth-client-id: "your_client_id"
oauth-client-secret: "your_client_secret"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: flux-orchestrator
spec:
template:
spec:
containers:
- name: flux-orchestrator
image: flux-orchestrator:latest
env:
- name: OAUTH_ENABLED
value: "true"
- name: OAUTH_PROVIDER
value: "github" # or "entra"
- name: OAUTH_CLIENT_ID
valueFrom:
secretKeyRef:
name: flux-orchestrator-oauth
key: oauth-client-id
- name: OAUTH_CLIENT_SECRET
valueFrom:
secretKeyRef:
name: flux-orchestrator-oauth
key: oauth-client-secret
- name: OAUTH_REDIRECT_URL
value: "https://flux-orchestrator.example.com/api/v1/auth/callback"
- name: OAUTH_SCOPES
value: "read:user,user:email"
- name: OAUTH_ALLOWED_USERS
value: "admin@example.com,ops@example.com"
version: '3.8'
services:
flux-orchestrator:
image: flux-orchestrator:latest
environment:
OAUTH_ENABLED: "true"
OAUTH_PROVIDER: "github"
OAUTH_CLIENT_ID: "${OAUTH_CLIENT_ID}"
OAUTH_CLIENT_SECRET: "${OAUTH_CLIENT_SECRET}"
OAUTH_REDIRECT_URL: "http://localhost:8080/api/v1/auth/callback"
OAUTH_SCOPES: "read:user,user:email"
OAUTH_ALLOWED_USERS: "user1@example.com,user2@example.com"
ports:
- "8080:8080"
.env:
cp .env.example .env
# Edit .env with your OAuth credentials
make run # or docker-compose up
http://localhost:8080Check the auth status endpoint:
curl http://localhost:8080/api/v1/auth/status
# Response: {"enabled":true}
Check current user (requires authentication):
curl -b cookies.txt http://localhost:8080/api/v1/auth/me
# Response: {"id":"123","email":"user@example.com","name":"User Name","username":"username","provider":"github"}
Cause: State parameter mismatch (possible CSRF attack or cookie issues)
Solution:
OAUTH_REDIRECT_URL matches exactly with the registered callback URLCause: Invalid client credentials or authorization code
Solution:
OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET are correctCause: User email not in OAUTH_ALLOWED_USERS list
Solution:
OAUTH_ALLOWED_USERSOAUTH_ALLOWED_USERS to allow all users from the providerCause: System clock skew or incorrect session expiration
Solution:
Cause: Frontend and backend URL mismatch
Solution:
OAUTH_REDIRECT_URL points to the backend API endpointEnable verbose logging by checking application logs:
docker logs flux-orchestrator -f
Look for OAuth-related log messages:
OAuth enabled with provider: githubOAuth token exchange failed: ...Failed to get user info: ...User not allowed: ...To disable OAuth and run in open mode:
OAUTH_ENABLED=false
Or simply omit the OAUTH_ENABLED variable (defaults to false).
GET /api/v1/auth/statusCheck if authentication is enabled.
Response:
{
"enabled": true
}
GET /api/v1/auth/loginInitiate OAuth login flow. Redirects to OAuth provider.
GET /api/v1/auth/callbackOAuth callback endpoint. Handles authorization code exchange.
Query Parameters:
code: Authorization code from OAuth providerstate: CSRF protection state parameterGET /api/v1/auth/meGet current authenticated user information.
Response:
{
"id": "123456",
"email": "user@example.com",
"name": "User Name",
"username": "username",
"provider": "github"
}
POST /api/v1/auth/logoutLogout current user and invalidate session.
Response:
{
"message": "Logged out successfully"
}
session_token (HttpOnly, SameSite=Lax)The current implementation uses in-memory session storage. For production deployments with multiple replicas, consider:
Secure: true with HTTPSOAUTH_ALLOWED_USERS for sensitive environmentsFor issues or questions: