Skip to main content

Core Concepts

Understanding these core concepts will help you make the most of Signia.

OIDC (OpenID Connect)​

OpenID Connect is an identity layer built on top of OAuth 2.0. It allows applications to verify the identity of users and obtain basic profile information.

Signia implements OIDC, which means:

  • Standard protocol - Works with any OIDC-compliant client
  • Secure tokens - JWT-based authentication
  • Automatic discovery - Endpoints are discovered via .well-known/openid-configuration

How It Works​

  1. User clicks "Login" in your app
  2. Your app redirects to Signia Auth
  3. User authenticates (WebAuthn, passkey, etc.)
  4. Signia redirects back to your app with an authorization code
  5. Your app exchanges the code for tokens
  6. User is authenticated!

Key Terms​

Issuer​

The OIDC Issuer is the base URL of your authentication server. In Signia, this is your tenant URL:

https://YOUR_TENANT.signiaauth.com

The issuer hosts the .well-known/openid-configuration endpoint that clients use to discover all other endpoints automatically.

Client ID​

A unique identifier for your application. You get this when you register an application in the Signia ID dashboard.

5190b937-5392-4eab-984e-ac0cb0fc0c9a

Redirect URI​

The URL where Signia sends users after authentication. This must match exactly what's configured in your application settings.

Important: The redirect URI path is automatically handled by the Signia SDK:

  • Base URI: http://localhost:5173/oidc-callback
  • Login callback: http://localhost:5173/oidc-callback/login
  • Logout callback: http://localhost:5173/oidc-callback/logout
Callback Route Strategy

Signia uses a callback route strategy pattern to handle different flows. You only configure the base redirect URI - the SDK automatically appends /login or /logout as needed.

Scopes​

Scopes define what information your app can access:

  • openid - Required for OIDC (always include this)
  • profile - Access to user profile (name, etc.)
  • email - Access to user email
scopes: ['openid', 'profile', 'email']

Tokens​

After successful authentication, you receive:

ID Token - Contains user identity claims (who the user is) Access Token - Used to access protected resources Refresh Token - Used to get new access tokens (optional)

Multi-Tenancy​

Signia supports multi-tenant architecture:

  • Tenant - An organization (has a subdomain like acme.signiaauth.com)
  • Applications - Apps within a tenant
  • Users - Belong to applications within tenants

Each tenant has its own:

  • Unique subdomain
  • Isolated user base
  • Independent configuration

Authentication Flow​

Authorization Code Flow (Default)​

This is the most secure flow for web applications:

WebAuthn/Passkeys​

Signia supports passwordless authentication using WebAuthn:

  • Biometrics - Face ID, Touch ID, fingerprint
  • Security keys - YubiKey, etc.
  • Device credentials - Platform authenticators

Benefits:

  • 🔒 More secure than passwords
  • ⚡ Faster login experience
  • 📱 Works across devices

SDK Architecture​

The Signia SDK uses a layered architecture:

Core Layer​

  • @getsignia/signia-auth-sdk - Core OIDC/OAuth2 client (framework-agnostic)

Framework Layer​

  • @getsignia/signia-auth-ui-react - React hooks & components
  • @getsignia/signia-auth-ui-react-native - React Native components
  • @getsignia/signia-auth-ui-flutter - Flutter widgets

This separation means:

  • ✅ Protocol logic is reusable
  • ✅ Framework-specific UI is optimized
  • ✅ Easy to add new frameworks

Protected Routes​

Use the <ProtectedRoute> component to restrict access:

<ProtectedRoute loadingComponent={<Spinner />}>
  <SecretPage />
</ProtectedRoute>

The component:

  1. Checks if user is authenticated
  2. Shows loading state while checking
  3. Redirects to login if not authenticated
  4. Renders protected content if authenticated

Session Management​

The SDK automatically handles:

  • Token storage - Secure storage in browser
  • Token refresh - Automatic renewal before expiry
  • Session state - Reactive state updates

Access session state with the useSigniaAuth hook:

const {
  isAuthenticated,  // boolean
  isLoading,        // boolean
  user,            // user info from ID token
  error            // error if any
} = useSigniaAuth();

Next Steps​

Now that you understand the concepts: