Cloudflare Pages + SSO Setup Guide

Step-by-step guide to deploy your LATTS documentation to Cloudflare Pages with Cloudflare Access authentication.

Overview

This guide provides the exact steps needed to deploy the LATTS internal documentation to Cloudflare Pages with Cloudflare Access authentication for secure team access control.

Prerequisites

  • Admin access to the latts-ie/wiki-internal repository
  • Cloudflare account with domain management
  • The Hugo site is already configured and ready to deploy

Step 1: Set up Cloudflare Pages

1.1 Create Cloudflare Pages Project

  1. Log into Cloudflare Dashboard

  2. Connect to Git Repository

    • Click Create a project → Connect to Git
    • Select GitHub and authorize Cloudflare
    • Choose the latts-ie/wiki-internal repository

  3. Configure Build Settings

    • Project name: latts-internal-docs
    • Production branch: main
    • Build command: hugo --minify --enableGitInfo
    • Build output directory: public
    • Root directory: (leave empty)

  4. Set Environment Variables

    • HUGO_VERSION: 0.131.0
    • NODE_VERSION: 20

  5. Deploy

    • Click Save and Deploy
    • Your site will be available at: https://latts-internal-docs.pages.dev

1.2 Configure Custom Domain (Optional)

  1. Add Custom Domain
    • In your Pages project, go to Custom domains
    • Click Set up a custom domain
    • Enter your domain: docs.latts.ie
    • Follow DNS setup instructions

Step 2: Set up GitHub Actions for Automated Deployment

The repository includes a GitHub Actions workflow that automatically deploys to Cloudflare Pages on every push to main.

2.1 Configure Repository Secrets

  1. Get Cloudflare API Token

    • Go to Cloudflare Dashboard → My Profile → API Tokens
    • Click Create Token → Custom token
    • Permissions:
      • Zone:Zone:Read
      • Zone:Page Rules:Edit
      • Account:Cloudflare Pages:Edit
    • Account Resources: Include All accounts
    • Zone Resources: Include All zones

  2. Get Account ID

    • Go to Cloudflare Dashboard → Overview
    • Copy Account ID from right sidebar

  3. Add Secrets to GitHub

    • Go to repository Settings → Secrets and variables → Actions
    • Add repository secrets:
      • CLOUDFLARE_API_TOKEN: Your API token
      • CLOUDFLARE_ACCOUNT_ID: Your account ID

Step 3: Set up Cloudflare Access Authentication

3.1 Enable Cloudflare Zero Trust

  1. Navigate to Zero Trust

    • In Cloudflare Dashboard, go to Zero Trust
    • Complete the onboarding if first time

  2. Configure Team Domain

    • Set your team domain: latts-team.cloudflareaccess.com
    • This will be used for authentication flows

3.2 Add GitHub as Identity Provider

  1. Create GitHub OAuth App

    • Go to https://github.com/organizations/latts-ie/settings/applications
    • Click New OAuth App
    • Configure:
      • Application name: LATTS Docs - Cloudflare Access
      • Homepage URL: https://docs.latts.ie (or your custom domain)
      • Authorization callback URL: https://latts-team.cloudflareaccess.com/cdn-cgi/access/callback

  2. Configure GitHub in Cloudflare

    • Go to Zero Trust → Settings → Authentication
    • Click Add new → GitHub
    • Configure:
      • App ID: GitHub OAuth App Client ID
      • Client Secret: GitHub OAuth App Client Secret
      • Connection name: GitHub - LATTS Team

