useLogin()

A React hook that provides functionality to initiate the OAuth/OIDC authentication flow. It supports both redirect and popup-based login flows with PKCE for secure authentication.

Basic Usage

The simplest way to use the hook is to call signinRedirect() which will redirect the user to the authorization endpoint:

import { useLogin } from 'authsafe-react';

function LoginButton() {
  const { signinRedirect, isLoading } = useLogin();

  return (
    <button onClick={() => signinRedirect()} disabled={isLoading}>
      {isLoading ? 'Logging in...' : 'Login with AuthSafe'}
    </button>
  );
}

Return Values

Property	Type	Description
`signinRedirect`	`(extraParams?: Record<string, string>) => Promise<void>`	Initiates the OAuth/OIDC authorization flow by redirecting to the authorization endpoint. Uses OIDC client with PKCE for secure authentication.
`signinPopup`	`(extraParams?: Record<string, string>) => Promise<void>`	Initiates the OAuth/OIDC authorization flow using a popup window. The user will authenticate in a popup and the current page will remain unchanged.
`isLoading`	`boolean`	Indicates if the login flow is being initiated
`error`	`Error \| null`	Error that occurred during login initiation

Extra Parameters

Both signinRedirect and signinPopup accept optional extra parameters that will be passed to the authorization endpoint. Common parameters include:

Parameter	Type	Description
`scope`	`string`	OAuth scopes to request (e.g., 'openid profile email')
`prompt`	`string`	Controls the authentication UI behavior ('none', 'login', 'consent', 'select_account')
`ui_locales`	`string`	Preferred language for the authentication UI (e.g., 'en-US')
`login_hint`	`string`	Hint to the authorization server about the user's login identifier
`max_age`	`string`	Maximum authentication age in seconds

Login with Extra Parameters

import { useLogin } from 'authsafe-react';

function LoginButton() {
  const { signinRedirect, isLoading, error } = useLogin();

  const handleLogin = () => {
    signinRedirect({
      scope: 'openid profile email',
      prompt: 'login',
      ui_locales: 'en-US'
    });
  };

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return (
    <button onClick={handleLogin} disabled={isLoading}>
      {isLoading ? 'Logging in...' : 'Login'}
    </button>
  );
}

Popup Mode

Use signinPopup() for a less disruptive login experience that keeps the user on the current page:

import { useLogin } from 'authsafe-react';

function LoginButton() {
  const { signinPopup, isLoading } = useLogin();

  const handlePopupLogin = async () => {
    try {
      await signinPopup({
        scope: 'openid profile email'
      });
      // User is now authenticated
    } catch (err) {
      console.error('Login failed:', err);
    }
  };

  return (
    <button onClick={handlePopupLogin} disabled={isLoading}>
      {isLoading ? 'Logging in...' : 'Login with Popup'}
    </button>
  );
}

Popup vs Redirect

Redirect: The user is redirected to the authorization server and then back to your app. This is the most compatible method and works in all browsers.
Popup: A popup window opens for authentication, keeping the current page intact. This provides a better user experience but may be blocked by popup blockers.

Type Definition

interface IUseLogin {
  /**
   * Initiates the OAuth/OIDC authorization flow by redirecting to the authorization endpoint.
   * Uses OIDC client with PKCE for secure authentication.
   */
  signinRedirect: (extraParams?: Record<string, string>) => Promise<void>;

  /**
   * Initiates the OAuth/OIDC authorization flow using a popup window.
   * The user will authenticate in a popup and the current page will remain unchanged.
   */
  signinPopup: (extraParams?: Record<string, string>) => Promise<void>;

  /**
   * Indicates if the login flow is being initiated.
   */
  isLoading: boolean;

  /**
   * Error that occurred during login initiation.
   */
  error: Error | null;
}

Security & Best Practices

The hook automatically uses PKCE (Proof Key for Code Exchange) for enhanced security
Always disable the login button when isLoading is true to prevent multiple login attempts
Handle the error state to provide meaningful feedback to users
Request only the scopes your application needs to follow the principle of least privilege
When using popup mode, ensure popup blockers won't interfere by triggering the login from a direct user action (e.g., button click)