Skip to content

Backstage GitHub OAuth Validation Checklist

Overview

This checklist validates that GitHub OAuth authentication is properly configured for Backstage.

Prerequisites

  • [ ] Backstage is deployed and running
  • [ ] GitHub OAuth app has been created
  • [ ] OAuth credentials are configured in Kubernetes secrets

Validation Steps

1. Verify OAuth Credentials Secret

# Check secret exists
kubectl get secret backstage-oauth-credentials -n fawkes

# Verify secret has required keys (don't decode values in production)
kubectl get secret backstage-oauth-credentials -n fawkes -o jsonpath='{.data}' | grep -o '"[^"]*"' | head -5

# Expected output should show:
# "github-client-id"
# "github-client-secret"

Expected Result: ✅ Secret exists with both required keys

2. Verify Environment Variables in Backstage Pods

# Check environment variables are set
kubectl exec -n fawkes deployment/backstage -- printenv | grep AUTH_GITHUB

# Expected output:
# AUTH_GITHUB_CLIENT_ID=<your-client-id>
# AUTH_GITHUB_CLIENT_SECRET=<redacted>

Expected Result: ✅ Both environment variables are set and don't contain "CHANGE_ME"

3. Verify App Configuration

# Check app-config has auth section
kubectl get configmap backstage-app-config -n fawkes -o yaml | grep -A 10 "auth:"

# Expected output should include:
# auth:
#   environment: production
#   providers:
#     github:
#       production:
#         clientId: ${AUTH_GITHUB_CLIENT_ID}
#         clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}

Expected Result: ✅ Auth configuration is present with GitHub provider

4. Test OAuth Callback Endpoint

# Get a Backstage pod name
POD_NAME=$(kubectl get pods -n fawkes -l app.kubernetes.io/name=backstage -o jsonpath='{.items[0].metadata.name}')

# Test callback endpoint (should return 404 or 400 without auth code, not 500)
kubectl exec -n fawkes $POD_NAME -- curl -s -o /dev/null -w '%{http_code}' http://localhost:7007/api/auth/github/handler/frame

# Expected: 404 or 400 (not 500 which indicates config error)

Expected Result: ✅ Returns 404 or 400 (endpoint exists but needs auth code)

5. Test Health Check Endpoint

# Verify Backstage is healthy
kubectl exec -n fawkes $POD_NAME -- curl -s http://localhost:7007/healthcheck

# Expected: {"status":"ok"}

Expected Result: ✅ Health check returns OK

6. Verify GitHub OAuth App Configuration

Manually verify in GitHub:

  1. Go to your OAuth app settings:

  2. Personal: https://github.com/settings/developers

  3. Organization: https://github.com/organizations/YOUR_ORG/settings/applications

  4. Check configuration:

  5. [ ] Application name is descriptive (e.g., "Fawkes Backstage - Production")
  6. [ ] Homepage URL matches your Backstage URL
  7. [ ] Authorization callback URL is: https://backstage.fawkes.idp/api/auth/github/handler/frame
  8. [ ] Callback URL uses correct protocol (http for local, https for production)
  9. [ ] Callback URL ends with /api/auth/github/handler/frame

Expected Result: ✅ All OAuth app settings are correct

7. Test Login Flow (Manual)

  1. Access Backstage:
# If using port-forward for local testing:
kubectl port-forward -n fawkes svc/backstage 7007:7007

# Open browser to: http://localhost:7007
# Or for production: https://backstage.fawkes.idp

  1. Verify Login Button:

  2. [ ] "Sign in with GitHub" button is visible on the page

  3. [ ] No error messages are displayed on the login page

  4. Test Authentication:

  5. [ ] Click "Sign in with GitHub"
  6. [ ] Browser redirects to GitHub
  7. [ ] GitHub shows OAuth authorization prompt
  8. [ ] Authorization prompt shows correct app name
  9. [ ] After clicking "Authorize", browser redirects back to Backstage
  10. [ ] User is logged in (username visible in top-right corner)
  11. [ ] No console errors in browser developer tools

Expected Result: ✅ Complete login flow works without errors

