@bookassist/ba-sso

SSO

This is the Single Sign On application to authenticate with AWS Cognito service.

This project has different targets.

1. Create a React standalone application. Here
2. Crerate a library to integrate with other React projects. Here

SSO Application

This is the application to process the authentication of the user using AWS Cognito service.

The application has following features

1. Authentication of the user
2. Change password of the user
3. Forgot password procedure of the user
4. Control of rotation fo the password

The application is preconfigured with default parameters that you need to customize. You have to set a global object to override values of the configuration. The global object you need to override is global.bookassist.auth

Configuration

Global properties of global.bookassist.auth

Name	Type	Description
enviroment	enum [ secure | sso ]	Define the environment of the authetication. Secure and SSO have different AWS Cognito Pool
authSever	url	Endpoint of the SSO Server Auth
i18nEndpoint	url	Endpoint to get JED i18n feed
gaAccount	string	Google Analytics account
captchaKey	string	ReCaptcha v2 key to use
confirmWithServer	bool	If this flag is true, the application confirms with SSO Server Auth the identity of the user. If it's false, the AWS Cognito identity is enough
aws	object	AWS Amplify configuration

Properties of aws

Name	Type	Description
Auth	object	Configuration of the Auth

Example of the global object

{
  "environment": "secure",
  "authServer": "https://auth.milocalhost.com",
  "i18nEndpoint": "https://api.milocalhost.com/master/i18n/bookassist.i18n.HotelAdminRB/{0}/jed",
  "gaAccount": "UA-25321856-1",
  "captchaKey": "6Lc9vSUTAAAAAGNnZJGco_7GxWAWuZ9n99DSQw1V",
  "confirmWithServer": false,
  "orderActionButtons": "cta-right",
  "aws": {
    "Auth": {
      "identityPoolId": "eu-west-1:d1105de5-c924-4f4c-8e6c-bc5be3df684f",
      "region": "eu-west-1",
      "userPoolId": "eu-west-1_NycYtNl1g",
      "userPoolWebClientId": "p21h8qinoaculq94vmqmahigd",
      "mandatorySignIn": true,
      "authenticationFlowType": "USER_PASSWORD_AUTH",
      "clientMetadata": {
        "userLang": "en",
        "pci": "true"
      }
    }
  }
}

Build app

This project is using webpack to build the app, so you can execute

yarn install && yarn build:app

After you build the application the result is in the dist directory.

dist
├── ba-sso-component-styles.css
├── config.js
├── favicon
├── fonts
├── images
├── index.html
└── sso.min.js

Docker environment

The project can create a Docker image to run the application. The image is based on nginx.

As same as other apps, you have to build the docker image of this project. To build that, you have to run following command.

docker build -t 479499153175.dkr.ecr.eu-west-1.amazonaws.com/bookassist/sso-auth .

For developer environment, you probably want to use a local registry instead of ECR

docker build -t registry.localhost:5000/bookassist/sso-auth .

SSO Library

The project can also create a library to use the component inside an application. The library is take into account you can use the component in different environments.

1. React Web Application
2. Standalone in a web page

The library exports some UI components and some functions to work with the component and control workflows.

Components

The library exports 3 components

Component	Description
SSOComponent	This is to use in a non-react application
SSOReactComponent	This is to use in a react application
SSOWrapper	This is to use in a react application but using redirections instead of embedded component

Properties of the components

Property	Type	Controls	Description
forceSignIn	bool	All	Flag to force login when control is created. Default false
language	string	All	Language code to translate the keys. Default is "en"
signInUri	uri	SSOWrapper	URI where the control has to redirect when the user is not logged in
enabledAnalytics	bool	All	Flag to enable Google Analytics. Default true
enabledHotReload	bool	All	Flag to enable hot reload. Default true
childrenToControl	control	All	HTML or React controls to render is the user is logged in. Default null
loginFormContainer	control	SSOReactComponent, SSOWrapper	Container where SSO form is mount
withCaptcha	bool	SSOComponent, SSOReactComponent	Flag to show captcha on sign in dialog. Default false
checkCaptcha	bool	SSOComponent, SSOReactComponent	Flag to check captcha into control. The parameter depends if withCaptcha is enabled. Default is true
minPasswordLength	number	SSOComponent, SSOReactComponent	Minimum length of the password. Default 8
displayBehaviour	enum [ embedded | wrapper | wrapperWithHeader ]	SSOComponent, SSOReactComponent	Behaviour of the control to wrapper other controls. Default wrapperWithHeader
initialAction	enum [ normal | changepass | logout ]	SSOComponent, SSOReactComponent	Initial action if the user is signed in. Default normal
redirect	uri	SSOComponent, SSOReactComponent	redirect URL to redirect after sign in. Default null
callback	function	SSOComponent, SSOReactComponent	Callback function. Default null
theme	enum [ Classic | Modern ]	SSOComponent, SSOReactComponent	Theme to use into control. Default Classic
hasTemporaryPassword	bool	SSOComponent, SSOReactComponent	A flag to know if the static use has temporary password. Default false
checkURL	bool	SSOComponent	Flag to parse URL parameters. Default true
container	string or HTMLnode	SSOComponent	The container to put the control. You can set and valid document query parameter or and DOM element. Default "#sso"

