SSO Integration

Overview

Atlas Auth Guard provides a popup-based SSO flow that allows consumer applications to integrate Google OAuth authentication with minimal code. The Auth Guard handles the entire OAuth flow, and your application just needs to:

Open a popup window
Listen for a postMessage with the auth result
Store the token

No callback page needed in your application!

Quick Start

Minimal Integration (10 lines of code)

function login(teamId, projectId) {
  // 1. Open SSO popup
  const authGuardUrl = 'https://your-auth-guard.run.app';
  let ssoUrl = `${authGuardUrl}/v1/auth/sso?origin=${encodeURIComponent(window.location.origin)}`;

  // Optional: Login to a specific team
  if (teamId) {
    ssoUrl += `&team_id=${encodeURIComponent(teamId)}`;
  }

  // Optional: Login to a specific project (requires team_id)
  if (projectId && teamId) {
    ssoUrl += `&project_id=${encodeURIComponent(projectId)}`;
  }

  const popup = window.open(ssoUrl, 'Atlas SSO', 'width=500,height=600,left=100,top=100');

  // 2. Listen for auth result
  window.addEventListener('message', function handler(event) {
    // Verify origin
    if (!event.origin.includes('your-auth-guard.run.app')) return;

    if (event.data.type === 'ATLAS_AUTH_SUCCESS') {
      const { token, user } = event.data;

      // 3. Store credentials
      localStorage.setItem('auth_token', token);
      localStorage.setItem('user', JSON.stringify(user));

      // 4. Update your app state
      console.log('Logged in as:', user.user_email);
      console.log('Team:', user.team_name);       // User's team context
      console.log('Project:', user.project_name); // User's project context
      window.removeEventListener('message', handler);

      // Refresh page or update UI
      location.reload();
    } else if (event.data.type === 'ATLAS_AUTH_ERROR') {
      console.error('Login failed:', event.data.error);
      window.removeEventListener('message', handler);
    }
  });
}

// Usage examples:
login();                                                                    // Default team/project login
login('ab2785b2-b5d0-4926-92fb-00aae5ec860a');                             // Login to specific team
login('ab2785b2-b5d0-4926-92fb-00aae5ec860a', 'cd1234e5-f6g7-8h9i-jklm'); // Login to specific team + project

HTML Button Example

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <!-- Default login -->
  <button onclick="login()">Sign in with Google</button>

  <!-- Team-specific login buttons -->
  <button onclick="login('team-uuid-1')">Sign in to Engineering Team</button>
  <button onclick="login('team-uuid-2')">Sign in to Data Science Team</button>

  <!-- Project-specific login buttons -->
  <button onclick="login('team-uuid-1', 'project-uuid-1')">Sign in to Project Alpha</button>
  <button onclick="login('team-uuid-1', 'project-uuid-2')">Sign in to Project Beta</button>

  <script>
    const AUTH_GUARD_URL = 'https://your-auth-guard.run.app';

    function login(teamId, projectId) {
      let ssoUrl = `${AUTH_GUARD_URL}/v1/auth/sso?origin=${encodeURIComponent(window.location.origin)}`;

      // Add team_id if provided
      if (teamId) {
        ssoUrl += `&team_id=${encodeURIComponent(teamId)}`;
      }

      // Add project_id if provided (requires team_id)
      if (projectId && teamId) {
        ssoUrl += `&project_id=${encodeURIComponent(projectId)}`;
      }

      const popup = window.open(ssoUrl, 'Atlas SSO', 'width=500,height=600');

      window.addEventListener('message', function handler(event) {
        if (event.data.type === 'ATLAS_AUTH_SUCCESS') {
          localStorage.setItem('auth_token', event.data.token);
          localStorage.setItem('user', JSON.stringify(event.data.user));

          // User context includes team and project info
          const user = event.data.user;
          alert(`Welcome to ${user.project_name || user.team_name}, ${user.user_name}!`);

          window.removeEventListener('message', handler);
        }
      });
    }
  </script>
</body>
</html>

API Reference

`GET /v1/auth/sso`

Opens the SSO login page in a popup window.

Query Parameters:

Parameter

Required

Description

origin

Yes

Your app's origin URL (e.g., https://myapp.turing.com)

team_id

Team ID for team-specific login

Example URLs:

# Basic login
https://auth-guard.run.app/v1/auth/sso?origin=https://myapp.turing.com

