keycloak-angular 7.3.1 → 8.2.0

package/README.md

@@ -1,22 +1,23 @@
 # Keycloak Angular
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Build Status](https://travis-ci.org/mauriciovigolo/keycloak-angular.svg?branch=master)](https://travis-ci.org/mauriciovigolo/keycloak-angular)
-[![Known Vulnerabilities](https://snyk.io/test/github/mauriciovigolo/keycloak-angular/badge.svg)](https://snyk.io/test/github/mauriciovigolo/keycloak-angular)
-[![npm version](https://badge.fury.io/js/keycloak-angular.svg)](https://badge.fury.io/js/keycloak-angular)
-![npm](https://img.shields.io/npm/dm/keycloak-angular.svg)
-[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors)
-[![Slack](https://slackin-iijwrzzihr.now.sh/badge.svg)](https://slackin-iijwrzzihr.now.sh)
+<!-- prettier-ignore-start -->
+[![License: MIT][license-mit-badge]][license-mit]
+[![Build Status][build-badge]][build]
+[![Known Vulnerabilities][vulnerabilities-badge]][vulnerabilities]
+[![npm version][npm-version-badge]][npm-version]
+[![npm][npm-badge]][npm]
+[![All Contributors][contributors-badge]](#contributors)
+[![Discord][discord-badge]][discord]
+<!-- prettier-ignore-end -->
 
 > Easy Keycloak setup for Angular applications.
 
 ---
 
 - [About](#about)
-- [Install](#install)
+- [Installation](#installation)
 - [Setup](#setup)
-  - [Angular](#angular)
-  - [Keycloak](#keycloak)
+- [Example project](#example-project)
 - [AuthGuard](#authguard)
 - [HttpClient Interceptor](#httpclient-interceptor)
 - [Contributors](#contributors)
@@ -26,9 +27,9 @@
 
 ## About
 
-This library helps you to use [keycloak-js](https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter) in Angular > v4.3 applications providing the following features:
+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:
 
-- A **Keycloak Service** which wraps the keycloak-js methods to be used in Angular, giving extra
+- 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.
@@ -37,178 +38,146 @@ This library helps you to use [keycloak-js](https://www.keycloak.org/docs/latest
 - 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.
 
-## Install
+## Installation
 
-### keycloak-angular
+Run the following command to install both Keycloak Angular and the official Keycloak client library:
 
 ```sh
-npm i --save keycloak-angular
+npm install keycloak-angular keycloak-js
 ```
 
-**Note about versions**:
+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.
 
-- For Angular v9, please use keycloak-angular v7.3 or higher.
-- For Angular v8 and bellow, keycloak-angular v7.2.
+### Versions
 
-### keycloak-js
+| 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                |
 
-> Since keycloak-angular v.7.0.0, the [keycloak-js](https://www.npmjs.com/package/keycloak-js) dependency became a peer dependency. This change allows greater flexibility for choosing the keycloak-js adapter version and follows the [project documentation recommendation](https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter).
+We try to support the same Angular versions that are [supported](https://angular.io/guide/releases#support-policy-and-schedule) by the Angular team. That said, it's always best to keep up to date with the latest version of Angular for optimal support.
 
-```sh
-npm i --save keycloak-js@version
-```
-
-#### Choosing the keycloak-js version
+#### Choosing the right keycloak-js version
 
-The keycloak-js adapter documentation recommends to use the same version of your Keycloak / RH-SSO (Red Hat Single Sign On) installation.
+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
 
-### Angular
-
-The following topics explain two different ways to bootstrap the library and configure keycloak-angular. The first one is by using the APP_INITIALIZER token and the second option uses ngDoBootstrap. You will have to choose one of them.
-
-#### Using APP_INITIALIZER
+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.
 
-The KeycloakService can be initialized during the application loading, using the [APP_INITIALIZER](https://angular.io/api/core/APP_INITIALIZER) token.
+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.
 
-##### AppModule
-
-```js
-import { NgModule, APP_INITIALIZER } from '@angular/core';
-import { KeycloakService, KeycloakAngularModule } from 'keycloak-angular';
-import { initializer } from './utils/app-init';
+```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({
+      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({
-  imports: [KeycloakAngularModule],
+  declarations: [AppComponent],
+  imports: [AppRoutingModule, BrowserModule, KeycloakAngularModule],
   providers: [
     {
       provide: APP_INITIALIZER,
-      useFactory: initializer,
+      useFactory: initializeKeycloak,
       multi: true,
       deps: [KeycloakService],
     },
   ],
+  bootstrap: [AppComponent],
 })
 export class AppModule {}
 ```
 
-##### Initializer Function
+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.
 
-This function can be named and placed in the way you think is most appropriate. In the
-underneath example it was placed in a separate file `app-init.ts` and the function was called
-`initializer`.
+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`.
 
-```js
-import { KeycloakService } from 'keycloak-angular';
+Create a file called `silent-check-sso.html` in the `assets` directory of your application and paste in the contents as seen below.
 
-export function initializer(keycloak: KeycloakService): () => Promise<any> {
-  return (): Promise<any> => keycloak.init();
-}
+```html
+<html>
+  <body>
+    <script>
+      parent.postMessage(location.href, location.origin);
+    </script>
+  </body>
+</html>
 ```
 
-#### Using ngDoBootstrap
+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).
 
-The KeycloakService can be initialized before the application loading. When the Keycloak initialization is successful the application is bootstrapped.
+## Example project
 
-This has two major benefits.
-
-1. This is faster because the application isn't fully bootstrapped and
-1. It prevents a moment when you see the application without having the authorization.
-
-#### AppModule
-
-```js
-import { NgModule, DoBootstrap, ApplicationRef } from '@angular/core';
-import { KeycloakAngularModule, KeycloakService } from 'keycloak-angular';
-
-const keycloakService = new KeycloakService();
-
-@NgModule({
-  imports: [KeycloakAngularModule],
-  providers: [
-    {
-      provide: KeycloakService,
-      useValue: keycloakService,
-    },
-  ],
-  entryComponents: [AppComponent],
-})
-export class AppModule implements DoBootstrap {
-  ngDoBootstrap(appRef: ApplicationRef) {
-    keycloakService
-      .init()
-      .then(() => {
-        console.log('[ngDoBootstrap] bootstrap app');
-
-        appRef.bootstrap(AppComponent);
-      })
-      .catch((error) =>
-        console.error('[ngDoBootstrap] init Keycloak failed', error)
-      );
-  }
-}
-```
-
-**Hint:** Do not forget to remove `bootstrap: [AppComponent]` from NgModule decorator options.
-
-### Keycloak
-
-Besides configuring the keycloak lib in your application it is also necessary to setup the
-access - scope for the **account** client.
-
-In this documentation we assume that you already installed and configured your Keycloak
-instance, as well created the client app.
-
-**Hint:** If you need to create an environment for testing purposes, try out the [Keycloak demo](http://www.keycloak.org/downloads.html) or the official [keycloak docker image](https://hub.docker.com/r/jboss/keycloak/).
-
-#### Client configuration
-
-When requesting the method to get the User's Profile, the client app should have the scope and access to the account **view-profile** role. To do it, access **Clients** :arrow_right: **My-app** :arrow_right: **Scope**. Select the **account** app in Client Roles and assign the view-profile role.
-
-![keycloak-account-scope](./docs/images/keycloak-account-scope.png)
-
-Please be aware that when accessing the `https://keycloak/auth/realms/REALM/account` endpoint, if this role is not configured, a misleading `No 'Access-Control-Allow-Origin'` error might show up. If that happens, this role should be enough to fix it, no changes in the Web Origin of the account client is needed.
+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](example/README.md) in this repository.
 
 ## AuthGuard
 
-A generic AuthGuard, `KeycloakAuthGuard`, was created to help you bootstrap your security configuration and avoid duplicate code. This class already checks if the user is logged in and get the list of roles from the authenticated user, provided by the keycloak instance. In your implementation you just need to implement the desired security logic.
+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.
 
-Example:
+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.
 
-```js
+```ts
 import { Injectable } from '@angular/core';
-import { CanActivate, ActivatedRouteSnapshot, RouterStateSnapshot, Router } from '@angular/router';
+import {
+  ActivatedRouteSnapshot,
+  Router,
+  RouterStateSnapshot,
+} from '@angular/router';
 import { KeycloakAuthGuard, KeycloakService } from 'keycloak-angular';
 
 @Injectable({
-  providedIn: 'root'
+  providedIn: 'root',
 })
-export class CanAuthenticationGuard extends KeycloakAuthGuard implements CanActivate {
-  constructor(protected router: Router, protected keycloakAngular: KeycloakService) {
-    super(router, keycloakAngular);
+export class AuthGuard extends KeycloakAuthGuard {
+  constructor(
+    protected readonly router: Router,
+    protected readonly keycloak: KeycloakService
+  ) {
+    super(router, keycloak);
   }
 
-  isAccessAllowed(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Promise<boolean> {
-    return new Promise((resolve, reject) => {
-      if (!this.authenticated) {
-        this.keycloakAngular.login()
-          .catch(e => console.error(e));
-        return reject(false);
-      }
-
-      const requiredRoles: string[] = route.data.roles;
-      if (!requiredRoles || requiredRoles.length === 0) {
-        return resolve(true);
-      } else {
-        if (!this.roles || this.roles.length === 0) {
-          resolve(false);
-        }
-        resolve(requiredRoles.every(role => this.roles.indexOf(role) > -1));
-      }
-    });
+  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));
   }
 }
 ```
@@ -217,25 +186,17 @@ export class CanAuthenticationGuard extends KeycloakAuthGuard implements CanActi
 
 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 informed in the keycloak initialization. For example:
-
-```js
-try {
-  await keycloak.init({
-    config: {
-      url: 'http://localhost:8080/auth',
-      realm: 'your-realm',
-      clientId: 'client-id',
-    },
-    initOptions: {
-      onLoad: 'login-required',
-      checkLoginIframe: false,
-    },
-    enableBearerInterceptor: true,
-    bearerExcludedUrls: ['/assets', '/clients/public'],
-  });
-  resolve();
-} catch (error) {}
+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:
+
+```ts
+await keycloak.init({
+  config: {
+    url: 'http://localhost:8080/auth',
+    realm: 'your-realm',
+    clientId: 'your-client-id',
+  },
+  bearerExcludedUrls: ['/assets', '/clients/public'],
+});
 ```
 
 ## Contributors
@@ -248,11 +209,25 @@ try {
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
-If you want to contribute to the project, please check out the [contributing](docs/contributing.md)
+If you want to contribute to the project, please check out the [contributing](CONTRIBUTING.md)
 document.
 
 ## License
 
-**keycloak-angular** is licensed under the **[MIT](LICENSE)**.
-
-[keycloak-js](https://github.com/keycloak/keycloak-js-bower) is licensed under the **Apache 2.0**.
+**keycloak-angular** is licensed under the **[MIT license](LICENSE)**.
+
+<!-- prettier-ignore-start -->
+[license-mit-badge]: https://img.shields.io/badge/License-MIT-yellow.svg
+[license-mit]: https://opensource.org/licenses/MIT
+[build-badge]: https://travis-ci.org/mauriciovigolo/keycloak-angular.svg?branch=master
+[build]: https://travis-ci.org/mauriciovigolo/keycloak-angular
+[vulnerabilities-badge]: https://snyk.io/test/github/mauriciovigolo/keycloak-angular/badge.svg
+[vulnerabilities]: https://snyk.io/test/github/mauriciovigolo/keycloak-angular
+[npm-version-badge]: https://badge.fury.io/js/keycloak-angular.svg
+[npm-version]: https://badge.fury.io/js/keycloak-angular
+[npm-badge]: https://img.shields.io/npm/dm/keycloak-angular.svg
+[npm]: https://www.npmjs.com/package/keycloak-angular
+[contributors-badge]: https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square
+[discord-badge]: https://img.shields.io/discord/790617227853692958.svg?color=7389D8&labelColor=6A7EC2&logo=discord&logoColor=ffffff&style=flat-square
+[discord]: https://discord.gg/mmzEhYXXDG
+<!-- prettier-ignore-end -->