Client Authentication

Implement secure authentication for your application using Signify iD's redirect-based authentication system.

Authentication Flow

Signify iD uses a redirect-based authentication flow. Here's how it works:

Authentication Flow

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Your App     │    │   Signify iD    │    │  Signify API    │
│                 │    │   Login Page    │    │                 │
└────────┬────────┘    └────────┬────────┘    └────────┬────────┘
         │                      │                      │
         │ 1. User visits       │                      │
         │    protected route   │                      │
         │                      │                      │
         │ 2. Redirect ───────► │                      │
         │    ?redirect=...     │                      │
         │                      │                      │
         │                      │ 3. User logs in      │
         │                      │                      │
         │ 4. Redirect back ◄── │                      │
         │    ?token=...        │                      │
         │                      │                      │
         │ 5. SDK extracts token, stores in cookie     │
         │                      │                      │
         │ 6. Validate session ─────────────────────► │
         │                      │                      │
         │ 7. Session data ◄─────────────────────────  │
         │                      │                      │
         │ 8. User authenticated│                      │
         │    ✓                 │                      │

1
User Visits Protected Route
User attempts to access a page wrapped with ProtectedRoute
2
Redirect to Signify iD
User is redirected to Signify iD login page with a redirect URL
3
User Authenticates
User enters credentials and completes MFA if required
4
Redirect Back with Token
User is redirected back to your app with a token in the URL
5
SDK Processes Token
The SDK automatically extracts the token, stores it in a cookie, and cleans the URL
6
Session Validation
The SDK validates the session with the Signify API and retrieves user data

Using the SDK

The Signify iD SDK handles the entire authentication flow for you. Here's how to implement it:

1. Configure the Provider

tsx

1 import { SignifyProvider } from "signifyid/client";
2 
3 <SignifyProvider
4   config={{
5     apiUrl: process.env.NEXT_PUBLIC_SIGNIFY_API_URL!,
6     loginUrl: process.env.NEXT_PUBLIC_SIGNIFY_LOGIN_URL!,
7     cookieName: "clientSession",     // Optional
8     cookieMaxAge: 86400,             // Optional: 24 hours
9     tokenParam: "token",             // Optional
10     debug: false,                    // Optional
11   }}
12   onAuthStateChange={(state) => {
13     // Optional: Listen to auth state changes
14     console.log("Auth state changed:", state);
15   }}
16 >
17   {children}
18 </SignifyProvider>

2. Trigger Login

tsx

1 import { useSignifyAuth } from "signifyid/client";
2 
3 function LoginButton() {
4   const { login, isLoading } = useSignifyAuth();
5 
6   return (
7     <button onClick={login} disabled={isLoading}>
8       {isLoading ? "Redirecting..." : "Sign in with Signify iD"}
9     </button>
10   );
11 }

3. Access User Data

tsx

1 import { useSignifyAuth } from "signifyid/client";
2 
3 function UserProfile() {
4   const { isAuthenticated, user, session } = useSignifyAuth();
5 
6   if (!isAuthenticated) {
7     return <div>Please sign in</div>;
8   }
9 
10   return (
11     <div>
12       <h1>Welcome, {user?.name}!</h1>
13       <p>Email: {user?.email}</p>
14       <p>Session expires: {new Date(session?.expiresAt).toLocaleString()}</p>
15     </div>
16   );
17 }

Session Management

The SDK manages sessions automatically using secure cookies.

Cookie Storage

• Tokens are stored in HTTP-only cookies
• Default cookie name: clientSession
• Uses SameSite=Lax for CSRF protection

Automatic Validation

• Session is validated on page load
• Invalid sessions trigger automatic logout
• Manual re-validation available via validateSession()

Token Handling

• Tokens are extracted from URL automatically
• URL is cleaned after token extraction
• Tokens are never exposed in JavaScript state

Manual Session Validation

tsx

const { validateSession } = useSignifyAuth();

// Re-validate session on demand
const handleRefresh = async () => {
  await validateSession();
  console.log("Session re-validated");
};

Protected Routes

Use the ProtectedRoute component to secure pages:

tsx

