OAuth Integration

About

How the builder automatically provisions OAuth clients via Bio-ID on every deploy. Covers naming conventions, environment variable injection (BIO_CLIENT_ID, BIO_CLIENT_SECRET), the critical /api/auth/callback route requirement, complete implementation examples for login and callback routes, and available scopes.

Skill Content

This is the raw markdown that gets installed as a Claude Code rule.

# OAuth Integration

## What this skill covers
How Bio-ID OAuth is auto-provisioned on deploy and how to implement the callback in your service.

## Auto-Provisioning

On every deploy, the builder automatically:
1. Creates an OAuth client in Bio-ID (if it doesn't exist)
2. Registers the redirect URI based on naming conventions
3. Injects BIO_CLIENT_ID and BIO_CLIENT_SECRET as environment variables

The operation is idempotent — if the client exists, it updates rather than creating a duplicate.

## Naming Conventions

| Component | Format | Example |
|-----------|--------|---------|
| OAuth Client ID | `{service}-{environment}` | ppay-board-sandbox |
| Redirect URI (sandbox) | `https://{service}.sandbox.tawa.insureco.io/api/auth/callback` | |
| Redirect URI (prod) | `https://{service}.tawa.insureco.io/api/auth/callback` | |

## Environment Variables Injected

| Variable | Description |
|----------|-------------|
| `BIO_CLIENT_ID` | Auto-generated OAuth client ID |
| `BIO_CLIENT_SECRET` | Auto-generated OAuth client secret |

## CRITICAL: Callback Route

Your service MUST implement the callback at this exact path:

```
/api/auth/callback
```

The builder registers this path as the redirect URI. Any other path will fail.

```typescript
// CORRECT — matches builder convention
router.get('/api/auth/callback', async (req, res) => {
  // Handle OAuth callback
})

// WRONG — builder won't register this
router.get('/api/auth/bio-id/callback', async (req, res) => {
  // Will fail with "Invalid Redirect URI"
})
```

## Implementation

### Configuration
```typescript
export const config = {
  bioId: {
    clientId: process.env.BIO_CLIENT_ID,
    clientSecret: process.env.BIO_CLIENT_SECRET,
    baseUrl: process.env.BIO_ID_BASE_URL || 'https://bio.tawa.insureco.io',
    callbackUrl: process.env.BIO_ID_CALLBACK_URL || 'http://localhost:3301/api/auth/callback'
  }
}
```

### Login Route
```typescript
router.get('/auth/login', (req, res) => {
  const authUrl = new URL(\`\${config.bioId.baseUrl}/oauth/authorize\`)
  authUrl.searchParams.set('client_id', config.bioId.clientId)
  authUrl.searchParams.set('redirect_uri', config.bioId.callbackUrl)
  authUrl.searchParams.set('response_type', 'code')
  authUrl.searchParams.set('scope', 'openid profile email')
  res.json({ authUrl: authUrl.toString() })
})
```

### Callback Route
```typescript
router.get('/auth/callback', async (req, res) => {
  const { code } = req.query
  const tokenRes = await fetch(\`\${config.bioId.baseUrl}/oauth/token\`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'authorization_code',
      client_id: config.bioId.clientId,
      client_secret: config.bioId.clientSecret,
      redirect_uri: config.bioId.callbackUrl,
      code
    })
  })
  const tokens = await tokenRes.json()
  // Store tokens in session, set cookies, etc.
})
```

## Available Scopes

| Scope | Description |
|-------|-------------|
| `openid` | Required — returns ID token with unique identifier |
| `profile` | User's name, username, and avatar |
| `email` | User's email address and verification status |

## Common Mistakes
- Using `/api/auth/bio-id/callback` instead of `/api/auth/callback`
- Hardcoding client ID/secret instead of reading from process.env
- Forgetting that credentials are auto-injected — no manual setup needed
- Not having a fallback `BIO_ID_CALLBACK_URL` for local development

Install

Copy the skill content and save it to:

~/.claude/rules/oauth-integration.md

Details

Format

Rule

Category

provision

Version

1.0.0

Tokens

~1,000

Updated

2026-02-13