Skills
skills/olino3/forge/oauth-integrations

oauth-integrations

SKILL.md

skill:oauth-integrations - OAuth 2.0 Provider Integrations

Version: 1.0.0

Purpose

Implements OAuth 2.0 authentication with multiple providers: GitHub, Okta, Google, and Microsoft Entra (Azure AD). This skill covers the full OAuth 2.0 lifecycle: Authorization Code Flow, PKCE (Proof Key for Code Exchange), token exchange, refresh tokens, scope management, and provider-specific quirks.

Use this skill when:

  • Implementing OAuth 2.0 authentication with GitHub, Okta, Google, or Microsoft Entra
  • Setting up Authorization Code Flow with or without PKCE
  • Configuring callback handling and token exchange
  • Managing token storage, refresh, and revocation
  • Handling provider-specific scope configuration and consent flows
  • Implementing multi-provider authentication in a single application
  • Setting up OIDC (OpenID Connect) for identity verification

What it produces:

  • OAuth 2.0 provider configuration and client registration guidance
  • Authorization Code Flow implementation with PKCE support
  • Callback route handlers for token exchange
  • Token storage and refresh logic (access tokens, refresh tokens, ID tokens)
  • Scope configuration per provider
  • State parameter CSRF protection
  • Error handling for OAuth failure scenarios
  • Multi-provider authentication architecture

Triggers: oauth, oauth2, oauth integration, github oauth, okta auth, google oauth, microsoft entra, azure ad oauth

Provider-Specific Details

GitHub

  • OAuth App vs GitHub App: OAuth Apps for user-level access; GitHub Apps for org/repo-level with fine-grained permissions
  • User and org scopes: user, repo, read:org, admin:org, gist, notifications
  • Device flow: For CLI tools and devices without browsers (urn:ietf:params:oauth:grant-type:device_code)
  • Quirks: Access tokens don't expire by default (OAuth Apps); GitHub Apps use installation tokens with 1-hour TTL

Okta

  • Authorization Server configuration: Default (/oauth2/default) vs custom authorization servers
  • Custom scopes: Define and manage custom scopes in Okta Admin Console
  • OIDC: Full OpenID Connect support with ID tokens, UserInfo endpoint, and claims mapping
  • Quirks: Requires explicit authorization server ID in URLs; supports both Okta-hosted and custom login pages

Google

  • OAuth 2.0 for Web: Google Identity Services (GIS) library for sign-in button and one-tap
  • Consent screen: Configure in Google Cloud Console; unverified apps limited to 100 users
  • Offline access: Use access_type=offline to receive refresh tokens; prompt=consent forces re-consent
  • Quirks: Refresh tokens only returned on first authorization unless prompt=consent is set; Google uses id_token for identity via OIDC

Microsoft Entra (Azure AD)

  • Tenant types: Single-tenant, multi-tenant, personal accounts, or B2C
  • App registration: Register in Azure Portal → App registrations; configure redirect URIs per platform
  • Graph API scopes: User.Read, Mail.Read, Calendars.Read, Files.Read — use /.default for application permissions
  • Quirks: Uses MSAL.js library; v2.0 endpoint supports both work/school and personal accounts; token cache management via msal-node or msal-browser

File Structure

skills/oauth-integrations/
├── SKILL.md (this file)
└── examples.md

Interface References

Mandatory Workflow

IMPORTANT: Execute ALL steps in order. Do not skip any step.

