Package Exports

@raddiamond/nexauth-core
@raddiamond/nexauth-core/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@raddiamond/nexauth-core) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

NexAuth Core

A pluggable authentication core supporting Local, Active Directory (AD/LDAP), and UI-based login strategies. Designed for multi-tenant or flexible backend environments using TypeScript and TypeORM.

🔧 Installation

npm install @raddiamond/nexauth-core

✨ Features

🔐 Local database-backed authentication
🧑‍💼 Active Directory (LDAP) login support
🖥️ React UI components for authentication
🏢 Multi-tenant support with client secrets
⚡ Custom user entity support
🔄 Full control over how users and roles are resolved
🧪 Drop-in compatibility with passport via a custom strategy

🧠 Overview

This library expects a TenantContext object to define the authentication method (local, AD, or UI) and its required configuration. It supports:

Your own user entity via LocalUserLookupOptions
External LDAP servers via ADUserLookupOptions
UI-based authentication via UIProviderConfig
Client secrets for secure communication
Custom password field and logic
Custom role mapping

🔄 TenantContext Interface

import { DataSource } from 'typeorm';

export interface TenantContext {
  identityProviderType: 'local' | 'ad' | 'ui';
  dbConnection?: DataSource;
  tenantId?: string;
  clientSecret?: string;

  localUser?: LocalUserLookupOptions<any>;
  adConfig?: {
    url: string;
    bindDN: string;
    bindCredentials: string;
    baseDN: string;
    userLookup: ADUserLookupOptions;
  };
  uiConfig?: UIProviderConfig;
}

🔐 LocalUserLookupOptions

Used when identityProviderType = 'local'. This allows authentication against a custom entity (e.g., User) in your database.

export interface LocalUserLookupOptions<T> {
  entity: new () => T;
  matchField: keyof T;
  passwordField?: string; // Defaults to "passwordHash"
  comparePassword?: (plain: string, hashed: string) => Promise<boolean>; // Defaults to bcrypt.compare
  extractRoles?: (user: T) => string[];
}

Example

import { createIdentityProvider } from '@raddiamond/nexauth-core';
import { User } from './entities/User';
import dataSource from './db';

const provider = createIdentityProvider({
  identityProviderType: 'local',
  dbConnection: dataSource,
  localUser: {
    entity: User,
    matchField: 'email',
    passwordField: 'encrypted_password',
    extractRoles: (user) => user.roles || [],
  },
});

🧑‍💼 ADUserLookupOptions

Used when identityProviderType = 'ad'. This performs authentication via LDAP/AD bind + user search.

export interface ADUserLookupOptions {
  matchField: string; // e.g., "mail", "sAMAccountName"
  extractRoles?: (ldapUser: Record<string, string>) => string[];
  additionalAttributes?: string[]; // Extra LDAP fields to fetch
}

Example

import { createIdentityProvider } from '@raddiamond/nexauth-core';

const provider = createIdentityProvider({
  identityProviderType: 'ad',
  adConfig: {
    url: 'ldap://your-ad-server:389',
    bindDN: 'cn=admin,dc=example,dc=org',
    bindCredentials: 'password',
    baseDN: 'dc=example,dc=org',
    userLookup: {
      matchField: 'mail',
      extractRoles: (user) => user.memberOf ? user.memberOf.split(',') : [],
      additionalAttributes: ['memberOf'],
    },
  },
});

🖥️ UI Components

NexAuth Core now includes React components for authentication UIs:

import { AuthUI } from '@raddiamond/nexauth-core';

function App() {
  return (
    <AuthUI
      clientId="your-client-id"
      clientSecret="your-client-secret"
      tenantId="your-tenant-id"
      apiUrl="https://your-backend.com/api"
      logo="/path/to/logo.png"
      theme="light"
      showRegister={true}
    />
  );
}

See UI_COMPONENTS.md for full documentation on UI components.

🏢 Tenant Management

The TenantManager class helps manage multiple tenants and client secrets:

import { TenantManager } from '@raddiamond/nexauth-core';

// Initialize tenant manager
const tenantManager = new TenantManager();

// Register a tenant
tenantManager.registerTenant('tenant1', {
  identityProviderType: 'local',
  dbConnection: dataSource,
  localUser: {
    entity: User,
    matchField: 'email',
  }
});

// Configure UI provider
const uiConfig = tenantManager.configureUIProvider(
  'tenant1',        // tenantId
  'my-client',      // clientId
  '/auth/callback', // redirectUrl
  ['https://myapp.com'] // allowedOrigins
);

console.log(`Client Secret: ${uiConfig.clientSecret}`);

🧪 Passport Integration

A NexAuthStrategy is provided for Passport.js integration:

import passport from 'passport';
import { NexAuthStrategy } from '@raddiamond/nexauth-core';
import { User } from './entities/User';
import dataSource from './db';

passport.use(
  new NexAuthStrategy(
    {
      field: 'username', // form field name
      providerOptions: {
        identityProviderType: 'local',
        dbConnection: dataSource,
        localUser: {
          entity: User,
          matchField: 'email',
          passwordField: 'password',
        },
      },
    },
    (user, done) => {
      done(null, user); // Passport user session
    }
  )
);

🧱 Session Example

passport.serializeUser((user, done) => {
  done(null, user);
});

passport.deserializeUser((user, done) => {
  done(null, user);
});

@raddiamond/nexauth-core

Package Exports

Readme

NexAuth Core

🔧 Installation

✨ Features

🧠 Overview

🔄 TenantContext Interface

🔐 LocalUserLookupOptions

Example

🧑‍💼 ADUserLookupOptions

Example

🖥️ UI Components

🏢 Tenant Management

🧪 Passport Integration

🧱 Session Example

📄 License