8. Test Permissions (Manual)

After logging in:

  1. Access Service Catalog:

  2. [ ] Navigate to "Catalog" section

  3. [ ] Can view catalog entities

  4. [ ] Username/identity is displayed correctly

  5. Test Authenticated Routes:

  6. [ ] Can access all main sections (Catalog, Create, Docs)
  7. [ ] No unexpected "unauthorized" errors

Expected Result: ✅ All routes accessible after authentication

9. Test Logout

  1. Logout:
  2. [ ] Click username in top-right corner
  3. [ ] Click "Sign Out"
  4. [ ] Redirected to login page
  5. [ ] Cannot access protected routes without re-authentication

Expected Result: ✅ Logout works and session is terminated

10. Verify Logs

# Check Backstage logs for auth-related messages
kubectl logs -n fawkes -l app.kubernetes.io/name=backstage --tail=100 | grep -i auth

# Look for successful auth messages, no errors like:
# ❌ "GitHub OAuth configuration error"
# ❌ "Invalid client ID or secret"
# ✅ "GitHub authentication successful"

Expected Result: ✅ No auth errors in logs

Run BDD Acceptance Tests

# Run OAuth authentication tests
cd /home/runner/work/fawkes/fawkes
behave tests/bdd/features/backstage-deployment.feature --tags=@authentication

Expected Result: ✅ All authentication tests pass

Common Issues and Solutions

Issue 1: "Invalid redirect_uri" Error

Symptoms: Error when clicking "Sign in with GitHub"

Diagnosis:

# Check callback URL in secret
kubectl get secret backstage-oauth-credentials -n fawkes -o jsonpath='{.data.github-client-id}' | base64 -d

Solution:

  • Verify callback URL in GitHub OAuth app matches: https://backstage.fawkes.idp/api/auth/github/handler/frame
  • Check protocol (http vs https)
  • Check for trailing slashes
  • Update GitHub OAuth app if needed

Issue 2: "GitHub OAuth configuration error"

Symptoms: Error in logs about OAuth configuration

Diagnosis:

# Check if secrets contain placeholder values
kubectl get secret backstage-oauth-credentials -n fawkes -o yaml | grep CHANGE_ME

Solution:

  • Update secrets with real GitHub OAuth credentials
  • Apply updated secret: kubectl apply -f platform/apps/backstage/secrets.yaml
  • Restart Backstage: kubectl rollout restart deployment/backstage -n fawkes

Issue 3: Login Button Not Visible

Symptoms: No "Sign in with GitHub" button on login page

Diagnosis:

# Check app-config has auth section
kubectl get configmap backstage-app-config -n fawkes -o yaml | grep -A 5 "auth:"

Solution:

  • Verify app-config.yaml has auth.providers.github section
  • Check environment variables are properly injected
  • Restart Backstage pods

Issue 4: 500 Error on Callback

Symptoms: After GitHub authorization, get 500 error

Diagnosis:

# Check Backstage logs for errors
kubectl logs -n fawkes -l app.kubernetes.io/name=backstage --tail=50

Solution:

  • Verify client secret is correct (regenerate if needed)
  • Check database connectivity
  • Ensure all environment variables are set correctly

Success Criteria

All of the following must be true:

  • ✅ OAuth credentials secret exists and is correctly configured
  • ✅ Environment variables are set in Backstage pods
  • ✅ App configuration includes GitHub auth provider
  • ✅ OAuth callback endpoint responds (not 500)
  • ✅ Health check passes
  • ✅ GitHub OAuth app configuration is correct
  • ✅ Login flow completes successfully
  • ✅ User identity is displayed after login
  • ✅ Permissions work correctly
  • ✅ Logout works correctly
  • ✅ No auth errors in logs
  • ✅ BDD tests pass

Sign-Off

  • [ ] Validated by: **____**
  • [ ] Date: **____**
  • [ ] Environment: [ ] Development [ ] Staging [ ] Production
  • [ ] Issues found: **____**
  • [ ] All issues resolved: [ ] Yes [ ] No

References

Last Updated: December 2024