Step 1: Initial Analysis

  • Gather inputs: required OAuth providers, application type, redirect URI requirements
  • Detect framework (Express, Next.js, FastAPI, Spring Boot, ASP.NET) — determines callback handling and middleware patterns
  • Detect language (TypeScript, JavaScript, Python, Java, C#) — determines SDK and library choices
  • Identify required OAuth providers (GitHub, Okta, Google, Microsoft Entra) from user request
  • Detect existing auth setup — check for existing OAuth configurations, Passport.js strategies, MSAL instances, or Okta SDKs
  • Check for existing dependencies: passport, @okta/okta-auth-js, @azure/msal-node, googleapis, octokit
  • Determine project name for memory lookup

Step 2: Load Memory

Follow Standard Memory Loading with skill="oauth-integrations" and domain="security".

  • Load project_overview.md — understand project's OAuth history and configured providers
  • Load common_patterns.md — reuse previously established OAuth patterns and token management strategies
  • If first run: create memory directory for the project

Step 3: Load Context

Follow Standard Context Loading for the security domain. Stay within the file budget declared in frontmatter.

  • Load security domain context relevant to OAuth 2.0, token management, and session security
  • Cross-reference with any framework-specific context (Express middleware, Next.js API routes, etc.)
  • Respect the file budget of 4 context files maximum

Step 4: Implement OAuth Integration

This is the core action. Set up OAuth 2.0 authentication for the requested providers:

4a: OAuth 2.0 Flow Setup

  • Determine flow type:
    • Authorization Code Flow — standard server-side applications
    • Authorization Code Flow + PKCE — SPAs, mobile apps, and public clients
    • Device Authorization Flow — CLI tools and devices without browsers (GitHub)
  • Generate cryptographically secure state parameter for CSRF protection
  • Generate PKCE code_verifier (43-128 character random string) and code_challenge (SHA-256 hash, base64url-encoded)
  • Construct authorization URL with required parameters (client_id, redirect_uri, scope, state, code_challenge, code_challenge_method)

4b: Provider Configuration

  • GitHub:

    • Register OAuth App or GitHub App in GitHub Developer Settings
    • Configure callback URL (e.g., http://localhost:3000/auth/github/callback)
    • Store GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in environment variables
    • Authorization endpoint: https://github.com/login/oauth/authorize
    • Token endpoint: https://github.com/login/oauth/access_token
    • User endpoint: https://api.github.com/user

  • Okta:

    • Create application in Okta Admin Console (Web Application type for Auth Code flow)
    • Configure authorization server (default or custom)
    • Store OKTA_DOMAIN, OKTA_CLIENT_ID, OKTA_CLIENT_SECRET in environment variables
    • Authorization endpoint: https://{okta-domain}/oauth2/{server-id}/v1/authorize
    • Token endpoint: https://{okta-domain}/oauth2/{server-id}/v1/token
    • UserInfo endpoint: https://{okta-domain}/oauth2/{server-id}/v1/userinfo

  • Google:

    • Create OAuth 2.0 credentials in Google Cloud Console → APIs & Services → Credentials
    • Configure OAuth consent screen (External or Internal)
    • Store GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in environment variables
    • Authorization endpoint: https://accounts.google.com/o/oauth2/v2/auth
    • Token endpoint: https://oauth2.googleapis.com/token
    • UserInfo endpoint: https://www.googleapis.com/oauth2/v3/userinfo

  • Microsoft Entra:

    • Register application in Azure Portal → App registrations
    • Configure redirect URIs and supported account types (single-tenant, multi-tenant)
    • Store AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID in environment variables
    • Authorization endpoint: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    • Token endpoint: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
    • Use MSAL.js for client-side or @azure/msal-node for server-side

4c: Callback Handling and Token Exchange

  • Implement callback route to receive authorization code
  • Validate state parameter matches the stored value (CSRF protection)
  • Exchange authorization code for tokens via POST to token endpoint
  • Parse token response: access_token, refresh_token, id_token (OIDC), expires_in, token_type
  • Validate ID token signature and claims (for OIDC providers: Okta, Google, Microsoft Entra)

4d: Token Storage and Refresh

  • Server-side: Store tokens in encrypted server-side sessions or database; never expose to client
  • Client-side (SPA): Store in memory only; use backend-for-frontend (BFF) pattern for token management
  • Implement token refresh logic:
    • Check expires_in before API calls
    • Use refresh_token grant type to obtain new access tokens
    • Handle refresh token rotation (Okta, Microsoft Entra)
    • Handle refresh token revocation on sign-out
  • Token revocation: Call provider's revocation endpoint on sign-out

4e: Scope Configuration

  • Configure minimum required scopes per provider:
    • GitHub: read:user, user:email (minimum for authentication)
    • Okta: openid, profile, email (OIDC standard scopes)
    • Google: openid, profile, email (OIDC standard scopes)
    • Microsoft Entra: openid, profile, email, User.Read (Graph API access)
  • Request additional scopes incrementally (progressive authorization)
  • Handle scope changes and re-authorization flows

4f: Error Handling

  • Handle OAuth error responses: access_denied, invalid_grant, invalid_scope, server_error
  • Handle token expiration and refresh failures
  • Handle provider-specific errors:
    • GitHub: rate limiting (403), bad verification code
    • Okta: invalid authorization server, expired sessions
    • Google: consent required, unverified app restrictions
    • Microsoft Entra: admin consent required, tenant restrictions
  • Implement user-facing error messages with appropriate detail level

4g: State Parameter CSRF Protection

  • Generate cryptographically random state value (minimum 32 bytes, base64url-encoded)
  • Store state in server-side session or secure HTTP-only cookie before redirect
  • Validate returned state matches stored value in callback handler
  • Reject requests with missing or mismatched state values
  • Clear stored state after validation (one-time use)

Step 5: Generate Output

  • Save output to /claudedocs/oauth-integrations_{project}_{YYYY-MM-DD}.md
  • Follow naming conventions in ../OUTPUT_CONVENTIONS.md
  • Include:
    • OAuth provider configuration and registration instructions
    • Authorization flow implementation code
    • Callback handler implementation
    • Token management (storage, refresh, revocation)
    • Scope configuration per provider
    • Environment variable list
    • Error handling patterns
    • Security considerations and best practices
    • Provider console setup checklists

Step 6: Update Memory

Follow Standard Memory Update for skill="oauth-integrations". Store any newly learned patterns, conventions, or project insights.

  • Update project_overview.md with configured OAuth providers and flow details
  • Update common_patterns.md with OAuth patterns, token management strategies, and provider-specific quirks
  • Record any project-specific customizations or workarounds

Compliance Checklist

Before completing, verify:

  • All mandatory workflow steps executed in order
  • Standard Memory Loading pattern followed (Step 2)
  • Standard Context Loading pattern followed (Step 3)
  • Client secrets stored in environment variables (never hardcoded)
  • State parameter CSRF protection implemented
  • PKCE used for public clients (SPAs, mobile apps)
  • Tokens stored securely (server-side session or encrypted storage)
  • Token refresh logic implemented with expiration checks
  • ID tokens validated (signature and claims) for OIDC providers
  • OAuth error responses handled with user-facing messages
  • Redirect URIs match registered values in provider consoles
  • Output saved with standard naming convention
  • Standard Memory Update pattern followed (Step 6)

Version History

Version Date Changes
1.0.0 2026-02-12 Initial release — OAuth 2.0 integrations with GitHub, Okta, Google, Microsoft Entra (Azure AD); Authorization Code Flow, PKCE, token management, scope configuration, CSRF protection
Weekly Installs
2
Repository
olino3/forge
First Seen
Feb 13, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
cursor2
claude-code2
replit2
mcpjam1
openhands1
zencoder1