oauth-token-automation/README.md

Zero-setup OAuth authorization code flow automation with browser automation

# OAuth Token Generator

A minimal OAuth authorization code flow automation tool that handles the complete flow from user authentication to token retrieval in one click.

## Features

- ✅ **Zero-setup deployment** - Automatically installs Playwright and browser dependencies if missing
- ✅ **Automatic clipboard copy** - Access token is automatically copied to clipboard for instant use
- ✅ **Environment-based configuration** - Support multiple environments with JSON config files
- ✅ **Environment-specific selectors** - Handles different login HTML structures per environment
- ✅ **Detailed logging** - Step-by-step logging for debugging and monitoring
- ✅ **Browser automation** - Automated login using Playwright
- ✅ **Direct URL parsing** - Extracts authorization code directly from callback URL
- ✅ **One-click execution** - Complete flow with a single command
- ✅ **Cross-platform compatibility** - Works on Windows, macOS, and Linux
- ✅ **Robust error handling** - Comprehensive error reporting and recovery

## Quick Start

1. **Configure your environment**:
   ```bash
   # Copy and edit the config file for your environment
   cp config.dev.json config.myenv.json
   ```

2. **Update configuration** in `config.myenv.json`:
   ```json
   {
     "authentication_url": "https://your-auth-server.com/oauth/authorize",
     "username": "your-username",
     "password": "your-password",
     "client_id": "your-client-id",
     "scope": "read write",
     "state": "random-state-string",
     "response_type": "code",
     "redirect_uri": "http://localhost:3000/callback",
     "token_url": "https://your-auth-server.com/oauth/token",
     "client_secret": "your-client-secret",
     "timeout": 30000,
     "headless": true,
     "port": 3000
   }
   ```

3. **Run the automation**:
   ```bash
   # Using npx (automatically installs dependencies)
   npx playwright install chromium
   node oauth-automation.js --env=myenv
   ```

## Installation & Dependencies

### Zero-Setup Usage (Recommended)
The tool automatically handles all dependencies for you:

```bash
# Just run directly - it will auto-install everything needed
node oauth-standalone.js --env=myenv
```

The first run will:
1. ✅ Detect if Playwright is installed
2. ✅ Auto-install Playwright if missing 
3. ✅ Auto-install Chromium browser if missing
4. ✅ Continue with OAuth automation

### Manual Installation (Optional)
If you prefer to install dependencies manually:

```bash
# Install Playwright
npm install playwright

# Install browser (required for automation)
npx playwright install chromium
```

## Usage

### Basic Usage
```bash
# Run with default dev environment
node oauth-automation.js --env=dev

# Run with production environment
node oauth-automation.js --env=prod

# Run with custom environment
node oauth-automation.js --env=staging
```

### Using npm scripts
```bash
# Install dependencies first
npm setup

# Run with predefined scripts
npm run dev    # Uses dev environment
npm run prod   # Uses prod environment
```

## Configuration

### Environment Files
Create `config.{environment}.json` files for each environment:

- `config.dev.json` - Development environment
- `config.prod.json` - Production environment  
- `config.staging.json` - Staging environment

### Configuration Parameters

| Parameter | Description | Required |
|-----------|-------------|----------|
| `authentication_url` | OAuth authorization endpoint | ✅ |
| `username` | User credentials for login | ✅ |
| `password` | User credentials for login | ✅ |
| `client_id` | OAuth client identifier | ✅ |
| `client_secret` | OAuth client secret for token exchange | ✅ |
| `token_url` | Token exchange endpoint | ✅ |
| `scope` | Requested permissions | ✅ |
| `state` | CSRF protection token | ✅ |
| `response_type` | OAuth response type (usually "code") | ✅ |
| `redirect_uri` | Callback URL for OAuth redirect | ✅ |
| `timeout` | Browser timeout in milliseconds | ❌ |
| `headless` | Run browser in headless mode | ❌ |

### Configurable Selectors

Different OAuth providers may have different HTML structures for their login pages. You can configure custom selectors for each environment:

```json
{
  // ...other config...
  "selectors": {
    "username": [
      "input[name=\"j_username\"]",
      "input[id=\"j_username\"]",
      "#username",
      "input[name=\"username\"]",
      "input[type=\"email\"]"
    ],
    "password": [
      "input[name=\"j_password\"]",
      "input[id=\"j_password\"]", 
      "#password",
      "input[name=\"password\"]",
      "input[type=\"password\"]"
    ],
    "submit": [
      "input[type=\"submit\"]",
      "button[type=\"submit\"]",
      "#submit",
      ".submit-btn",
      "button:has-text(\"Sign In\")",
      "button:has-text(\"Login\")"
    ]
  }
}
```

**How it works:**
- The tool tries each selector in order until it finds a matching element
- If no custom selectors are provided, it uses default common selectors
- Logs show which selector was successfully used for debugging

**Common selector patterns:**
- **Standard OAuth**: `input[name="username"]`, `input[type="password"]`
- **JSF/Java**: `input[name="j_username"]`, `input[name="j_password"]`
- **Custom forms**: Use specific IDs, classes, or text content

## Output

The tool provides:
1. **Console logs** - Detailed step-by-step progress
2. **Token response** - Complete OAuth token response in JSON format
3. **File output** - Tokens saved to `tokens.{environment}.json`

Example output:
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "def50200f3a5c8b7e...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}
```

## Troubleshooting

### Common Issues

1. **Browser automation fails**:
   - Check if login form selectors match your OAuth provider
   - Try running in non-headless mode (`"headless": false`)
   - Increase timeout value

2. **Callback not received**:
   - Ensure redirect_uri matches exactly in OAuth app settings
   - Verify the redirect URL is accessible
   - Check OAuth provider documentation for correct redirect format

3. **Token exchange fails**:
   - Verify client_secret is correct
   - Check token_url endpoint
   - Review OAuth provider documentation

### Debug Mode
Set `"headless": false` in your config to see the browser automation in action.

## Security Notes

- Never commit real credentials to version control
- Use environment variables for sensitive data in production
- Rotate client secrets regularly
- Consider using OAuth PKCE flow for enhanced security

## Automatic Clipboard Integration

The tool automatically copies the access token to your system clipboard after successful OAuth completion:

- ✅ **Cross-platform compatibility** - Works on Windows, macOS, and Linux
- ✅ **Instant availability** - Token is ready to paste immediately after completion
- ✅ **Fallback handling** - If clipboard fails, token is still displayed in output
- ✅ **Zero configuration** - No additional setup required

After running the tool, you can immediately paste (`Ctrl+V` / `Cmd+V`) the access token into:
- API testing tools (Postman, Insomnia)
- Terminal commands (`curl -H "Authorization: Bearer <paste-here>"`)
- Browser dev tools for testing
- Any application requiring the OAuth token

## Dependencies

- **playwright** - Browser automation for OAuth flow
- **Node.js** - Runtime (requires Node.js 16+ for fetch API)

## License

MIT