@zango/login

A dynamic and flexible login package for Zango CRM React applications that adapts to various authentication configurations.

Features

• Dynamic Authentication Methods
  • Password-based authentication
  • OTP (One-Time Password) via email/mobile
  • SSO (Single Sign-On) integration
  • OAuth/OIDC providers (Google, Microsoft, GitHub, LinkedIn, Facebook, Apple, Slack, Twitter)
• Adaptive UI - Automatically adjusts based on enabled authentication methods
• Multi-username Support - Email and/or mobile number login
• Multi-Factor Authentication - 2FA support via email/mobile
• Role Selection - Support for users with multiple roles
• OAuth Callback Handling - Secure OAuth flow with CSRF protection
• Forgot/Reset Password flow
• Authentication State Management
• Fully Customizable - Styling, branding, and behavior
• Built with React and Ant Design

Installation

npm install @zango/login

Basic Usage

Dynamic Configuration (Recommended)

The login page automatically fetches authentication methods from your API:

import { LoginPage, AuthProvider } from '@zango/login';

function App() {
  const handleLogin = async (credentials) => {
    // Handle login based on the method used
    console.log('Login attempt:', credentials);
  };

  return (
    <AuthProvider>
      <LoginPage 
        onLogin={handleLogin}
        logo="/path/to/logo.png"
        title="Welcome to Zango CRM"
        subtitle="Please login to continue"
        useDynamicConfig={true} // Fetches config from API
        apiConfig={{
          loginMethodsEndpoint: '/api/v1/login/?action=fetch_methods'
        }}
      />
    </AuthProvider>
  );
}

Static Configuration

You can also provide a static configuration:

<LoginPage 
  onLogin={handleLogin}
  staticConfig={{
    usernames: ['email', 'mobile'],
    methods: {
      password: {
        enabled: true,
        forgot_password_enabled: true
      },
      otp: {
        enabled: true,
        usernames: ['email', 'mobile'],
        otp_digits: 6,
        retry_interval_in_seconds: 30
      }
    }
  }}
/>

Configuration API

The login methods configuration endpoint should return:

{
  "usernames": ["email", "mobile"],
  "methods": {
    "password": {
      "enabled": true,
      "forgot_password_enabled": true
    },
    "sso": {
      "enabled": true,
      "providers": [
        {"name": "Company SSO", "icon": "", "url": "https://sso.company.com"}
      ]
    },
    "oidc": {
      "enabled": true,
      "providers": [
        {"name": "Google", "icon": "", "url": "https://accounts.google.com"},
        {"name": "Microsoft", "icon": "", "url": "https://login.microsoft.com"}
      ]
    },
    "otp": {
      "enabled": true,
      "usernames": ["email", "mobile"],
      "otp_digits": 6,
      "retry_interval_in_seconds": 30
    }
  }
}

Components

LoginPage

Main login page that dynamically adapts to authentication configuration.

Props:

• onLogin - Callback function for handling login
• logo - Logo element or image URL
• title - Page title
• subtitle - Page subtitle
• useDynamicConfig - Enable dynamic configuration fetching (default: true)
• staticConfig - Static configuration object
• apiConfig - API configuration for endpoints

DynamicLoginForm

Adaptive form that renders different authentication methods based on configuration.

OTPForm

Complete OTP authentication flow with request and verification steps.

OTPInput

Customizable OTP input component with auto-focus and paste support.

ProviderButton

SSO/OIDC provider button with built-in icons and styling.

LoginForm

Traditional username/password login form (fallback).

ForgotPasswordForm

Form for requesting password reset emails.

ResetPasswordForm

Form for resetting password with token.

AuthProvider

Context provider for authentication state management.

CompleteAuthFlow

Handles multi-step authentication flow including role selection, 2FA, and password reset.

OAuthCallbackPage

Processes OAuth provider callbacks and handles the authentication flow.

OAuthCallback

Component that handles OAuth provider responses and error states.

SecondFactorAuth

Two-factor authentication component supporting email and mobile verification.

RoleSelection

Role selection component for users with multiple roles.

PasswordResetRequired

Forces password reset when required by security policies.

Hooks

useAuth

Hook to access authentication context and methods.

Services

authService

Service for handling authentication API calls.

Configuration

The package can be configured through the AuthProvider:

<AuthProvider config={{
  loginEndpoint: '/api/auth/login',
  tokenKey: 'myAppToken',
  apiClient: customApiClient
}}>
  {/* Your app */}
</AuthProvider>

OAuth/SSO Integration

Setting Up OAuth Providers

1. Configure OAuth URLs in fetch_methods response:

{
  "methods": {
    "oidc": {
      "enabled": true,
      "providers": [
        {
          "name": "Google",
          "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https://app.example.com/auth/callback&response_type=code&scope=openid%20email%20profile"
        }
      ]
    }
  }
}

2. Set up OAuth callback route:

import { OAuthCallbackPage } from '@zango/login';
import { useNavigate } from 'react-router-dom';

function AuthCallback() {
  const navigate = useNavigate();
  
  const handleAuthComplete = (result) => {
    // Store token, update user state
    localStorage.setItem('authToken', result.token);
    // Redirect to dashboard
    navigate('/dashboard');
  };
  
  return (
    <OAuthCallbackPage
      onAuthComplete={handleAuthComplete}
      apiConfig={{
        oauthCallbackEndpoint: '/api/auth/oauth/callback'
      }}
    />
  );
}

// In your router configuration
<Route path="/auth/callback" element={<AuthCallback />} />

3. Handle multi-step authentication:

import { CompleteAuthFlow } from '@zango/login';

function Login() {
  return (
    <CompleteAuthFlow
      logo="/logo.png"
      title="Welcome Back"
      onAuthComplete={(result) => {
        // Handle successful authentication
        console.log('Auth complete:', result);
      }}
      roleSelectionTitle="Select Your Role"
      twoFactorTitle="Verify Your Identity"
      passwordResetTitle="Update Your Password"
    />
  );
}

OAuth Security Features

• CSRF Protection: Automatic state parameter generation and validation
• Secure Token Handling: Tokens are securely processed and stored
• Error Handling: Comprehensive error handling for OAuth failures
• Provider Support: Built-in support for major OAuth providers

Development

Running Standalone

To run the login package as a standalone application for development:

# Install dependencies
npm install

# Start the development server (runs on port 3001)
npm start

This will launch a development environment with:

• Live reloading
• Example implementations of all components
• Mock authentication API
• React Router integration

Development Features

The standalone app includes:

• Configuration Selector - Test different authentication scenarios
• Mock API - Simulates all authentication endpoints
• Test Scenarios:
  • All Methods Enabled - Password, OTP, SSO, and OIDC
  • Password Only - Traditional login
  • OTP Only - Email/mobile OTP authentication
  • Social Login Only - OIDC providers only
  • Password + OTP - Combined authentication
  • Mobile Only - Mobile number authentication
• Demo Credentials:
  • Email: [email protected]
  • Mobile: 1234567890
  • Password: password
  • OTP: Check console for mock OTP

Building

# Build the library for distribution
npm run build

# Build the development app
npm run build:dev

# Watch mode for library development
npm run dev

License

MIT