Skip to main content

Authentication

This section provides a collection of recipes for building a secure authentication system with Archibald.

Sections​

  • Core Concepts: Deep dive into session management, providers, adapters, token handling, route protection, and SSR hydration.
  • OIDC Login: The OpenID Connect authorization code flow (since v9) — flow overview, setup as in the shop template, and migration from the password flow.
  • CDC Integration: A guide to integrating SAP Customer Data Cloud (CDC) as an identity provider.
  • Best Practices: Security recommendations and best practices for production applications.
  • API Reference: Technical reference for classes, hooks, and configuration options.

Auth Architecture Diagram

This diagram illustrates the architecture of the @archibald/auth package and its integration within the Archibald framework, covering both server-side and client-side components for web and native platforms.

Key Components​

Server-Side (@archibald/auth)​

  • AuthModule: The central module that orchestrates authentication. It's configured with providers and a strategy when registered in the main CoreServer.
  • AuthService: Contains the core business logic for handling login, logout, token refreshing, and user data retrieval.
  • AuthController: Exposes the REST API endpoints (e.g., /login, /logout, /user) that the client-side interacts with.
  • getSession(): A utility function to access the current user's session data from anywhere in the backend (services, controllers).
  • Providers: Connect to a backend system (e.g., SAP Commerce Cloud, CDC) to validate credentials and fetch user data.

Client-Side (@archibald/auth)​

  • SessionClient: A singleton service that manages the user's session state on the client.
  • SessionClientProvider: A React Context provider, typically bootstrapped via ProviderComposer.
  • useUser, useIsLoggedIn: Standard hooks to access the user's authentication state.
  • RestrictedRoute: A web-specific component used to guard pages and redirect unauthenticated users.
  • Stack.Protected: An expo-router feature used in native apps to define guarded navigation stacks.

Flow​

  1. Initialization:

    • On the server, the CoreServer registers the AuthModule with the appropriate strategy.
    • On the client, the SessionClientProvider (inside ProviderComposer) makes the SessionClient available.

  2. Login:

    • The useLogin hook calls sessionClient.logIn().
    • Which flow runs is chosen per call via credentials.authProtocol:
      • 'oidc' (recommended since v9): the browser is redirected to the identity provider and back — see OIDC Login Flow.
      • 'password' (deprecated since v9): the SessionClient, via an AuthAdapter, sends credentials to the server's POST auth/login endpoint.
    • In both cases the AuthModule validates via a Provider and sets secure JWE tokens in cookies or headers.

  3. UI Protection:

    • Web: The RestrictedRoute checks useIsLoggedIn() and uses <Navigate /> if the user is not authenticated.
    • Native: The navigation layout uses <Stack.Protected guard={isLoggedIn}> to dynamically swap available screens.

Key Takeaways​

  • Use the provided hooks: Always use the hooks provided by the @archibald/auth package (e.g., useUser, useLogin, useLogOut) to interact with the user's session.
  • Secure token storage: Use CookieAuthAdapter for web applications and HeaderAuthAdapter for native applications.
  • Bootstrapping: Always use ProviderComposer in your App component to wrap the SessionClientProvider.
  • Server Context: Use getSession() in your backend services instead of passing the request object manually.