🛡️Introduction

Enterprise-grade Authentication & Authorization Gateway for Atlas Microservices

Atlas Auth Guard is a centralized authentication and authorization service that provides:

• 🔐 Single Sign-On (SSO) via Google OAuth

• 👥 Multi-tenant architecture with Organization → Team → Project hierarchy

• 🎭 Role-based access control (RBAC) with fine-grained permissions

• 🔑 API key management for service-to-service communication

• 🚦 Service routing to backend microservices with policy enforcement

---

🌐 Environment URLs

Production Environment

Service	URL	Description
Web Dashboard	https://auth-gw.atlas.turing.com	Admin portal for managing teams, projects, users
API Endpoint	https://apac-atlas-guard-svc-589688574290.asia-south1.run.app	Backend API
API Documentation	https://apac-atlas-guard-svc-589688574290.asia-south1.run.app/v1/docs	Swagger UI with all endpoints
Health Check	https://apac-atlas-guard-svc-589688574290.asia-south1.run.app/v1/health	Service health status

Development (R&D) Environment

Service	URL	Description
Web Dashboard	https://auth-gw.rd.atlas.turing.com	Development admin portal
API Endpoint	https://apac-atlas-guard-svc-264685500362.us-central1.run.app	Development API
API Documentation	https://apac-atlas-guard-svc-264685500362.us-central1.run.app/v1/docs	Development Swagger UI
Health Check	https://apac-atlas-guard-svc-264685500362.us-central1.run.app/v1/health	Development health status

---

📚 Documentation Guide

For End Users

Document	Description
Getting Started	Quick overview of how to use the system
Team Management	Understanding teams, members, and team policies
Project Management	Managing projects, metadata, and data isolation
User Management	User roles, permissions, and access control
API Keys	Creating and managing API keys

For Developers

Document	Description
SSO Integration	Integrate SSO into your application
Service Routes	How Auth Guard routes requests to backends
Service Policies	Service-to-service authorization
Security Model	Complete security architecture
Troubleshooting	Common issues and solutions

---

🏗️ System Architecture

Multi-Tenant Hierarchy

Atlas Auth Guard implements a three-level tenant hierarchy:

┌─────────────────────────────────────────────────────────────────────────────┐
│                            ORGANIZATION                                      │
│                              (Turing)                                        │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │ • Billing entity                                                       │ │
│  │ • SSO/MFA policies                                                     │ │
│  │ • Organization-wide settings                                           │ │
│  │ • Users belong to organization via @turing.com email                   │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                              │
│  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐  │
│  │       TEAM          │  │       TEAM          │  │       TEAM          │  │
│  │    Engineering      │  │    Data Science     │  │      Platform       │  │
│  │ ┌─────────────────┐ │  │ ┌─────────────────┐ │  │ ┌─────────────────┐ │  │
│  │ │ • Team admins   │ │  │ │ • Team admins   │ │  │ │ • Team admins   │ │  │
│  │ │ • Team members  │ │  │ │ • Team members  │ │  │ │ • Team members  │ │  │
│  │ │ • Service policy│ │  │ │ • Service policy│ │  │ │ • Service policy│ │  │
│  │ └─────────────────┘ │  │ └─────────────────┘ │  │ └─────────────────┘ │  │
│  │                     │  │                     │  │                     │  │
│  │ ┌───────┐ ┌───────┐ │  │ ┌───────┐          │  │ ┌───────┐          │  │
│  │ │Project│ │Project│ │  │ │Project│          │  │ │Project│          │  │
│  │ │LLM API│ │Rater  │ │  │ │Research│         │  │ │Guard  │          │  │
│  │ │       │ │       │ │  │ │       │          │  │ │       │          │  │
│  │ │API Key│ │API Key│ │  │ │API Key│          │  │ │API Key│          │  │
│  │ └───────┘ └───────┘ │  │ └───────┘          │  │ └───────┘          │  │
│  └─────────────────────┘  └─────────────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

