Authentication Flows on AuthOS Docs | Auth Operating System API and SDK Guides

OAuth Web Redirect

Mon, 01 Jan 0001 00:00:00 +0000

Complete the authentication flow prerequisites before starting this browser flow.

The most common authentication flow for web applications. Users authenticate using OAuth providers (GitHub, Google, Microsoft) configured by your organization.

Step 1: Initialize the SDK

import { SsoClient } from '@drmhse/sso-sdk';

const sso = new SsoClient({
  baseURL: 'https://sso.example.com'
});

Step 2: Redirect User to OAuth Provider

// Generate the OAuth login URL
const loginUrl = sso.auth.getLoginUrl('github', {
  org: 'acme-corp',
  service: 'main-app',
  redirect_uri: 'https://app.acme.com/callback'
});

// Redirect the user to authenticate
window.location.href = loginUrl;

Supported Providers:

Admin Login

Mon, 01 Jan 0001 00:00:00 +0000

Complete the authentication flow prerequisites before adding an administration login.

Platform owners and organization admins use a separate authentication flow with dedicated OAuth credentials managed by the platform.

Platform owner dashboard
Organization administration panel
Service configuration interfaces
Any interface that requires elevated privileges

Implementation

// Generate admin login URL
const adminLoginUrl = sso.auth.getAdminLoginUrl('github', {
  org_slug: 'acme-corp' // Optional: redirect to specific org after login
});

// Redirect admin to authenticate
window.location.href = adminLoginUrl;

// The callback handling is identical to end-user flow
// Tokens are returned in the same way

// Example consumer-application admin component
export function AdminDashboard() {
  const handleAdminLogin = () => {
    // After login, user will be directed to acme-corp dashboard
    const loginUrl = sso.auth.getAdminLoginUrl('github', {
      org_slug: 'acme-corp'
    });
    window.location.href = loginUrl;
  };

  return (
    <div>
      <h1>Admin Panel</h1>
      <button onClick={handleAdminLogin}>Sign in as Admin</button>
    </div>
  );
}

Key Differences from End-User Flow:

Device Authorization

Mon, 01 Jan 0001 00:00:00 +0000

Complete the authentication flow prerequisites before requesting device codes.

Device Flow (CLIs and Mobile Apps)

The device authorization flow (RFC 8628) enables authentication on devices that don’t have a browser or have limited input capabilities, such as CLIs, IoT devices, or smart TVs.

How Device Flow Works

Device requests a user code
Device displays the code and verification URL to the user
User visits the URL on another device (phone/computer)
User enters the code and authenticates
Device polls for the token
Token is granted after user approves

CLI Implementation

import { SsoClient } from '@drmhse/sso-sdk';

const sso = new SsoClient({
  baseURL: 'https://sso.example.com'
});

async function loginCLI() {
  // Step 1: Request device code
  const deviceAuth = await sso.auth.deviceCode.request({
    client_id: 'acme-cli',
    org: 'acme-corp',
    service: 'acme-cli'
  });

  console.log('\n=================================');
  console.log('To authenticate, visit:');
  console.log(deviceAuth.verification_uri);
  console.log('\nAnd enter code:');
  console.log(deviceAuth.user_code);
  console.log('=================================\n');

  // Step 2: Poll for token
  const token = await pollForToken(deviceAuth.device_code, deviceAuth.interval);

  if (token) {
    // Save token to config file
    console.log('Authentication successful!');
    return token.access_token;
  }
}

async function pollForToken(deviceCode: string, interval: number) {
  const maxAttempts = 60; // 5 minutes with 5-second intervals
  let attempts = 0;

  while (attempts < maxAttempts) {
    await sleep(interval * 1000);
    attempts++;

    try {
      const tokenResponse = await this.sso.auth.deviceCode.exchangeToken({
        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
        device_code: deviceCode,
        client_id: 'acme-cli'
      });

      return tokenResponse;
    } catch (error) {
      if (error instanceof SsoApiError) {
        if (error.errorCode === 'DEVICE_CODE_PENDING') {
          // User hasn't authorized yet, keep polling
          process.stdout.write('.');
          continue;
        } else if (error.errorCode === 'TOO_MANY_REQUESTS') {
          // Increase interval if requested
          interval += 5;
          continue;
        } else if (error.errorCode === 'DEVICE_CODE_EXPIRED') {
          console.error('\nDevice code expired. Please try again.');
          return null;
        } else if (error.isForbidden()) {
          console.error('\nUser denied the request.');
          return null;
        }
      }
      throw error;
    }
  }

  console.error('\nAuthentication timed out.');
  return null;
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Web Application: Device Code Verification

Your web application needs a route to handle device code verification (typically at /activate).

Tokens and Sessions

Mon, 01 Jan 0001 00:00:00 +0000

Start after completing a login flow from the authentication flows overview.

Token Refresh Workflow

Access tokens expire after a period of time (typically 1 hour). Use refresh tokens to obtain new access tokens without requiring the user to log in again.

When to Refresh Tokens

When an API call returns a 401 Unauthorized error
Proactively before the access token expires (if you track expiration)
On application startup if the stored token might be expired

Basic Token Refresh

async function refreshAccessToken() {
  const refreshToken = localStorage.getItem('sso_refresh_token');

  if (!refreshToken) {
    // No refresh token - user needs to log in
    window.location.href = '/login';
    return null;
  }

  try {
    const tokens = await sso.auth.refreshToken(refreshToken);

    // Store new tokens (both are rotated)
    localStorage.setItem('sso_access_token', tokens.access_token);
    localStorage.setItem('sso_refresh_token', tokens.refresh_token);

    // Update SDK
    sso.setAuthToken(tokens.access_token);

    return tokens.access_token;
  } catch (error) {
    console.error('Token refresh failed:', error);
    // Refresh token invalid or expired - user must log in
    localStorage.removeItem('sso_access_token');
    localStorage.removeItem('sso_refresh_token');
    window.location.href = '/login';
    return null;
  }
}

Automatic Token Refresh with Interceptor

Implement automatic token refresh by intercepting 401 errors:

Authentication Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Use this guide when a login is challenged or fails. For token expiry and refresh behavior, see Tokens and Sessions.

Risk-Based Authentication

AuthOS includes an intelligent Risk Engine that evaluates login attempts in real-time. When suspicious activity is detected, the platform may require additional verification through MFA, even if the user’s credentials are correct.

Understanding Risk Assessment

The Risk Engine evaluates multiple signals during every authentication attempt:

Geographic Location: Logins from new countries or impossible travel patterns
Device Trust: Logins from previously unseen devices
Velocity Detection: Rapid login attempts or suspicious patterns
User Agent Analysis: Unusual browsers or automation tools

Based on the risk score (0-100), the platform takes one of these actions:

Authentication Flows on AuthOS Docs | Auth Operating System API and SDK Guides

OAuth Web Redirect

End-User OAuth Login (Web Redirect Flow)

Step 1: Initialize the SDK

Step 2: Redirect User to OAuth Provider

Admin Login

Admin Login (Platform & Organization Admins)

When to Use Admin Login

Implementation

Admin Login with Organization Context

Device Authorization

Device Flow (CLIs and Mobile Apps)

How Device Flow Works

CLI Implementation

Web Application: Device Code Verification

Tokens and Sessions

Token Refresh Workflow

When to Refresh Tokens

Basic Token Refresh

Automatic Token Refresh with Interceptor

Authentication Troubleshooting

Risk-Based Authentication

Understanding Risk Assessment