Guide to Using SSO with Keycloak on Angular

Introduction

SSO (Single Sign-On) is a way for users to log in just once - with a single set of credentials (username and password)—to access many different applications.

The main benefit of SSO is that it improves the user experience because people don't have to remember multiple passwords. It also boosts security by reducing potential weak spots from using weak or reused passwords.

Keycloak is a popular, open-source Identity and Access Management (IAM) solution designed to implement SSO and other security features. Keycloak supports industry standards like OAuth 2.0, OpenID Connect, and SAML 2.0, which makes it easy to integrate with most modern applications.

Key benefits of Keycloak include:

Easy SSO Implementation: It provides a central platform to manage user authentication for thousands of applications.
Diverse Authentication Method Support: It allows for one-time passwords (OTP), Multi-Factor Authentication (MFA), and integration with external systems like LDAP/Active Directory or third-party providers (Google, Facebook, etc.).
Flexible User and Authorization Management: It offers a user-friendly admin interface for managing users, Roles, and Groups, along with the ability to grant detailed access permissions (authorization).

In this article, I'll show you how to use Keycloak on Angular. It's a powerful tool that helps organizations effectively implement the SSO model, simplifying security management and making things more convenient for end-users.

Detail

Set Up the Keycloak Environment

To use Keycloak, you can run the following Docker command:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN={admin username} -e KEYCLOAK_ADMIN_PASSWORD={password} quay.io/keycloak/keycloak:latest start-dev

This command will start Keycloak on port 8080. Make sure to replace {admin username} and {password} with the credentials you want to use.

After accessing http://localhost:8080, use the account you just created to log in.

Next, go to the `Manage realms` menu to create a new realm you want to use, or you can use the existing one. This realm information will be used when integrating with your Angular project.

Then, go to the `Clients` menu and click `Create Client`. There are many configuration settings, but you need to fill in these basic details:

Client ID: This is the unique name for your client.
Valid redirect URIs: This is the URI Keycloak will redirect to after a successful login. It should be the URI where your Angular project runs. Angular usually runs on port 4200 by default, so you can enter `http://localhost:4200/*` (you can change this to match your project's setup).
Web origins: These are the Allowed CORS origins. You can enter the URI of your Angular project or enter a `+` sign to use the same configuration as the `Valid redirect URIs`.

Finally, access the `Users` menu and click `Add user` to create a new user. Click the `Credentials` tab to set a password for the user.

Set Up the Angular Project

First, create an Angular project, and then install the necessary packages:

yarn add keycloak-angular keycloak-js

While you could integrate Keycloak just by installing `keycloak-js`, the `keycloak-angular` package provides additional, ready-made utility functions that are convenient to use.

Modify `app.config.ts` to add the provider for Keycloak, like this:

import {
  ApplicationConfig,
  importProvidersFrom,
  provideBrowserGlobalErrorListeners,
  provideZoneChangeDetection,
} from '@angular/core';
import {
  AutoRefreshTokenService,
  provideKeycloak,
  UserActivityService,
  withAutoRefreshToken,
} from 'keycloak-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    ...
    provideKeycloak({
      config: {
        url: 'http://localhost:8080',
        realm: '<realm name>',
        clientId: '<client id>',
      },
      initOptions: { onLoad: 'login-required' },
      features: [withAutoRefreshToken()],
      providers: [AutoRefreshTokenService, UserActivityService],
    }),
  ],
};

Explanation:

The fields url, realm and clientId are the details you created when setting up Keycloak.
I've added the `withAutoRefreshToken` feature, which, as the name suggests, will automatically refresh the token based on the access token's expiration time.
To customize the access token's expiration time, go to the `Realm settings` menu > `Token` tab and change the value of the `Access Token Lifespan` field.
The `AutoRefreshTokenService` and `UserActivityService` services are required to use the `withAutoRefreshToken` feature.

Next, create a component with some simple features, as shown here:

import { Component, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { CommonModule } from '@angular/common';
import { HasRolesDirective } from 'keycloak-angular';
import Keycloak from 'keycloak-js';

@Component({
  selector: 'keycloak',
  templateUrl: './index.html',
  styleUrl: './index.scss',
  imports: [FormsModule, CommonModule, HasRolesDirective],
})
export class KeycloakComponent {
  private readonly keycloak = inject(Keycloak);

  constructor() {
    console.log('token', this.keycloak.token);
  }

  logout() {
    this.keycloak.logout();
  }
}

After a successful login, Keycloak will provide an access token. You can use this token for API requests. The `keycloak-js` library also comes with a built-in `logout()` function and many other functions you can check out.

<div *kaHasRoles="['offline_access']; checkRealm: true">Pass realm role</div>
<div *kaHasRoles="['view-profile']; resource: 'account'">Pass resource role</div>
<button (click)="logout()">Logout</button>

`keycloak-angular` provides the `HasRolesDirective` out-of-the-box to check roles directly.

Keycloak supports two types of roles: Realm roles and Client roles.

If you use the `checkRealm: true` parameter, it checks the Realm role.
To check a Client role, you need to pass the `resource` parameter, which must be the `Client ID` you want to check against.