Productify

Appearance

Authentication ​

The Manager integrates with Pocket ID via OAuth 2.0 and OpenID Connect (OIDC) for secure user authentication and authorization.

Overview ​

Authentication in the Productify Framework follows a federated model:

  • Identity Provider - Pocket ID authentication service
  • OAuth 2.0 / OIDC - Standard protocols for authentication
  • Session Management - The Proxy maintains user sessions; the Manager is stateless and receives the authenticated identity with each request
  • API Authentication - Personal Access Tokens and Machine Users

Supported Authentication Methods ​

1. OAuth/OIDC (User Login) ​

Standard web authentication flow for users accessing the UI. The OAuth/OIDC exchange is performed by the Proxy, not the Manager:

  1. User navigates to the Manager UI (through the proxy)
  2. Proxy redirects to the identity provider
  3. User authenticates with the provider
  4. Provider redirects back with an authorization code
  5. Proxy exchanges the code for tokens and establishes the session
  6. Proxy forwards requests to the Manager with the authenticated user's identity

2. Personal Access Tokens (PAT) ​

Bearer tokens for API access:

http
Authorization: Bearer pat_AbCd1234_9f8e7d6c5b4a...

Tokens use the format pat_<prefix>_<random>, where the 8-character prefix allows efficient lookup without exposing the full token.

See Personal Access Tokens for details.

3. Machine Users ​

Service account authentication with Bearer or Basic auth:

http
Authorization: Bearer <generated-machine-user-token>

or

http
Authorization: Basic <base64(username:password)>

See Machine Users for details.

Pocket ID Configuration ​

Manager Configuration ​

The Manager connects to Pocket ID using an API key for backend operations. Configure in config.yml:

yaml
pocket_id:
  host: http://pocketid:1411
  api_key: your-api-key-here

Or using environment variables:

bash
export PFY_POCKET_ID_HOST=https://pocketid.example.com
export PFY_POCKET_ID_API_KEY=your-api-key-here

Pocket ID Setup ​

  1. Deploy Pocket ID instance (see Deployment Guide)
  2. Log in to Pocket ID admin panel
  3. Navigate to Settings > Admin > API Keys
  4. Create a new API key for the Manager
  5. Copy the API key to your Manager configuration
  6. Restart Manager to apply changes

OAuth/OIDC for Users

User authentication via OAuth/OIDC is handled by the Proxy component, not the Manager directly. The proxy authenticates users with Pocket ID and forwards authenticated requests to the Manager with identity headers. The Manager trusts these headers unconditionally — there is no shared proxy secret or any other check that the request actually came from the proxy, so anyone who can reach the Manager directly can forge them. The Manager API must therefore never be exposed anywhere but behind the proxy; enforce that at the network layer. See Known Issues. See Proxy Configuration for OIDC client setup.

Authentication Flow ​

Web UI Authentication ​

mermaid
sequenceDiagram
    User->>Proxy: Access UI
    Proxy->>User: Redirect to Pocket ID
    User->>Pocket ID: Login
    Pocket ID->>User: Redirect with code
    User->>Proxy: Callback with code
    Proxy->>Pocket ID: Exchange code for tokens
    Pocket ID->>Proxy: Access token + ID token
    Proxy->>Proxy: Create session
    Proxy->>Manager: Forward request with user info
    Manager->>Proxy: Response
    Proxy->>User: Redirect to dashboard

API Authentication (PAT) ​

mermaid
sequenceDiagram
    Client->>Manager: Request with Bearer token
    Manager->>Manager: Validate PAT
    Manager->>Manager: Load user context
    Manager->>Client: Response

API Authentication (Machine User) ​

mermaid
sequenceDiagram
    Service->>Manager: Request with credentials
    Manager->>Manager: Validate machine user
    Manager->>Manager: Load tenant context
    Manager->>Service: Response

Token Security ​

Personal Access Tokens ​

  • PBKDF2 Hashing - 600,000 iterations with SHA-256
  • Unique Salts - Per-token salt values
  • One-time Display - Token shown only during creation
  • Optional Expiration - Time-limited tokens
  • Revocation - Immediate invalidation

Machine User Tokens ​

  • PBKDF2 Hashing - Same security as PATs
  • Token Prefix - Searchable without exposing full token
  • No Expiration - Valid until revoked or deleted
  • Dual Auth Support - Bearer or Basic authentication

Session Management ​

Session Duration ​

User sessions are managed by the identity provider and the Proxy; the Manager itself is stateless:

  • IdP Session - Managed by the identity provider (configurable)
  • Proxy Session - Maintained by the proxy after the OAuth exchange
  • Refresh Tokens - Automatic session renewal (if supported)

Session Termination ​

Sessions end when:

  • User logs out explicitly
  • Session timeout is reached
  • User account is disabled
  • Identity provider invalidates session

Multi-Device Sessions ​

Users can have multiple active sessions across different devices. No single-session restriction is enforced.

Role-Based Access Control ​

