Auth Management Portal

OAuth2/OIDC Authentication Service

Complete Authentication & Authorization Management

Manage users, create OAuth2 applications (tenants), configure permissions, and monitor OAuth2/OIDC authentication with a powerful, secure, and easy-to-use interface.

Key Features

User Management
Create, edit, and manage users with role-based access control
  • Create and manage user accounts
  • Assign roles (Member/Admin)
  • View and revoke active sessions
  • Manage user permissions
Application Management
Register and manage OAuth2/OIDC client applications
  • Register new OAuth2 applications
  • Manage client credentials
  • Configure redirect URIs and scopes
  • Rotate client secrets securely
RBAC & Permissions
Fine-grained permission management and access control
  • Create custom permissions
  • Assign permissions to users
  • Resource-based access control
  • Admin role with full access
Audit Logging
Comprehensive audit trail of all system events
  • View all authentication events
  • Track OAuth2 token operations
  • Filter by user, application, or event type
  • Export audit logs
OAuth2/OIDC Provider
Full-featured OAuth2 and OpenID Connect provider
  • Authorization Code Flow
  • Client Credentials (M2M)
  • PKCE support
  • OIDC discovery endpoints
OTP Authentication
Secure one-time password authentication via email or SMS
  • Email OTP via SendGrid
  • SMS OTP via RingCentral
  • Rate limiting and security
  • Configurable expiry times

Getting Started Guide

1Initial Login

To access the management portal, you need to authenticate using OTP (One-Time Password):

  1. Navigate to the Login page
  2. Enter your email address or phone number
  3. Select verification method (Email or SMS)
  4. Check your email or phone for the 6-digit verification code
  5. Enter the code to complete authentication

Note: The first user to log in will automatically be assigned the ADMIN role. Subsequent users will be MEMBER role by default.

2Managing Users

As an admin, you can manage all system users:

  • View Users: Navigate to Users page to see all registered users with their roles and status
  • Create User: Click "Add User" button to create a new user account. Provide email or phone (at least one required)
  • Edit User: Click the edit icon or navigate to user detail page to modify user details, role (MEMBER/ADMIN), or active status
  • View User Details: Click on a user to see:
    • User information and metadata
    • Active sessions (with IP addresses and user agents)
    • Assigned permissions
  • Revoke Sessions: In user detail page, use "Revoke All Sessions" button to immediately log out a user from all devices
  • Manage Permissions: Click "Manage Permissions" in user detail page to assign or revoke specific permissions to users
  • Delete User: Remove users from the system (use with caution - this action cannot be undone)

Important: Only ADMIN role users can manage other users. MEMBER role users have read-only access. The first user to log in automatically becomes ADMIN.

3Registering OAuth2 Applications (Creating "Tenants")

Each OAuth2 application acts as a "tenant" - a separate client that can authenticate users. To register a new application/tenant:

  1. Go to the Applications page
  2. Click "Register Application"
  3. Enter application name (this represents your tenant/service name)
  4. Select application type:
    • CONFIDENTIAL: For server-side applications (web backends, APIs)
    • PUBLIC: For client-side applications (mobile apps, SPAs)
  5. Add redirect URIs (where users will be redirected after authorization)
    • Example: https://yourapp.com/callback
    • You can add multiple URIs for different environments
  6. Configure scopes (permissions your app will request)
    • Example: openid profile email
    • Scopes define what user information your app can access
  7. Save the application - you'll receive Client ID and Client Secret
    • Important: Save the Client Secret immediately - it's only shown once!
    • You can rotate the secret later if needed

Security Tip: Store Client Secret securely. You can rotate it anytime from the application detail page.

Application Types:

CONFIDENTIALFor server-side applications that can securely store client secrets
PUBLICFor client-side applications (mobile apps, SPAs) that cannot store secrets
4OAuth2 Integration

To integrate OAuth2/OIDC into your application:

1. Authorization Code Flow (Web Apps)

GET /oauth/authorize?
client_id=YOUR_CLIENT_ID
redirect_uri=YOUR_REDIRECT_URI
response_type=code
scope=openid profile email
state=YOUR_STATE
code_challenge=YOUR_PKCE_CHALLENGE
code_challenge_method=S256

2. Exchange Code for Tokens

POST /oauth/token
grant_type=authorization_code
code=AUTHORIZATION_CODE
redirect_uri=YOUR_REDIRECT_URI
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
code_verifier=YOUR_PKCE_VERIFIER

3. Client Credentials Flow (M2M)

POST /oauth/token
grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

Discovery Endpoint: GET /.well-known/openid-configuration for OIDC configuration

5Permission Management

Create and manage fine-grained permissions for RBAC:

  • Navigate to Permissions page
  • Create new permissions with resource and action (e.g., "users:read", "applications:write")
  • Assign permissions to users from their detail page
  • Use @RequirePermissions decorator in your backend code
  • Admin users automatically have all permissions

Example: Permission "tickets:create" allows users to create tickets. Permission "tickets:delete" allows deletion.

6Configuration & Monitoring

System Configuration

  • Navigate to Configuration page
  • Adjust OTP expiry times and length
  • Configure JWT token expiry (access and refresh tokens)
  • Set rate limiting thresholds
  • Update SMS/Email provider settings
  • Changes take effect immediately

Audit Logs

  • Navigate to Audit Logs page
  • View all authentication events
  • Monitor OAuth2 token operations
  • Track user management actions
  • Filter by user, application, event type, or date range
  • Export logs for compliance and analysis
7Quick Start Checklist

Follow these steps to get your authentication service up and running:

  1. Start Backend Service: Ensure the auth-backend is running on port 3001
  2. Configure Environment: Set up all required environment variables (see backend README)
  3. Run Database Migrations: Execute npm run prisma:migrate in the backend
  4. First Login: Log in with your email/phone to become the first ADMIN user
  5. Create Additional Users: Use the Users page to create team members
  6. Register Applications: Create OAuth2 applications for your services
  7. Set Up Permissions: Create custom permissions and assign them to users
  8. Configure Settings: Adjust OTP and JWT settings as needed

Pro Tip: Bookmark the Swagger documentation at http://localhost:3001/api/docs for API reference while developing.

API Documentation

Backend API Endpoints
All API endpoints are documented via Swagger/OpenAPI

Once the backend is running, access the interactive API documentation at:

http://localhost:3001/api/docs

Authentication

  • POST /api/auth/otp/request
  • POST /api/auth/otp/verify
  • POST /api/auth/refresh
  • POST /api/auth/logout

OAuth2/OIDC

  • GET /oauth/authorize
  • POST /oauth/token
  • GET /oauth/userinfo
  • GET /.well-known/openid-configuration

Additional Resources

Backend API

Full REST API for programmatic access to all features.

http://localhost:3001/api/docs

Interactive Swagger documentation with try-it-out functionality

OIDC Discovery

Standard OIDC discovery endpoint for automatic configuration.

http://localhost:3001/.well-known/openid-configuration

Use this URL in OIDC libraries for automatic configuration

JWKS Endpoint

JSON Web Key Set for JWT token verification.

http://localhost:3001/.well-known/jwks.json

Public keys for verifying access tokens

Database Schema

All data is stored in PostgreSQL with the "oauth" schema.

See backend DATABASE.md for schema documentation, indexing strategies, and best practices.