Key Concepts

Concept	Description
Organization	Top-level tenant. All users, teams, and projects belong to an organization. Currently: "Turing"
Team	Logical grouping of users. Teams have service access policies that control which backend services members can use.
Project	Isolated workspace within a team. Each project has its own API key and data isolation.
User	Individual authenticated via Google OAuth. Users have roles at global, team, and project levels.

---

👥 Role Hierarchy

Atlas Auth Guard implements a comprehensive role-based access control (RBAC) system:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           ROLE HIERARCHY                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  GLOBAL SCOPE (Platform-wide)                                               │
│  ════════════════════════════                                               │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ super_admin (Level 100)                                              │   │
│  │ • Full platform access                                               │   │
│  │ • Can access all organizations (if multi-org)                        │   │
│  │ • Bypasses all access checks                                         │   │
│  │ • Can manage system routes and policies                              │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ org_admin (Level 80)                                                 │   │
│  │ • Full organization access                                           │   │
│  │ • Can see all teams and projects in the org                          │   │
│  │ • Bypasses team policies and membership checks                       │   │
│  │ • Can manage routes and policies                                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ member (Level 70)                                                    │   │
│  │ • Basic organization member                                          │   │
│  │ • Must be explicitly added to teams                                  │   │
│  │ • Subject to team policies                                           │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
│  TEAM SCOPE                                                                 │
│  ══════════                                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ team_admin (Level 60)                                                │   │
│  │ • Create/delete projects in the team                                 │   │
│  │ • Add/remove team members                                            │   │
│  │ • Manage team API keys                                               │   │
│  │ • Configure team service policy                                      │   │
│  │ • Has implicit access to all projects in the team                    │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ team_member (Level 50)                                               │   │
│  │ • View team information                                              │   │
│  │ • Access projects they're assigned to                                │   │
│  │ • Execute services allowed by team policy                            │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
│  PROJECT SCOPE                                                              │
│  ═════════════                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ project_admin (Level 40)                                             │   │
│  │ • Manage project members                                             │   │
│  │ • Manage project settings and metadata                               │   │
│  │ • Create/revoke project API keys                                     │   │
│  │ • Full read/write access to project data                             │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ editor (Level 20)                                                    │   │
│  │ • Read and write project data                                        │   │
│  │ • Execute services                                                   │   │
│  │ • Cannot manage members or settings                                  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ viewer (Level 10)                                                    │   │
│  │ • Read-only access to project data                                   │   │
│  │ • Cannot modify anything                                             │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Effective Role Calculation

When you access a resource, your effective role is determined by the most specific assignment:

Priority	Check	Example
1️⃣ Highest	Explicit project role	You have viewer on Project X → You're a viewer
2️⃣	Explicit team role	You have team_admin on Team A → You're team_admin for all projects in Team A
3️⃣ Lowest	Global role (fallback)	You're org_admin globally → Full org access where no explicit role exists

Important: Even super_admin can be restricted to viewer on a specific project if explicitly assigned.

---

🚀 Getting Started

For Dashboard Users

1. Login: Go to https://auth-gw.atlas.turing.com and click "Sign in with Google"

2. Select Context: Choose your team and project from the dropdown

3. Navigate: Use the sidebar to access Teams, Projects, Users, API Keys, etc.

For Developers Integrating SSO

// Minimal SSO integration - 10 lines of code
const AUTH_URL = 'https://auth-gw.atlas.turing.com';

function login() {
  // Open SSO popup
  const popup = window.open(
    `${AUTH_URL}/v1/auth/sso?origin=${encodeURIComponent(window.location.origin)}`,
    'Atlas SSO',
    'width=500,height=600'
  );

  // Listen for auth result
  window.addEventListener('message', (event) => {
    if (event.data.type === 'ATLAS_AUTH_SUCCESS') {
      const { token, user } = event.data;
      localStorage.setItem('auth_token', token);
      console.log('Logged in as:', user.user_name);
      console.log('Team:', user.team_name);
      console.log('Project:', user.project_name);
    }
  });
}