Functions

The library also exports some functions

Function	Description
retrieveUserInformation	Retrieve the user information from AWS Cognito
retrieveCredentials	Retrieve AWS Cognito Tokens
signOut	Sign Out from SSO
changePassword	Go to change password form

retrieveUserInformation

Retrieve user information of current user

parameters

Parameter	Type	Description

output

Object that contains following properties

Propety	Type	Description
username	string	Username of the current user
userid	number	Id of the user
accountId	string	Account linked to the user
name	string	Full name of the user
email	string	email of the user
phone	string	Phoner of the user
lastLoginDate	string	Last date that the user was logged in
status	enum [ ACTIVE | PASSWORD_EXPIRED | USER_EXPIRED | DISABLED | TEMP_PASSWORD | TEMP_PASSWORD_EXPIRED ]	Status of the user
administrator*	bool	Flag to know if the user is an administrator of the account
hotelId*	number	The id of the hotel that the user is linked to
guideId*	number	The guide of the hotel that the user is linked to
hotelGroupId*	number	The id of the group that the user is linked to

NOTE: * means this field is deprecated

retrieveCredentials

Retrieve AWS Cognito credentials. Usually contains JWT

parameters

Parameter	Type	Description

output

Object with following properties

Propety	Type	Description
accessToken	string	Access token from AWS Cognito
idToken	string	Identity token from AWS Cognito
refreshToken	string	Refresh token from AWS Cognito

Example

{
  "accessToken": "ydashdalk...",
  "idToken": "jbdslkj2783..",
  "refreshToken": "jdkas=_ksajhd..."
}

signOut

Sign out from the Single Sign On globally

parameters

Parameter	Type	Description
message	string	Message or reason to sign out. Default ''
callback	function	Callback to execute when signed out. Default () => {}

output

None

changePassword

Go to change password

parameters

Parameter	Type	Description

output

None

Build library

To build the library you can execute

yarn install && yarn build:lib

Publish library

You can publish this library to a npm repository.

yarn publish

Using in a React project

First of all you have to include the library in your project

yarn add @bookassist/ba-sso

or you can use npm

npm install @bookassist/ba-sso

You have to wrapper your application with a component

import { SSOWrapper } from '@bookassist/ba-sso'
...
<SSOWrapper signInUri={ 'https://login.bookassist.com' }>
  <div>My application</div>
</SSOWrapper>

In case you want to use only the wrapper, you can import from a compat file

import SSOWrapper from '@bookassist/ba-sso/dist/ba-sso-wrapper'
...
<SSOWrapper signInUri={ 'https://login.bookassist.com' }>
  <div>My application</div>
</SSOWrapper>

Using a function

import { retrieveUserInformation } from '@bookassist/ba-sso/dist/ba-sso-functions';
...
const myFunction = () => {
  retrieveUserInformation()
  .then(user -> {
    // your code of user
  })
}

Using in a page

You have to include the CSS file and the Script file. You can pick them from the dist directory after you build the application.

The application needs an HTML container with id sso.

<!doctype html>
<html>
  <head>
    <title>Bookassist SSO</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    
    <script type="text/javascript">
      window.signInCallback = function() {
        alert('Signed In');
      };
    </script>

   <link href="./ba-sso-styles.css" rel="stylesheet">
  </head>
  <body class="ha-login">
     <div id="sso"></div>
     <script type="text/javascript">
      <!-- Override values -->
     </script>
     <script type="text/javascript" src="./ba-sso-component.js"></script>
     <script type="text/javascript">
        SSOComponent = window["ba-sso-component"].SSOComponent;
        var c = new SSOComponent({ "displayBehaviour": "embedded" });
        c.run();
     </script>
   </body>
</html>