OAuth2 - Flows App

A standards-compliant OAuth2 application for Flows that implements the authorization code flow with automatic token refresh.

Overview

This app provides OAuth2 authentication for external services, automatically managing tokens and exposing them as signals for use in other blocks.

• Access Token block: Expose OAuth2 tokens as block-level signals for use in your flows

Quick Start

1. Install the app in your Flows environment
2. Configure OAuth2 endpoints - Authorization URL and Token URL
3. Register with provider - Follow the prompt to register your OAuth2 application
4. Authorize - Click the prompt button to authorize the application
5. Use the Access Token block - Add it to your flow to access OAuth2 tokens as block signals

Features

• Standards-compliant OAuth2: Implements RFC 6749 authorization code flow
• Automatic token refresh: Uses refresh tokens to maintain authentication
• CSRF protection: State parameter validation on callbacks
• Secure storage: Sensitive tokens stored securely, never exposed
• Block-level signals: Access Token block exposes tokens as signals for use in flows
• Flexible configuration: Support for custom scopes, audiences, and additional parameters

App Structure

├── .github/workflows/ci.yml  # CI/CD pipeline
├── main.ts                   # OAuth2 app definition with token management
├── blocks/
│   ├── index.ts              # Block registry
│   └── accessToken.ts        # Access Token block
├── package.json              # Dependencies
└── README.md                 # This file

Configuration

Required Fields

• Authorization URL: The OAuth2 authorization endpoint (e.g., https://provider.com/oauth/authorize)
• Token URL: The OAuth2 token endpoint (e.g., https://provider.com/oauth/token)

Optional Fields (after initial setup)

• Client ID: OAuth2 client identifier (configured after provider registration)
• Client Secret: OAuth2 client secret (configured after provider registration)
• Scope: Space-separated OAuth2 scopes (e.g., read write)
• Additional Authorization Parameters: JSON object with extra params for authorization request
• Additional Token Parameters: JSON object with extra params for token request

Common OAuth2 Provider Examples

GitHub OAuth App

Authorization URL: https://github.com/login/oauth/authorize
Token URL: https://github.com/login/oauth/access_token
Scope: repo user (or as needed)

Note: GitHub OAuth tokens don't expire by default. The app will default to checking every hour, but the token remains valid until revoked.

GitHub-specific considerations:

• GitHub returns tokens as application/x-www-form-urlencoded by default
• The app automatically handles this by requesting JSON responses via the Accept header
• Refresh tokens are available if you include the refresh_token scope

Google OAuth

Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
Token URL: https://oauth2.googleapis.com/token
Scope: (depends on API - e.g., https://www.googleapis.com/auth/userinfo.email)

Microsoft/Azure AD

Authorization URL: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
Token URL: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Scope: (depends on API - e.g., https://graph.microsoft.com/.default)

Generic OAuth2 Provider

Most OAuth2 providers follow a similar pattern:

Authorization URL: https://provider.com/oauth/authorize
Token URL: https://provider.com/oauth/token

Check your provider's documentation for:

• The correct endpoint URLs
• Available scopes
• Any provider-specific parameters needed

How It Works

Authorization Flow

1. Initial Setup: User configures Authorization URL and Token URL
2. Provider Registration: Prompt guides user to register OAuth2 app with provider
3. Authorization: User clicks prompt button → redirects to provider → authorizes app
4. Callback: Provider redirects back to /callback with authorization code
5. Token Exchange: App exchanges code for access token and refresh token
6. Ready: Access token exposed as signal, available for use in blocks

Token Refresh

• Scheduled check every 10 minutes
• Automatically refreshes token 5 minutes before expiration
• Uses refresh token if available
• Falls back to authorization code if refresh fails
• Updates all Access Token blocks when tokens are refreshed

Security Features

• CSRF Protection: State parameter validated on OAuth callback
• Secure Storage: Client secrets and tokens stored securely in KV store
• Sensitive Signals: Access token marked as sensitive, never exposed in logs
• HTTPS Only: OAuth callback requires HTTPS in production

Development

Prerequisites

• Node.js 20+
• npm

Available Scripts

npm install          # Install dependencies
npm run typecheck    # Type checking
npm run format       # Code formatting
npm run bundle       # Create deployment bundle

Blocks

Access Token Block

Exposes OAuth2 tokens as block-level signals. Automatically stays synchronized with the app's token state.

Signals:

• accessToken: OAuth2 bearer token (sensitive)
• expiresAt: Unix timestamp when token expires

Use case: When you need to reference OAuth2 tokens as block-level signals in your flows instead of using app-level signals.

Troubleshooting

Authorization fails

• Verify Authorization URL and Token URL are correct
• Check that Redirect URI in provider matches: {appEndpointUrl}/callback
• Ensure Client ID and Client Secret are correct
• Check provider logs for error details

Token refresh fails

• Verify provider supports refresh tokens
• Check that refresh token was returned in initial token response
• Some providers (like GitHub) don't expire tokens, so refresh isn't needed

HTTP requests fail with 401

• Check token hasn't been revoked in provider
• Verify the scope includes necessary permissions
• Try re-authorizing the application

OAuth2 Standards

This implementation follows:

• RFC 6749: The OAuth 2.0 Authorization Framework
• Authorization Code Grant: Section 4.1
• Refresh Token: Section 6

License

MIT