# Team-specific login
https://auth-guard.run.app/v1/auth/sso?origin=https://myapp.turing.com&team_id=abc-123

postMessage Events

The popup sends these messages to the opener window:

Success: `ATLAS_AUTH_SUCCESS`

{
  type: 'ATLAS_AUTH_SUCCESS',
  token: 'eyJhbGciOiJIUzI1NiIs...', // JWT access token
  user: {
    user_id: 'uuid',
    user_email: '[email protected]',
    user_name: 'John Doe',
    org_id: 'org-uuid',
    org_name: 'Turing',
    team_id: 'team-uuid',
    team_name: 'Engineering',
    project_id: 'project-uuid',
    project_name: 'Atlas',
    global_role: 'member',
    team_role: 'member',
    permissions: ['read:projects', 'write:tasks'],
    user_picture: 'https://...',
    // ... more fields
  }
}

Error: `ATLAS_AUTH_ERROR`

{
  type: 'ATLAS_AUTH_ERROR',
  error: 'Error message describing what went wrong'
}

Framework Examples

React

import { useState, useEffect } from 'react';

const AUTH_GUARD_URL = import.meta.env.VITE_AUTH_GUARD_URL;

function useAuth() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // Check for existing session
    const token = localStorage.getItem('auth_token');
    const savedUser = localStorage.getItem('user');
    if (token && savedUser) {
      setUser(JSON.parse(savedUser));
    }
    setLoading(false);
  }, []);

  const login = (teamId) => {
    let url = `${AUTH_GUARD_URL}/v1/auth/sso?origin=${encodeURIComponent(window.location.origin)}`;
    if (teamId) {
      url += `&team_id=${encodeURIComponent(teamId)}`;
    }

    const popup = window.open(url, 'Atlas SSO', 'width=500,height=600');

    const handler = (event) => {
      if (!event.origin.includes(new URL(AUTH_GUARD_URL).host)) return;

      if (event.data.type === 'ATLAS_AUTH_SUCCESS') {
        localStorage.setItem('auth_token', event.data.token);
        localStorage.setItem('user', JSON.stringify(event.data.user));
        setUser(event.data.user);
        window.removeEventListener('message', handler);
      } else if (event.data.type === 'ATLAS_AUTH_ERROR') {
        console.error('Login failed:', event.data.error);
        window.removeEventListener('message', handler);
      }
    };

    window.addEventListener('message', handler);
  };

  const logout = () => {
    localStorage.removeItem('auth_token');
    localStorage.removeItem('user');
    setUser(null);
  };

  return { user, loading, login, logout };
}

// Usage in component
function App() {
  const { user, loading, login, logout } = useAuth();

  if (loading) return <div>Loading...</div>;

  return (
    <div>
      {user ? (
        <>
          <p>Welcome, {user.user_name}!</p>
          <button onClick={logout}>Logout</button>
        </>
      ) : (
        <button onClick={() => login()}>Sign in with Google</button>
      )}
    </div>
  );
}

Vue 3

<template>
  <div>
    <div v-if="loading">Loading...</div>
    <div v-else-if="user">
      <p>Welcome, {{ user.user_name }}!</p>
      <button @click="logout">Logout</button>
    </div>
    <div v-else>
      <button @click="login()">Sign in with Google</button>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';

const AUTH_GUARD_URL = import.meta.env.VITE_AUTH_GUARD_URL;

const user = ref(null);
const loading = ref(true);

onMounted(() => {
  const token = localStorage.getItem('auth_token');
  const savedUser = localStorage.getItem('user');
  if (token && savedUser) {
    user.value = JSON.parse(savedUser);
  }
  loading.value = false;
});

function login(teamId) {
  let url = `${AUTH_GUARD_URL}/v1/auth/sso?origin=${encodeURIComponent(window.location.origin)}`;
  if (teamId) {
    url += `&team_id=${encodeURIComponent(teamId)}`;
  }

  const popup = window.open(url, 'Atlas SSO', 'width=500,height=600');

  const handler = (event) => {
    if (!event.origin.includes(new URL(AUTH_GUARD_URL).host)) return;

    if (event.data.type === 'ATLAS_AUTH_SUCCESS') {
      localStorage.setItem('auth_token', event.data.token);
      localStorage.setItem('user', JSON.stringify(event.data.user));
      user.value = event.data.user;
      window.removeEventListener('message', handler);
    } else if (event.data.type === 'ATLAS_AUTH_ERROR') {
      console.error('Login failed:', event.data.error);
      window.removeEventListener('message', handler);
    }
  };

  window.addEventListener('message', handler);
}