After authentication, authorization is handled via roles at several levels:

  • System Role - normal, audit, or administrator (per user, fixed enum, operator-side)
  • Project Roles - readonly, tester, developer, maintainer, owner (fixed enum, operator-side)
  • Tenant Roles - configurable per project over a fixed platform permission vocabulary. The platform seeds member, admin, and owner; checks test permissions, not role names.

The full model — the fixed permission vocabulary, the precedence rule (system administrator > project role for operator resources; tenant-role permissions govern only tenant-scoped resources), and the platform-forwards-facts / apps-own-capability boundary — is documented in the Access Model. See also User Management.

Opt-in identity forwarding ​

An application can opt in (per-application forward_role setting, default off) to receive the caller's membership context. When enabled the proxy injects:

  • X-User-Tenant-Role — the role name in the selected tenant (project-configurable, not a stable contract).
  • X-User-Tenant-Permissions — comma-separated permissions from the fixed vocabulary. Gate on permissions, not role names.
  • X-User-Picture — the Pocket ID picture claim when present.

The same values appear in window.__PRODUCTIFY__ as tenantRole, tenantPermissions, and user.picture. All three headers are on the proxy's sanitizer strip list, so client-supplied copies are removed. This forwards the membership fact only — apps keep owning their in-app capability model.

Best Practices ​

Pocket ID ​

  • Enable MFA - Multi-factor authentication for enhanced security
  • Regular Audits - Review user access and permissions
  • Strong Passwords - Enforce password complexity policies
  • Keep Updated - Regularly update Pocket ID to latest version

Token Management ​

  • Rotate Regularly - Create new tokens and retire old ones
  • Limit Scope - Grant minimal required permissions
  • Monitor Usage - Track token usage and identify anomalies
  • Secure Storage - Use secret managers for production tokens

Configuration ​

  • Environment Variables - Override config with env vars in production
  • Secret Management - Use secret managers (Vault, AWS Secrets Manager)
  • HTTPS Only - Always use TLS/SSL for authentication
  • Restrict Redirects - Limit allowed callback URLs

Session Security ​

  • Secure Cookies - Use secure, httpOnly cookies
  • CSRF Protection - Implement CSRF tokens
  • Session Timeout - Configure appropriate timeout values
  • Activity Logging - Log authentication events

Troubleshooting ​

Cannot Login ​

Check:

  • Pocket ID is accessible
  • Client ID and secret are correct
  • Redirect URLs are configured properly
  • User exists in Pocket ID
  • User account is not disabled

Authentication Loop ​

Possible causes:

  • Incorrect issuer URL
  • Clock skew between Manager and Pocket ID
  • Invalid redirect URI configuration
  • Cookie/session issues

API Authentication Fails ​

Verify:

  • Token format is correct (Bearer <token>)
  • Token hasn't expired or been revoked
  • Token belongs to active user/machine user
  • Required scopes/permissions are granted

Session Expires Too Quickly ​

Solutions:

  • Increase session timeout in config
  • Enable refresh token rotation
  • Configure IdP session length
  • Check for clock synchronization issues

Security Considerations ​

HTTPS/TLS ​

Always use HTTPS for:

  • Manager UI and API
  • Pocket ID service
  • All redirect URLs
  • Token exchange

Token Storage ​

Never:

  • Commit tokens to version control
  • Log tokens in application logs
  • Expose tokens in error messages
  • Send tokens over unencrypted connections

Always:

  • Use environment variables
  • Encrypt tokens at rest
  • Use secret management systems
  • Rotate tokens regularly

Network Security ​

  • Firewall Rules - Restrict access to Manager and IdP
  • VPN/Private Network - Use for internal services
  • Rate Limiting - Prevent brute-force attacks
  • IP Whitelisting - For sensitive operations

OAuth 2.0 Flows ​

Authorization Code Flow ​

Standard flow for web applications (performed by the Proxy for the Manager UI):

  1. Authorization Request - Redirect to IdP with client_id
  2. User Authentication - User logs in at IdP
  3. Authorization Grant - IdP redirects back with code
  4. Token Request - Proxy exchanges code for access token
  5. Access Protected Resource - Proxy forwards authenticated requests

Machine-to-machine authentication does not use OAuth: machine users authenticate directly with a static Bearer token or Basic credentials issued by the Manager.

Integration Examples ​

Using PAT with GraphQL ​

javascript
import { createClient } from "@urql/core";

const client = createClient({
  url: "https://manager.example.com/query",
  fetchOptions: {
    headers: {
      Authorization: `Bearer ${process.env.PRODUCTIFY_PAT}`,
    },
  },
});

const result = await client.query(myQuery, variables).toPromise();

Using Machine User with REST ​

bash
#!/bin/bash

MACHINE_TOKEN="<machine-user-bearer-token>"

curl -X POST https://manager.example.com/api/machine/register-backend \
  -H "Authorization: Bearer $MACHINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "application_id": "550e8400-e29b-41d4-a716-446655440000",
    "callback_url": "https://backend.example.com/callback"
  }'

Bearer Only

The /api/machine/* and /esb/* endpoints accept Bearer tokens only. Basic-auth machine users are validated by the proxy (via the Manager's credential-validation endpoint) when calling applications behind the proxy.

API Reference ​

Authentication-related API operations:

See the full API Reference for details.