Neverending Programming Mistakes
    Have ideas to improve npm?Join in the discussion! »

    keycloak-angular
    TypeScript icon, indicating that this package has built-in type declarations

    8.2.0 • Public • Published

    Keycloak Angular

    License: MIT Build Status Known Vulnerabilities npm version npm All Contributors Discord

    Easy Keycloak setup for Angular applications.



    About

    This library helps you to use keycloak-js in Angular applications providing 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.

    Installation

    Run the following command to install both Keycloak Angular and the official Keycloak client library:

    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.

    Versions

    Angular keycloak-angular keycloak-js Support
    11.x - 12.x 8.2.x 10 - 13 Bugs / New Features
    10.x 8.x.x 10 - 11 Bugs
    9.x 7.3.x 3.4.3 - 10 (excluding v7) Bugs

    We try to support the same Angular versions that are supported by the Angular team. That said, it's always best to keep up to date with the latest version of Angular for optimal support.

    Choosing the right keycloak-js version

    The Keycloak client documentation recommends to use the same version of your Keycloak installation.

    A best practice is to load the JavaScript adapter directly from Keycloak Server as it will automatically be updated when you upgrade the server. If you copy the adapter to your web application instead, make sure you upgrade the adapter only after you have upgraded the server.

    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.

    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.

    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({
          config: {
            url: 'http://localhost:8080/auth',
            realm: 'your-realm',
            clientId: 'your-client-id',
          },
          initOptions: {
            onLoad: 'check-sso',
            silentCheckSsoRedirectUri:
              window.location.origin + '/assets/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 {}

    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.

    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.

    Create a file called silent-check-sso.html in the assets directory of your application and paste in the contents as seen below.

    <html>
      <body>
        <script>
          parent.postMessage(location.href, location.origin);
        </script>
      </body>
    </html>

    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.

    Example project

    If you want to see an complete overview a pre-configured client together with a working Keycloak server make sure to check out the example project in this repository.

    AuthGuard

    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.

    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.

    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);
      }
    
      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 to proceed if no additional roles are required to access the route.
        if (!(requiredRoles instanceof Array) || 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));
      }
    }

    HttpClient Interceptor

    By default all HttpClient requests will add the Authorization header in the format of: Authorization: Bearer TOKEN.

    There is also the possibility to exclude a list of URLs that should not have the authorization header. The excluded list must be provided in the keycloak initialization. For example:

    await keycloak.init({
      config: {
        url: 'http://localhost:8080/auth',
        realm: 'your-realm',
        clientId: 'your-client-id',
      },
      bearerExcludedUrls: ['/assets', '/clients/public'],
    });

    Contributors


    Mauricio Gemelli Vigolo


    Jon Koops


    Frederik Prijck


    Jonathan Share


    jmparra


    Marcel Német


    Raphael Alex Silva Abreu

    If you want to contribute to the project, please check out the contributing document.

    License

    keycloak-angular is licensed under the MIT license.

    Install

    npm i keycloak-angular

    DownloadsWeekly Downloads

    33,637

    Version

    8.2.0

    License

    MIT

    Unpacked Size

    230 kB

    Total Files

    25

    Last publish

    Collaborators

    • avatar