function logout() {
  localStorage.removeItem('auth_token');
  localStorage.removeItem('user');
  user.value = null;
}
</script>

Angular

// auth.service.ts
import { Injectable } from '@angular/core';
import { BehaviorSubject } from 'rxjs';
import { environment } from '../environments/environment';

interface User {
  user_id: string;
  user_email: string;
  user_name: string;
  // ... other fields
}

@Injectable({ providedIn: 'root' })
export class AuthService {
  private userSubject = new BehaviorSubject<User | null>(null);
  user$ = this.userSubject.asObservable();

  constructor() {
    // Check for existing session
    const token = localStorage.getItem('auth_token');
    const savedUser = localStorage.getItem('user');
    if (token && savedUser) {
      this.userSubject.next(JSON.parse(savedUser));
    }
  }

  login(teamId?: string): void {
    let url = `${environment.authGuardUrl}/v1/auth/sso?origin=${encodeURIComponent(window.location.origin)}`;
    if (teamId) {
      url += `&team_id=${encodeURIComponent(teamId)}`;
    }

    const popup = window.open(url, 'Atlas SSO', 'width=500,height=600');

    const handler = (event: MessageEvent) => {
      if (!event.origin.includes(new URL(environment.authGuardUrl).host)) return;

      if (event.data.type === 'ATLAS_AUTH_SUCCESS') {
        localStorage.setItem('auth_token', event.data.token);
        localStorage.setItem('user', JSON.stringify(event.data.user));
        this.userSubject.next(event.data.user);
        window.removeEventListener('message', handler);
      } else if (event.data.type === 'ATLAS_AUTH_ERROR') {
        console.error('Login failed:', event.data.error);
        window.removeEventListener('message', handler);
      }
    };

    window.addEventListener('message', handler);
  }

  logout(): void {
    localStorage.removeItem('auth_token');
    localStorage.removeItem('user');
    this.userSubject.next(null);
  }

  getToken(): string | null {
    return localStorage.getItem('auth_token');
  }
}

Making Authenticated API Calls

After login, include the token in your API requests:

const token = localStorage.getItem('auth_token');

// Using fetch
const response = await fetch('https://api.turing.com/v1/some-endpoint', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

// Using axios
import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.turing.com',
  headers: {
    'Content-Type': 'application/json'
  }
});

