@soapjs/soap-auth 0.1.0

package/build/types.d.ts

@@ -0,0 +1,251 @@
+import * as Soap from "@soapjs/soap";
+import { LocalStrategyConfig } from "./strategies/local/local.types";
+import { OAuth2StrategyConfig } from "./strategies/oauth2/oauth2.types";
+import { ApiKeyStrategyConfig } from "./strategies/api-key/api-key.types";
+import { BasicStrategyConfig } from "./strategies/basic/basic.types";
+import { JwtConfig } from "./strategies/jwt/jwt.types";
+export interface SessionStore {
+    getSession<T = SessionData>(sid: string, ...args: unknown[]): Promise<T | null>;
+    setSession<T = SessionData>(sid: string, session: T, ...args: unknown[]): void | Promise<void>;
+    destroySession(sid: string, ...args: unknown[]): void | Promise<void>;
+    touchSession<T = SessionData>(sid: string, session: T, ...args: unknown[]): void | Promise<void>;
+}
+export type SessionData = {
+    [key: string]: any;
+} | any;
+export type SessionInfo<TData = any> = {
+    sessionId: string;
+    data: TData;
+};
+export interface SessionConfig {
+    secret: string;
+    resave?: boolean;
+    saveUninitialized?: boolean;
+    store?: SessionStore;
+    sessionKey?: string;
+    sessionHeader?: string;
+    generateSessionId?: (...args: unknown[]) => string;
+    createSessionData?: <T>(data?: unknown, context?: unknown) => T;
+    embedSessionId?: (context: any, sessionId: string) => void;
+    getSessionId(context: any): string | null;
+    [key: string]: any;
+}
+export type Credentials = {
+    id: string;
+    hashedPassword: string;
+    [key: string]: unknown;
+};
+export interface AuthResultConfig<TContext = unknown, TUser = unknown> {
+    onSuccess?: (context: AuthSuccessContext<TUser, TContext>) => Promise<void> | void;
+    onFailure?: (context: AuthFailureContext<TContext>) => Promise<void> | void;
+}
+export interface SecurityConfig {
+    security?: {
+        maxFailedLoginAttempts?: number;
+        lockoutDuration?: number;
+        notifyOnLockout?: (account: any) => Promise<void>;
+    };
+}
+export interface BaseAuthStrategyConfig<TContext = unknown, TUser = unknown> extends AccountLockConfig<TContext>, RateLimitConfig, RoleAuthorizationConfig<TUser>, SecurityConfig {
+    mfa?: MfaConfig<TUser, TContext>;
+    session?: SessionConfig;
+}
+export interface AuditLoggingConfig<TContext = unknown> {
+    logAttempt?: (userId: string, success: boolean, context?: TContext) => Promise<void>;
+    logPasswordChange?: (userId: string, context?: TContext) => Promise<void>;
+}
+export interface MfaConfig<TUser = unknown, TContext = unknown> {
+    extractMfaCode?: (context?: TContext) => string;
+    sendMfaCode?: (user: TUser, context?: TContext) => Promise<boolean>;
+    validateMfaCode?: (user: TUser, code: string) => Promise<boolean>;
+    isMfaRequired?: (user: TUser) => boolean;
+    generateMfaSecret?: (user: TUser) => Promise<string>;
+    verifyMfaSetup?: (user: TUser, secret: string) => Promise<boolean>;
+    disableMfa?: (user: TUser) => Promise<void>;
+    generateBackupCodes?: (user: TUser) => Promise<string[]>;
+    validateBackupCode?: (user: TUser, code: string) => Promise<boolean>;
+    maxMfaAttempts?: number;
+    lockMfaOnFailure?: (user: TUser) => Promise<void>;
+    getMfaAttempts?: (user: TUser) => Promise<number>;
+    resetMfaAttempts?: (user: TUser) => Promise<void>;
+    incrementMfaAttempts?: (user: TUser) => Promise<void>;
+}
+export interface PasswordPolicyConfig {
+    validatePassword?: (password: string) => boolean;
+    getLastPasswordChange?: (identifier: string) => Date;
+    forcePasswordChangeOnFirstLogin?: boolean;
+    passwordExpirationDays?: number;
+}
+export interface CredentialBasedAuthStrategyConfig<TContext = unknown, TUser = unknown> extends BaseAuthStrategyConfig<TContext, TUser> {
+    passwordPolicy?: PasswordPolicyConfig;
+    audit?: AuditLoggingConfig<TContext>;
+    logout: {} & AuthResultConfig<TContext, TUser>;
+    login: {
+        extractCredentials: (context: TContext) => Promise<{
+            identifier: string;
+            password: string;
+        }>;
+        retrieveUserData: (identifier: string) => Promise<TUser | null>;
+        verifyUserCredentials: (identifier: string, password: string) => Promise<boolean>;
+        incrementFailedAttempts?: (identifier: string) => Promise<void>;
+        resetFailedAttempts?: (identifier: string) => Promise<void>;
+        getFailedAttempts?: (identifier: string) => Promise<number>;
+    } & AuthResultConfig<TContext, TUser>;
+    passwordReset?: {
+        generateResetToken?: (identifier: string) => Promise<string>;
+        sendResetEmail?: (identifier: string, token: string) => Promise<void>;
+        validateResetToken?: (token: string) => Promise<boolean>;
+        updatePassword?: (identifier: string, newPassword: string) => Promise<void>;
+    } & AuthResultConfig<TContext, TUser>;
+}
+export interface TokenBasedAuthStrategyConfig<TContext = unknown, TUser = unknown> extends BaseAuthStrategyConfig<TContext, TUser>, TokenRotationConfig<TUser> {
+    tokens?: TokenHandlersConfig;
+    login: {
+        retrieveUserData: (identifier: string) => Promise<TUser | null>;
+    } & AuthResultConfig<TContext, TUser>;
+    logout: {} & AuthResultConfig<TContext, TUser>;
+}
+export interface TokenRotationConfig<TUser = unknown> {
+    enableRotation?: boolean;
+    maxRotations?: number;
+    storeUsedTokens?: boolean;
+    getRefreshToken?: (user: TUser) => Promise<string>;
+    rotateToken?: (refreshToken: string) => Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>;
+    onTokenRotated?: (user: TUser, newTokens: {
+        accessToken: string;
+        refreshToken: string;
+    }) => Promise<void>;
+    onTokenRotationFailure?: (user: TUser, error: Error) => Promise<void>;
+}
+export interface AccountLockConfig<TContext = unknown> {
+    logFailedAttempt?: (account: any, context?: TContext) => Promise<void>;
+    lockAccount?: (account: any, ...args: unknown[]) => Promise<void>;
+    isAccountLocked?: (account: any, ...args: unknown[]) => Promise<boolean>;
+}
+export interface RateLimitConfig {
+    checkRateLimit?: (...args: unknown[]) => Promise<boolean>;
+    incrementRequestCount?: (...args: unknown[]) => Promise<void>;
+}
+export interface RoleAuthorizationConfig<TUser = unknown> {
+    authorizeByRoles?: (user: TUser, roles: string[]) => Promise<boolean>;
+    roles?: string[];
+}
+export type AuthSuccessContext<TUser = unknown, TContext = unknown, TSessionData = unknown> = {
+    user?: TUser;
+    context?: TContext;
+    session?: SessionInfo<TSessionData>;
+    tokens?: string;
+    identifier?: string;
+    email?: string;
+};
+export type AuthFailureContext<TContext = unknown> = {
+    error: Error;
+    context?: TContext;
+    identifier?: string;
+    email?: string;
+};
+export type AuthResult<TUser, TSessionData = unknown> = {
+    user: TUser;
+    session?: SessionInfo<TSessionData>;
+    tokens?: {
+        accessToken?: string;
+        refreshToken?: string | null;
+        apiKey?: string | null;
+    };
+};
+export interface AuthStrategy<TContext = unknown, TUser = unknown> {
+    init?(...args: unknown[]): Promise<void>;
+    authenticate(context?: TContext, ...args: unknown[]): Promise<AuthResult<TUser>>;
+    authorize?(user: any, action: string, resource?: string): Promise<boolean>;
+    refresh?(refreshToken: string): Promise<string>;
+    logout?(context?: TContext): Promise<void>;
+}
+export interface SoapHttpAuthConfig<TContext = unknown, TUser = unknown> {
+    local?: LocalStrategyConfig<TContext, TUser>;
+    oauth2?: {
+        [provider: string]: OAuth2StrategyConfig<TContext, TUser>;
+    };
+    apiKey?: ApiKeyStrategyConfig<TContext, TUser>;
+    jwt?: JwtConfig<TContext, TUser>;
+    basic?: BasicStrategyConfig<TContext, TUser>;
+    custom: {
+        [label: string]: AuthStrategy;
+    };
+}
+export interface SoapSocketAuthConfig<TContext = unknown, TUser = unknown> {
+    jwt?: JwtConfig<TContext, TUser>;
+    apiKey?: ApiKeyStrategyConfig<TContext, TUser>;
+    custom: {
+        [provider: string]: AuthStrategy;
+    };
+}
+export interface SoapAuthConfig<TContext = unknown, TUser = unknown> {
+    session?: SessionConfig;
+    tokens?: TokenHandlersConfig;
+    http?: SoapHttpAuthConfig<TContext, TUser>;
+    socket?: SoapSocketAuthConfig<TContext, TUser>;
+    logger?: Soap.Logger;
+}
+export interface CookieStorageOptions {
+    cookieName: string;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    maxAge?: number;
+}
+export interface HeaderStorageOptions {
+    headerName: string;
+    scheme?: string;
+    extractor: (scheme: string) => string | null;
+}
+export interface BodyStorageOptions {
+    name: string;
+    extractor: (name: string) => string | null;
+}
+export interface QueryStorageOptions {
+    name: string;
+    extractor: (name: string) => string | null;
+}
+export interface SessionStorageOptions {
+    name: string;
+    extractor: (name: string) => string | null;
+}
+export interface DatabaseOptions {
+    extractor: (...args: unknown[]) => Promise<string | null>;
+}
+export interface StorageContext {
+    storeInHeader?: (data: string, options?: HeaderStorageOptions) => Promise<void> | void;
+    storeInCookie?: (data: string, options?: CookieStorageOptions) => Promise<void> | void;
+    storeInSession?: (data: string, name?: string) => Promise<void> | void;
+    storeInBody?: (data: string, name?: string) => Promise<void> | void;
+    getFromHeader?: (options?: HeaderStorageOptions) => Promise<string | null> | string | null;
+    getFromCookie?: (cookieName: string) => Promise<string | undefined> | string | undefined;
+    getFromSession?: (name: string) => Promise<string | undefined> | string | undefined;
+    getFromBodyField?: (name: string) => Promise<string | undefined> | string | undefined;
+    removeFromCookie?: (cookieName: string) => Promise<void> | void;
+    removeFromSession?: (name: string) => Promise<void> | void;
+    encrypt?: (data: string) => Promise<string> | string;
+    decrypt?: (data: string) => Promise<string> | string;
+}
+export interface TokenHandlerConfig {
+    secretKey: string;
+    expiresIn: string | number;
+    audience?: string | string[];
+    issuer?: string | string[];
+    subject?: string;
+    tokenType?: string;
+    generate?: (payload: any) => string;
+    verify?: (token: string) => Promise<any>;
+    store?: (token: string, data: any, expiresIn: number) => Promise<void>;
+    retrieve?: (context: any) => Promise<string | null>;
+    remove?: (context: any) => Promise<void>;
+    embed?: (context: any, token: string) => void;
+    rotate?: (oldToken: string) => Promise<string>;
+}
+export interface TokenHandlersConfig {
+    access: TokenHandlerConfig;
+    refresh?: TokenHandlerConfig;
+}

