OAuth Providers

OAuth provider extensions handle authentication with external services. They enable single sign-on across multiple consumer extensions.

Architecture

Kiket uses a shared OAuth provider architecture:

┌─────────────────────────────────────────────────────────────┐
│                     User's Account                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────────┐      ┌─────────────────┐             │
│   │  google-oauth   │      │ microsoft-oauth │             │
│   │  (Provider)     │      │  (Provider)     │             │
│   └────────┬────────┘      └────────┬────────┘             │
│            │                        │                       │
│   ┌────────┴────────┐      ┌────────┴────────┐             │
│   │ OAuthConnection │      │ OAuthConnection │             │
│   │   (Tokens)      │      │   (Tokens)      │             │
│   └────────┬────────┘      └────────┬────────┘             │
│            │                        │                       │
│     ┌──────┴──────┐          ┌──────┴──────┐               │
│     │             │          │             │               │
│ ┌───┴───┐   ┌─────┴─────┐  ┌─┴────┐  ┌────┴────┐          │
│ │Google │   │Google     │  │MS    │  │MS       │          │
│ │Calndr │   │Drive      │  │Teams │  │Calendar │          │
│ └───────┘   └───────────┘  └──────┘  └─────────┘          │
│ (Consumer)   (Consumer)   (Consumer) (Consumer)            │
└─────────────────────────────────────────────────────────────┘

Benefits

• Single Sign-On: Connect once, use everywhere
• Scope Aggregation: Only prompted for new permissions when needed
• Centralized Management: View and revoke all connections in one place
• Automatic Refresh: Tokens are refreshed automatically

Available Providers

Provider	ID	Services
Google	google-oauth	Google Calendar, Google Drive, Gmail
Microsoft	microsoft-oauth	Outlook Calendar, Teams, OneDrive

Building an OAuth Provider Extension

To create a new OAuth provider extension:

Manifest Structure

model_version: "1.0"
extension:
  id: dev.kiket.ext.my-oauth
  name: My OAuth Provider
  capabilities:
    - oauth2-provider
  provides:
    oauth_provider:
      provider_id: my-provider
      display_name: My Service
      icon: bi-cloud
      endpoints:
        authorize: https://auth.example.com/oauth/authorize
        token: https://auth.example.com/oauth/token
        revoke: https://auth.example.com/oauth/revoke
        userinfo: https://api.example.com/me
      grant_types:
        - authorization_code
        - refresh_token
      default_scopes:
        - openid
        - email
      available_scopes:
        - id: openid
          description: Sign you in
          default: true
        - id: email
          description: View your email
          default: true
        - id: calendar.read
          description: Read calendars
          consumer: my-calendar

Required Endpoints

Your extension must handle these webhook events:

1. oauth.callback: Exchange authorization code for tokens
2. oauth.refresh: Refresh expired tokens
3. oauth.revoke: Revoke tokens

Token Exchange Response

Return tokens in this format:

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_at": "2024-01-15T12:00:00Z",
  "scope": "openid email calendar.read",
  "user_id": "user123",
  "email": "user@example.com"
}

Building a Consumer Extension

Consumer extensions declare their OAuth provider dependency:

model_version: "1.0"
extension:
  id: dev.kiket.ext.my-calendar
  name: My Calendar
  capabilities:
    - calendar-sync
  requires:
    oauth_provider:
      provider: my-oauth
      scopes:
        - calendar.read
      on_missing: prompt_connect

on_missing Options

• prompt_connect: Show connection prompt to user
• ignore: Silently skip OAuth features (for optional OAuth)
• error: Fail extension install if provider not installed

Token Management

Getting a Token

In your extension code, request tokens via the extension API:

// Node.js SDK example
const token = await kiket.oauth.getToken({
  provider: 'my-oauth',
  scopes: ['calendar.read']
});

const response = await fetch('https://api.example.com/calendars', {
  headers: {
    'Authorization': `Bearer ${token.access_token}`
  }
});

Handling Token Expiry

Tokens are automatically refreshed by Kiket. If a token cannot be refreshed (e.g., refresh token expired), the OAuth connection status changes to "expired" and the user is notified.

Security Considerations

1. Encryption: All tokens are encrypted at rest using AES-256
2. Key Rotation: Encryption keys can be rotated without re-authorization
3. Scope Minimization: Only request scopes you need
4. Revocation: Tokens are immediately cleared on disconnect
5. Provider Uninstall Protection: Cannot uninstall a provider while consumers depend on it