Authentication Provider Setup Guides

This document provides setup instructions for each supported authentication provider.

Overview

The Greenfield Cluster supports the following authentication providers:

• Azure AD - Microsoft Azure Active Directory (OIDC)
• Google - Google Workspace / Gmail (OIDC)
• GitHub - GitHub Organizations (OAuth2)
• Okta - Okta SAML via Keycloak broker
• Keycloak - Self-hosted identity provider

Quick Setup Matrix

Azure AD Setup

Prerequisites

• Azure AD tenant
• Admin access to create App Registrations

Step-by-Step

1. Create App Registration

   Azure Portal → Azure Active Directory → App registrations → New registration
   - Name: Greenfield Cluster Auth
   - Supported account types: Single tenant
   - Redirect URI: https://auth.example.com/oauth2/callback
   

2. Note Configuration Values

3. Application (client) ID
4. Directory (tenant) ID

5. Create a client secret in "Certificates & secrets"

6. Configure Groups (Optional)

   App Registration → API permissions → Add permission
   - Microsoft Graph → Application permissions
   - Add: GroupMember.Read.All
   - Grant admin consent
   
   Token configuration → Add groups claim
   - Select: Security groups or All groups
   

7. Deploy to Cluster

   make auth.install PROVIDER=azuread DOMAIN=example.com
   
   # Create secrets
   kubectl create secret generic oauth2-proxy-secret \
     --from-literal=client-id=YOUR_CLIENT_ID \
     --from-literal=client-secret=YOUR_CLIENT_SECRET \
     --from-literal=cookie-secret=$(openssl rand -base64 32 | head -c 32) \
     -n greenfield
   

8. Update Configuration Edit kustomize/base/auth/overlays/provider-azuread/configmap.yaml:

   data:
     oidc-issuer-url: "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0"
     azure-tenant: "YOUR_TENANT_ID"
   

Testing

# Check deployment
kubectl get pods -n greenfield -l app=oauth2-proxy

# Test auth flow
curl -I https://myapp.example.com
# Should redirect to login.microsoftonline.com

Common Issues

• Groups not in token: Check API permissions and token configuration
• Redirect loop: Verify redirect URI matches exactly
• Invalid token: Check tenant ID in issuer URL

Google Setup

Prerequisites

• Google Cloud Project
• Google Workspace (for group support)

Step-by-Step

1. Create OAuth Credentials

   Google Cloud Console → APIs & Services → Credentials
   - Create OAuth 2.0 Client ID
   - Application type: Web application
   - Authorized redirect URIs: https://auth.example.com/oauth2/callback
   

2. Note Configuration Values

3. Client ID (ends with .apps.googleusercontent.com)

4. Client secret

5. Deploy to Cluster

   make auth.install PROVIDER=google DOMAIN=example.com
   
   # Create secrets
   kubectl create secret generic oauth2-proxy-secret \
     --from-literal=client-id=YOUR_CLIENT_ID.apps.googleusercontent.com \
     --from-literal=client-secret=YOUR_CLIENT_SECRET \
     --from-literal=cookie-secret=$(openssl rand -base64 32 | head -c 32) \
     -n greenfield
   

6. Configure Domain Restriction (Optional)

   kubectl set env deployment/oauth2-proxy -n greenfield \
     OAUTH2_PROXY_GOOGLE_GROUP=your-company.com
   

Testing

# Check deployment
kubectl get pods -n greenfield -l app=oauth2-proxy

# Test auth flow
curl -I https://myapp.example.com
# Should redirect to accounts.google.com

Common Issues

• Domain restriction not working: Check OAUTH2_PROXY_GOOGLE_GROUP environment variable
• Groups not supported: Google OIDC doesn't provide groups; use domain restriction or service account

GitHub Setup

Prerequisites

• GitHub Organization (for team support)
• Admin access to create OAuth Apps

Step-by-Step

1. Create OAuth App

   GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
   - Application name: Greenfield Cluster Auth
   - Homepage URL: https://example.com
   - Authorization callback URL: https://auth.example.com/oauth2/callback
   

2. Note Configuration Values

3. Client ID

4. Client secret

5. Deploy to Cluster

   make auth.install PROVIDER=github DOMAIN=example.com
   
   # Create secrets
   kubectl create secret generic oauth2-proxy-secret \
     --from-literal=client-id=YOUR_CLIENT_ID \
     --from-literal=client-secret=YOUR_CLIENT_SECRET \
     --from-literal=cookie-secret=$(openssl rand -base64 32 | head -c 32) \
     -n greenfield
   

6. Configure Organization/Team (Optional) Edit kustomize/base/auth/overlays/provider-github/configmap.yaml:

   data:
     github-org: "your-organization"
     github-team: "team1,team2"  # Optional
   

Testing

# Check deployment
kubectl get pods -n greenfield -l app=oauth2-proxy

