@idp.global/idp.global

the code that runs the idp.global platform

readme.md for @idp.global/idp.global

🔐 A modern, open-source Identity Provider (IdP) SaaS platform for managing user authentication, registrations, sessions, and organization-based access control.

Built with TypeScript and designed for modern web applications, idp.global provides a complete identity management solution that you can self-host or use as a service.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

✨ Features

🔑 Authentication & Authorization

🏢 Organization Management

🔗 Third-Party Integration

💳 Billing Integration

🎨 Modern Web UI

📡 Real-Time Communication

🏗️ Architecture

idp.global is built as a modular TypeScript monorepo:

├── ts/                    # Server-side code (Node.js)
│   └── reception/         # Core identity management logic
├── ts_interfaces/         # Shared TypeScript interfaces (published as @idp.global/interfaces)
├── ts_idpclient/          # Browser/Node client library (published as @idp.global/idpclient)
├── ts_idpcli/             # Command-line interface tool
└── ts_web/                # Web frontend (published as @idp.global/web)

Core Managers

Manager Responsibility
JwtManager JWT generation, validation, and key management
LoginSessionManager Session creation and authentication
UserManager User CRUD and profile management
OrganizationManager Organization lifecycle management
RoleManager RBAC and permission management
OidcManager OpenID Connect provider functionality
AppManager OAuth client app registration
BillingPlanManager Subscription and payment handling

🚀 Quick Start

🐳 Docker Deployment (Recommended)

The easiest way to run idp.global is using Docker:

# Pull the latest image
docker pull code.foss.global/idp.global/idp.global

# Run with environment variables
docker run -d \
  -p 2999:2999 \
  -e MONGODB_URL=mongodb://your-mongo:27017/idp \
  -e IDP_BASEURL=https://your-domain.com \
  -e INSTANCE_NAME=idp.global \
  code.foss.global/idp.global/idp.global

Environment Variables

Variable Description Required
MONGODB_URL MongoDB connection string ✅ Yes
IDP_BASEURL Public URL of your idp.global instance ✅ Yes
INSTANCE_NAME Name for this IDP instance No (default: idp.global)
SERVEZONE_PLATFROM_AUTHORIZATION ServeZone platform auth token No

Docker Compose Example

version: '3.8'
services:
  idp:
    image: code.foss.global/idp.global/idp.global
    ports:
      - "2999:2999"
    environment:
      MONGODB_URL: mongodb://mongo:27017/idp
      IDP_BASEURL: https://idp.yourdomain.com
      INSTANCE_NAME: my-idp
    depends_on:
      - mongo

  mongo:
    image: mongo:7
    volumes:
      - mongo-data:/data/db

volumes:
  mongo-data:

The server listens on port 2999 by default.

🛠️ Local Development

Prerequisites

Getting Started

# Clone the repository
git clone https://code.foss.global/idp.global/idp.global.git
cd idp.global

# Install dependencies
pnpm install

# Build the project
pnpm build

# Start development server with hot reload
pnpm watch

The server runs on http://localhost:2999 with:

Environment Setup

Create environment variables for the backend:

export MONGODB_URL=mongodb://localhost:27017/idp-dev
export IDP_BASEURL=http://localhost:2999
export INSTANCE_NAME=idp-dev

Development Routes

Route Description
/ Welcome/landing page
/login Sign in form
/register New user registration
/account User dashboard (requires auth)

🔑 Default Development Credentials

For local development with the test database, use:

Field Value
Email/Username admin@idp.global or admin
Password admin

This account has isGlobalAdmin: true for full platform access including the admin panel at /account/admin.

⚠️ Security Note: These credentials are for local development only. Never use default credentials in production environments.

📦 Published Packages

This monorepo publishes the following npm packages:

Package Description
@idp.global/interfaces TypeScript interfaces for API contracts
@idp.global/idpclient Client library for browser and Node.js
@idp.global/web Web UI components

💻 Client Usage

Browser Client

import { IdpClient } from '@idp.global/idpclient';

// Initialize the client
const idpClient = new IdpClient('https://idp.global');

// Enable WebSocket connection
await idpClient.enableTypedSocket();

// Check login status
const isLoggedIn = await idpClient.determineLoginStatus();

// Login with email and password
const response = await idpClient.requests.loginWithUserNameAndPassword.fire({
  username: 'user@example.com',
  password: 'securepassword'
});

if (response.refreshToken) {
  await idpClient.refreshJwt(response.refreshToken);
  console.log('✅ Login successful!');
}

// Get current user info
const userInfo = await idpClient.whoIs();
console.log('User:', userInfo.user);

// Get user's organizations
const orgs = await idpClient.getRolesAndOrganizations();
console.log('Organizations:', orgs.organizations);

Organization Management

// Create a new organization
const result = await idpClient.createOrganization('My Company', 'my-company', 'manifest');
console.log('Created:', result.resultingOrganization);

