keycloak-angular 16.0.1 → 19.0.0

package/README.md

@@ -8,7 +8,7 @@
 [![npm][npm-badge]][npm]
 <!-- prettier-ignore-end -->
 
-> Easy Keycloak setup for Angular applications.
+> Easy Keycloak integration for Angular applications.
 
 ---
 
@@ -16,9 +16,11 @@
 - [Installation](#installation)
 - [Setup](#setup)
 - [Example project](#example-project)
-- [AuthGuard](#authguard)
-- [HttpClient Interceptor](#httpclient-interceptor)
-- [Keycloak-js Events](#keycloak-js-events)
+- [Keycloak Angular Features](#Keycloak-angular-features)
+- [Guards](#guards)
+- [HttpClient Interceptors](#httpclient-interceptors)
+- [Directives](#directives)
+- [Keycloak Events Signal](#keycloak-events-signal)
 - [Contributors](#contributors)
 - [License](#license)
 
@@ -26,16 +28,15 @@
 
 ## About
 
-This library helps you to use [keycloak-js](https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter) in Angular applications providing the following features:
+`Keycloak-Angular` is a library that makes it easier to use [keycloak-js](https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter) in Angular applications. It provides the following features:
 
-- A **Keycloak Service** which wraps the `keycloak-js` methods to be used in Angular, giving extra
-  functionalities to the original functions and adding new methods to make it easier to be consumed by
-  Angular applications.
-- Generic **AuthGuard implementation**, so you can customize your own AuthGuard logic inheriting the authentication logic and the roles load.
-- A **HttpClient interceptor** that adds the authorization header to all HttpClient requests.
-  It is also possible to disable this interceptor or exclude routes from having the authorization header.
-- This documentation also assists you to configure the keycloak in your Angular applications and with
-  the client setup in the admin console of your keycloak installation.
+- **Easy Initialization**: Use the `provideKeycloak` function to set up and initialize a Keycloak instance with `provideAppInitializer`. This simplifies the setup process.
+- **Angular DI Support**: The Keycloak client instance can be injected directly into Angular components, services, and other parts of your app. There’s no need to create a custom service to wrap the client.
+- **HTTP Interceptors**: Add the Bearer token to the `Authorization` header with built-in interceptors. These are modular and easy to configure using injection tokens. You can also create your own interceptors with provided helper functions.
+- **Keycloak Events as Signals**: Access Keycloak events easily using Angular Signals, provided through the `KEYCLOAK_EVENT_SIGNAL` injection token.
+- **Automatic Token Refresh**: Use the `withAutoRefreshToken` feature to automatically refresh tokens when they expire, considering the user activity and a sessionTimeout.
+- **Custom Route Guards**: Use the `createAuthGuard` factory to build guards for `CanActivate` and `CanActivateChild`, helping you secure routes with custom logic.
+- **Role-Based Rendering**: The `*kaHasRoles` directive lets you show or hide parts of the DOM based on the user’s resource or realm roles.
 
 ## Installation
 
@@ -45,20 +46,20 @@ Run the following command to install both Keycloak Angular and the official Keyc
 npm install keycloak-angular keycloak-js
 ```
 
-Note that `keycloak-js` is a peer dependency of Keycloak Angular. This change allows greater flexibility of choosing the right version of the Keycloak client version for your project.
+Note that `keycloak-js` is a peer dependency of `keycloak-angular`. This allows greater flexibility of choosing the right version of the Keycloak client for your project.
 
 ### Versions
 
 | Angular | keycloak-js | keycloak-angular |       Support       |
-| :-----: |:-----------:| :--------------: | :-----------------: |
-|  18.x   |   18 - 25   |      16.x.x      | New Features / Bugs |
-|  17.x   |   18 - 25   |      15.x.x      |        Bugs         |
+| :-----: | :---------: | :--------------: | :-----------------: |
+|  19.x   |   18 - 26   |      19.x.x      | New Features / Bugs |
+|  18.x   |   18 - 26   |      16.x.x      |        Bugs         |
+|  17.x   |   18 - 25   |      15.x.x      |          -          |
 |  16.x   |   18 - 25   |      14.x.x      |          -          |
 |  15.x   |   18 - 21   |      13.x.x      |          -          |
-|  14.x   |   18 - 19   |      12.x.x      |          -          |
-|  14.x   |   10 - 17   |      11.x.x      |          -          |
 
-Only the latest version of Angular in the table above is actively supported. This is due to the fact that compilation of Angular libraries might be [incompatible between major versions](https://angular.io/guide/creating-libraries#ensuring-library-version-compatibility).
+> 1. Only the latest version of Angular listed in the table above is actively supported. This is because the compilation of Angular libraries can be [incompatible between major versions](https://angular.io/guide/creating-libraries#ensuring-library-version-compatibility).
+> 2. Starting with Angular v19, Keycloak-Angular will adopt the same **major** version numbering as Angular, making it easier to identify the correct version to use.
 
 #### Choosing the right keycloak-js version
 
@@ -66,54 +67,47 @@ The Keycloak client documentation recommends to use the same version of your Key
 
 ## Setup
 
-In order to make sure Keycloak is initialized when your application is bootstrapped you will have to add an `APP_INITIALIZER` provider to your `AppModule`. This provider will call the `initializeKeycloak` factory function shown below which will set up the Keycloak service so that it can be used in your application.
+To initialize Keycloak, add `provideKeycloak` to the `providers` array in the `ApplicationConfig` object (e.g., in `app.config.ts`). If `initOptions` is included, `keycloak-angular` will automatically use `provideAppInitializer` to handle initialization, following the recommended approach for starting dependencies.
 
-Use the code provided below as an example and implement it's functionality in your application. In this process ensure that the configuration you are providing matches that of your client as configured in Keycloak.
+Use the example code below as a guide for your application.
 
 ```ts
-import { APP_INITIALIZER, NgModule } from '@angular/core';
-import { BrowserModule } from '@angular/platform-browser';
-import { KeycloakAngularModule, KeycloakService } from 'keycloak-angular';
-import { AppRoutingModule } from './app-routing.module';
-import { AppComponent } from './app.component';
-
-function initializeKeycloak(keycloak: KeycloakService) {
-  return () =>
-    keycloak.init({
+import { provideRouter } from '@angular/router';
+import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
+import { provideKeycloak } from 'keycloak-angular';
+
+import { routes } from './app.routes';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideKeycloak({
       config: {
-        url: 'http://localhost:8080',
-        realm: 'your-realm',
-        clientId: 'your-client-id'
+        url: 'keycloak-server-url',
+        realm: 'realm-id',
+        clientId: 'client-id'
       },
       initOptions: {
         onLoad: 'check-sso',
-        silentCheckSsoRedirectUri:
-          window.location.origin + '/assets/silent-check-sso.html'
+        silentCheckSsoRedirectUri: window.location.origin + '/silent-check-sso.html'
       }
-    });
-}
-
-@NgModule({
-  declarations: [AppComponent],
-  imports: [AppRoutingModule, BrowserModule, KeycloakAngularModule],
-  providers: [
-    {
-      provide: APP_INITIALIZER,
-      useFactory: initializeKeycloak,
-      multi: true,
-      deps: [KeycloakService]
-    }
-  ],
-  bootstrap: [AppComponent]
-})
-export class AppModule {}
+    }),
+    provideZoneChangeDetection({ eventCoalescing: true }),
+    provideRouter(routes)
+  ]
+};
 ```
 
-In the example we have set up Keycloak to use a silent `check-sso`. With this feature enabled, your browser will not do a full redirect to the Keycloak server and back to your application, instead this action will be performed in a hidden iframe, so your application resources only need to be loaded and parsed once by the browser when the app is initialized and not again after the redirect back from Keycloak to your app.
+> **Important:**
+>
+> 1. You do not need to call `provideAppInitializer` if `initOptions` is provided. The library handles this automatically.
+> 2. If you need to control when `keycloak.init` is called, do not pass the `initOptions` to the `provideKeycloak` function. In this case, you are responsible for calling `keycloak.init` manually.
+> 3. For reference, Angular's `APP_INITIALIZER` is deprecated. The recommended approach is to use `provideAppInitializer`.
+
+In the example, Keycloak is configured to use a silent `check-sso`. With this feature enabled, your browser avoids a full redirect to the Keycloak server and back to your application. Instead, this action is performed in a hidden iframe, allowing your application resources to be loaded and parsed only once during initialization, rather than reloading after a redirect.
 
-To ensure that Keycloak can communicate through the iframe you will have to serve a static HTML asset from your application at the location provided in `silentCheckSsoRedirectUri`.
+To enable communication through the iframe, you need to serve a static HTML file from your application at the location specified in `silentCheckSsoRedirectUri`.
 
-Create a file called `silent-check-sso.html` in the `assets` directory of your application and paste in the contents as seen below.
+Create a file named `silent-check-sso.html` in the `public` or `assets` directory of your application and paste in the content shown below.
 
 ```html
 <html>
@@ -127,130 +121,230 @@ Create a file called `silent-check-sso.html` in the `assets` directory of your a
 
 If you want to know more about these options and various other capabilities of the Keycloak client is recommended to read the [JavaScript Adapter documentation](https://www.keycloak.org/docs/latest/securing_apps/#_javascript_adapter).
 
+> **Note About NgModules:**
+> Since Keycloak-Angular v19, the KeycloakAngularModule, KeycloakService, KeycloakBearerInterceptor and KeycloakAuthGuard are deprecated.
+> If your application relies on NgModules, the library still has support for it. See more information on how to configure a [NgModule the application](https://github.com/mauriciovigolo/keycloak-angular/docs/ngmodule.md).
+
+**Additional Resources**
+For more details, refer to the [provideKeycloak](https://github.com/mauriciovigolo/keycloak-angular/docs/provide.md) documentation.
+
 ## Example project
 
-If you want to see a complete overview a pre-configured client together with a working Keycloak server make sure to check out the [example project](projects/example/README.md) in this repository.
+If you want to see a complete overview a pre-configured client together with a working Keycloak server make sure to check out the [standalone example project](projects/examples/standalone/README.md) in this repository.
 
-## AuthGuard
+## Keycloak Angular Features
 
-A generic AuthGuard, `KeycloakAuthGuard` is provided to help you protect authenticated routes in your application. This guard provides you with information to see if the user is logged in and a list of roles from that belong to the user. In your implementation you just need to implement the desired logic to protect your routes.
+Keycloak Angular Features enhance the library's capabilities and make it more modular and composable. These features are executed during application initialization and have access to Angular's Dependency Injection (DI) context. While there is currently only one feature available, more features will be introduced over time to address new scenarios and expand functionality.
 
-To write your own implementation extend the `KeycloakAuthGuard` class and implement the `isAccessAllowed` method. For example the code provided below checks if the user is authenticated and if not the user is requested to sign in. It also checks if the user has the correct roles which could be provided by passing the `roles` field into the data of the route.
+### Usage
+
+The example below adds the `withAutoRefreshToken` feature to Keycloak Angular. Note that this feature depends on two services provided by Keycloak Angular, which are: `AutoRefreshTokenService` and `UserActivityService`.
 
 ```ts
-import { Injectable } from '@angular/core';
-import {
-  ActivatedRouteSnapshot,
-  Router,
-  RouterStateSnapshot
-} from '@angular/router';
-import { KeycloakAuthGuard, KeycloakService } from 'keycloak-angular';
-
-@Injectable({
-  providedIn: 'root'
-})
-export class AuthGuard extends KeycloakAuthGuard {
-  constructor(
-    protected readonly router: Router,
-    protected readonly keycloak: KeycloakService
-  ) {
-    super(router, keycloak);
+import { provideKeycloak, withAutoRefreshToken, AutoRefreshTokenService, UserActivityService } from 'keycloak-angular';
+
+export const provideKeycloakAngular = () =>
+  provideKeycloak({
+    config: {
+      url: 'keycloak-server-url',
+      realm: 'realm-id',
+      clientId: 'client-id'
+    },
+    initOptions: {
+      onLoad: 'check-sso',
+      silentCheckSsoRedirectUri: window.location.origin + '/silent-check-sso.html'
+    },
+    features: [
+      withAutoRefreshToken({
+        onInactivityTimeout: 'logout',
+        sessionTimeout: 60000
+      })
+    ],
+    providers: [AutoRefreshTokenService, UserActivityService]
+  });
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideKeycloakAngular(), provideZoneChangeDetection({ eventCoalescing: true }), provideRouter(routes)]
+};
+```
+
+## Guards
+
+The `createAuthGuard` function is a higher-order function that simplifies the creation of guards relying on Keycloak data. It can be used to create `CanActivateFn` or `CanActivateChildFn` guards to protect the routes in your application.
+
+### Usage:
+
+```ts
+import { ActivatedRouteSnapshot, CanActivateFn, Router, RouterStateSnapshot, UrlTree } from '@angular/router';
+import { inject } from '@angular/core';
+import { AuthGuardData, createAuthGuard } from 'keycloak-angular';
+
+const isAccessAllowed = async (
+  route: ActivatedRouteSnapshot,
+  _: RouterStateSnapshot,
+  authData: AuthGuardData
+): Promise<boolean | UrlTree> => {
+  const { authenticated, grantedRoles } = authData;
+
+  const requiredRole = route.data['role'];
+  if (!requiredRole) {
+    return false;
   }
 
-  public async isAccessAllowed(
-    route: ActivatedRouteSnapshot,
-    state: RouterStateSnapshot
-  ) {
-    // Force the user to log in if currently unauthenticated.
-    if (!this.authenticated) {
-      await this.keycloak.login({
-        redirectUri: window.location.origin + state.url
-      });
-    }
-
-    // Get the roles required from the route.
-    const requiredRoles = route.data.roles;
-
-    // Allow the user to proceed if no additional roles are required to access the route.
-    if (!Array.isArray(requiredRoles) || requiredRoles.length === 0) {
-      return true;
-    }
-
-    // Allow the user to proceed if all the required roles are present.
-    return requiredRoles.every((role) => this.roles.includes(role));
+  const hasRequiredRole = (role: string): boolean =>
+    Object.values(grantedRoles.resourceRoles).some((roles) => roles.includes(role));
+
+  if (authenticated && hasRequiredRole(requiredRole)) {
+    return true;
   }
-}
-```
 
-## HttpClient Interceptor
+  const router = inject(Router);
+  return router.parseUrl('/forbidden');
+};
 
-By default, all HttpClient requests will add the Authorization header in the format of: `Authorization: Bearer **_TOKEN_**`.
+export const canActivateAuthRole = createAuthGuard<CanActivateFn>(isAccessAllowed);
+```
 
-There is also the possibility to exclude requests that should not have the authorization header. This is accomplished by implementing the `shouldAddToken` method in the keycloak initialization. For example, the configuration below will not add the token to `GET` requests that match the paths `/assets` or `/clients/public`:
+The `canActivateAuthRole` can be used in the route configuration to protect specific routes.
 
 ```ts
-await keycloak.init({
-  config: {
-    url: 'http://localhost:8080',
-    realm: 'your-realm',
-    clientId: 'your-client-id'
-  },
-  initOptions: {
-    onLoad: 'check-sso',
-    silentCheckSsoRedirectUri:
-      window.location.origin + '/assets/silent-check-sso.html'
-  },
-  shouldAddToken: (request) => {
-    const { method, url } = request;
-
-    const isGetRequest = 'GET' === method.toUpperCase();
-    const acceptablePaths = ['/assets', '/clients/public'];
-    const isAcceptablePathMatch = acceptablePaths.some((path) =>
-      url.includes(path)
-    );
-
-    return !(isGetRequest && isAcceptablePathMatch);
+import { Routes } from '@angular/router';
+
+import { HomeComponent } from './components/home/home.component';
+import { BooksComponent } from './components/books/books.component';
+import { canActivateAuthRole } from './guards/auth-role.guard';
+
+export const routes: Routes = [
+  { path: '', component: HomeComponent },
+  {
+    path: 'books',
+    component: BooksComponent,
+    canActivate: [canActivateAuthRole],
+    data: { role: 'view-books' }
   }
-});
+];
 ```
 
-In the case where your application frequently polls an authenticated endpoint, you will find that users will not be logged out automatically over time. If that functionality is not desirable, you can add an http header to the polling requests then configure the `shouldUpdateToken` option in the keycloak initialization.
+## HttpClient Interceptors
+
+Keycloak Angular provides `HttpClient` interceptors for managing the Bearer Token in the HTTP request header.
+
+> By default, the library **does not** add the Bearer token to requests. It is the application's responsibility to configure and use the appropriate interceptors.
+>
+> **Important:** This behavior is a significant change from previous versions of the library. The new approach is more declarative, secure, extendable and configurable. There are no services directly interacting with interceptors anymore. All configurations are handled within the interceptor itself.
 
-In the example below, any http requests with the header `token-update: false` will not trigger the user's keycloak token to be updated.
+### Usage:
 
 ```ts
-await keycloak.init({
-  config: {
-    url: 'http://localhost:8080',
-    realm: 'your-realm',
-    clientId: 'your-client-id'
-  },
-  initOptions: {
-    onLoad: 'check-sso',
-    silentCheckSsoRedirectUri:
-      window.location.origin + '/assets/silent-check-sso.html'
-  },
-  bearerExcludedUrls: ['/assets', '/clients/public'],
-  shouldUpdateToken(request) {
-    return !request.headers.get('token-update') === 'false';
-  }
+import { provideRouter } from '@angular/router';
+import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import {
+  provideKeycloak,
+  createInterceptorCondition,
+  IncludeBearerTokenCondition,
+  INCLUDE_BEARER_TOKEN_INTERCEPTOR_CONFIG
+} from 'keycloak-angular';
+
+import { routes } from './app.routes';
+
+const urlCondition = createInterceptorCondition<IncludeBearerTokenCondition>({
+  urlPattern: /^(http:\/\/localhost:8181)(\/.*)?$/i,
+  bearerPrefix: 'Bearer'
 });
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideKeycloak({
+      config: {
+        url: 'keycloak-server-url',
+        realm: 'realm-id',
+        clientId: 'client-id'
+      },
+      initOptions: {
+        onLoad: 'check-sso',
+        silentCheckSsoRedirectUri: window.location.origin + '/silent-check-sso.html'
+      }
+    }),
+    {
+      provide: INCLUDE_BEARER_TOKEN_INTERCEPTOR_CONFIG,
+      useValue: [urlCondition] // <-- Note that multiple conditions might be added.
+    },
+    provideZoneChangeDetection({ eventCoalescing: true }),
+    provideRouter(routes),
+    provideHttpClient(withInterceptors([includeBearerTokenInterceptor]))
+  ]
+};
+```
+
+**Additional Resources**
+For more details on the available interceptors and their configurations, refer to the [Keycloak HttpClient Interceptors](https://github.com/mauriciovigolo/keycloak-angular/docs/interceptors.md) documentation.
+
+## Directives
+
+The library offers the `*kaHasRoles` structural directive to evaluate if the user has the required Realm or Resource Roles to render or not to render a DOM.
+
+### Usage
+
+In the component, add the `HasRolesDirective` in the imports list.
+
+```ts
+@Component({
+  selector: 'app-menu',
+  imports: [RouterModule, HasRolesDirective],
+  templateUrl: './menu.component.html',
+  styleUrls: ['./menu.component.css']
+})
+export class MenuComponent {}
+```
+
+```html
+<nav class="menu">
+  <div class="developer-status"><strong>Keycloak Events:</strong> {{ keycloakStatus }}</div>
+
+  <div class="actions">
+    <a routerLink="/" class="action-item">Home</a>
+    <a routerLink="/books" class="action-item" *kaHasRoles="['view-books']">My Books</a>
+  </div>
+</nav>
 ```
 
-## Keycloak-js Events
+> **Note:**  
+> If no resource is specified in `*kaHasRoles="['view-books']"`, the default resource used will be the Keycloak application client ID.
 
-The callback events from [keycloak-js](https://www.keycloak.org/docs/latest/securing_apps/index.html#javascript-adapter-reference) are available through a RxJS subject which is defined by `keycloakEvents$`.
+## Keycloak Events Signal
 
-For example you make keycloak-angular auto refreshing your access token when expired:
+Keycloak Angular provides a Signal that allows Angular applications to easily react to `keycloak-js` authorization and session events.
+
+This Signal is created during the library's initialization and is available without any additional configuration. It can be accessed by injecting the `KEYCLOAK_EVENT_SIGNAL` injection token.
+
+### Usage
 
 ```ts
-keycloakService.keycloakEvents$.subscribe({
-  next(event) {
-    if (event.type == KeycloakEventType.OnTokenExpired) {
-      keycloakService.updateToken(20);
-    }
+@Component({
+  selector: 'app-menu',
+  templateUrl: './menu.component.html',
+  styleUrls: ['./menu.component.css']
+})
+export class MenuComponent {
+  authenticated = false;
+
+  constructor(private readonly keycloak: Keycloak) {
+    const keycloakSignal = inject(KEYCLOAK_EVENT_SIGNAL);
+
+    effect(() => {
+      const keycloakEvent = keycloakSignal();
+
+      if (keycloakEvent.type === KeycloakEventType.Ready) {
+        this.authenticated = typeEventArgs<ReadyArgs>(keycloakEvent.args);
+      }
+
+      if (keycloakEvent.type === KeycloakEventType.AuthLogout) {
+        this.authenticated = false;
+      }
+    });
   }
-});
+}
 ```
 
 ## Contributors