# Auth Server - Demo OAuth 2.0 Provider

Demonstration OAuth 2.0 authorization server representing commercial providers (Auth0, Okta, Google OAuth).

## Purpose

Complete OAuth 2.1 server implementing:
- Client registration (Dynamic Client Registration)
- Authorization flow with PKCE
- Token issuance and refresh
- Token introspection (RFC 7662)
- User authentication (via demo upstream IDP)

In production, replace this server with a commercial OAuth provider.

## Quick Start

```bash
# From this directory:
npm run dev

# Server starts on http://localhost:3001
```

## Flow

```
MCP Client ──OAuth──> Auth Server ──tokens──> MCP Client ──MCP requests──> MCP Server
                                                                                │
                                                                                └──validate──> Auth Server /introspect
```

1. MCP Client initiates OAuth flow with this server
2. Server handles authorization and user authentication
3. Server issues access tokens
4. Client uses tokens to access MCP server
5. MCP server validates tokens by calling this server's `/introspect` endpoint

## Key Components

### `src/index.ts`
Main entry point. Sets up:
- OAuth endpoints via SDK's `mcpAuthRouter`
- Token introspection endpoint (`POST /introspect`)
- Mock upstream auth UI for demo
- Rate limiting and CORS

### `src/auth/provider.ts`
**FeatureReferenceAuthProvider** - Implements OAuth server logic:
- Client registration storage
- Authorization code generation
- PKCE challenge validation
- Token issuance and refresh
- Token verification

### `src/services/`
- **auth.ts**: Auth service wrappers
- **redis-auth.ts**: Redis operations for OAuth data

### `src/handlers/mock-upstream-idp.ts`
Mock upstream identity provider. Simulates user authentication that would be handled by corporate SSO or social login in production OAuth providers.

## OAuth Endpoints

```bash
# Discovery
GET /.well-known/oauth-authorization-server

# Client registration
POST /register

# Authorization
GET /authorize?client_id=...&redirect_uri=...&code_challenge=...

# Token exchange
POST /token

# Token introspection (called by MCP server)
POST /introspect
```

## Configuration

Environment variables in `.env`:
```bash
AUTH_SERVER_URL=http://localhost:3001
AUTH_SERVER_PORT=3001
BASE_URI=http://localhost:3232         # MCP server URL
REDIS_URL=redis://localhost:6379
```

## Testing

```bash
npm test              # 37 unit tests
npm run lint          # Lint code
npm run typecheck     # Type checking
npm run build         # Build to dist/
```

## Production Replacement

Commercial OAuth providers supporting RFC 7662 introspection:
- Auth0, Okta, Azure AD/Microsoft Entra
- AWS Cognito, Google Identity Platform
- GitHub OAuth

The MCP server integrates with any RFC 7662-compliant provider.

## Redis Data

This server stores in Redis:
- `auth:client:{clientId}` - OAuth client registrations (30 day TTL)
- `auth:pending:{code}` - Pending authorizations (10 min TTL)
- `auth:installation:{token}` - Active installations (7 day TTL)
- `auth:refresh:{refreshToken}` - Refresh token mappings (7 day TTL)
- `auth:exch:{code}` - Token exchanges (10 min TTL)

## Related Documentation

- [Main README](../README.md) - Complete project documentation
- [MCP Server README](../mcp-server/README.md) - How MCP server uses these tokens
- [OAuth Patterns](../docs/oauth-patterns.md) - OAuth architecture patterns
- [OAuth Flow](../docs/oauth-flow.md) - Detailed OAuth flow analysis