@flusys/ng-auth

JWT authentication library for FLUSYS Angular apps — login, session restore, token refresh, multi-company selection, and provider adapter registration.

Installation

npm install @flusys/ng-auth @flusys/ng-core @flusys/ng-shared

1. Register Providers

// app.config.ts
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { provideAuthProviders, provideAuthLayoutIntegration, authInterceptor, tokenRefreshInterceptor } from '@flusys/ng-auth';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withInterceptors([
        authInterceptor,           // attaches Bearer token; sends withCredentials for cookie endpoints
        tokenRefreshInterceptor,   // proactive + reactive refresh; queues concurrent 401s
      ])
    ),
    ...provideAuthProviders(),          // USER_PROVIDER, COMPANY_API_PROVIDER, USER_PERMISSION_PROVIDER, AUTH_STATE_PROVIDER
    ...provideAuthLayoutIntegration(),  // LAYOUT_AUTH_STATE, LAYOUT_AUTH_API
  ],
};

Interceptor order matters: authInterceptor must come before tokenRefreshInterceptor.

2. Add Routes

// app.routes.ts
import { AUTH_ROUTES, ADMINISTRATION_ROUTES, PROFILE_ROUTES } from '@flusys/ng-auth';

export const routes: Routes = [
  {
    path: 'auth',
    loadChildren: () => AUTH_ROUTES,        // login, register, forgot-password, reset-password, verify-email
  },
  {
    path: 'administration',
    loadChildren: () => ADMINISTRATION_ROUTES, // users, company, branch (protected by authGuard)
  },
  {
    path: 'profile',
    loadChildren: () => PROFILE_ROUTES,     // profile page (protected by authGuard)
  },
];

3. Protect Routes with Guards

import { authGuard, guestGuard, companyFeatureGuard } from '@flusys/ng-auth';

const routes: Routes = [
  {
    path: 'dashboard',
    canActivate: [authGuard],          // redirects to /auth/login if not authenticated
    loadComponent: () => import('./dashboard.component'),
  },
  {
    path: 'auth/login',
    canActivate: [guestGuard],         // redirects to '/' if already authenticated; restores session first
    loadComponent: () => import('./login.component'),
  },
];

| Guard | Exported name | Behavior | |---|---|---| | Require auth | authGuard | Redirects to /auth/login; checks company if enableCompanyFeature is on | | Require guest | guestGuard | Redirects to / (or returnUrl) if authenticated; calls AuthInitService.initialize() | | Require company feature | companyFeatureGuard | Redirects to / if company feature is disabled in config |

4. Read Auth State

AuthStateService holds all auth state as read-only signals. The access token is memory-only (never persisted).

import { AuthStateService } from '@flusys/ng-auth';

@Component({ ... })
export class MyComponent {
  private readonly authState = inject(AuthStateService);

  readonly user        = this.authState.user;           // Signal<IUserInfo | null>
  readonly company     = this.authState.company;        // Signal<ICompanyInfo | null>
  readonly branch      = this.authState.branch;         // Signal<IBranchInfo | null>
  readonly isAuth      = this.authState.isAuthenticated; // Signal<boolean>
  readonly tokenExpired = this.authState.isTokenExpired; // Signal<boolean>
}

Key state methods:

authState.setLoginState(data);          // sets user + token + company + branch
authState.setSelectionState(data);      // multi-company selection flow
authState.resetState();                 // logout — clears all state + localStorage
authState.navigateToLogin(returnUrl?);  // safe redirect (rejects external URLs)

6. Session Restore

AuthInitService.initialize() runs POST /auth/refresh (HTTP-only cookie) then POST /auth/me to restore session in memory. It is called automatically by guestGuard. Call it manually if needed:

import { AuthInitService } from '@flusys/ng-auth';

const authInit = inject(AuthInitService);

authInit.initialize().subscribe(isAuthenticated => {
  // safe to read authState signals now
});

The initialized signal is true after the first call completes (success or failure).

7. Extend Registration / Profile (Optional)

Inject custom fields and sections via extension tokens:

import { AUTH_REGISTRATION_EXTENSION, AUTH_PROFILE_EXTENSION, AUTH_USER_LIST_EXTENSION, AUTH_VALIDATION_CONFIG } from '@flusys/ng-auth';

providers: [
  { provide: AUTH_REGISTRATION_EXTENSION, useClass: MyRegistrationExtension }, // extra fields on register form
  { provide: AUTH_PROFILE_EXTENSION, useClass: MyProfileExtension },            // extra sections on profile page
  { provide: AUTH_USER_LIST_EXTENSION, useClass: MyUserListExtension },         // extra columns/actions on user list
  {
    provide: AUTH_VALIDATION_CONFIG,
    useValue: {
      password: { minLength: 10, requireUppercase: true, requireSpecialChars: true },
    },
  },
]

License

MIT © FLUSYS