Authentication Overview

What is Authentication?

Authentication is the process of verifying the identity of users before they can access CampusMindAI's APIs. The platform uses enterprise-grade authentication through Azure Active Directory (Azure AD) integrated with WorkOS, ensuring secure access to all system resources.

Why Authentication Matters

Authentication is critical for:

• Security: Protects sensitive educational data and AI agent configurations

• Access Control: Ensures users only access resources they're authorized to use

• Compliance: Meets organizational security and privacy requirements

• Audit Trail: Tracks who performs actions within the system

Authentication Flow

CampusMindAI uses a two-step authentication process:

1. Azure AD Authentication: Users authenticate with their organizational Microsoft account

2. JWT Token Exchange: The Azure AD token is exchanged for a CampusMindAI-specific JWT token

sequenceDiagram
    participant User
    participant Script
    participant Azure AD
    participant CampusMindAI API
    
    User->>Script: Provide credentials
    Script->>Azure AD: Authenticate (ROPC flow)
    Azure AD->>Script: Return Azure AD token
    Script->>CampusMindAI API: POST /api/v1/login with Azure AD token
    CampusMindAI API->>Script: Return JWT access token
    Script->>CampusMindAI API: Use JWT token for API calls

Authentication Methods

Resource Owner Password Credentials (ROPC)

CampusMindAI supports the ROPC flow for programmatic access:

• Use Case: Automation scripts, CI/CD pipelines, server-to-server integrations

• Requirements: Client ID, Tenant ID, Client Secret, username, and password

• Token Lifetime: Time-limited tokens that expire after a set duration

Prerequisites

Before using the authentication system, ensure:

1. Azure AD Access: Your email account must be registered in the Azure AD tenant

2. App Registration Permissions: You must be added as an Owner or have appropriate permissions in the Azure AD App Registration

3. Database Entry: Your account must be added to the CampusMindAI SQL database by an administrator

Token Types

Azure AD Access Token

• Generated by Microsoft Azure Active Directory

• Used to verify identity with Microsoft services

• Exchanged for CampusMindAI JWT token

CampusMindAI JWT Token

• Application-specific authentication token

• Used for all CampusMindAI API requests

• Contains user identity, roles, and permissions

• Must be included in the Authorization header as a Bearer token

Security Best Practices

1. Never Share Tokens: Keep authentication tokens confidential

2. Use Environment Variables: Store credentials in .env files, never in code

3. Rotate Credentials: Regularly update client secrets and passwords

4. Limit Token Scope: Request only the permissions needed

5. Monitor Access: Review authentication logs regularly

Token Security

• Tokens are short-lived and expire automatically

• Each token is bound to a specific user and tenant

• Tokens cannot be used across different environments (dev/prod)

• Invalid or expired tokens return 401 Unauthorized errors

Common Authentication Errors

Next Steps

• Azure AD Login Guide: Learn how to set up the Python authentication script

• API Authentication: Understand how to use tokens in API requests

• User Roles & Permissions: Learn about access control and role-based permissions

Additional Resources

• Microsoft Authentication Library (MSAL) Documentation

• OAuth 2.0 ROPC Flow

• WorkOS Documentation