# Test auth flow
curl -I https://myapp.example.com
# Should redirect to github.com/login/oauth

Common Issues

• Organization restriction not working: Check OAUTH2_PROXY_GITHUB_ORG environment variable
• Team access denied: Ensure user is member of specified team
• Private org members: User must authorize OAuth app to access private membership

Okta SAML Setup

Prerequisites

• Okta account with admin access
• PostgreSQL database (included in greenfield cluster)

Architecture

This setup uses Keycloak as a broker to convert Okta SAML to OIDC.

Step-by-Step

1. Deploy Keycloak

   make auth.install PROVIDER=okta-saml DOMAIN=example.com
   

2. Create Secrets

   # Keycloak admin
   kubectl create secret generic keycloak-admin-secret \
     --from-literal=password=$(openssl rand -base64 32) \
     -n greenfield
   
   # Keycloak database
   kubectl create secret generic keycloak-db-secret \
     --from-literal=username=keycloak \
     --from-literal=password=$(openssl rand -base64 32) \
     -n greenfield
   
   # oauth2-proxy (client secret will be set later from Keycloak)
   kubectl create secret generic oauth2-proxy-secret \
     --from-literal=client-id=oauth2-proxy \
     --from-literal=client-secret=TEMPORARY \
     --from-literal=cookie-secret=$(openssl rand -base64 32 | head -c 32) \
     -n greenfield
   

3. Configure Okta SAML App

   Okta → Applications → Create App Integration
   - Sign-in method: SAML 2.0
   - App name: Keycloak
   - Single sign on URL: https://keycloak.example.com/auth/realms/master/broker/okta/endpoint
   - Audience URI: https://keycloak.example.com/auth/realms/master
   
   Attribute Statements:
   - email → user.email
   - firstName → user.firstName
   - lastName → user.lastName
   - groups → user.groups (if group support needed)
   

4. Configure Keycloak

   # Access Keycloak admin
   kubectl port-forward -n greenfield svc/keycloak 8080:8080
   # Open http://localhost:8080/auth
   
   # In Keycloak:
   # 1. Add Identity Provider (SAML v2.0)
   #    - Alias: okta
   #    - Service Provider Entity ID: https://keycloak.example.com/auth/realms/master
   #    - Single Sign-On Service URL: (from Okta)
   #    - Upload Okta signing certificate
   #
   # 2. Create OIDC Client
   #    - Client ID: oauth2-proxy
   #    - Access Type: confidential
   #    - Valid Redirect URIs: https://auth.example.com/oauth2/callback
   #    - Copy client secret
   #
   # 3. Configure Mappers
   #    - Add group membership mapper
   #    - Add SAML attribute mappers
   

5. Update oauth2-proxy Secret

   # Update with Keycloak client secret
   kubectl patch secret oauth2-proxy-secret -n greenfield \
     --type='json' \
     -p='[{"op":"replace","path":"/data/client-secret","value":"'$(echo -n KEYCLOAK_CLIENT_SECRET | base64)'"}]'
   

Testing

# Check deployments
kubectl get pods -n greenfield -l app=keycloak
kubectl get pods -n greenfield -l app=oauth2-proxy

# Test auth flow
curl -I https://myapp.example.com
# Should redirect to Keycloak, which redirects to Okta

Common Issues

• SAML assertion failed: Check certificate, SSO URL, Entity ID
• Groups not in token: Configure SAML attribute mapper and group mapper
• Redirect loop: Verify all URLs match (Okta, Keycloak, oauth2-proxy)

Keycloak as Primary IdP

Prerequisites

• PostgreSQL database (included in greenfield cluster)

Step-by-Step

1. Deploy Keycloak

   kubectl apply -k kustomize/base/auth/overlays/keycloak-enabled/
   

2. Create Secrets

   kubectl create secret generic keycloak-admin-secret \
     --from-literal=password=$(openssl rand -base64 32) \
     -n greenfield
   
   kubectl create secret generic keycloak-db-secret \
     --from-literal=username=keycloak \
     --from-literal=password=$(openssl rand -base64 32) \
     -n greenfield
   

3. Access Admin Console

   kubectl port-forward -n greenfield svc/keycloak 8080:8080
   # Open http://localhost:8080/auth
   

4. Configure Realms and Clients

5. Create application-specific realms
6. Configure OIDC clients
7. Set up user federation (LDAP, AD)
8. Configure identity brokering

Testing

# Check deployment
kubectl get pods -n greenfield -l app=keycloak

# Test realm availability
curl https://keycloak.example.com/auth/realms/master/.well-known/openid-configuration

Next Steps

After provider setup:

1. Protect an Application

   make auth.protect APP=myapp HOST=myapp.example.com POLICY=group:developers
   

2. Verify Configuration

   make auth.doctor
   

3. Review Documentation

4. Architecture
5. Troubleshooting
6. App Templates