See SSO Integration Guide for complete documentation.

For Backend Services Using API Keys

import httpx

AUTH_GUARD_URL = "https://auth-gw.atlas.turing.com"
API_KEY = "sk-your-project-api-key"

async def call_llm_service(prompt: str):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{AUTH_GUARD_URL}/v1/llm/generate",
            headers={
                "X-Atlas-API-Key": API_KEY,
                "Content-Type": "application/json"
            },
            json={"prompt": prompt}
        )
        return response.json()

See API Keys Guide for complete documentation.

---

🔄 Request Flow

Here's how a request flows through the system:

┌──────────────────────────────────────────────────────────────────────────────┐
│                              REQUEST FLOW                                     │
└──────────────────────────────────────────────────────────────────────────────┘

  ┌─────────┐
  │  User   │
  │ Browser │
  └────┬────┘
       │
       │ 1. Request with JWT token
       │    Authorization: Bearer eyJhbG...
       ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │                          AUTH GUARD                                      │
  │  ┌────────────────────────────────────────────────────────────────────┐ │
  │  │ 2. AUTHENTICATION                                                   │ │
  │  │    • Validate JWT signature                                         │ │
  │  │    • Check token expiration                                         │ │
  │  │    • Verify user is active                                          │ │
  │  │    ❌ If fails → 401 Unauthorized                                    │ │
  │  └────────────────────────────────────────────────────────────────────┘ │
  │                              │                                           │
  │                              ▼                                           │
  │  ┌────────────────────────────────────────────────────────────────────┐ │
  │  │ 3. TEAM POLICY CHECK                                                │ │
  │  │    • Is the target service in team's allowed_services?              │ │
  │  │    • Bypassed for: super_admin, org_admin                           │ │
  │  │    ❌ If fails → 403 Forbidden: Service not allowed                  │ │
  │  └────────────────────────────────────────────────────────────────────┘ │
  │                              │                                           │
  │                              ▼                                           │
  │  ┌────────────────────────────────────────────────────────────────────┐ │
  │  │ 4. MEMBERSHIP CHECK                                                 │ │
  │  │    • Is user a member of the team in their JWT?                     │ │
  │  │    • Is user a member of the project (if project_id in JWT)?        │ │
  │  │    • Bypassed for: super_admin, org_admin                           │ │
  │  │    ❌ If fails → 403 Forbidden: Not a member                         │ │
  │  └────────────────────────────────────────────────────────────────────┘ │
  │                              │                                           │
  │                              ▼                                           │
  │  ┌────────────────────────────────────────────────────────────────────┐ │
  │  │ 5. INJECT HEADERS                                                   │ │
  │  │    • X-User-ID, X-User-Email, X-User-Name                           │ │
  │  │    • X-Org-ID, X-Team-ID, X-Project-ID                              │ │
  │  │    • X-Effective-Role, X-Permissions                                │ │
  │  │    • X-Request-ID (for tracing)                                     │ │
  │  └────────────────────────────────────────────────────────────────────┘ │
  │                              │                                           │
  │                              ▼                                           │
  │  ┌────────────────────────────────────────────────────────────────────┐ │
  │  │ 6. PROXY TO BACKEND                                                 │ │
  │  │    • Route: /v1/llm/generate → https://llm-svc.run.app/api/v1/...   │ │
  │  └────────────────────────────────────────────────────────────────────┘ │
  └─────────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
                          ┌─────────────┐
                          │   Backend   │
                          │   Service   │
                          │             │
                          │ Receives:   │
                          │ • Headers   │
                          │ • Request   │
                          └─────────────┘

---

📞 Support

• API Documentation: See Swagger UI links above

• Issues: Contact [email protected]

• Feature Requests: Create a ticket in JIRA

---

Built with ❤️ by the Turing APAC Platform Team