Documenting Auth

Every application EGI builds will eventually be handed off to Anchor MSP for ongoing management and support. Clear authentication documentation is essential to that handoff. If Anchor cannot understand how auth works in a system, they cannot manage it safely. This document defines what must be documented, the required template, and the standards for auth documentation.

Why Auth Documentation Matters

Authentication is one of the most common sources of incidents in managed applications:

• Token expiration causing unexpected logouts or service failures
• Misconfigured redirect URIs after domain changes
• Unclear role structures leading to privilege escalation
• Lost or undocumented service account credentials
• Inability to rotate secrets without understanding dependencies

Proper documentation prevents all of these. It is not optional.

When to Document

Auth documentation must be created or updated at the following points:

Trigger	Action
Initial auth implementation	Create the auth documentation using the template below
Auth flow changes	Update the documentation before merging the PR
Provider changes (e.g., switching from Google to GitHub auth)	Rewrite the affected sections
Role or permission changes	Update the roles and permissions table
Pre-handoff to Anchor	Review and finalize all auth documentation
Post-incident (auth-related)	Update documentation to reflect any changes made during incident response

Required Information

Every auth documentation package must include the following:

1. Authentication Provider

• Provider name: (e.g., Google OAuth, GitHub OAuth, custom email/password)
• Library/framework: (e.g., NextAuth.js, custom implementation, Auth0)
• Provider configuration location: (e.g., environment variables, admin dashboard URL)
• Client ID and secret location: (which environment variable names, which secret store)

2. Authentication Flow

• Flow type: (e.g., OAuth 2.0 Authorization Code with PKCE, API key, session-based)
• Step-by-step description: What happens from the user's perspective and from the server's perspective
• Redirect URIs: All configured redirect URIs for each environment (development, staging, production)
• Scopes requested: What permissions the application requests from the provider

3. Token Management

• Token type: (e.g., JWT, opaque session token, API key)
• Storage location: (e.g., httpOnly cookie, server-side session store, database)
• Access token lifetime: (e.g., 15 minutes, 1 hour)
• Refresh token lifetime: (e.g., 7 days, 30 days)
• Refresh mechanism: How tokens are refreshed (automatic, manual, sliding window)

4. Roles and Permissions

• Role definitions: List of all roles in the system and what each role can do
• How roles are assigned: (e.g., database field, provider claim, admin panel)
• Default role for new users: What permissions a newly registered user receives
• Admin escalation path: How to grant admin access and who can do it

5. Environment Configuration

• Required environment variables: List every auth-related environment variable with its purpose (not its value)
• Differences by environment: Any configuration that differs between development, staging, and production
• Secrets rotation procedure: How to rotate each secret without downtime

Auth Documentation Template

Use this template for every project. Store it in the project repository at /docs/auth.md or in the relevant section of the project's documentation.

# Authentication Documentation - [Project Name]

## Overview
Brief description of the auth system and its purpose.

## Provider
- **Provider:** [e.g., Google OAuth via NextAuth.js]
- **Library:** [e.g., next-auth@4.x with Prisma adapter]
- **Configuration:** [e.g., /app/api/auth/[...nextauth]/route.ts]

## Authentication Flow
1. [Step-by-step description]
2. [...]

## Redirect URIs
| Environment | URI |
|---|---|
| Development | http://localhost:3000/api/auth/callback/google |
| Staging | https://staging.project.com/api/auth/callback/google |
| Production | https://project.com/api/auth/callback/google |

## Scopes
- [e.g., openid, email, profile]

## Token Management
- **Type:** [e.g., JWT stored in httpOnly cookie]
- **Access token lifetime:** [e.g., 1 hour]
- **Refresh token lifetime:** [e.g., 30 days]
- **Refresh mechanism:** [e.g., Automatic via NextAuth.js session callback]

## Roles and Permissions
| Role | Permissions | Assignment Method |
|---|---|---|
| User | [list] | Default on registration |
| Admin | [list] | Manual via database |

## Environment Variables
| Variable | Purpose | Sensitive |
|---|---|---|
| GOOGLE_CLIENT_ID | OAuth client identifier | Yes |
| GOOGLE_CLIENT_SECRET | OAuth client secret | Yes |
| NEXTAUTH_SECRET | Session encryption key | Yes |
| NEXTAUTH_URL | Application base URL | No |

## Secrets Rotation
- **GOOGLE_CLIENT_SECRET:** Rotate via Google Cloud Console; update env var; redeploy
- **NEXTAUTH_SECRET:** Generate new value; update env var; redeploy (will invalidate active sessions)

## Known Issues / Notes
- [Any auth-related quirks, known issues, or technical debt]

Handoff Checklist

Before handing a project to Anchor, confirm the following:

• Auth documentation exists and follows the template above
• All environment variables are listed with their purpose
• Redirect URIs are documented for every environment
• Role definitions are complete and accurate
• Secrets rotation procedure is documented and tested
• The Anchor team has reviewed the documentation and confirmed understanding
• At least one Anchor team member has been granted admin access to the auth provider dashboard

Quality Standards

• Auth documentation must be reviewed by at least one other EGI team member before handoff
• Do not include actual secret values in documentation (only variable names and descriptions)
• Keep documentation in sync with the code; stale auth documentation is dangerous
• Use concrete examples and exact configuration paths, not vague references