1 import { ProtectedRoute } from "signifyid/client";
2 
3 // Basic usage
4 <ProtectedRoute>
5   <Dashboard />
6 </ProtectedRoute>
7 
8 // With custom loading component
9 <ProtectedRoute
10   loadingComponent={
11     <div className="flex items-center justify-center min-h-screen">
12       <Spinner />
13     </div>
14   }
15 >
16   <Dashboard />
17 </ProtectedRoute>
18 
19 // With custom redirect URL
20 <ProtectedRoute redirectUrl="/custom-login">
21   <Dashboard />
22 </ProtectedRoute>
23 
24 // With redirect callback
25 <ProtectedRoute
26   onRedirect={() => {
27     analytics.track("Unauthenticated access attempt");
28   }}
29 >
30   <Dashboard />
31 </ProtectedRoute>

Logging Out

Use the logout function to sign out users:

tsx

1 import { useSignifyAuth } from "signifyid/client";
2 
3 function LogoutButton() {
4   const { logout, isLoading } = useSignifyAuth();
5 
6   const handleLogout = async () => {
7     await logout();
8     // User is now logged out
9     // Session cookie is cleared
10   };
11 
12   return (
13     <button onClick={handleLogout} disabled={isLoading}>
14       {isLoading ? "Signing out..." : "Sign Out"}
15     </button>
16   );
17 }

Logout Behavior

The logout function clears the session cookie and calls the API to invalidate the session server-side. The user will need to re-authenticate on their next visit.

Security Considerations

SSR Safe

All browser APIs are wrapped with isBrowser() checks for server-side rendering compatibility.

CORS Support

Uses credentials: 'include' for cross-domain cookie support with CORS.

Token Security

Tokens are automatically removed from URLs after extraction to prevent exposure in browser history.

CSRF Protection

Uses SameSite=Lax cookies for built-in CSRF protection.

1	import { SignifyProvider } from "signifyid/client";
2
3	<SignifyProvider
4	config={{
5	apiUrl: process.env.NEXT_PUBLIC_SIGNIFY_API_URL!,
6	loginUrl: process.env.NEXT_PUBLIC_SIGNIFY_LOGIN_URL!,
7	cookieName: "clientSession", // Optional
8	cookieMaxAge: 86400, // Optional: 24 hours
9	tokenParam: "token", // Optional
10	debug: false, // Optional
11	}}
12	onAuthStateChange={(state) => {
13	// Optional: Listen to auth state changes
14	console.log("Auth state changed:", state);
15	}}
16	>
17	{children}
18	</SignifyProvider>

1	import { useSignifyAuth } from "signifyid/client";
2
3	function LoginButton() {
4	const { login, isLoading } = useSignifyAuth();
5
6	return (
7	<button onClick={login} disabled={isLoading}>
8	{isLoading ? "Redirecting..." : "Sign in with Signify iD"}
9	</button>
10	);
11	}

1	import { useSignifyAuth } from "signifyid/client";
2
3	function UserProfile() {
4	const { isAuthenticated, user, session } = useSignifyAuth();
5
6	if (!isAuthenticated) {
7	return <div>Please sign in</div>;
8	}
9
10	return (
11	<div>
12	<h1>Welcome, {user?.name}!</h1>
13	<p>Email: {user?.email}</p>
14	<p>Session expires: {new Date(session?.expiresAt).toLocaleString()}</p>
15	</div>
16	);
17	}

1	import { ProtectedRoute } from "signifyid/client";
2
3	// Basic usage
4	<ProtectedRoute>
5	<Dashboard />
6	</ProtectedRoute>
7
8	// With custom loading component
9	<ProtectedRoute
10	loadingComponent={
11	<div className="flex items-center justify-center min-h-screen">
12	<Spinner />
13	</div>
14	}
15	>
16	<Dashboard />
17	</ProtectedRoute>
18
19	// With custom redirect URL
20	<ProtectedRoute redirectUrl="/custom-login">
21	<Dashboard />
22	</ProtectedRoute>
23
24	// With redirect callback
25	<ProtectedRoute
26	onRedirect={() => {
27	analytics.track("Unauthenticated access attempt");
28	}}
29	>
30	<Dashboard />
31	</ProtectedRoute>

1	import { useSignifyAuth } from "signifyid/client";
2
3	function LogoutButton() {
4	const { logout, isLoading } = useSignifyAuth();
5
6	const handleLogout = async () => {
7	await logout();
8	// User is now logged out
9	// Session cookie is cleared
10	};
11
12	return (
13	<button onClick={handleLogout} disabled={isLoading}>
14	{isLoading ? "Signing out..." : "Sign Out"}
15	</button>
16	);
17	}