keycloak-angular 16.1.0 → 19.0.0

package/lib/legacy/core/services/keycloak-auth-guard.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright Mauricio Gemelli Vigolo and contributors.
+ *
+ * Use of this source code is governed by a MIT-style license that can be
+ * found in the LICENSE file at https://github.com/mauriciovigolo/keycloak-angular/blob/main/LICENSE.md
+ */
+import { CanActivate, Router, ActivatedRouteSnapshot, RouterStateSnapshot, UrlTree } from '@angular/router';
+import { KeycloakService } from './keycloak.service';
+/**
+ * A simple guard implementation out of the box. This class should be inherited and
+ * implemented by the application. The only method that should be implemented is #isAccessAllowed.
+ * The reason for this is that the authorization flow is usually not unique, so in this way you will
+ * have more freedom to customize your authorization flow.
+ *
+ * @deprecated Class based guards are deprecated in Keycloak Angular and will be removed in future versions.
+ * Use the new `createAuthGuard` function to create a Guard for your application.
+ * More info: https://github.com/mauriciovigolo/keycloak-angular/docs/migration-guides/v19.md
+ */
+export declare abstract class KeycloakAuthGuard implements CanActivate {
+    protected router: Router;
+    protected keycloakAngular: KeycloakService;
+    /**
+     * Indicates if the user is authenticated or not.
+     */
+    protected authenticated: boolean;
+    /**
+     * Roles of the logged user. It contains the clientId and realm user roles.
+     */
+    protected roles: string[];
+    constructor(router: Router, keycloakAngular: KeycloakService);
+    /**
+     * CanActivate checks if the user is logged in and get the full list of roles (REALM + CLIENT)
+     * of the logged user. This values are set to authenticated and roles params.
+     *
+     * @param route
+     * @param state
+     */
+    canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Promise<boolean | UrlTree>;
+    /**
+     * Create your own customized authorization flow in this method. From here you already known
+     * if the user is authenticated (this.authenticated) and the user roles (this.roles).
+     *
+     * Return a UrlTree if the user should be redirected to another route.
+     *
+     * @param route
+     * @param state
+     */
+    abstract isAccessAllowed(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Promise<boolean | UrlTree>;
+}

package/lib/legacy/core/services/keycloak.service.d.ts

@@ -0,0 +1,316 @@
+import { HttpHeaders, HttpRequest } from '@angular/common/http';
+import { Subject } from 'rxjs';
+import { ExcludedUrlRegex, KeycloakOptions } from '../interfaces/keycloak-options';
+import { KeycloakEventLegacy } from '../interfaces/keycloak-event';
+import * as i0 from "@angular/core";
+/**
+ * Service to expose existent methods from the Keycloak JS adapter, adding new
+ * functionalities to improve the use of keycloak in Angular v > 4.3 applications.
+ *
+ * This class should be injected in the application bootstrap, so the same instance will be used
+ * along the web application.
+ *
+ * @deprecated This service is deprecated and will be removed in future versions.
+ * Use the new `provideKeycloak` function to load Keycloak in an Angular application.
+ * More info: https://github.com/mauriciovigolo/keycloak-angular/docs/migration-guides/v19.md
+ */
+export declare class KeycloakService {
+    /**
+     * Keycloak-js instance.
+     */
+    private _instance;
+    /**
+     * User profile as KeycloakProfile interface.
+     */
+    private _userProfile;
+    /**
+     * Flag to indicate if the bearer will not be added to the authorization header.
+     */
+    private _enableBearerInterceptor;
+    /**
+     * When the implicit flow is choosen there must exist a silentRefresh, as there is
+     * no refresh token.
+     */
+    private _silentRefresh;
+    /**
+     * Indicates that the user profile should be loaded at the keycloak initialization,
+     * just after the login.
+     */
+    private _loadUserProfileAtStartUp;
+    /**
+     * The bearer prefix that will be appended to the Authorization Header.
+     */
+    private _bearerPrefix;
+    /**
+     * Value that will be used as the Authorization Http Header name.
+     */
+    private _authorizationHeaderName;
+    /**
+     * @deprecated
+     * The excluded urls patterns that must skip the KeycloakBearerInterceptor.
+     */
+    private _excludedUrls;
+    /**
+     * Observer for the keycloak events
+     */
+    private _keycloakEvents$;
+    /**
+     * The amount of required time remaining before expiry of the token before the token will be refreshed.
+     */
+    private _updateMinValidity;
+    /**
+     * Returns true if the request should have the token added to the headers by the KeycloakBearerInterceptor.
+     */
+    shouldAddToken: (request: HttpRequest<unknown>) => boolean;
+    /**
+     * Returns true if the request being made should potentially update the token.
+     */
+    shouldUpdateToken: (request: HttpRequest<unknown>) => boolean;
+    /**
+     * Binds the keycloak-js events to the keycloakEvents Subject
+     * which is a good way to monitor for changes, if needed.
+     *
+     * The keycloakEvents returns the keycloak-js event type and any
+     * argument if the source function provides any.
+     */
+    private bindsKeycloakEvents;
+    /**
+     * Loads all bearerExcludedUrl content in a uniform type: ExcludedUrl,
+     * so it becomes easier to handle.
+     *
+     * @param bearerExcludedUrls array of strings or ExcludedUrl that includes
+     * the url and HttpMethod.
+     */
+    private loadExcludedUrls;
+    /**
+     * Handles the class values initialization.
+     *
+     * @param options
+     */
+    private initServiceValues;
+    /**
+     * Keycloak initialization. It should be called to initialize the adapter.
+     * Options is an object with 2 main parameters: config and initOptions. The first one
+     * will be used to create the Keycloak instance. The second one are options to initialize the
+     * keycloak instance.
+     *
+     * @param options
+     * Config: may be a string representing the keycloak URI or an object with the
+     * following content:
+     * - url: Keycloak json URL
+     * - realm: realm name
+     * - clientId: client id
+     *
+     * initOptions:
+     * Options to initialize the Keycloak adapter, matches the options as provided by Keycloak itself.
+     *
+     * enableBearerInterceptor:
+     * Flag to indicate if the bearer will added to the authorization header.
+     *
+     * loadUserProfileInStartUp:
+     * Indicates that the user profile should be loaded at the keycloak initialization,
+     * just after the login.
+     *
+     * bearerExcludedUrls:
+     * String Array to exclude the urls that should not have the Authorization Header automatically
+     * added.
+     *
+     * authorizationHeaderName:
+     * This value will be used as the Authorization Http Header name.
+     *
+     * bearerPrefix:
+     * This value will be included in the Authorization Http Header param.
+     *
+     * tokenUpdateExcludedHeaders:
+     * Array of Http Header key/value maps that should not trigger the token to be updated.
+     *
+     * updateMinValidity:
+     * This value determines if the token will be refreshed based on its expiration time.
+     *
+     * @returns
+     * A Promise with a boolean indicating if the initialization was successful.
+     */
+    init(options?: KeycloakOptions): Promise<boolean>;
+    /**
+     * Redirects to login form on (options is an optional object with redirectUri and/or
+     * prompt fields).
+     *
+     * @param options
+     * Object, where:
+     *  - redirectUri: Specifies the uri to redirect to after login.
+     *  - prompt:By default the login screen is displayed if the user is not logged-in to Keycloak.
+     * To only authenticate to the application if the user is already logged-in and not display the
+     * login page if the user is not logged-in, set this option to none. To always require
+     * re-authentication and ignore SSO, set this option to login .
+     *  - maxAge: Used just if user is already authenticated. Specifies maximum time since the
+     * authentication of user happened. If user is already authenticated for longer time than
+     * maxAge, the SSO is ignored and he will need to re-authenticate again.
+     *  - loginHint: Used to pre-fill the username/email field on the login form.
+     *  - action: If value is 'register' then user is redirected to registration page, otherwise to
+     * login page.
+     *  - locale: Specifies the desired locale for the UI.
+     * @returns
+     * A void Promise if the login is successful and after the user profile loading.
+     */
+    login(options?: Keycloak.KeycloakLoginOptions): Promise<void>;
+    /**
+     * Redirects to logout.
+     *
+     * @param redirectUri
+     * Specifies the uri to redirect to after logout.
+     * @returns
+     * A void Promise if the logout was successful, cleaning also the userProfile.
+     */
+    logout(redirectUri?: string): Promise<void>;
+    /**
+     * Redirects to registration form. Shortcut for login with option
+     * action = 'register'. Options are same as for the login method but 'action' is set to
+     * 'register'.
+     *
+     * @param options
+     * login options
+     * @returns
+     * A void Promise if the register flow was successful.
+     */
+    register(options?: Keycloak.KeycloakLoginOptions): Promise<void>;
+    /**
+     * Check if the user has access to the specified role. It will look for roles in
+     * realm and the given resource, but will not check if the user is logged in for better performance.
+     *
+     * @param role
+     * role name
+     * @param resource
+     * resource name. If not specified, `clientId` is used
+     * @returns
+     * A boolean meaning if the user has the specified Role.
+     */
+    isUserInRole(role: string, resource?: string): boolean;
+    /**
+     * Return the roles of the logged user. The realmRoles parameter, with default value
+     * true, will return the resource roles and realm roles associated with the logged user. If set to false
+     * it will only return the resource roles. The resource parameter, if specified, will return only resource roles
+     * associated with the given resource.
+     *
+     * @param realmRoles
+     * Set to false to exclude realm roles (only client roles)
+     * @param resource
+     * resource name If not specified, returns roles from all resources
+     * @returns
+     * Array of Roles associated with the logged user.
+     */
+    getUserRoles(realmRoles?: boolean, resource?: string): string[];
+    /**
+     * Check if user is logged in.
+     *
+     * @returns
+     * A boolean that indicates if the user is logged in.
+     */
+    isLoggedIn(): boolean;
+    /**
+     * Returns true if the token has less than minValidity seconds left before
+     * it expires.
+     *
+     * @param minValidity
+     * Seconds left. (minValidity) is optional. Default value is 0.
+     * @returns
+     * Boolean indicating if the token is expired.
+     */
+    isTokenExpired(minValidity?: number): boolean;
+    /**
+     * If the token expires within _updateMinValidity seconds the token is refreshed. If the
+     * session status iframe is enabled, the session status is also checked.
+     * Returns a promise telling if the token was refreshed or not. If the session is not active
+     * anymore, the promise is rejected.
+     *
+     * @param minValidity
+     * Seconds left. (minValidity is optional, if not specified updateMinValidity - default 20 is used)
+     * @returns
+     * Promise with a boolean indicating if the token was succesfully updated.
+     */
+    updateToken(minValidity?: number): Promise<boolean>;
+    /**
+     * Loads the user profile.
+     * Returns promise to set functions to be invoked if the profile was loaded
+     * successfully, or if the profile could not be loaded.
+     *
+     * @param forceReload
+     * If true will force the loadUserProfile even if its already loaded.
+     * @returns
+     * A promise with the KeycloakProfile data loaded.
+     */
+    loadUserProfile(forceReload?: boolean): Promise<import("keycloak-js").KeycloakProfile>;
+    /**
+     * Returns the authenticated token.
+     */
+    getToken(): Promise<string>;
+    /**
+     * Returns the logged username.
+     *
+     * @returns
+     * The logged username.
+     */
+    getUsername(): string;
+    /**
+     * Clear authentication state, including tokens. This can be useful if application
+     * has detected the session was expired, for example if updating token fails.
+     * Invoking this results in onAuthLogout callback listener being invoked.
+     */
+    clearToken(): void;
+    /**
+     * Adds a valid token in header. The key & value format is:
+     * Authorization Bearer <token>.
+     * If the headers param is undefined it will create the Angular headers object.
+     *
+     * @param headers
+     * Updated header with Authorization and Keycloak token.
+     * @returns
+     * An observable with with the HTTP Authorization header and the current token.
+     */
+    addTokenToHeader(headers?: HttpHeaders): import("rxjs").Observable<HttpHeaders>;
+    /**
+     * Returns the original Keycloak instance, if you need any customization that
+     * this Angular service does not support yet. Use with caution.
+     *
+     * @returns
+     * The KeycloakInstance from keycloak-js.
+     */
+    getKeycloakInstance(): Keycloak.KeycloakInstance;
+    /**
+     * @deprecated
+     * Returns the excluded URLs that should not be considered by
+     * the http interceptor which automatically adds the authorization header in the Http Request.
+     *
+     * @returns
+     * The excluded urls that must not be intercepted by the KeycloakBearerInterceptor.
+     */
+    get excludedUrls(): ExcludedUrlRegex[];
+    /**
+     * Flag to indicate if the bearer will be added to the authorization header.
+     *
+     * @returns
+     * Returns if the bearer interceptor was set to be disabled.
+     */
+    get enableBearerInterceptor(): boolean;
+    /**
+     * Keycloak subject to monitor the events triggered by keycloak-js.
+     * The following events as available (as described at keycloak docs -
+     * https://www.keycloak.org/docs/latest/securing_apps/index.html#callback-events):
+     * - OnAuthError
+     * - OnAuthLogout
+     * - OnAuthRefreshError
+     * - OnAuthRefreshSuccess
+     * - OnAuthSuccess
+     * - OnReady
+     * - OnTokenExpire
+     * In each occurrence of any of these, this subject will return the event type,
+     * described at {@link KeycloakEventTypeLegacy} enum and the function args from the keycloak-js
+     * if provided any.
+     *
+     * @returns
+     * A subject with the {@link KeycloakEventLegacy} which describes the event type and attaches the
+     * function args.
+     */
+    get keycloakEvents$(): Subject<KeycloakEventLegacy>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KeycloakService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<KeycloakService>;
+}

package/lib/{keycloak-angular.module.d.ts → legacy/keycloak-angular.module.d.ts}

@@ -1,5 +1,10 @@
 import * as i0 from "@angular/core";
 import * as i1 from "./core/core.module";
+/**
+ * @deprecated NgModules are deprecated in Keycloak Angular and will be removed in future versions.
+ * Use the new `provideKeycloak` function to load Keycloak in an Angular application.
+ * More info: https://github.com/mauriciovigolo/keycloak-angular/docs/migration-guides/v19.md
+ */
 export declare class KeycloakAngularModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<KeycloakAngularModule, never>;
     static ɵmod: i0.ɵɵNgModuleDeclaration<KeycloakAngularModule, never, [typeof i1.CoreModule], never>;

package/lib/legacy/public_api.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright Mauricio Gemelli Vigolo All Rights Reserved.
+ *
+ * Use of this source code is governed by a MIT-style license that can be
+ * found in the LICENSE file at https://github.com/mauriciovigolo/keycloak-angular/blob/main/LICENSE.md
+ */
+export { KeycloakEventLegacy, KeycloakEventTypeLegacy } from './core/interfaces/keycloak-event';
+export { KeycloakOptions } from './core/interfaces/keycloak-options';
+export { KeycloakAuthGuard } from './core/services/keycloak-auth-guard';
+export { KeycloakService } from './core/services/keycloak.service';
+export { KeycloakBearerInterceptor } from './core/interceptors/keycloak-bearer.interceptor';
+export { CoreModule } from './core/core.module';
+export { KeycloakAngularModule } from './keycloak-angular.module';

package/lib/provide-keycloak.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright Mauricio Gemelli Vigolo All Rights Reserved.
+ *
+ * Use of this source code is governed by a MIT-style license that can be
+ * found in the LICENSE file at https://github.com/mauriciovigolo/keycloak-angular/blob/main/LICENSE.md
+ */
+import { KeycloakConfig, KeycloakInitOptions } from 'keycloak-js';
+import { EnvironmentProviders, Provider } from '@angular/core';
+import { KeycloakFeature } from './features/keycloak.feature';
+/**
+ * Options for configuring Keycloak and additional providers.
+ */
+export type ProvideKeycloakOptions = {
+    /**
+     * Keycloak configuration, including the server URL, realm, and client ID.
+     */
+    config: KeycloakConfig;
+    /**
+     * Optional initialization options for the Keycloak instance.
+     * If not provided, Keycloak will not initialize automatically.
+     */
+    initOptions?: KeycloakInitOptions;
+    /**
+     * Optional array of additional Angular providers or environment providers.
+     */
+    providers?: Array<Provider | EnvironmentProviders>;
+    /**
+     * Optional array of Keycloak features to extend the functionality of the Keycloak integration.
+     */
+    features?: Array<KeycloakFeature>;
+};
+/**
+ * Configures and provides Keycloak as a dependency in an Angular application.
+ *
+ * This function initializes a Keycloak instance with the provided configuration and
+ * optional initialization options. It integrates Keycloak into Angular dependency
+ * injection system, allowing easy consumption throughout the application. Additionally,
+ * it supports custom providers and Keycloak Angular features.
+ *
+ * If `initOptions` is not provided, the Keycloak instance will not be automatically initialized.
+ * In such cases, the application must call `keycloak.init()` explicitly.
+ *
+ * @param options - Configuration object for Keycloak:
+ *   - `config`: The Keycloak configuration, including the server URL, realm, and client ID.
+ *   - `initOptions` (Optional): Initialization options for the Keycloak instance.
+ *   - `providers` (Optional): Additional Angular providers to include.
+ *   - `features` (Optional): Keycloak Angular features to configure during initialization.
+ *
+ * @returns An `EnvironmentProviders` object integrating Keycloak setup and additional providers.
+ *
+ * @example
+ * ```ts
+ * import { provideKeycloak } from './keycloak.providers';
+ * import { bootstrapApplication } from '@angular/platform-browser';
+ * import { AppComponent } from './app/app.component';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideKeycloak({
+ *       config: {
+ *         url: 'https://auth-server.example.com',
+ *         realm: 'my-realm',
+ *         clientId: 'my-client',
+ *       },
+ *       initOptions: {
+ *         onLoad: 'login-required',
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function provideKeycloak(options: ProvideKeycloakOptions): EnvironmentProviders;

package/lib/services/auto-refresh-token.service.d.ts

@@ -0,0 +1,47 @@
+import Keycloak from 'keycloak-js';
+import { UserActivityService } from './user-activity.service';
+import * as i0 from "@angular/core";
+/**
+ * Configuration options for the `AutoRefreshTokenService`.
+ */
+type AutoRefreshTokenOptions = {
+    /**
+     * Maximum allowed inactivity duration in milliseconds before
+     * the session times out. Default is `50000`.
+     */
+    sessionTimeout?: number;
+    /**
+     * Action to take when the session times out due to inactivity.
+     * Options are:
+     * - `'login'`: Redirect to the Keycloak login page.
+     * - `'logout'`: Log the user out of the session.
+     * - `'none'`: Do nothing.
+     * Default is `'logout'`.
+     */
+    onInactivityTimeout?: 'login' | 'logout' | 'none';
+};
+/**
+ * Service to automatically manage the Keycloak token refresh process
+ * based on user activity and token expiration events. This service
+ * integrates with Keycloak for session management and interacts with
+ * user activity monitoring to determine the appropriate action when
+ * the token expires.
+ *
+ * The service listens to `KeycloakSignal` for token-related events
+ * (e.g., `TokenExpired`) and provides configurable options for
+ * session timeout and inactivity handling.
+ */
+export declare class AutoRefreshTokenService {
+    private readonly keycloak;
+    private readonly userActivity;
+    private options;
+    private initialized;
+    constructor(keycloak: Keycloak, userActivity: UserActivityService);
+    private get defaultOptions();
+    private executeOnInactivityTimeout;
+    private processTokenExpiredEvent;
+    start(options?: AutoRefreshTokenOptions): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AutoRefreshTokenService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AutoRefreshTokenService>;
+}
+export {};

package/lib/services/user-activity.service.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright Mauricio Gemelli Vigolo All Rights Reserved.
+ *
+ * Use of this source code is governed by a MIT-style license that can be
+ * found in the LICENSE file at https://github.com/mauriciovigolo/keycloak-angular/blob/main/LICENSE.md
+ */
+import { OnDestroy, NgZone } from '@angular/core';
+import * as i0 from "@angular/core";
+/**
+ * Service to monitor user activity in an Angular application.
+ * Tracks user interactions (e.g., mouse movement, touch, key presses, clicks, and scrolls)
+ * and updates the last activity timestamp. Consumers can check for user inactivity
+ * based on a configurable timeout.
+ *
+ * The service is supposed to be used in the client context and for safety, it checks during the startup
+ * if it is a browser context.
+ */
+export declare class UserActivityService implements OnDestroy {
+    private ngZone;
+    /**
+     * Signal to store the timestamp of the last user activity.
+     * The timestamp is represented as the number of milliseconds since epoch.
+     */
+    private lastActivity;
+    /**
+     * Subject to signal the destruction of the service.
+     * Used to clean up RxJS subscriptions.
+     */
+    private destroy$;
+    /**
+     * Computed signal to expose the last user activity as a read-only signal.
+     */
+    readonly lastActivitySignal: import("@angular/core").Signal<number>;
+    constructor(ngZone: NgZone);
+    /**
+     * Starts monitoring user activity events (`mousemove`, `touchstart`, `keydown`, `click`, `scroll`)
+     * and updates the last activity timestamp using RxJS with debounce.
+     * The events are processed outside Angular zone for performance optimization.
+     */
+    startMonitoring(): void;
+    /**
+     * Updates the last activity timestamp to the current time.
+     * This method runs inside Angular's zone to ensure reactivity with Angular signals.
+     */
+    private updateLastActivity;
+    /**
+     * Retrieves the timestamp of the last recorded user activity.
+     * @returns {number} The last activity timestamp in milliseconds since epoch.
+     */
+    get lastActivityTime(): number;
+    /**
+     * Determines whether the user interacted with the application, meaning it is activily using the application, based on
+     * the specified duration.
+     * @param timeout - The inactivity timeout in milliseconds.
+     * @returns {boolean} `true` if the user is inactive, otherwise `false`.
+     */
+    isActive(timeout: number): boolean;
+    /**
+     * Cleans up RxJS subscriptions and resources when the service is destroyed.
+     * This method is automatically called by Angular when the service is removed.
+     */
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UserActivityService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UserActivityService>;
+}