package/build/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/jest.config.unit.json

@@ -0,0 +1,10 @@
+{
+  "preset": "ts-jest",
+  "testEnvironment": "node",
+  "clearMocks": true,
+  "collectCoverage": true,
+  "coverageDirectory": "coverage",
+  "coverageProvider": "v8",
+  "testMatch": ["**/__tests__/**/*.test.ts"],
+  "testTimeout": 10000
+}

package/ldap.md

@@ -0,0 +1,62 @@
+## **LDAP Authentication Strategy - Example (WIP)**
+
+The `LdapStrategy` allows authentication via an LDAP server. It extends the base `CredentialBasedAuthStrategy` and provides methods for user authentication, authorization, and session management.
+
+### **Installation**
+
+Before using the LDAP strategy, ensure you have installed the necessary package:
+
+```bash
+npm install ldapjs
+```
+
+### **Example Usage**
+
+```typescript
+import { LdapStrategy, LdapStrategyConfig } from "./strategies/ldap-strategy";
+
+const ldapConfig: LdapStrategyConfig = {
+  ldapUrl: "ldap://ldap.example.com",
+  baseDn: "ou=users,dc=example,dc=com",
+  bindDn: "cn=admin,dc=example,dc=com",
+  bindCredentials: "adminpassword",
+  userFilter: "(uid={{identifier}})",
+  groupFilter: "(memberUid={{identifier}})",
+  mapUserAttributes: (entry) => ({
+    id: entry.uid,
+    fullName: entry.cn,
+    email: entry.mail,
+  }),
+};
+
+const ldapAuth = new LdapStrategy(ldapConfig);
+
+async function authenticateUser(username: string, password: string) {
+  try {
+    const result = await ldapAuth.authenticate({ identifier: username, password });
+    console.log("User authenticated:", result.user);
+  } catch (error) {
+    console.error("Authentication failed:", error.message);
+  }
+}
+```
+
+### **Features**
+
+- Binds to the LDAP server using provided credentials.
+- Retrieves user data based on LDAP search filters.
+- Supports group membership verification (optional).
+- Provides session management.
+- Easily extendable and configurable.
+
+### **Configuration Options**
+
+| Option             | Description                                                  | Required |
+|-------------------|--------------------------------------------------------------|----------|
+| `ldapUrl`          | URL of the LDAP server                                       | ✅        |
+| `baseDn`           | Base DN (Distinguished Name) for searching users             | ✅        |
+| `bindDn`           | DN used to bind to the LDAP server                           | ✅        |
+| `bindCredentials`  | Password for the binding DN                                  | ✅        |
+| `userFilter`       | LDAP filter to find users, e.g. `"(uid={{identifier}})"`     | ✅        |
+| `groupFilter`      | (Optional) LDAP filter to check group membership             | ❌        |
+| `mapUserAttributes`| Function to map LDAP user attributes to application structure| ❌        |

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@soapjs/soap-auth",
+  "version": "0.1.0",
+  "description": "",
+  "homepage": "https://docs.soapjs.com",
+  "repository": "https://github.com/soapjs/soap-auth",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "license": "MIT",
+  "author": "Radoslaw Kamysz",
+  "scripts": {
+    "test:unit": "jest --config=jest.config.unit.json",
+    "clean": "rm -rf ./build",
+    "build": "npm run clean && tsc -b",
+    "prepublish": "npm run clean && tsc --project tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@soapjs/soap": "^0.5.2",
+    "@types/jest": "^27.0.3",
+    "jest": "^27.4.5",
+    "ts-jest": "^27.1.3",
+    "typescript": "^4.8.2"
+  },
+  "peerDependencies": {
+    "@soapjs/soap": ">=0.5.2"
+  },
+  "dependencies": {
+    "axios": "^1.7.9",
+    "bcrypt": "^5.1.1",
+    "jsonwebtoken": "^9.0.2",
+    "uuid": "^9.0.1"
+  }
+}

