Angular - node.js sample app
The Angular - Node JS sample application showcases the capabilities of the CyberArk Identity APIs and widgets. It also includes an OAuth and OpenID Connect playground with all possible grant flows. This app uses a Node JS backend and an Angular JS frontend.
CyberArk Identity tenant configuration
If you don't have any existing CyberArk tenants, you can try a free trial tenant here.
Step 1: Create a role
-
To create a role refer here.
-
Ensure that User Management, Role Management Rights are added to the role under the Administrative Rights section.
Step 2: Set up an Authentication profile
Set up an Authentication profile and add it to the policy under the Authentication Policies section. For more information, refer to here.
Step 3: Create a policy
To create a policy, refer here.
Ensure that the above-created role is added to the policy.
Step 4: Setup an OpenID Connect application
-
In the Identity Administration portal, select Apps > Web Apps, then click Add Web Apps.
-
In the Custom section, click Add OpenID Connect app.
-
Open the OpenID Connect app that you created in the above step.
-
In the Settings section, add an ID of your choice for the Application ID.
-
Navigate to Trust Section.
Enter the client secret. Example,
sample1234
. In the Service Provider Configuration select Login initiated by the app only option.Let's make sure we set the below feature flags to true:
-
Core.Enable.WidgetOIDCIntegration
-
Core.Enable.OAuthInOIDC
-
-
Add the Redirect destinations for the sample app.
http://localhost:2200/api/RedirectResource
Based on your app configuration the URL configuration should be changed.
Setup Permissions for OpenID Connect. Add the above-created role and provide Run permission to generate Tokens.
For more Information on OpenID Connect, refer Use OpenID Connect.
Specify trusted DNS domains for API calls
Include Web App Domain in Trusted DNS Domains for API Calls:
-
Navigate to Settings -> Authentication -> Security Settings -> API Security in the admin portal.
-
Add an entry under Trusted DNS Domains for API Calls.
localhost
Step 5: Create an Authentication Widget and configure it
Link the widget with the OpenID connect app created above.
Angular node sample app deployment guide
A step-by-step guide to setup a sample app environment
Overview
This guide aims to help you install the prerequisite tools and deploy the Angular Node sample app.
Before you begin
Install NODE.js
-
Download the Node.js installer from https://nodejs.org/en/download/ and run the file(highly recommended to download 64-bit version).
-
Node.js installer includes the NPM package manager.
-
Ensure that the path of Node.js is configured into the system PATH environment variable.
-
Use the commands below to check Node.js installation.
-
Minimum version of node required is 16.15.0.
node -v
npm -v
Install JS SDK
Install SDK from here.
Build and run
Follow the steps below to Build and Run the Angular Node application.
Angular
-
Navigate to
identity-sample-nodejs/angular
folder.cd angular
-
Install the dependencies.
npm i
-
Run the application.
npm start
Nodejs server application
-
Navigate to identity-sample-nodejs folder.
-
Install the dependencies
npm i
-
Run the server as an administrator.
npm start
Now, you can use the environment for the Angular Node Sample App.
Open
http://localhost:4200
and configure Settings to access web application.
Explore Sign Up and Sign In widget
Using the widget customer application will not redirect to the CyberArk Identity server for user authentication. The widget will embed the existing customer web application to perform user authentication.
Introduction to Sign Up / Sign In widget
CyberArk provides a widget that customers can use to avail of the sign up and sign in capabilities in their applications.
The Sign Up and Sign In widget can be integrated into a custom application where the company can authenticate the identity of end users using CyberArk Identity.
Widget overview
-
User can register an account with the CyberArk Identity server
-
Admin needs to map the role in CyberArk Admin portal for newly registered user
-
User will authenticate to CyberArk Identity server
Widget usage
The signup/signin widget in the sample web app secures end-user registration and authentication using CyberArk SignUp/SignIn widget, respectively.
On click of the Get Started button of the widget's card, it should navigate to the login protocols page. Then again, On click of Get Started of the login protocols page, it also has a Sign up and Sign in widgets, which we can see how the widget can be integrated into a client app.
Widget exploration
-
On the click of the Sign up button, the CyberArk Identity Sign Up widget will appear where you can register and create an account.
-
On Post creation of the user, the Sign In widget appears through which the user can sign in to the sample app.
-
When clicked on the Next button, the authentication challenges appear, responding to which the user authenticates itself.
On a successful response, we use OAuth Authorization with PKCE flow to get access token. Use the access token in the authorization header for subsequent requests in a sample application.
User info
After successful authentication using the widget, the user will navigate to the application to explore additional functionalities provided.
Explore OIDC flows
Using the OpenID Connect Web application connected with the widget we used above for login, we can explore the following OIDC flows.
As part of Authorized Redirect URIs of the OpenID Connect web application, have http://localhost:4200/RedirectResource
.
Explore sample application functionalities
After successful authentication, a user logs in to the Node js - Angular Sample app and sees demo functionalities as a menu in the top-right corner of the page.
These functionalities are included as part of the sample app to demonstrate how a client application can integrate CyberArk Identity authentication and authorization services in their application features/tasks or activities like updating the user profile, resetting the password, and TOTP registration, or even the necessary items like transferring funds.
Some of these use cases added in the sample app are discussed below.
Fund transfer
Clients can integrate the CyberArk Identity into their applications to authenticate and authorize users for crucial activities like transferring funds and similar functionalities. This use case demonstrates the Fund Transfer functionality.
-
On clicking the Fund Transfer tab, the user navigates to a page where an input field is provided for some amount to be entered and description.
-
Click on the Transfer button after entering the amount and description (optional). It initiates the process using the CyberArk Identity platform to authorize the user.
-
The user enters the password or responds to the various challenges corresponding to the user account and proceeds by clicking Next.
-
After successful authorization, the process of fund transfer is marked completed, and the Fund Transfer screen displaying the success can be seen.
-
The transaction would be successful if the TransferFunds scope is present in the OIDC scope section on the settings page. Else we will get the unauthorized error.
-
On click of Fund Transfer, we see a drop-down with Transaction Summary, which displays all the transaction details for the user.
-
To view the Transaction Summary details, we need
TransferSummaryData
scope in the access token.The value of the amount entered on this page is only for demonstration purposes, and no actual transaction takes place in the database. This part is integrated into a sample app to showcase how CyberArk Identity can be used to provide authorization mechanisms for crucial activities like Fund Transfer at the client end.
Enroll factors
On click of Enroll Factors we get a drop-down with TOTP Registration and Change Password.
TOTP registration
TOTP authentication mode is also provided as part of the CyberArk Identity product. This time-based one-time password is used to authorize users in the sample app to showcase how clients can use it to authenticate and authorize users to their application or platform using CyberArk Identity.
TOTP registration is configurable from the admin portal provided by CyberArk at the time of availing the services.
-
On clicking the TOTP Register tab under Enroll Factors, the app navigates the user to the TOTP Registration page.
-
The steps to register for receiving the OTP along with a QR code and a verification code input field can be seen on this page.
TOTP authentication
-
Following the steps mentioned on the page a user first needs to install any 3rd party authenticator app like Google authenticator/ Microsoft authenticator and scan the QR code available on a sample app page.
-
Upon scanning the QR code, a one-time password will be displayed on the authenticator app.
-
Enter this OTP in the Code input box and click on Verify to proceed.
Change password
On clicking the Change Password tab, a user can reset their password. UserMgmt/ChangeUserPassword()
endpoint is invoked to update the password for a user who is authenticated.
User profile
This page contains the current user account details and provides an option to update the profile information. The profile information includes username, email address, display name, and mobile number. The user is allowed to edit the details and use the Update button to submit the details.
Updating the user profile invokes /user/UpdateProfile endpoint, which updates the cloud user properties and the local database user properties to the latest updated values, depending upon the scenario in use.
Example:
After a successful update, a success popup is displayed on the same screen.
Logout
In the end, click Logout to revoke the access token and end the session to log the user out.