React SPA Sample App

This Sample Application showcases the capabilities of CyberArk Identity Widget linked with an OpenID connect application and includes an OpenID Connect playground with all possible grant flows. This app uses React JS as the frontend.

CyberArk Identity Tenant Configuration

If you don't have any existing CyberArk tenants, you can try a free trial tenant [here]. (https://www.idaptive.com/free-trial)

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: Setup 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

Navigate to the CyberArk Admin portal and click Web Apps under the Apps section.

Click Add Web Apps and navigate to the Custom section->Add OpenID Connect app.
Open the OpenID Connect app created in the above step.
In the Settings section, add an ID of your choice for the Application ID.
Navigate to Trust Section

Enter client secret (E.g.: $3CrE!4327)
- Add Resource application URL for the sample app.

http://localhost:3000/Resource

Add the Redirect destinations for the sample app.

http://localhost:3000/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 to here .

Specify Trusted DNS Domains for API Calls

📘
Administrator privileges
To add a trusted domain, you require administrator privileges.

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 as follows.

Link the widget with the OpenID connect app created above.

React SPA Deployment Guide

A step-by-step guide to setting up a sample app environment

Overview

This guide will help you install the prerequisite tools and deploy the React SPA 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 the JavaScript SDK from here

Run

Run the application

npm install
npm start

Explore Sign Up and Sign In widget

Using the widget, the customer application will embed to the existing customer web application to perform the user authentication instead of regular redirection.

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 / Sign In widget can be integrated into a custom application where the organization can authenticate end-users identities using CyberArk Identity.

Widget overview

User can register an account with the CyberArk Identity server.
Admin needs to map the role in the CyberArk Admin portal for newly registered users.
User will authenticate to CyberArk Identity server.

Widget Usage

The Sign Up/ Sign In widget in the sample web app secures their end-user registration and authentication using CyberArk Sign Up/Sign In widget, respectively.

On clicking the Get Started button of the widget's card, it should navigate to the login protocols page. On clicking the Login button from the login protocols page, it has a Sign Up / Sign In widget.

Widget Exploration

On the click of the Sign Up button, the CyberArk Identity Sign Up widget will appear. Users will be able to register and create an account.

Post creation of the user, the Sign In widget appears through which the user can sign in to the sample app.

The authentication challenges appear when clicked on the Next button, responding to which the user authenticates.

📘
Note:
We use OAuth Authorization with PKCE flow to get an access token upon successful response. 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 "user info" page, where the user can explore additional functionalities provided.

Update Profile

Update Profile 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 can edit the details and click on the update button to submit the details.
Updating the user profile invokes the /user/UpdateProfile endpoint, which updates the cloud user properties.

After the successful update, a success popup gets displayed on the same screen.

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.

Authorization
Implicit
Hybrid

📘
Note
As part of Authorized Redirect URIs of the OpenID Connect web application have "http://localhost:3000/redirect".

Each flow explanation as follows.

Authorization code flow

When configuring public applications, such as mobile apps or single-page apps, where the client secret is not secure, this flow helps removes the use of client secret, making it more secure.

The following section provides more details about Authorization code flow in React Sample App.

Select Authorization from the drop-down and click Build Authorize URL.

The generated authorization URL is hit on click of Authorize after taking access permissions of the scopes requested (which were set up on the settings page).
The authorization code is sent with a preview of the Token Endpoint API.

On click of Proceed, Token set and Claims are fetched using the access_token.

Try Another Flow performs the logout against the user and navigates to the home page of the sample app.

Implicit flow

This flow is the simplest and is typically used by JavaScript applications running in a browser. The access token under this flow is assumed to be used temporarily. By default, id_token is selected as response_type; if the token is also chosen, the response contains access_token along with id_token.

The following section provides more details about Implicit code flow in React Sample App.

Select Implicit from the drop-down and check the token box to get it as the response.
Click the Build Authorize URL to get the URL as in the previous flow with the response types.

On click of Authorize, the authorize response is returned with the access_token.

On click of Proceed, we get the Claims information.
Try Another Flow performs the logout against the user and navigates to the home page of the sample app.

Hybrid flow

Hybrid flow is the combination of Authorization code and Implicit flow.

The following section provides more details about Hybrid code flow in React Sample App.

Select Hybrid from the dropdown and choose the response types for additional information in the response and click on Build Authorize URL.

On Authorize action, we get the Authorize Response and the preview of the Token Endpoint.

On Proceed button click, we get a similar response as the Authorization code flow with Token set and Claims.
Try Another Flow performs the logout against the user and navigates to the home page of the sample app.

Introspect

Creates a request to validate the JWT or opaque token by calling introspect endpoint.
Set the clientId and clientSecret for authorization and pass token as a parameter.

On click of the Introspect button, we will get the Introspect response containing the active status as true or false.