Authentication

QBITEL Bridge supports multiple authentication methods: API keys for programmatic access, JWT tokens for user sessions, mTLS for service-to-service communication, and OIDC for enterprise SSO.

Authentication Methods

Method Use Case Security Level
API Key Programmatic API access Standard
JWT Token User session authentication Standard
mTLS Service-to-service communication High
OIDC / SSO Enterprise user authentication Enterprise

API Key Authentication

Include the API key in the X-API-Key header:

curl -H "X-API-Key: your_api_key_here" \
  http://localhost:8000/api/v1/discover

Generate an API Key

# Generate via the management API
curl -X POST http://localhost:8000/api/v1/auth/api-keys \
  -H "Authorization: Bearer admin_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-integration",
    "scopes": ["discovery:read", "discovery:write"],
    "expires_in_days": 90
  }'

Rotate API Keys

API keys can be rotated manually or automatically via the secrets rotation script:

python scripts/rotate_secrets.py --type api-key --key-id key_12345

JWT Token Authentication

Include the JWT token in the Authorization header:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  http://localhost:8000/api/v1/discover

Obtain a JWT Token

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your_password"
  }'

# Response:
# {
#   "access_token": "eyJhbGci...",
#   "token_type": "bearer",
#   "expires_in": 3600
# }

JWT Configuration

Variable Description
QBITEL_JWT_SECRET Secret key for token signing (fallback: JWT_SECRET)
JWT_ALGORITHM Signing algorithm (default: HS256)
JWT_EXPIRATION Token expiration time in seconds (default: 3600)

Mutual TLS (mTLS)

For service-to-service communication, enable mTLS to verify both client and server identities:

# Enable mTLS
export MTLS_ENABLED=true
export MTLS_CA_CERT=/path/to/ca.pem
export MTLS_SERVER_CERT=/path/to/server-cert.pem
export MTLS_SERVER_KEY=/path/to/server-key.pem

# Connect with client certificate
curl --cert client-cert.pem --key client-key.pem --cacert ca.pem \
  https://qbitel-engine:8000/health

Enterprise SSO (OIDC)

The UI Console supports OpenID Connect (OIDC) for enterprise SSO integration:

Provider Status
Okta Supported
Azure AD Supported
Keycloak Supported
Auth0 Supported

Configure OIDC in the UI Console .env:

VITE_OIDC_AUTHORITY=https://auth.example.com
VITE_OIDC_CLIENT_ID=qbitel-console
VITE_OIDC_REDIRECT_URI=http://localhost:3000/callback
VITE_OIDC_SCOPE=openid profile email

Role-Based Access Control

QBITEL Bridge supports RBAC with the following default roles:

Role Permissions
admin Full access to all endpoints and settings
analyst Read/write access to discovery and security
viewer Read-only access to dashboards and reports
api-client API access with configured scopes

Next Steps