Skip to main content

Authentication and Authorization Overview

Overview​

The NeoSpace platform implements a robust, multi-tenant authentication and authorization framework that supports multiple authentication methods, granular permission management, and seamless integration with enterprise identity providers. This system enables organizations to leverage their existing identity infrastructure while maintaining fine-grained control over user access and permissions across multiple tenants and spaces.

Key Features​

  • Multi-Authentication Support: OIDC (OpenID Connect), JWT tokens, and API keys
  • Granular Permissions: Fine-grained, resource-based permission system with space-scoped access control
  • Enterprise Integration: Native support for Microsoft Entra ID (Azure AD) and other OIDC-compliant providers
  • Multi-Tenant Architecture: Complete tenant isolation with per-tenant identity provider configuration
  • Security-First Design: PKCE, CSRF protection, token validation, and permission caching

How It Works​

The authentication and authorization flow follows these steps:

  1. Authentication: Users authenticate via OIDC, API keys, or JWT tokens
  2. Seat Resolution: OIDC tokens contain memberOf claims that map to Seats in the system
  3. Permission Mapping: Seats define permissions within specific spaces
  4. Token Generation: Internal JWT tokens are generated with space-seat mappings (hash_perm)
  5. Permission Validation: Each API request validates permissions by checking Seat permissions in Redis cache

Table of Contents​

OpenID Connect (OIDC) Foundation​

What is OpenID Connect?​

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol. It enables clients to verify the identity of end-users based on authentication performed by an authorization server, as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner.

OIDC extends OAuth 2.0 with:

  • ID Tokens: JSON Web Tokens (JWT) that contain identity information about the authenticated user
  • UserInfo Endpoint: Standardized endpoint for retrieving user profile information
  • Standardized Claims: Common claims (sub, email, name, etc.) for user identity
  • Discovery: Well-known configuration endpoints for automatic provider discovery

Why We Chose OIDC​

Industry Standard and Interoperability​

OIDC is an industry-standard protocol (OpenID Foundation standard) that ensures interoperability across different identity providers and applications. This means:

  • Universal Support: Works with major cloud providers (AWS, Azure, Google Cloud)
  • Enterprise Compatibility: Native support in Microsoft Entra ID, Okta, Auth0, Keycloak, and others
  • Future-Proof: Based on open standards, ensuring long-term compatibility and support

Cloud Provider Support​

OIDC is natively supported by all major cloud providers:

  • Microsoft Azure: Microsoft Entra ID (formerly Azure AD) provides full OIDC support
  • AWS: AWS Cognito and AWS IAM Identity Center support OIDC
  • Google Cloud: Google Workspace and Google Cloud Identity support OIDC
  • Multi-Cloud: Enables organizations to use different identity providers across different cloud environments

Security Advantages​

OIDC provides several security benefits:

  1. PKCE (Proof Key for Code Exchange): Prevents authorization code interception attacks
  2. State Parameter: CSRF protection through secure state validation
  3. Token Validation: Cryptographic verification of ID tokens using JWKS (JSON Web Key Set)
  4. Short-Lived Tokens: Access tokens and ID tokens have configurable expiration times
  5. No Credential Storage: Users authenticate with their identity provider, eliminating the need to store passwords

Single Sign-On (SSO) Capabilities​

OIDC enables seamless SSO experiences:

  • Centralized Authentication: Users authenticate once with their identity provider
  • Cross-Application Access: Single authentication works across multiple applications
  • Enterprise Directory Integration: Direct integration with Active Directory, LDAP, and other enterprise directories
  • Reduced Password Fatigue: Users don't need separate credentials for each application

Multi-Tenant Architecture Support​

OIDC is ideal for multi-tenant applications:

  • Tenant-Specific Providers: Each tenant can use their own identity provider
  • Isolated Authentication: Complete tenant isolation in authentication flows
  • Flexible Configuration: Per-tenant OIDC configuration (issuer, client ID, scopes)
  • Scalable: No shared authentication state between tenants

Developer Experience​

OIDC provides excellent developer experience:

  • Well-Defined Flows: Standardized authentication flows reduce implementation complexity
  • Libraries and SDKs: Rich ecosystem of libraries and tools
  • Discovery: Automatic provider configuration discovery reduces manual setup
  • Documentation: Extensive documentation and community support

Authentication Methods​

The platform supports three authentication methods, evaluated in priority order:

API Key Authentication (Priority 1)​

Purpose: Service-to-service authentication and programmatic access

Header: x-api-Key

Key Format: sk_<base62_encoded_data>

The encoded data contains: {tenant_id}_{api_key_id}_{random}

Validation Process:

  1. Format validation (regex: ^sk_[A-Za-z0-9]+$)
  2. Extract tenant ID from encoded key
  3. Database lookup in MongoDB
  4. Expiration check
  5. Revocation status check

Use Cases:

  • Automated scripts and CI/CD pipelines
  • Service-to-service communication
  • Third-party integrations
  • Background jobs and scheduled tasks

JWT Bearer Token Authentication (Priority 2)​

Purpose: User authentication via internally generated JWT tokens

Header: Authorization: Bearer <jwt_token>

Token Structure:

{
  "sub": "user_id",
  "email": "[email protected]",
  "tenant_id": "tenant1",
  "is_sso": true,
  "user_metadata": {
    "email": "[email protected]",
    "name": "John Doe",
    "sub": "external_user_id"
  },
  "exp": 1234567890,
  "iat": 1234567890,
  "nbf": 1234567890
}

Validation Process:

  1. Token parsing and format validation
  2. Signature verification using HMAC
  3. Token validity check (CVE-2024-51744 fix)
  4. Expiration verification (exp, nbf claims)
  5. Claims extraction

Token Generation:

  • Generated after successful OIDC authentication
  • Contains user identity and metadata
  • Signed with tenant-specific JWT secret
  • Configurable expiration (default: 1 hour)

OIDC Authentication (Priority 3)​

Purpose: Single Sign-On (SSO) with external identity providers

Flow: Authorization Code with PKCE

Supported Providers:

  • Microsoft Entra ID (Azure AD)
  • Auth0
  • Keycloak
  • Google Workspace
  • Okta
  • Any OIDC-compliant provider

Endpoints:

  • POST /auth/oidc/login - Initiate authentication
  • GET /auth/oidc/callback - Handle provider callback
  • POST /auth/oidc/validate - Validate OIDC token
  • POST /auth/oidc/refresh - Refresh expired token
info

For detailed OIDC setup instructions, see the OIDC Setup Guide.

Permission Validation Flow​

The following diagram illustrates the complete authentication and permission validation flow:

Flow Explanation​

The permission validation flow consists of four main phases:

  1. OIDC Authentication: User authenticates with the OIDC provider and receives a token containing memberOf claims (Seat names)
  2. Token Processing & Seat Resolution: The API extracts Seat names from the OIDC token and queries MongoDB to resolve Seats with their associated spaces and permissions
  3. JWT Creation: The API creates an internal JWT token with hash_perm array containing space-seat mappings, and caches Seat permissions in Redis
  4. API Request with Permission Check: On each API request, the system validates permissions by matching the space ID, extracting the Seat name, querying Redis for permissions, and validating the required permission
tip

For detailed information about Seat management and permissions, see the Seat Management Guide.