// Add auth interceptor
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('auth_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

Fetching User's Teams & Projects

After login, you can fetch the user's team and project memberships:

Get User's Teams

GET /v1/admin/users/me/teams
Authorization: Bearer {token}

Response:

[
  {
    "team_id": "ab2785b2-b5d0-4926-92fb-00aae5ec860a",
    "team_name": "Engineering",
    "role": "member",
    "org_id": "org-uuid",
    "assigned_at": "2025-01-15T10:30:00Z"
  },
  {
    "team_id": "cd3896c3-c6e1-5037-a3gc-11bbf6fd971b",
    "team_name": "Data Science",
    "role": "team_admin",
    "org_id": "org-uuid",
    "assigned_at": "2025-01-10T08:00:00Z"
  }
]

Get User's Projects

GET /v1/admin/users/me/projects
Authorization: Bearer {token}

Response:

[
  {
    "project_id": "ef4907d4-d7f2-6148-b4hd-22ccg7ge082c",
    "project_name": "LLM API",
    "team_id": "ab2785b2-b5d0-4926-92fb-00aae5ec860a",
    "role": "project_admin",
    "assigned_at": "2025-01-15T10:30:00Z"
  },
  {
    "project_id": "gh5018e5-e8g3-7259-c5ie-33ddh8hf193d",
    "project_name": "Auto Rater",
    "team_id": "ab2785b2-b5d0-4926-92fb-00aae5ec860a",
    "role": "editor",
    "assigned_at": "2025-01-10T08:00:00Z"
  }
]

JavaScript Example

const AUTH_GUARD_URL = 'https://your-auth-guard.run.app';

async function fetchUserContext() {
  const token = localStorage.getItem('auth_token');

  if (!token) {
    throw new Error('Not authenticated');
  }

  const headers = {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  };

  // Fetch teams and projects in parallel
  const [teamsRes, projectsRes] = await Promise.all([
    fetch(`${AUTH_GUARD_URL}/v1/admin/users/me/teams`, { headers }),
    fetch(`${AUTH_GUARD_URL}/v1/admin/users/me/projects`, { headers })
  ]);

  if (!teamsRes.ok || !projectsRes.ok) {
    throw new Error('Failed to fetch user context');
  }

  const teams = await teamsRes.json();
  const projects = await projectsRes.json();

  return { teams, projects };
}

// Usage
async function onLoginSuccess() {
  try {
    const { teams, projects } = await fetchUserContext();

    console.log('User teams:', teams);
    console.log('User projects:', projects);

    // Example: Show team selector if user belongs to multiple teams
    if (teams.length > 1) {
      showTeamSelector(teams);
    }

    // Example: Filter projects by selected team
    const selectedTeamId = teams[0].team_id;
    const teamProjects = projects.filter(p => p.team_id === selectedTeamId);

  } catch (error) {
    console.error('Failed to load user context:', error);
  }
}

React Hook Example

import { useState, useEffect } from 'react';

function useUserContext() {
  const [teams, setTeams] = useState([]);
  const [projects, setProjects] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function fetchContext() {
      const token = localStorage.getItem('auth_token');
      if (!token) {
        setLoading(false);
        return;
      }

      try {
        const headers = { 'Authorization': `Bearer ${token}` };
        const [teamsRes, projectsRes] = await Promise.all([
          fetch(`${AUTH_GUARD_URL}/v1/admin/users/me/teams`, { headers }),
          fetch(`${AUTH_GUARD_URL}/v1/admin/users/me/projects`, { headers })
        ]);

        setTeams(await teamsRes.json());
        setProjects(await projectsRes.json());
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    fetchContext();
  }, []);

  return { teams, projects, loading, error };
}

// Usage in component
function Dashboard() {
  const { teams, projects, loading } = useUserContext();

  if (loading) return <div>Loading...</div>;

  return (
    <div>
      <h2>Your Teams</h2>
      <ul>
        {teams.map(team => (
          <li key={team.team_id}>
            {team.team_name} ({team.role})
          </li>
        ))}
      </ul>

      <h2>Your Projects</h2>
      <ul>
        {projects.map(project => (
          <li key={project.project_id}>
            {project.project_name} ({project.role})
          </li>
        ))}
      </ul>
    </div>
  );
}

To log users into a specific team:

// Team-specific login URL
function loginToTeam(teamId) {
  const url = `${AUTH_GUARD_URL}/v1/auth/sso?origin=${encodeURIComponent(window.location.origin)}&team_id=${encodeURIComponent(teamId)}`;

  window.open(url, 'Atlas SSO', 'width=500,height=600');
  // ... rest of the handler
}

// Usage
loginToTeam('ab2785b2-b5d0-4926-92fb-00aae5ec860a');

Behavior:

New users: Automatically assigned to the specified team
Existing users: Must already be a member of the team, or will be auto-assigned if team belongs to their org

Security Considerations

Origin Validation

The Auth Guard validates the origin parameter to prevent unauthorized apps from using SSO. Allowed origins:

*.turing.com and *.atlas.turing.com subdomains
localhost:* for development

To add your domain, contact the Auth Guard administrators.

postMessage Security

Always verify the event origin in your message handler:

window.addEventListener('message', (event) => {
  // IMPORTANT: Verify origin
  if (!event.origin.includes('your-auth-guard.run.app')) {
    return; // Ignore messages from unknown origins
  }

  // Process message...
});

Token Storage

Store tokens in localStorage for persistence across browser sessions
For higher security, use sessionStorage (cleared when browser closes)
Never store tokens in cookies without proper security flags

Troubleshooting

If the browser blocks the popup:

const popup = window.open(url, 'Atlas SSO', 'width=500,height=600');

if (!popup || popup.closed || typeof popup.closed === 'undefined') {
  // Popup was blocked
  alert('Please allow popups for this site to login');
  // Fallback: redirect instead of popup
  window.location.href = url;
}

CORS Issues

The SSO flow uses postMessage which doesn't have CORS restrictions. If you're making API calls after login and getting CORS errors, ensure:

Your origin is in the Auth Guard's allowed origins
You're including the Authorization header correctly

Token Expired

JWT tokens expire after a configurable time (default: 24 hours). Handle token expiration:

api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // Token expired - prompt re-login
      localStorage.removeItem('auth_token');
      localStorage.removeItem('user');
      login(); // Re-open SSO popup
    }
    return Promise.reject(error);
  }
);

Consumer APIs

