OAuth: Popup Login

Overview

Limited Use Cases

Popup login does not work reliably on mobile browsers or in environments with popup blockers. For most applications, Direct Auth (Passkey, Email Code, Social Login) is the recommended approach. If you need OAuth/OIDC, prefer Cross-Domain SSO (trySilentLogin()) or the redirect flow first.

OAuth popup login opens a small browser window for the Authrim authorization endpoint. The user authenticates in the popup, and the result is passed back to the main window. Your application stays open in the background.

This requires enableOAuth: true in the client configuration.

Setup

import { createAuthrim } from '@authrim/web';

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
  enableOAuth: true,  // Required for oauth namespace
});

Popup Login

const { data, error } = await auth.oauth.popup.login();

if (error) {
  console.error('Popup login failed:', error.message);
  return;
}

console.log('Access Token:', data.accessToken);
console.log('ID Token:', data.idToken);
console.log('Expires At:', new Date(data.expiresAt * 1000));

Response

interface OAuthTokenSet {
  accessToken: string;
  idToken?: string;
  refreshToken?: string;
  expiresAt: number;    // Unix timestamp (seconds)
  scope?: string;
}

Popup Options

interface OAuthPopupLoginOptions {
  /** Redirect URI for the popup (default: auto-detected) */
  redirectUri?: string;
  /** OAuth scopes to request */
  scopes?: string[];
  /** Popup window dimensions */
  popupFeatures?: {
    width?: number;   // default: 500
    height?: number;  // default: 600
  };
}

// Example
const { data, error } = await auth.oauth.popup.login({
  scopes: ['openid', 'profile', 'email'],
  popupFeatures: { width: 600, height: 700 },
});

How It Works

sequenceDiagram
    participant App as Main Window
    participant Popup as Popup Window
    participant IdP as Authrim IdP

    App->>Popup: Open popup
    Popup->>IdP: Authorization request (PKCE)
    IdP->>IdP: User authenticates
    IdP->>Popup: Redirect with auth code
    Popup->>App: postMessage(code)
    Popup->>Popup: Close
    App->>IdP: Exchange code for tokens
    IdP->>App: Token response

The SDK handles PKCE (Proof Key for Code Exchange) automatically — generating code_verifier and code_challenge internally.

Popup Blocked

Some browsers block popups by default. Handle this gracefully:

const { data, error } = await auth.oauth.popup.login();

if (error) {
  if (error.code === 'AR005004' && error.message.includes('popup')) {
    // Popup was blocked — offer alternative
    showMessage('Please allow popups, or use redirect login.');
  }
}

Tip

To avoid popup blockers, call auth.oauth.popup.login() directly inside a user-triggered event handler (e.g., click). Popups initiated without user interaction are more likely to be blocked.

When to Use Popup Login

Scenario	Recommended Approach
SPA with no page navigation	Popup login
Mobile web	Redirect login
Need to preserve app state	Popup login
OAuth/OIDC compliance requirement	Popup or redirect
Users behind strict popup blockers	Redirect login

Building Authorization URLs Manually

For advanced use cases, you can build the authorization URL yourself:

const result = await auth.oauth.buildAuthorizationUrl({
  redirectUri: 'https://myapp.com/callback',
  scopes: ['openid', 'profile', 'email'],
  prompt: 'login',       // Force login screen
  loginHint: '[email protected]',
});

console.log('Authorization URL:', result.url);
console.log('State:', result.state);

This is useful when you need full control over the redirect flow or want to implement custom popup management.

Complete Example

import { createAuthrim } from '@authrim/web';

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
  enableOAuth: true,
});

document.getElementById('login-btn').addEventListener('click', async () => {
  const button = document.getElementById('login-btn');
  button.disabled = true;

  const { data, error } = await auth.oauth.popup.login({
    scopes: ['openid', 'profile', 'email'],
  });

  if (error) {
    alert(error.message);
    button.disabled = false;
    return;
  }

  // Store tokens or use session
  console.log('Authenticated:', data);
  window.location.href = '/dashboard';
});

Next Steps

• OAuth: Redirect & Silent Auth — Redirect-based flows and silent authentication
• Cross-Domain SSO — SSO across multiple domains
• Session Management — Managing sessions after OAuth login