Integrate CyberArk Identity authentication APIs

📘

Prerequisite

1. Setup OpenID Connect (OIDC) custom application in CyberArk Identity tenant
2. Install the CyberArk Identity Java-angular sample app
3. Setup the Java-angular sample app

The Java angular sample app contains examples of how the client application can integrate the CyberArk Identity authentication APIs to provide strong authentication to their apps and leverage MFA such as QR code and mobile push authenticator.

Please refer to the Overview for more details. The detailed overview can be found here.

To try out the authentication API integration on the sample app, Click the "Login" link on the authentication APIs tile as shown below:

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, 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 fulfill for each challenge. The user’s responses to these mechanisms are submitted using the /Security/AdvanceAuthentication endpoint.

On the sample app, the below screen leverages the start authentication API. Enter the username and click on next to invoke the start authentication API.

Example of the start authentication request:

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

2. The server validates the user and tenant and creates an MFA package that includes other things, such as session ID and one 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.

3. The client should then invoke /Security/AdvanceAuthentication to respond to an authentication challenge.

📘

/Security/AdvanceAuthentication

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

Once the user enters the password as shown above and clicks on next, the advance authentication API is invoked as below:

/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 based on the MFA policy setup:

• If only one challenge is set up, log the user in and return LoginSuccess.
• If multiple challenges are set up: Requests the user with another challenge mechanism.
• For challenges such as email OTP or SMS: Notifies the client that an out-of-bounds (OOB) challenge is pending. The client must poll until the server returns success result.

📘

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

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

To login without any protocol select API only protocol of authentication and click on continue.

The user is navigated successfully to the user profile page and is logged in.