QuickPass Authorization Integration with Main Product

QuickPass uses its own JWT (JSON Web Tokens) based authentication system for managing user sessions. To integrate with the main product where the user is already authenticated, it's necessary to implement one of the mechanisms for transferring authentication data between systems.

The main goal of integration is to ensure:

1. Single sign-on between the main product and QuickPass
2. Transfer of minimally necessary user data
3. Security of credential transmission

Below are integration options that allow transferring authentication data from the main product to QuickPass.

Integration Options

1. OAuth2

• Flow:

  1. Main product → redirect to QuickPass
  2. Authorization in QuickPass
  3. QuickPass → authorization code → main product
  4. Exchange code for access token
  5. Request user data by token

• Technical Requirements:

  • Register OAuth2 application in QuickPass
  • HTTPS for all redirect_uri
  • Support for Authorization Code flow

2. Iframe with Shared Cookies

• Flow:

  1. Main product → QuickPass iframe (subdomain)
  2. Check shared domain cookies
  3. Automatic authorization in iframe
  4. Data transfer via postMessage

• Technical Requirements:

  • Shared domain or subdomains (e.g.: main.example.com and qp.example.com)
  • SameSite=None configuration for cross-domain cookies
  • Content Security Policy for iframe
  • postMessage event handling with origin validation

3. JWT Tokens

• Flow:

  1. Main product → generates JWT
  2. Redirect to QuickPass with token in URL
  3. QuickPass → JWT verification
  4. Create session based on token data

• Technical Requirements:

  • Shared secret key or asymmetric cryptography (RS256)
  • Short token lifetime (5-15 minutes)
  • Required claims: user_id, exp, iat, iss
  • Transfer via POST body instead of URL for security

4. Server-to-Server Synchronization

• Flow:

  1. Main product → QuickPass API call
  2. Transfer session/token hash
  3. QuickPass → verification → return user data
  4. Main product → create local session

• Technical Requirements:

  • API keys for request authentication
  • Rate limiting (e.g., 100 requests/minute)
  • Request timeout (3-5 seconds)
  • Retry mechanism for temporary failures
  • Webhook for session change notifications

Method Selection Recommendations

Method	When to Use	Complexity	Security
OAuth2	Full integration, high security requirements	High	Maximum
Iframe	Embedded integration, shared domain	Medium	High
JWT	Simple integration, trusted environment	Low	Medium
Server-to-Server	Backend integration, high load	Low	High

Quick Start: JWT tokens for prototype, OAuth2 for production.

User ID Management

When integrating authorization, you need to decide how users will be mapped between the main product and QuickPass. There are two main approaches:

Option 1: Unified Identifiers

Principle: userId in QuickPass corresponds to userId in the main product

Implementation:

• Users have identical IDs in both systems
• Common userId is passed during authorization
• Direct mapping without additional connections

Advantages:

• Simplicity of implementation and support
• Fast user search
• Minimal overhead

Integration Example:

{
  "user_id": "12345",
  "source": "main_product"
}

Option 2: Linked Accounts

Principle: QuickPass uses its own userId system, and the main product account is linked as an external profile

Implementation:

• Each QuickPass user has a unique internal ID
• Main product account is added as a linked social network profile
• Storage: source="main_product" and source_id="{main product userId}"
• Support for multiple links to one QuickPass account

Data Structure:

{
  "quickpass_user_id": "qp_67890",
  "linked_accounts": [
    {
      "source": "main_product",
      "source_id": "12345",
      "linked_at": "2024-01-15T10:30:00Z",
      "status": "active"
    },
    {
      "source": "telegram",
      "source_id": "tg_98765",
      "linked_at": "2024-01-10T15:20:00Z",
      "status": "active"
    }
  ]
}

Advantages:

• Independence of identification systems
• Ability to link multiple external accounts
• Flexibility during migrations and changes
• Compliance with QuickPass social integration architecture

API Request Example:

POST /api/v1/users/accounts
{
  "quickpass_user_id": "qp_67890",
  "source": "main_product",
  "source_id": "12345",
  "verification_token": "jwt_token_from_main_product"
}

Account Linking Process

1. Primary Authorization:

   • User authorizes in the main product through integration options
   • QuickPass receives userId from the main product

2. Account Creation or Search:

   • QuickPass checks if there's already a link with source="main_product" and given source_id
   • If exists - authorizes existing user
   • If not - creates new QuickPass account or offers to link to existing one

3. Link Establishment:

   • Save linked account record
   • Set active QuickPass session
   • Ability to use any authorization method in the future