// Invite members
await idpClient.requests.createInvitation.fire({
  jwt: await idpClient.getJwt(),
  organizationId: 'org-id',
  email: 'newmember@example.com',
  roles: ['member']
});

CLI Tool

The ts_idpcli module provides a command-line interface:

# Login
idp login

# Show current user
idp whoami

# List organizations
idp orgs

# List organization members
idp members --org <org-id>

# Invite a user
idp invite --org <org-id> --email user@example.com

🔐 OIDC Integration

idp.global implements a full OpenID Connect provider. Third-party applications can use it for SSO:

Discovery Document

GET /.well-known/openid-configuration

Authorization Flow

GET /oauth/authorize?
  client_id=your-client-id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=openid profile email organizations&
  state=random-state&
  code_challenge=PKCE_CHALLENGE&
  code_challenge_method=S256

Token Exchange

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://yourapp.com/callback&
client_id=your-client-id&
client_secret=your-client-secret&
code_verifier=PKCE_VERIFIER

UserInfo

GET /oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Response:

{
  "sub": "user-id",
  "name": "John Doe",
  "email": "john@example.com",
  "email_verified": true,
  "organizations": [
    { "id": "org-1", "name": "Acme Corp", "slug": "acme", "roles": ["admin"] }
  ],
  "roles": ["user"]
}

🛠️ Tech Stack

📚 API Reference

Request Interfaces

All API requests are type-safe. See ts_interfaces/request/ for the complete API:

Data Models

See ts_interfaces/data/ for all data structures:

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

changelog.md for @idp.global/idp.global

2026-01-29 - 1.16.0 - feat(dev)

add local development docs, update tswatch preset and add Playwright screenshots

2026-01-29 - 1.15.0 - feat(build)

add tsbundle/tswatch configs, update build/watch scripts, bump dependencies, and add CLI documentation

2025-12-22 - 1.14.1 - fix(oidc)

migrate OIDC endpoints and internal handlers to use typedserver IRequestContext and update dependencies

2025-12-16 - 1.14.0 - feat(docs)

add package READMEs and publish metadata; update web package publish order

2025-12-15 - 1.13.0 - feat(oidc)

feat(oidc): add OIDC provider (OidcManager, endpoints, and interfaces)

2025-12-15 - 1.12.1 - fix(dependencies)

fix(deps): bump @uptime.link/webwidget to ^1.2.6

2025-12-15 - 1.12.0 - feat(interfaces)

Add JWT public-key and blocklist request interfaces, publish ordering files, and update dependencies

2025-12-14 - 1.11.0 - feat(idpcli)

Add idp CLI (IdpCli) with commands, file-based credential storage, typed request APIs; bump deps and update config

2025-12-07 - 1.10.0 - feat(billingplan)

Add Paddle v2 checkout support and backend config endpoint; add CSP headers and bump typedserver

2025-12-01 - 1.9.0 - feat(account)

Refactor account UI: migrate modals to promise-based show() API and improve navigation URL tracking

2025-12-01 - 1.8.0 - feat(reception)

Add activity logging, session metadata and org-selection UI (backend and frontend)

2025-12-01 - 1.7.0 - feat(admin)

Add global admin functionality: backend admin APIs, model fields and UI integration

2025-12-01 - 1.6.0 - feat(apps)

Add Apps subsystem: App and AppConnection models, managers, typed request handlers, web UI routes and documentation

2025-12-01 - 1.5.0 - feat(account)

Refactor account UI styles into reusable design tokens, apply updated styles across views and fix login submit behavior

2025-04-03 - 1.4.3 - fix(website)

Update packageManager configuration in package.json and refine view container background styling

2024-12-11 - 1.5.0 - feat(UI)

Added 'Learn more about idp.global' button

2024-12-11 - 1.5.0 - feat(UI)

Added 'Learn more about idp.global' button

2024-10-12 - 1.4.2 - fix(UI)

Improve text rendering in account navigation.

2024-10-07 - 1.4.1 - fix(core)

Bug fixes and UI enhancements

2024-10-07 - 1.4.0 - feat(core)

Refactored plugin and request handling to use 'idpInterfaces'

2024-10-07 - 1.3.1 - fix(account)

Fix: updated cleanupViews method to correctly iterate over children.

2024-10-06 - 1.3.0 - feat(account)

Implement account and organization management features

2024-10-04 - 1.2.2 - fix(core)

Update dependencies and refactor registration process

2024-10-04 - 1.2.1 - fix(core)

Added logging for user email login process and fixed client URL parsing

2024-10-01 - 1.2.0 - feat(web)

Improve UI styling and add registration prompt

2024-10-01 - 1.1.1 - fix(core)

Corrected typos and added missing keywords.

2024-09-29 - 1.1.0 - feat(web)

Implement view container and update elements

2024-09-29 - 1.0.0 - Initial Release

Project initialization and initial documentation setup.