@gzl10/nexus-plugin-pocketid

PocketID authentication plugin for Nexus BaaS. Adds passwordless login via passkeys using Pocket ID as OIDC provider.

Features

• OIDC Authorization Code Flow with PKCE
• Auto-registration or manual account linking
• Email domain allowlist
• SCIM 2.0 provisioning (users & groups)

Requirements

• @gzl10/nexus-backend >= 0.13.0
• @gzl10/nexus-sdk >= 0.13.0
• A running Pocket ID instance

Installation

pnpm add @gzl10/nexus-plugin-pocketid

1. Configure Pocket ID

In the Pocket ID admin panel:

1. Go to OIDC Clients > Create Client
2. Set Name: my-app (or whatever you prefer)
3. Add Redirect URI: https://your-backend.com/api/v1/pocketid_auth/callback
4. Note the Client ID and Client Secret

The redirect URI must point to your Nexus backend's callback endpoint, not the frontend.

2. Configure Nexus

Add environment variables:

POCKETID_URL=https://auth.example.com
POCKETID_CLIENT_ID=your-client-id
POCKETID_CLIENT_SECRET=your-client-secret

Register the plugin in your backend:

import { start } from '@gzl10/nexus-backend'
import { pocketIdPlugin } from '@gzl10/nexus-plugin-pocketid'

await start({ plugins: [pocketIdPlugin] })

On first start, the plugin auto-seeds its configuration from the environment variables.

3. Frontend

The plugin registers an auth provider that nexus-ui picks up automatically. A "Sign in with PocketID" button appears on the login page.

For custom frontends, redirect users to:

GET /api/v1/pocketid_auth/authorize?redirect_uri=https://your-frontend.com/login

After authentication, the backend redirects back with tokens in the URL fragment:

https://your-frontend.com/login#accessToken=...&refreshToken=...

On error:

https://your-frontend.com/login#error=Your+account+does+not+exist

Configuration

The plugin creates a pocketid_config table on first run. Options:

| Field | Default | Description | |-------|---------|-------------| | enabled | true | Enable/disable PocketID login | | default_role | VIEWER | Role assigned to new users | | allowed_domains | null | JSON array of allowed email domains (null = all) | | scopes | openid profile email | OIDC scopes |

API Endpoints

| Method | Endpoint | Auth | Description | |--------|----------|------|-------------| | GET | /api/v1/pocketid_auth/authorize | No | Start OIDC flow | | GET | /api/v1/pocketid_auth/callback | No | Handle OIDC callback | | GET | /api/v1/pocketid_auth/link | Yes | Link existing account | | GET | /api/v1/pocketid_auth/status | Yes | Check if PocketID is linked |

SCIM 2.0

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/v1/scim/ServiceProviderConfig | SCIM capabilities | | GET | /api/v1/scim/Schemas | User & Group schemas | | GET/POST | /api/v1/scim/Users | List / create users | | GET/PUT/PATCH/DELETE | /api/v1/scim/Users/:id | Manage user | | GET/POST | /api/v1/scim/Groups | List / create groups | | GET/PUT/PATCH/DELETE | /api/v1/scim/Groups/:id | Manage group |

SCIM endpoints require Bearer token authentication configured in pocketid_scim_config.

License

MIT