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 - Manager maintains user sessions
  • 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:

  1. User navigates to Manager UI
  2. Manager redirects to identity provider
  3. User authenticates with provider
  4. Provider redirects back with authorization code
  5. Manager exchanges code for access token
  6. User session is established

2. Personal Access Tokens (PAT) ​

Bearer tokens for API access:

http
Authorization: Bearer pfy_abc123def456...

See Personal Access Tokens for details.

3. Machine Users ​

Service account authentication with Bearer or Basic auth:

http
Authorization: Bearer muser_abc123def456...

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. 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 Manager:

  • IdP Session - Managed by identity provider (configurable)
  • Manager Session - Application session (typically 24 hours)
  • 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. The Manager does not enforce single-session restrictions.

Role-Based Access Control ​

After authentication, authorization is handled via roles:

  • Project Roles - Admin, Editor, Viewer
  • Tenant Roles - Admin, Editor, Viewer
  • Application Roles - Admin, Editor, Viewer

See User Management for role details.

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 (used by 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 - Exchange code for access token
  5. Access Protected Resource - Use token in API requests

Client Credentials Flow ​

For machine-to-machine authentication (machine users):

  1. Token Request - Send client credentials to token endpoint
  2. Token Response - Receive access token
  3. Access Protected Resource - Use token in API requests

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="muser_abc123def456..."

curl -X POST https://manager.example.com/api/machine/register-backend \
  -H "Authorization: Bearer $MACHINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Service",
    "callbackUrl": "https://backend.example.com/callback"
  }'

Using Basic Auth ​

python
import requests
from requests.auth import HTTPBasicAuth

auth = HTTPBasicAuth('machine-user', 'password')

response = requests.get(
    'https://manager.example.com/api/machine/check',
    auth=auth
)

API Reference ​

Authentication-related API operations:

See the full API Reference for details.