package/saml.md

@@ -0,0 +1,244 @@
+# **SAML Authentication Strategy (Google Workspace) - Example (WIP)**
+
+This guide provides an example of implementing SAML authentication without Passport.js, using Google Workspace as the Identity Provider (IdP).
+
+---
+
+## **1. Installation**
+
+Install the required dependencies:
+
+```bash
+npm install samlify xml-crypto express
+```
+
+---
+
+## **2. Configure Google Workspace (IdP)**
+
+To set up Google as the Identity Provider (IdP):
+
+1. **Sign in to Google Admin Console** ([admin.google.com](https://admin.google.com/)).
+2. Navigate to **Apps > Web and Mobile Apps > Add App > Custom SAML App**.
+3. Copy the following details from Google and save them in your project:
+   - **SSO URL** (Single Sign-On Service)
+   - **Entity ID** (Issuer)
+   - **X.509 Certificate** (for validating SAML assertions)
+4. Configure the ACS URL (Assertion Consumer Service) to point to your application, e.g.:
+   ```
+   https://your-app.com/auth/saml/callback
+   ```
+5. Map attributes such as:
+   - `email`
+   - `first_name`
+   - `last_name`
+
+Save Google IdP metadata as `google-idp-metadata.xml` in your project.
+
+---
+
+## **3. Project Structure**
+
+```
+/saml-auth
+  ├── config/
+  │   ├── google-idp-metadata.xml  # Metadata from Google Admin
+  │   ├── sp-private-key.pem        # Service provider private key
+  │   ├── sp-public-cert.pem        # Service provider public certificate
+  ├── src/
+  │   ├── saml-strategy.ts          # SAML authentication strategy
+  │   ├── server.ts                  # Express server to handle requests
+  ├── package.json
+  ├── README.md
+```
+
+---
+
+## **4. Implementing the SAML Strategy**
+
+### **saml-strategy.ts**
+
+```typescript
+import * as saml from "samlify";
+import * as fs from "fs";
+
+export class SAMLStrategy {
+  private serviceProvider: saml.ServiceProviderInstance;
+  private identityProvider: saml.IdentityProviderInstance;
+
+  constructor() {
+    // Load IdP metadata (from Google)
+    this.identityProvider = saml.IdentityProvider({
+      metadata: fs.readFileSync("./config/google-idp-metadata.xml", "utf-8"),
+      isAssertionEncrypted: false,
+      wantAuthnRequestsSigned: true,
+    });
+
+    // Configure the Service Provider (our application)
+    this.serviceProvider = saml.ServiceProvider({
+      entityID: "https://your-app.com/metadata",
+      assertionConsumerService: [
+        {
+          Binding: saml.Constants.namespace.post,
+          Location: "https://your-app.com/auth/saml/callback",
+        },
+      ],
+      privateKey: fs.readFileSync("./config/sp-private-key.pem", "utf-8"),
+    });
+  }
+
+  /**
+   * Generates SAML login URL to redirect users to Google Workspace SSO
+   * @returns {Promise<string>} SSO Login URL
+   */
+  async getLoginUrl(): Promise<string> {
+    const { context } = await this.serviceProvider.createLoginRequest(
+      this.identityProvider,
+      "redirect"
+    );
+    return context; // SSO login URL for redirecting user
+  }
+
+  /**
+   * Handles SAML response from Google and extracts user info.
+   * @param {object} requestBody - The HTTP POST body containing SAMLResponse
+   * @returns {Promise<object>} Parsed user data
+   */
+  async handleSamlResponse(requestBody: any): Promise<object> {
+    if (!requestBody.SAMLResponse) {
+      throw new Error("Missing SAML response.");
+    }
+
+    const { extract } = await this.serviceProvider.parseLoginResponse(
+      this.identityProvider,
+      "post",
+      requestBody
+    );
+
+    return {
+      email: extract.attributes.email,
+      firstName: extract.attributes.first_name,
+      lastName: extract.attributes.last_name,
+    };
+  }
+}
+```
+
+---
+
+## **5. Handling authentication in Express.js**
+
+### **server.ts**
+
+```typescript
+import express from "express";
+import { SAMLStrategy } from "./saml-strategy";
+
+const app = express();
+const samlAuth = new SAMLStrategy();
+
+app.get("/auth/saml/login", async (req, res) => {
+  try {
+    const loginUrl = await samlAuth.getLoginUrl();
+    res.redirect(loginUrl);
+  } catch (error) {
+    res.status(500).send("Error generating login request.");
+  }
+});
+
+app.post("/auth/saml/callback", express.urlencoded({ extended: false }), async (req, res) => {
+  try {
+    const userData = await samlAuth.handleSamlResponse(req.body);
+    res.json({ message: "Authentication successful", user: userData });
+  } catch (error) {
+    res.status(401).send("Authentication failed");
+  }
+});
+
+app.listen(3000, () => {
+  console.log("Server running on http://localhost:3000");
+});
+```
+
+---
+
+## **6. Running the Application**
+
+1. Start the server:
+
+   ```bash
+   node dist/server.js
+   ```
+
+2. Open the browser and go to:
+
+   ```bash
+   http://localhost:3000/auth/saml/login
+   ```
+
+   You will be redirected to Google for login.
+
+3. After successful login, you will be redirected to the callback URL, and your user information will be displayed.
+
+---
+
+## **7. Additional Features**
+
+You can extend the SAML strategy with:
+
+1. **Single Logout (SLO) Support**
+   - Implement an endpoint to handle logout requests from the IdP.
+
+2. **Custom Attribute Mapping**
+   - Customize user attributes in the response (e.g. department, roles).
+
+3. **Multi-IdP Support**
+   - Allow configuration for multiple SAML providers dynamically.
+
+4. **Session Management**
+   - Store authenticated user session in Redis or JWT.
+
+---
+
+## **8. Environment Variables Example**
+
+To keep sensitive data secure, use environment variables:
+
+```
+SP_ENTITY_ID=https://your-app.com/metadata
+SP_CALLBACK_URL=https://your-app.com/auth/saml/callback
+SP_PRIVATE_KEY_PATH=./config/sp-private-key.pem
+IDP_METADATA_PATH=./config/google-idp-metadata.xml
+```
+
+And access them in code like this:
+
+```typescript
+import dotenv from "dotenv";
+dotenv.config();
+
+const spEntityId = process.env.SP_ENTITY_ID;
+const callbackUrl = process.env.SP_CALLBACK_URL;
+```
+
+---
+
+## **9. Security Considerations**
+
+1. **Always validate the SAML response signature to prevent tampering.**
+2. **Rotate the private keys regularly and store them securely.**
+3. **Monitor SAML authentication logs for suspicious activity.**
+
+---
+
+## **10. Conclusion**
+
+This guide provided a simple yet powerful way to implement SAML authentication without relying on external frameworks like Passport.js. The setup allows easy integration with Google Workspace while ensuring flexibility and control over the authentication process.
+
+---
+
+### **11. Useful Resources**
+
+- [Google Workspace SAML Setup](https://support.google.com/a/answer/6087519?hl=en)
+- [samlify npm package](https://www.npmjs.com/package/samlify)
+- [SAML Explained](https://www.okta.com/identity-101/what-is-saml/)