User Authentication

Overview

Our licensing system supports flexible end user authentication to integrate seamlessly with your existing user management infrastructure. This document outlines the available authentication methods and requirements for integration.

Authentication Methods

Option 1: WorkOS Integration

We recommend WorkOS as a very cost-effective identity provider.

Best for: Organizations already using WorkOS for identity management, or those who want a modern alternative to Auth0 with built-in enterprise SSO support.

Requirements

• WorkOS account and organisation
• WorkOS application with Client ID and Client Secret
• Users configured in your WorkOS environment

How it works

• We validate user credentials directly against your WorkOS instance
• Upon successful authentication, we handle session management
• No OAuth flow required - simple credential validation with immediate response

Benefits

• No custom development required on your end
• Enterprise-grade security and compliance

Option 2: Auth0 Integration

Best for: Organizations wanting a modern, secure authentication solution from the market leader or those already using Auth0.

Requirements

• Auth0 tenant/account
• Auth0 application with Client ID and Client Secret
• Auth0 domain URL
• Users configured in your Auth0 tenant

How it works

• We validate user credentials directly against your Auth0 instance
• Upon successful authentication, we handle session management
• No OAuth flow required - simple credential validation with immediate response

Benefits

• No custom development required on your end
• Enterprise-grade security and compliance
• User management dashboard included

Option 3: Custom Authentication API

Best for: Organizations with existing user management systems or specific authentication requirements.

If you have an existing user authentication system, we can integrate with it through a standardized API interface.

Technical Requirements

Endpoint Configuration

• HTTPS POST endpoint URL
• System-to-system authentication via HTTP Basic Auth
• End user credentials transmitted in JSON request body

Request Format

{
  "email": "user@example.com",
  "password": "userpassword"
}

Note: Field names (username/password vs email/password) are configurable based on your API.

Response Options

Option A: Status Code Authentication

• HTTP 200/201 = Authentication successful
• Any other status code = Authentication failed

Option B: Response Body Authentication

• HTTP 200 with JSON response containing success indicator
• Configurable property name (e.g., “success”: true, “valid”: true, “authenticated”: true)
• Can check for property presence or specific value

Explicit Customer Referencing (External ID)

For explicit referencing of customers, it is highly recommended to include the identifier you use in your system to reference the user in the response body when using custom URL authentication. This enables Product Hub to reliably associate end users with your internal records using it as an external id. This can be of great value when doing things like email changes.

How to do it:

• Your authentication API should return a property such as "user_id": "your-unique-user-id" in the JSON response body upon successful authentication.
• The property name for the external ID is configurable in Product Hub’s manufacturer settings under authentication configuration.

Configuration:

• In the Product Hub web interface, specify the property name (e.g., external_id, user_id, etc.) that your API uses for the identifier.
• Product Hub will extract this value from the response and store it in the user object.

Security Considerations

• HTTPS only (TLS 1.2 minimum)
• System authentication credentials stored securely in our system
• No user credentials cached or stored
• Failed authentication attempts logged for security monitoring

Option 4: None (Email + Serial Only)

Best for: Manufacturers who distribute exclusively through resellers or do not have an identity management system. Users never set a password; they identify themselves solely by their email address and the serial number they received from the reseller.

With this scheme, Product Hub creates a lightweight user record the first time an email address is seen for your manufacturer. There is no password, no SSO provider, and no login step. The serial number acts as the proof of purchase.

How it works

• The end user enters their email address and reseller serial number in your plugin’s activation UI.
• Product Hub looks up or creates a user record for that email under your manufacturer.
• The serial is claimed to that user and the license is activated in a single call.
• Subsequent activations on additional machines require only the same email + serial.

Requirements

• email_serial_claim_enabled must be enabled in your Auth Scheme settings (see the Reseller Support section in the web frontend).
• Licenses must exist in Product Hub either by creating batches to distribute via resellers or by integrating with the Product Hub API pushing licenses into the system on purchase.

Limitations

• No email change support — because there is no identity provider to send a webhook from, Product Hub has no way to learn about email changes. If a user changes their email address, their existing activations remain under the old address and cannot be automatically migrated.
• No password recovery — there is no password, so there is nothing to recover. But this also means there is no way to verify that a new device activation is coming from the same person, only that they have the original email + serial.

We strongly recommend considering an identity management system such as WorkOS (our preferred provider) or Auth0 instead of this scheme wherever possible. A proper IdP gives your customers a named account, supports graceful email changes via webhook, enables password recovery, and opens the door to features like subscription management and purchase history — none of which are available with email + serial only authentication.

The None scheme is intentionally simple and is best suited to more affordable webshop provider plans where a full account experience through IdP integration is not possible.

Email Change Webhook

Product Hub provides a unified webhook endpoint that allows your identity provider to notify us when a user changes their email address, keeping our records automatically in sync.

The endpoint supports all three authentication methods (Auth0, WorkOS, Custom URL) and automatically routes incoming events to the correct handling logic based on the auth scheme configured for your manufacturer.

• Auth0: Configure an Action on the Post Change Email trigger in the Auth0 Dashboard to call the webhook whenever a user’s email changes.
• WorkOS: Register the webhook URL in the WorkOS Dashboard and subscribe to user update events.
• Custom URL: Call the webhook from your own backend whenever a user’s email changes in your system.

For detailed integration instructions please consult the End User Auth Scheme configuration age in the Product Hub web frontend.

Self-Service Configuration

Product Hub Web Interface

You can configure your authentication method directly through the Product Hub web frontend:

1. Access Settings: Navigate to your manufacturer settings in the Product Hub
2. Authentication Configuration: Select your preferred authentication method
3. Credential Entry: Securely enter your configuration details:
   • For Auth0: Domain, Client ID, Client Secret, and optionally Audience and End User Connection
   • For WorkOS: API domain, Client ID, Client Secret, and Webhook Secret
   • For Custom API: Endpoint URL, system credentials, and response validation settings

Credential Storage

• Credentials are never logged or exposed in error messages
• You can update or rotate credentials at any time through the web interface

Security & Privacy

• No Credential Storage: We never store end user passwords
• Real-time Validation: Each login attempt is validated in real-time against your system
• Secure Token Generation: We generate our own JWT tokens for session management
• Error Sanitization: External authentication errors are logged internally but not exposed to end users

Technical Specifications

For Auth0 Integration

• Uses Auth0’s Resource Owner Password Grant for credential validation
• Supports custom realms and audiences
• Compatible with Auth0’s standard response format

For WorkOS Integration

• Uses WorkOS User Management password authentication (POST /user_management/authenticate)
• WorkOS User ID is stored as the external ID for reliable user referencing
• Webhook signature verification uses HMAC-SHA256 over <timestamp>.<raw_body> with a 5-minute replay window