@fnet/webauth

@fnet/webauth is a JavaScript library designed to facilitate user authentication using Keycloak, an open-source identity and access management solution. The primary goal of this project is to streamline the user authentication process for applications that require security integration with Keycloak. It provides a straightforward interface for logging in and out of applications while managing user sessions.

How It Works

This project leverages the Keycloak JavaScript adapter to manage authentication flows. It initializes with Keycloak configuration details and checks if the user is authenticated. If not authenticated, it redirects users to the login page. Once authenticated, it retrieves the user's profile and maintains the session. It also offers utility functions to generate login and logout URLs based on the application's requirements.

For more information on the Keycloak JavaScript adapter, visit Keycloak JS Adapter Documentation.

Key Features

• Easy Initialization: Begin authentication with simple configuration inputs like the Keycloak URL, realm, and client ID.
• User Authentication: Authenticate users and manage their sessions with built-in handling for login redirects.
• Session Management: Retrieve user profile data and retain session details once authenticated.
• Custom Redirects: Specify custom login and logout redirect URLs based on your application's flow.
• Silent Mode: Optionally enable silent authentication for seamless user experiences.

Conclusion

@fnet/webauth provides a straightforward approach to integrating Keycloak authentication into your application. By managing login sessions and redirects efficiently, it simplifies the user authentication process, making it a useful tool for maintaining secure access to your application.

@fnet/webauth Developer Guide

Overview

The @fnet/webauth library provides a simple interface for integrating Keycloak authentication into web applications. Utilizing Keycloak's robust identity and access management, developers can authenticate users and manage sessions with minimal setup. The library's core functionality revolves around initializing the Keycloak client, managing user sessions, and providing utility functions to create login and logout URLs.

Installation

To use @fnet/webauth in your project, you can install it via npm or yarn with the following commands:

npm install @fnet/webauth

or

yarn add @fnet/webauth

Usage

The library is straightforward to integrate into your application. The primary export is an asynchronous function that initializes the Keycloak API with the necessary configurations.

Initializing Keycloak

Here is a basic example of how to set up and use the library:

import initializeAuth from '@fnet/webauth';

(async () => {
  try {
    const auth = await initializeAuth({
      url: 'https://your-keycloak-server.com/auth',
      realm: 'your-realm',
      client_id: 'your-client-id',
      login_url: 'https://custom-login-url.com', // Optional
      redirect_url: window.location.href,       // Optional
      silent: true                              // Optional
    });

    console.log('User profile:', auth.user);
  } catch (error) {
    console.error('Authentication failed:', error);
  }
})();

Managing Authentication

• Initialization: Checks if the user is authenticated and redirect to login if not.
• Login URL Generation: Creates customizable login URLs with optional identity provider hints.
• Logout URL Generation: Generates URLs to facilitate user logout.

These features allow developers to handle user authentication with Keycloak efficiently.

Examples

Here are some practical code snippets demonstrating key functionalities the library offers:

Creating a Login URL

const createLoginUrl = async (auth) => {
  try {
    const loginUrl = await auth.createLoginUrl({
      redirect_url: 'https://your-app.com/dashboard',
      idp_hint: 'google' // Optional identity provider hint
    });
    console.log('Login URL:', loginUrl);
  } catch (error) {
    console.error('Failed to create login URL:', error);
  }
};

Creating a Logout URL

const createLogoutUrl = (auth) => {
  try {
    const logoutUrl = auth.createLogoutUrl({
      redirect_url: 'https://your-app.com/home'
    });
    console.log('Logout URL:', logoutUrl);
  } catch (error) {
    console.error('Failed to create logout URL:', error);
  }
};

Acknowledgement

This library integrates with Keycloak, a third-party identity and access management tool, using its JavaScript adapter for secure authentication. Keycloak's comprehensive features simplify the process of managing user sessions and access rights.

By following this guide, developers should be able to seamlessly integrate Keycloak authentication into their applications using @fnet/webauth.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
title: KeycloakArguments
type: object
properties:
  url:
    type: string
    description: The URL of the Keycloak issuer.
  realm:
    type: string
    description: The name of the Keycloak realm.
  client_id:
    type: string
    description: The client ID for Keycloak authentication.
  login_url:
    type: string
    description: A custom login URL for authentication.
  redirect_url:
    type: string
    description: A custom redirect URL after successful login.
  logout_redirect_url:
    type: string
    description: A custom redirect URL after logout.
  silent:
    type: boolean
    description: A flag to enable silent authentication.
    default: false
required:
  - url
  - realm
  - client_id