After SSO login, consumers can access various APIs using the JWT token.

Get User's Teams and Projects

// Get teams the user belongs to
const teams = await fetch(`${AUTH_URL}/v1/admin/users/me/teams`, {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

// Response includes access_type: "explicit" or "implicit"
// [
//   { team_id: "...", team_name: "Engineering", role: "team_admin", access_type: "explicit" },
//   ...
// ]

// Get projects the user can access
const projects = await fetch(`${AUTH_URL}/v1/admin/users/me/projects`, {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

// Response includes access_type: "explicit" or "implicit"
// [
//   { project_id: "...", project_name: "Alpha", role: "team_admin", access_type: "implicit" },
//   { project_id: "...", project_name: "Beta", role: "editor", access_type: "explicit" },
//   ...
// ]

Project Metadata API

Projects can store arbitrary metadata (configuration, settings, etc.):

// Get all metadata for a project
const metadata = await fetch(`${AUTH_URL}/v1/admin/projects/${projectId}/metadata`, {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

// Get specific metadata key
const config = await fetch(`${AUTH_URL}/v1/admin/projects/${projectId}/metadata?key=config.json`, {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

// Set metadata (requires project_admin or higher)
await fetch(`${AUTH_URL}/v1/admin/projects/${projectId}/metadata`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    key: 'config.json',
    value: { destination_folder: ['my-folder'] }
  })
});

// Merge multiple metadata keys at once
await fetch(`${AUTH_URL}/v1/admin/projects/${projectId}/metadata`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    'setting1': 'value1',
    'setting2': { nested: 'object' }
  })
});

// Delete metadata key
await fetch(`${AUTH_URL}/v1/admin/projects/${projectId}/metadata/config.json`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${token}` }
});

Permission Requirements

Endpoint

Method

Required Permission

/me/teams

GET

Any authenticated user

/me/projects

GET

Any authenticated user

/projects/{id}/metadata

GET

read:project (viewer+)

/projects/{id}/metadata

PUT

write:project (project_admin+)

/projects/{id}/metadata

PATCH

write:project (project_admin+)

/projects/{id}/metadata/{key}

DELETE

write:project (project_admin+)

Migration from Callback-Based Flow

If you're currently using the callback-based flow (/auth/login + /auth/callback), you can migrate:

Before (Callback-based)

// login.js
function login() {
  window.location.href = `${AUTH_URL}/auth/login?redirect_uri=${window.location.origin}/auth/callback`;
}

// callback.js (separate page)
const code = new URLSearchParams(window.location.search).get('code');
const response = await fetch(`${AUTH_URL}/auth/callback`, {
  method: 'POST',
  body: JSON.stringify({ code, redirect_uri: window.location.origin + '/auth/callback' })
});
const { token, user } = await response.json();
localStorage.setItem('auth_token', token);
window.location.href = '/';

// Just one file, no callback page needed!
function login() {
  const popup = window.open(
    `${AUTH_URL}/v1/auth/sso?origin=${encodeURIComponent(window.location.origin)}`,
    'Atlas SSO',
    'width=500,height=600'
  );

  window.addEventListener('message', (event) => {
    if (event.data.type === 'ATLAS_AUTH_SUCCESS') {
      localStorage.setItem('auth_token', event.data.token);
      // Done! No redirect needed
    }
  });
}

Support

For issues or questions:

Check the Auth Guard documentation
Contact the Atlas platform team
Open an issue in the repository

PreviousAPI Keys NextService Routes

Last updated 13 hours ago

Good evening

Overview

Quick Start

Minimal Integration (10 lines of code)

HTML Button Example

API Reference

GET /v1/auth/sso

postMessage Events

Success: ATLAS_AUTH_SUCCESS

Error: ATLAS_AUTH_ERROR

Framework Examples

React

Vue 3

Angular

Making Authenticated API Calls

Fetching User's Teams & Projects

Get User's Teams

Get User's Projects

JavaScript Example

React Hook Example

Team-Specific Login

Security Considerations

Origin Validation

postMessage Security

Token Storage

Troubleshooting

Popup Blocked

CORS Issues

Token Expired

Consumer APIs

Get User's Teams and Projects

Project Metadata API

Permission Requirements

Migration from Callback-Based Flow

Before (Callback-based)

After (Popup-based)

Support

`GET /v1/auth/sso`

Success: `ATLAS_AUTH_SUCCESS`

Error: `ATLAS_AUTH_ERROR`