3.3 Create Access Application

  1. Add Application

    • Go to Zero Trust → Access → Applications
    • Click Add an application → Self-hosted

  2. Configure Application

    • Application name: LATTS Internal Documentation
    • Subdomain: docs (if using docs.latts.ie)
    • Domain: latts.ie
    • Path: /*

  3. Configure Policies

    • Policy name: LATTS Team Members
    • Action: Allow
    • Rules:
      • Include: GitHub Organizations → latts-ie
    • Click Save

3.4 Advanced Access Control (Optional)

For more granular control, you can add additional policies:

  1. Team-based Access

    Include: GitHub Teams
Teams: latts-ie/developers, latts-ie/documentation-team

  2. Email Domain Restrictions

    Include: Emails ending in
Domains: company.com, latts.ie

  3. Geographic Restrictions

    Include: Country
Countries: Ireland, United Kingdom

Step 4: Configure Site Settings

4.1 Update Hugo Configuration

Update your config.toml for the new domain:

baseURL = 'https://docs.latts.ie/'  # Update to your custom domain

4.2 Add Cloudflare-specific Optimizations

Create static/_headers file for security headers:

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  X-XSS-Protection: 1; mode=block
  Referrer-Policy: strict-origin-when-cross-origin
  Content-Security-Policy: default-src 'self'; img-src 'self' data: https:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; script-src 'self' 'unsafe-inline'; connect-src 'self'

Step 5: Test the Complete Setup

5.1 Verify Deployment

  1. Check Build Status

    • Go to GitHub Actions tab in repository
    • Verify latest workflow completed successfully
    • Check Cloudflare Pages deployments

  2. Test Site Functionality

    • Visit your site URL
    • Verify all pages load correctly
    • Test search functionality
    • Check responsive design

5.2 Test Authentication

  1. Access Control Test

    • Open site in incognito/private window
    • Verify Cloudflare Access challenge appears
    • Test login with GitHub account that’s in latts-ie organization
    • Confirm access is granted

  2. Denied Access Test

    • Test with GitHub account NOT in latts-ie organization
    • Verify access is properly denied

  3. Team Member Access

    • Have multiple team members test access
    • Verify authentication flow works correctly

Step 6: Production Readiness

6.1 Configure Monitoring

  1. Cloudflare Analytics

    • Enable analytics in Cloudflare Pages
    • Monitor page views and performance

  2. Access Logs

    • Go to Zero Trust → Logs
    • Monitor authentication attempts and access patterns

6.2 Set up Alerts

  1. Build Failures

    • Configure GitHub Actions notifications
    • Set up Slack/email alerts for failed deployments

  2. Access Anomalies

    • Set up Cloudflare alerts for unusual access patterns
    • Monitor for failed authentication attempts

Advanced Configuration

Custom Branding

  1. Customize Cloudflare Access Pages
    • Go to Zero Trust → Settings → Custom Pages
    • Upload custom login page
    • Add LATTS branding and colors

Multiple Environments

  1. Staging Environment

    • Create separate Cloudflare Pages project for staging
    • Use different custom domain: docs-staging.latts.ie
    • Configure separate Access application

  2. Preview Deployments

    • Cloudflare Pages automatically creates preview URLs for pull requests
    • Use these for content review before merging

Troubleshooting

Common Issues

Site not building on Cloudflare Pages

  • Check build logs in Cloudflare Pages dashboard
  • Verify Hugo version and Node.js version are set correctly
  • Ensure Git submodules are properly configured

Authentication not working

  • Verify GitHub OAuth app callback URL is correct
  • Check that users are members of latts-ie organization
  • Ensure Access policy includes the correct GitHub organization

Custom domain issues

  • Verify DNS settings are correct
  • Check SSL certificate status in Cloudflare
  • Ensure domain is added to both Pages and Access applications

Debug Commands

# Test site accessibility
curl -I https://docs.latts.ie

# Check DNS resolution
dig docs.latts.ie

# Test authentication endpoint
curl -v https://docs.latts.ie/cdn-cgi/access/get-identity

Cost Considerations

Cloudflare Pages

  • Free tier: 500 builds per month, unlimited bandwidth
  • Pro tier: $20/month for 5,000 builds, advanced features

Cloudflare Access

  • Free tier: Up to 50 users
  • Paid tiers: $3/user/month for unlimited users and advanced features

For the LATTS team size, the free tiers should be sufficient initially.

Maintenance Tasks

Regular (Monthly)

  • Review access logs for unusual activity
  • Update team member access as needed
  • Check site performance metrics

Quarterly

  • Review and rotate API tokens
  • Audit user permissions and access policies
  • Update documentation based on team feedback

Annual

  • Review authentication provider settings
  • Update OAuth application credentials
  • Assess need for paid tier features

Next Steps

After completing this setup:

  1. Train team members on the new authentication flow
  2. Document internal processes for adding/removing team access
  3. Set up content governance workflows using GitHub PRs
  4. Consider additional integrations like Slack notifications
  5. Plan for scaling if team grows beyond free tier limits

See Also

Last modified July 29, 2025: Switch to Cloudflare Pages hosting and Cloudflare Access SSO (ca22e6b)