cidaas-javascript-sdk 4.3.3 → 5.0.0

package/CHANGELOG.md

@@ -1,13 +1,60 @@
-## [4.3.3](https://gitlab.widas.de/cidaas-public-devkits/cidaas-public-sdks/cidaas-javascript-sdk/compare/v4.3.2...v4.3.3) (2024-11-28)
+# [5.0.0](https://gitlab.widas.de/cidaas-public-devkits/cidaas-public-sdks/cidaas-javascript-sdk/compare/v4.3.3...v5.0.0) (2024-12-19)
 
 
-### Bug Fixes
+* feat()!: upgrade to v5 ([e5ac651](https://gitlab.widas.de/cidaas-public-devkits/cidaas-public-sdks/cidaas-javascript-sdk/commit/e5ac65125adbacf1e38dd21af5aad7d000eeb5e3))
 
-* fix vulnerabilty from npm audit ([2f8e0c5](https://gitlab.widas.de/cidaas-public-devkits/cidaas-public-sdks/cidaas-javascript-sdk/commit/2f8e0c5498e45d865ad4bdca8005339d5857c37e))
-* semantic release format ([0d8b601](https://gitlab.widas.de/cidaas-public-devkits/cidaas-public-sdks/cidaas-javascript-sdk/commit/0d8b6014a673098a44d18297777ce1c65ba35602))
+
+### BREAKING CHANGES
+
+* ### Changed
+- **Breaking** Rework library to calls functions from various modules
+- **Breaking** Rework renewToken() to store the newly generated token in user storage
+- **Breaking** Move setAcceptLanguageHeader function to Helper class
+- **Breaking** Rename getUserInfo() to getUserInfoFromStorage()
+- **Breaking** Rename getAccessToken() to generateTokenFromCode()
+- **Breaking** Standardize enums
+- **Breaking** Use enum instead of string for some function parameter
+
+### Removed
+- **Breaking** Removed silentSignin() & silentSignInCallback() function
+- **Breaking** Removed popupSignInCallback() & popupSignOutCallback()function
+- **Breaking** Removed logoutUser() function
+- **Breaking** Removed validateAccessToken() function
+- **Breaking** Removed createPreloginWebauth function
+- **Breaking** Removed unused & deprecated function parameters
 
 # Changelog
 
+## V5.0.0
+
+If you are upgrading from v4.x.x,  please see [UPGRADING.md](UPGRADING_V5.md)
+
+### Fixed
+- Fix vulnerabilities from `npm audit`
+
+### Added
+- Add invokeIdValidationCase() function
+- Add [documentation](https://cidaas.github.io/cidaas-javascript-sdk) generated by typedoc
+
+### Changed
+- Support tokens from predefined user storage
+- Use latest version of oidc client ts library
+- **Breaking** Rework library to calls functions from various modules
+- **Breaking** Rework renewToken() to store the newly generated token in user storage
+- **Breaking** Move setAcceptLanguageHeader function to Helper class
+- **Breaking** Rename getUserInfo() to getUserInfoFromStorage()
+- **Breaking** Rename getAccessToken() to generateTokenFromCode()
+- **Breaking** Standardize enums
+- **Breaking** Use enum instead of string for some function parameter
+
+### Removed
+- **Breaking** Removed silentSignin() & silentSignInCallback() function
+- **Breaking** Removed popupSignInCallback() & popupSignOutCallback()function
+- **Breaking** Removed logoutUser() function
+- **Breaking** Removed validateAccessToken() function
+- **Breaking** Removed createPreloginWebauth function
+- **Breaking** Removed unused & deprecated function parameters
+
 ## V4.3.3
 
 ## Changed
@@ -111,7 +158,7 @@
 
 ## V4.0.0
 
-If you are upgrading from v3.x.x,  please see ['UPGRADING.md'](UPGRADING.md)
+If you are upgrading from v3.x.x,  please see [UPGRADING.md](UPGRADING_V4.md)
 
 ### Fixed
 - fix vulnerabilities from `npm audit`

package/README.md

@@ -20,19 +20,11 @@ Please check the [Changelog](https://github.com/Cidaas/cidaas-sdk-javascript-v2/
 ## Table of Contents
 
 <!--ts-->
+* [Documentation](https://cidaas.github.io/cidaas-javascript-sdk)
 * [Installation](#installation)
 * [Initialisation](#initialisation)
 * [Usage](#usage)
 * [Functions Overview](#functions-overview)
-    <!--ts-->
-    * [Authentication Functions](#authentication-functions)
-    * [Login Management](#login-management)
-    * [User Management](#user-management)
-    * [Token Management](#token-management)
-    * [Verification Management](#verification-management)
-    * [Consent Management](#consent-management)
-    * [Other Functionality](#other-functionality)
-    <!--te-->
 * [Possible Error](#possible-error)
 
 ### Installation
@@ -63,6 +55,8 @@ Cidaas options variable support every [OIDC Client UserManagerSettings Propertie
 | redirect_uri | yes | URL to be redirected after successful login attempt. |
 | post_logout_redirect_uri | no | URL to be redirected after successful logout attempt. |
 | scope | no | the scope the application requires and requests from cidaas. The default value is 'openid' if no properties is being sent. |
+| userStore | no | define where authenticated user information will be saved on the client application. The default value is session storage if no properties is being sent. |
+| automaticSilentRenew | no | configure whether automatic token renewal will be activated. The default value is true. |
 
 an example of Cidaas options variable looks like this:
 
@@ -76,126 +70,148 @@ const options = {
 }
 ```
 
-### Initialise the cidaas sdk using the configured options mentioned above:
+### Configure user storage (Optional)
 
-```js
-const cidaas = new CidaasSDK.WebAuth(options);
-```
+The following storages are supported to store authenticated user information, such as tokens information & user profile:
+* window.sessionStorage (default)
+* window.localStorage
+* InMemoryWebStorage (all Information will be cleared after browser refresh) in case user do not want to save token in window object
 
-### Usage
+additionally, user can also define custom storage in the client side by implementing Storage class.
 
-#### Login With Browser
+If there is no userStore properties being send in Cidaas options variable, it will use session storage by default.
 
-To login through cidaas sdk, call **loginWithBrowser()**. This will redirect you to the hosted login page.
+In case local storage is prefered to be used, then Cidaas options can be modified as following:
 
 ```js
-cidaas.loginWithBrowser();
+const options = {
+    authority: 'your domain base url',
+    ...,
+    userStore: new WebStorageStateStore({ store: window.localStorage })
+}
 ```
 
-once login is successful, it will automatically redirects you to redirect_uri you have configured in cidaas options. You will get information such as code & state as redirect url parameter (query or fragment), which is needed to get access token.
-
-To complete the login process, call **logincallback()**.
+In case custom solution for storing authenticated user information is being used, or saving the token in memory is preferred, you can configured userStore with InMemoryWebStorage. Authenticated user information will be cleared as soon as the page is refreshed afterwards.
 
 ```js
-cidaas.loginCallback().then(function(response) {
-    // the response will give you login details.
-}).catch(function(ex) {
-    // your failure code here
-});
+const options = {
+    authority: 'your domain base url',
+    ...,
+    userStore: new WebStorageStateStore({ store: new InMemoryWebStorage()})
+}
 ```
 
-After successful loginCallback, You will get access token, along with id token and refresh token in the json response, depends on your application configuration.
+see [usage](#get-tokens-and-user-profile-information-from-user-storage) to get the stored informations from user storage.
 
-There are code documentations for each of the functions with example code of how to call them individually.
+### Configure automatic token renewal (Optional)
 
-### Functions Overview
+By default, The SDK will generate new tokens based on refresh token stored in user storage, one minute before the access token is expiring. To disable this behaviour, Cidaas options can be modified as following:
+
+```js
+const options = {
+    authority: 'your domain base url',
+    ...,
+    automaticSilentRenew: false
+}
+```
 
-Cidaas Javascript SDK features the following functionality:
+### Initialise the cidaas sdk using the configured options mentioned above:
 
-#### Authentication Functions
+Cidaas ConfigUserProvider have to be initialise to be added to each of the modules as dependencies:
 
-The SDK offers multiple way to authenticate user. Whether using browser redirection, in a pop up window, or in an iframe for silent sign in. The functions for authentication could be found [here](https://github.com/Cidaas/cidaas-javascript-sdk/blob/master/src/main/authentication/Authentication.ts)
+Example of Cidaas Service:
+```js
+export class CidaasService {
+    cidaasConfigUserProvider: ConfigUserProvider;
+    authenticationService: AuthenticationService;
+    verificationService: VerificationService;
+    options: OidcSettings = { ... };
+
+    constructor() {
+        // init ConfigUserProvider
+        this.cidaasConfigUserProvider = new ConfigUserProvider(this.options);
+        // init authentication module
+        this.authenticationService = new AuthenticationService(this.cidaasConfigUserProvider);
+        // init verification module
+        this.verificationService = new VerificationService(this.cidaasConfigUserProvider);
+    }
+
+    // get authentication module
+    getAuthentication() {
+        return this.authenticationService;
+    }
+
+    // get verification module
+    getVerificationService() {
+        return this.verificationService
+    }
+}
+```
 
-| SDK Functions                                                                    | Description                                                                                                                                                                    |
-|----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| loginWithBrowser, registerWithBrowser, loginCallback, logout, logoutCallback | The SDK support browser redirection for authenticating user. The authentication process will then happens in a new tab. This is the default authentication function of the SDK |
-| popupSignIn, popupSignInCallback, popupSignOut, popupSignOutCallback             | The SDK support using pop up window for authenticating user. The authentication process will then happens in a new popup window                                                      |
-| silentSignIn, silentSignInCallback                                               | The SDK support silent authentication. The authentication process will then happens in an iframe.                                                                              |
+Usage in Component:
+ ```js
+ // inject cidaas service
+constructor(private cidaasService: CidaasService, ...) {}
 
-#### Login Management
+...
 
-The login functions could be found [here](https://github.com/Cidaas/cidaas-javascript-sdk/blob/master/src/main/login-service/LoginService.ts). The SDK support the following login management functions:
+// init each of cidaas modules which are needed in the component
+this.cidaasAuthenticationService = this.cidaasService.getAuthenticationService();
+this.cidaasVerificationService = this.cidaasService.getVerificationService();
 
-| SDK Functions                                            | Description                                                                                                                                                                                         |
-|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| passwordlessLogin, loginWithCredentials, loginWithSocial | User could authenticate themselves using passwordless authentication, classic password credentials, as well as using social provider such as google or social media platform                        |
-| loginPrecheck, consentContinue, firstTimeChangePassword, mfaContinue    | Depending on the missing information from loginPrecheck, user will be redirected to another page after login to either  accepting consent, changing password, continuing MFA process, or do progressive registration  |
-| getMissingFields, progressiveRegistration                                  | In case a new required field is added in registration settings, it is possible to use the sdk to inform user of the changes and asked them to fill in the missing required fields by the next login |
-| loginAfterRegister                                  | By calling this sdk function, user could directly login to the app after successful registration |
-| actionGuestLogin                                  | If user has guestLoginForm prepared, it could be called using this function |
+...
+
+// call functions from each of the modules
+this.cidaasAuthenticationService.loginCallback();
+...
+this.cidaasVerificationService.getMFAList(getMFAListOptions);
+...
+
+```
 
-#### User Management
+Each of the functions and its module can be looked in the doc.
 
-The user functions could be found [here](https://github.com/Cidaas/cidaas-javascript-sdk/blob/master/src/main/user-service/UserService.ts). The SDK support the following user management functions:
+### Usage
 
-| SDK Functions                                                                                                                       | Description                                                                                                                                                                                                                                 |
-|-------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| getRegistrationSetup, register, registerWithSocial                                                                                                        | Registering a new user is possible by using classic registration (getting registration fields information & call register function) or by using social provider                                                                                                                                       |
-| getUserProfile, getInviteUserDetails, getCommunicationStatus, updateProfile, updateProfileImage, deleteUserAccount, userCheckExists | To maintain user, functions for getting user information by using cidaas internal api, updating user information, removing user, as well as check if user exist are supported                                                                                                           |
-| getUserInfo | The SDK could be used to get user information by using oidc client ts library                                                                                                           |
-| getUserActivities | In case user want to see the history of his activities, getUserActivities function is provided                                                                                                           |
-| initiateResetPassword, handleResetPassword, resetPassword                                                                           | In case user want to reset password, password reset flow is supported. From initiating the reset password, handling the code or link which has been sent to predefined medium such as email, sms & ivr, and finishing up the reset password |
-| changePassword                                                                                                                      | In case user want to change password, changePassword function is provided                                                                                                                                                                  |
-| registerDeduplication, deduplicationLogin, getDeduplicationDetails                                                                  | In case a new user is registered with similiar information as existing user, deduplication could be activated to either proceed with the registration, or combine the user with an existing one                                             |
-| initiateLinkAccount, completeLinkAccount, unlinkAccount, getLinkedUsers                                                             | Linking und unlinking user account with another account, as well as getting linked user is supported                                                                                                                                        |
+#### Login With Browser
 
-#### Token Management
+To login through cidaas sdk, call **loginWithBrowser()**. This will redirect you to the hosted login page.
 
-The token functions could be found [here](https://github.com/Cidaas/cidaas-javascript-sdk/blob/master/src/main/token-service/TokenService.ts). The SDK support the following token management functions:
+```js
+cidaasAuthenticationService.loginWithBrowser();
+```
 
-| SDK Functions                        | Description                                                                                         |
-|--------------------------------------|-----------------------------------------------------------------------------------------------------|
-| getAccessToken                       | The SDK facilitate login using PKCE flow by exchanging code after succesful login with access token |
-| renewToken                           | Session renewal is possible by using refresh token                                                  |
-| initiateDeviceCode, deviceCodeVerify | Device code flow is supported for authenticating user without user interaction possibilty in device |
-| validateAccessToken                  | Token validation could be done by using introspection endpoint                                      |
-| offlineTokenCheck                    | To save API call, offline token check function could be used                                        |
+once login is successful, it will automatically redirects you to redirect_uri you have configured in cidaas options. You will get information such as code & state as redirect url parameter (query or fragment), which is needed to get access token.
 
-#### Verification Management
+To complete the login process, call **logincallback()**.
 
-The verification functions could be found [here](https://github.com/Cidaas/cidaas-javascript-sdk/blob/master/src/main/verification-service/VerificationService.ts). The SDK support the following verification management functions:
+```js
+cidaasAuthenticationService.loginCallback().then(function(response) {
+    // the response will give you login details.
+}).catch(function(ex) {
+    // your failure code here
+});
+```
 
-| SDK Functions                                                       | Description                                                                           |
-|---------------------------------------------------------------------|---------------------------------------------------------------------------------------|
-| initiateMFA, authenticateMFA                                        | The SDK support initiating & authenticating MFA, which starts passwordless login flow |
-| initiateAccountVerification, verifyAccount                          | User account verification using preconfigured MFA is supported                         |
-| cancelMFA                                                           | MFA process could be aborted in case something go the wrong way                     |
-| getAllVerificationList, getMFAList, checkVerificationTypeConfigured | Information about every supported MFA Verification types, List of configured MFA, and details about particular configured verification type are provided by the SDK        |
-| initiateEnrollment, enrollVerification, getEnrollmentStatus         | Additional MFA verification type could be enrolled using the sdk                                   |
-| initiateVerification, configureVerification, configureFriendlyName         | The SDK support configuring verification request as well as friendly name |
+After successful loginCallback, You will get access token, along with id token and refresh token in the json response, depends on your application configuration.
 
-#### Consent Management
+There are code documentations for each of the functions with example code of how to call them individually.
 
-The consent functions could be found [here](https://github.com/Cidaas/cidaas-javascript-sdk/blob/master/src/main/consent-service/ConsentService.ts). The SDK support the following consent management functions:
+#### Get Tokens And User Profile Information From User Storage
 
-| SDK Functions                                                             | Description                                                                                                           |
-|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
-| getConsentDetails, getConsentVersionDetails                               | The SDK could be used to get consent details as well as details of consent's version                                  |
-| acceptConsent, acceptScopeConsent, acceptClaimConsent, revokeClaimConsent | The SDK support accepting consent (app level consent, scope consent or claim consent) as well as revoke claim consent |
+To get information from user storage, call **getUserInfoFromStorage()**. This function will fetch stored information from predefined user storage (session storage, local storage or in memory)
 
-#### Other Functionality
+```js
+cidaasAuthenticationService.getUserInfoFromStorage().then(function(response) {
+    // the response will contains tokens & user profile information.
+}).catch(function(ex) {
+    // your failure code here
+});
+```
 
-general SDK functions could be found [here](https://github.com/Cidaas/cidaas-javascript-sdk/blob/master/src/main/web-auth/WebAuth.ts). The SDK support the following other functionality:
+### Functions Overview
 
-| SDK Functions                                  | Description                                                                                 |
-|------------------------------------------------|---------------------------------------------------------------------------------------------|
-| getRequestId                                   | The SDK could be used to get request id, which is required as input to call other functions |
-| getLoginURL                                    | Getting login authz url is supported by the SDK                                                        |
-| getTenantInfo, getClientInfo                   | Getting public information such as tenant info & client info is supported by the SDK                                                    |
-| setAcceptLanguageHeader                        | The SDK could be used to change response language                                           |
-| createDeviceInfo, getDevicesInfo, deleteDevice | Creating, getting, and removing device information is supported by the SDK                          |
-| logoutUser                                     | The SDK could be used to end user session by using cidaas internal api                      |
-| userActionOnEnrollment                                     | The SDK could be used to run predefined action after enrollment |
+Cidaas Javascript SDK Functions can be found on the [documentation](https://cidaas.github.io/cidaas-javascript-sdk).
 
 ## Possible Error
 

package/dist/authentication-service/AuthenticationService.d.ts

@@ -0,0 +1,140 @@
+import ConfigUserProvider from '../common/ConfigUserProvider';
+import { OidcManager, OidcSettings, LoginRedirectOptions, LogoutRedirectOptions, PopupSignInOptions, PopupSignOutOptions, RenewTokenOptions, User, LogoutResponse, LoginRequestOptions } from './AuthenticationService.model';
+export declare class AuthenticationService {
+    userManager: OidcManager;
+    config: OidcSettings;
+    configUserProvider: ConfigUserProvider;
+    constructor(configUserProvider: ConfigUserProvider);
+    /**
+     * To register through cidaas sdk, call **registerWithBrowser()**. This will generate and redirect the app to authz url in same window for register view.
+     * Afterwards you will be redirected to the hosted registration page.
+     * @example
+     * ```js
+     * cidaasAuthenticationService.registerWithBrowser();
+     * ```
+     * @param {LoginRedirectOptions} options to over-ride the client config for redirect login
+     */
+    registerWithBrowser(options?: LoginRedirectOptions): Promise<void>;
+    /**
+     * To login through cidaas sdk, call **loginWithBrowser()**. This will generate and redirect the app to authz url in same window for logging in. Afterwards you will be redirected to the hosted login page.
+     * Once login successful, it will automatically redirects you to the redirect url, which is configured in cidaas config.
+     * @example
+     * ```js
+     * cidaasAuthenticationService.loginWithBrowser();
+     * ```
+     * @param {LoginRedirectOptions} options to over-ride the client config for redirect login
+     */
+    loginWithBrowser(options?: LoginRedirectOptions): Promise<void>;
+    /**
+     * To open the hosted login page in pop up window, call **popupSignIn()**. This will generate and open authz url in a popup window.
+     * On successful sign in, authenticated user is returned.
+     * @example
+     * ```js
+     * cidaasAuthenticationService.popupSignIn().then(function (response) {
+     *   // the response will give you user details after finishing loginCallback().
+     * }).catch(function(ex) {
+     *  // your failure code here
+     * });
+     * ```
+     * @param {PopupSignInOptions} options optional options to over-ride the client config for popup sign in
+     */
+    popupSignIn(options?: PopupSignInOptions): Promise<User>;
+    /**
+     * Once login successful, it will automatically redirects you to the redirect url, which is configured in cidaas config.
+     * To complete the login process, call **loginCallback()**. This will parses needed informations such as tokens in the redirect url.
+     *
+     * @example
+     * ```js
+     * cidaasAuthenticationService.loginCallback().then(function (response: User) {
+     *   // the response will give you login details.
+     * }).catch(function(ex) {
+     *  // your failure code here
+     * });
+     * ```
+     * @param {string} url optional url to read sign in state from
+     */
+    loginCallback(url?: string): Promise<import("oidc-client-ts").User>;
+    /**
+     * To end user session, call **logout()**. You need set the redirect url, if not it will automatically redirect to the login page
+     * @example
+     * ```js
+     * cidaasAuthenticationService.logout();
+     * ```
+     * @param {LogoutRedirectOptions} options optional logout options to override cidaas configuration
+     */
+    logout(options?: LogoutRedirectOptions): Promise<void>;
+    /**
+     * To open the hosted logout page in pop up window, call **popupSignOut()**.
+     * @example
+     * ```js
+     * cidaasAuthenticationService.popupSignOut().then(function() {
+     *   // success callback in main application window after finishing popupSignOutCallback().
+     * }).catch(function(ex) {
+     *   // your failure code here
+     * });
+     * ```
+     *
+     * @param {PopupSignOutOptions} options optional logout options to override cidaas configuration
+     */
+    popupSignOut(options?: PopupSignOutOptions): Promise<void>;
+    /**
+     * **logoutCallback()** will parses the details of userState after logout.
+     * Get the logout call state from the url provided, if none is provided current window url is used.
+     * @example
+     * ```js
+     * cidaasAuthenticationService.logoutCallback().then(function (response: LogoutResponse) {
+     *   // the response will give you userState details.
+     * }).catch(function(ex) {
+     *  // your failure code here
+     * });
+     * ```
+     * @param {string} url optional url to read signout state from,
+     * @param {boolean} keepopen optional boolean to keep the popup window open after logout, in case of popupSignOut()
+     */
+    logoutCallback(url?: string, keepopen?: boolean): Promise<LogoutResponse | undefined>;
+    /**
+     * **renewToken()** will update user information in user storage with a new token, based on refresh token that is stored in the storage.
+     * On successful token renewal, authenticated user is returned
+     *
+     * @example
+     * ```js
+     * cidaasAuthenticationService.renewToken().then(function (response) {
+     *   // the response will give you user details.
+     * }).catch(function(ex) {
+     *  // your failure code here
+     * });
+     * ```
+     * @param {RenewTokenOptions} options options to over-ride the client config for renewing token.
+     * @returns {Promise<User>} Authenticated user
+     */
+    renewToken(options?: RenewTokenOptions): Promise<User>;
+    /**
+     * To get the generated login url, call **getLoginURL()**. This will call authz service and generate login url to be used.
+     * @example
+     * ```js
+     * cidaasAuthenticationService.getLoginURL().then(function (response) {
+     *   // the response will give you login url.
+     * }).catch(function(ex) {
+     *   // your failure code here
+     * });
+     * ```
+     * @param {LoginRequestOptions} options login options to override config settings provided
+     * @return {Promise<string>} authz url for login
+     */
+    getLoginURL(options?: LoginRequestOptions): Promise<string>;
+    /**
+     * To get the user informations from defined UserStorage, call **getUserInfoFromStorage()**.
+     * This will fetch informations about the authenticated user such as tokens & user profiles, which has been stored in predefined user storage based on cidaas configuration. (default is session storage)
+     *
+     * @example
+     * ```js
+     * cidaasAuthenticationService.getUserInfoFromStorage().then(function (response) {
+     *   // the response will give you profile details.
+     * }).catch(function(ex) {
+     *   // your failure code here
+     * });
+     * ```
+     * @return {Promise<User|null>} returns authenticated user if present, else null
+     */
+    getUserInfoFromStorage(): Promise<User | null>;
+}