Cidaas native javascript sdk
!Logo
This cidaas javascript SDK library is built on the top of OIDC client typescript library.
Please check the Changelog for more information about the latest release.
* Overview
* Documentation
* Installation
* Initialisation
* Usage
* Functions Overview
* Possible Error
Here you can find general overview of cidaas javascript SDK
Here you can find technical documentation of cidaas javascript SDK
From CDN
``html`
From npm
`
npm install cidaas-javascript-sdk
After adding the sdk library, create a local file such as cidaas.service.ts and define Oidc settings variable there for initializing cidaas sdk.
Oidc settings variable support every OIDC Client UserManagerSettings Properties which has the following notable properties:
| Property Name | Required | Description |
| ------ | ------ | ------ |
| authority | yes | cidaas instance base url |
| client_id | yes | client application's identifier, which could be found in cidaas admin ui |
| 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 Oidc settings variable looks like this:
`js`
const options = {
authority: 'your domain base url',
client_id: 'your app id',
redirect_uri: 'your redirect url',
post_logout_redirect_uri: 'your post logout redirect url',
scope: 'openid email roles profile',
}
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
additionally, user can also define custom storage in the client side by implementing Storage class.
If there is no userStore properties being send in Oidc settings variable, it will use session storage by default.
In case local storage is prefered to be used, then Oidc settings can be modified as following:
`js`
const options = {
authority: 'your domain base url',
...,
userStore: new WebStorageStateStore({ store: window.localStorage })
}
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`
const options = {
authority: 'your domain base url',
...,
userStore: new WebStorageStateStore({ store: new InMemoryWebStorage()})
}
see usage to get the stored informations from user storage.
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, Oidc settings can be modified as following:
`js`
const options = {
authority: 'your domain base url',
...,
automaticSilentRenew: false
}
Cidaas ConfigUserProvider have to be initialised to be added to each of the modules as dependencies:
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
getAuthenticationService() {
return this.authenticationService;
}
// get verification module
getVerificationService() {
return this.verificationService
}
}
`
Usage in Component:
`js
// inject cidaas service
constructor(private cidaasService: CidaasService, ...) {}
...
// init each of cidaas modules which are needed in the component
this.cidaasAuthenticationService = this.cidaasService.getAuthenticationService();
this.cidaasVerificationService = this.cidaasService.getVerificationService();
...
// call functions from each of the modules
this.cidaasAuthenticationService.loginCallback();
...
this.cidaasVerificationService.getMFAList(getMFAListOptions);
...
`
#### Login With Browser
To login through cidaas sdk, call loginWithBrowser(). This will redirect you to the hosted login page.
`js`
cidaasAuthenticationService.loginWithBrowser();
once login is successful, it will automatically redirects you to redirect_uri you have configured in Oidc settings. 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().
`js`
cidaasAuthenticationService.loginCallback().then(function(response) {
// the response will give you login details.
}).catch(function(ex) {
// your failure code here
});
After successful loginCallback, You will get access token, along with id token and refresh token in the json response, depends on your application configuration.
#### Login With Social Provider
To login with social providers (e.g., Facebook, Google, LinkedIn), initialize the LoginService module and call loginWithSocial(). This will redirect you to the social provider's login page.
`js`
cidaasLoginService.loginWithSocial({
provider: 'facebook',
requestId: 'your requestId'
});
You can also pass optional query parameters:
`js`
cidaasLoginService.loginWithSocial({
provider: 'facebook',
requestId: 'your requestId'
}, {
dc: 'device-capacity',
device_fp: 'device-fingerprint',
// Any additional custom query parameters
customParam: 'customValue'
});
once login is successful, it will automatically redirects you to redirect_uri you have configured in Oidc settings. 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().
`js`
cidaasAuthenticationService.loginCallback().then(function(response) {
// the response will give you login details.
}).catch(function(ex) {
// your failure code here
});
After successful loginCallback, You will get access token, along with id token and refresh token in the json response, depends on your application configuration.
There are code documentations for each of the functions with example code of how to call them individually.
#### Get Tokens And User Profile Information From User Storage
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)
`js``
cidaasAuthenticationService.getUserInfoFromStorage().then(function(response) {
// the response will contains tokens & user profile information.
}).catch(function(ex) {
// your failure code here
});
Cidaas javascript SDK functions can be found on the documentation.
The SDK will throws Custom Exception if something went wrong during the operation:
| HTTP Status Code | When could it be thrown |
|----------------- | ----------------------- |
| 500 | during creation of WebAuth instance |
| 417 | if there are any other failure |