This guide aims to help the user in understanding and configuring the Settings page and explain the authentication flow in CyberArk Identity sample app.

Configure Sample App Settings

After completing the deployment as mentioned in previous section, user needs to build and run the app as suggested in README.

• CyberArk Identity sample app's Settings page provides a GUI form based page to help user in updating the application related data which was configured in Tenant Configuration.
• Open any browser and go to url which is configured as part of deployment. In this case, we use https://identitydemo.acmeinc.com:4200

• Click on the Settings link as highlighted in the above image.

• Update the settings form with the data obtained while configuring tenant. For further reference click here.

Application Logo

Any custom image can be uploaded with the supported png, jpg, gif, ico, bmp image file types.

Image will be auto-scaled accordingly.

CyberArk Tenant

OAuth 2.0

OpenID Connect

ReCaptcha Settings

Configure ReCaptcha on Admin Portal

• On Admin Portal, Navigate to Settings--> Authentication --> Security Settings and enable Captcha as shown below.

• Next, Navigate to Settings--> Customization--> System Configuration and Enable "Use Custom reCAPTCHA V2 API Settings" option to use custom reCAPTCHA settings for your tenant. Otherwise, default reCAPTCHA settings will apply. Then, provide Site Key and Secret key as shown below.

Update Settings

• Upon clicking on Save, details will be successfully saved.
• User can click on the Home button from the top-right corner of the page to proceed further.

Authentication using CyberArk Identity APIs

The CyberArk Identity provides you with a set of RESTful endpoints that enable you to use CyberArk Identity functionality in your custom applications. You can customize CyberArk Identity Access Management with templates to change the look and feel of your portal. Please refer to the Overview for more details.

To use the CyberArk Identity Platform APIs, user must authenticate to the application. The detailed overview can be found here.

The basic authentication process is as follows:

1. The client requests authentication for a user by calling /Security/StartAuthentication and passing enough information to identify the user and tenant.

📘

/Security/StartAuthentication

This endpoint updates the server that a user from a given tenant wants to be authenticated. If the user already exists then, the server returns an array of configured security challenges to the client, each containing an array of factors, known as mechanisms, that the user must fulfil for each challenge. The user’s responses to these mechanisms are submitted using the /Security/AdvanceAuthentication endpoint.

/Security/StartAuthentication
{
    "TenantId": "ABC1234",
    "User": "[email protected]",
    "Version": "1.0"
}

2. The server validates the user, tenant and creates an MFA package that includes other things such as session ID and zero or more authentication challenges for the client to answer.

{
    "ClientHints": {
        "PersistDefault": False,
        "AllowPersist": True,
        "AllowForgotPassword": False
    },
    "Version": "1.0",
    "SessionId": "1e5214e4-0921-4e9e-8ada-3ef2970f7c1f",
    "Challenges": [
        {
            "Mechanisms": [
                {
                    "AnswerType": "Text",
                    "Name": "UP",
                    "MechanismId": "4a23390d-dee9-4ead-aa33-2bacd93f81fa"
                }
            ] 
      }
    ],
    "Summary": "NewPackage",
    "TenantId": "ABC1234"
}

If a server’s response to the /Security/StartAuthentication request contains an array of two challenges, Multi Factor Authentication (MFA) is required to authenticate the user. That is, the user is expected to fulfill one mechanism from each of the Challenges. Please refer to Setup Multi-factor Authenticationfor more details about MFA at product level.

3. The client calls /Security/AdvanceAuthentication to respond to an authentication challenge.

📘

/Security/AdvanceAuthentication

This endpoint sends the user’s responses of the mechanisms back to the server. Server validates these challenges and it returns an authentication token cookie to the client. Once the client receives the authentication token, the client can use it to invoke subsequent endpoints on behalf of the user.

/Security/AdvanceAuthentication
{
        "TenantId": "ABC1234",
        "SessionId": "1e5214e4-0921-4e9e-8ada-3ef2970f7c1f",
        "MechanismId": "4a23390d-dee9-4ead-aa33-2bacd93f81fa",
        "Action": "Answer",
        "Answer": "Pass1234"
}

4. If the client answers the challenge correctly, the server does one of the following:

• Logs the user in and returns LoginSuccess.
• Requests the user with another challenge mechanism.
• Notifies the client that an out of bounds (OOB) challenge is pending. The client must poll until the server returns success result.

📘

Note:

After authentication is successful, we will receive authentication cookie i.e. .ASPXAUTH cookie as part of HTTP response headers. See Adaptive Authentication for information on API request and response.

After successful authentication, it redirects to Login Protocols page which provides details about all the protocol flows.

For exploring all the 4 protocol cards in detail, please refer the below links.

• Explore API flow
• Explore OIDC flows
• Explore OAuth User Interactive Flows
• Explore OAuth Machine to Machine Flows