Configure an Identity Verification workflow

This topic describes how to configure a connection between CyberArk Identity and your Identity Verification (IDV) solution (a third-party identity proofing solution). Identity Verification solutions use a process that compares a unique set of data points for an individual , such as email addresses, phone numbers, and addresses, to an IDV database of possible identity matches to verify that the individual initiating an application sign up process is a real person and is not creating a false Identity.

IDV solutions can be integrated into the CyberArk Identity user sign-up workflow to recognize high-risk users and take appropriate actions to prevent identity fraud. For instance, if a high-risk user is identified, you can put an approval process in place that is generated before that user can access the requested application. Rules for the sign up process are configured in the Identity Verification script editor to control the process based on your specific Identity Verification solution. The sign-up process allows users to sign up with any external application that integrates with CyberArk Identity .

The Identity Verification script editor allows you to configure standard and additional attributes for creating users using the signup API. For the signup API to accept additional attributes for a user, the additional attributes must already be created in the Identity Administration portal. These are then set up through the addAttributeInResponse method in the Identity Verification script. For more information, see Add custom user attributes.

Contact your CyberArk Account Representative to enable this feature.

Configure Identity Verification in the Identity Administration portal

This section covers the general steps required to configure Identity Verification settings in the Identity Administration portal. If your IDV solution requires additional steps or set up requirements specific to your IDV solution, see the specific topic for the supported IDV solution. For instance, for Ekata implementations, also see Integrate with Ekata for Identity Verification.

The following steps are required in order to configure the CyberArk Identity Verification process:

Step 1: Configure initial connection settings to a third-party IDV vendor in the Identity Administration portal.

  1. In the Identity Administration portal, select Settings > Users > Identity Verification.

    The following page is displayed:

  2. Select your IDV solution from the drop-down menu to configure the connection.

    A list of supported third-party IDV vendors are available in the drop-down menu. Depending on your selection additional configuration settings may be required. For Ekata integrations, refer to Integrate with Ekata for Identity Verification.

  3. Click Next once you have completed the steps above.

Step 2: Configure the Identity Verification Script for user sign up.

The script editor defines the operations performed once a sign-up request is processed. Modify the response to the signup API in the script editor to control actions performed in response to the sign-up request. User creation and sign-up approvals are generated based on the rules you configure in the script.

For more information regarding Identity Verification script objects and methods, see Modify the Identity Verification script Objects and Methods.

Step 3: Configure the Manual Sign-up Approvers List.

The Manual Sign-up Approvers List is used to add users or roles to approve user sign-up requests. You can select users, roles, or a combination of both, as approvers. If approval is required (for example, the user requesting to sign up is identified as a high risk user), then a review approval email is sent to all the selected approvers. Note the following:

  • Approvers should be in a role with the User Management Administrative Right.

  • Approval of a user sign-up request is generated based on the requirements configured in the Identity Verification script (using the createUserForSignupApproval method).

  • If only one user is added, approval from only the selected user is sufficient.

  • If a role is added, then approval of any user in that role is sufficient.

  • If multiple users and roles are added, then approval is required from all users and at least one user in each role.

  • The approval is done based on the order specified and one at a time.

To add approvers:

  1. Click Add to display the Add Members dialog box.

  2. Start typing the name of the user or role you want to add as an approver and once displayed, click Add.

    You can add multiple approvers.

  3. Click Save once you have added approvers.

Step 4: Configure Sign-up Email Settings.

The purpose of this step is to configure the email that is sent to users when they request access to a new application integrated with CyberArk Identity. For more information on email templates available for Identity Verification workflow and modifying the content in the email message, see Customize email message contents.

To configure sign-up email settings:

  1. In Name of the app, enter the application name to use in the sign-up user email templates.

  2. In URL of the app, enter the URL of the application used in the invite email. Once the sign-up process is successful the user is redirected to the URL.

  3. Click Save.

Step 5: Review your settings and save.

Review your settings to make sure that you have configured everything covered in this procedure, then click Save.

This is the end of the required IDV integration configuration. For information on additional topics, see:

Modify the Identity Verification script Objects and Methods

The following objects and methods can be used for each sign up response in the Identity Verification script. These objects provide information that the Identity Verification script can read and act on. A user is created once all the rules in the Identity Verification script are met and the createUser() method is successfully executed.

Identity Verification script objects

Object

Function

Corresponding field
that can be accessed

Example

SignupRequest

This object can be used to access the sign-up request and pass the information to IDV solution or it can be used to create users, or generate sign-up approvals.

The request body and the request headers that are sent as part of the signup API can be utilized using this object.

var signupRequestbody = SignupRequest.Body var

signupRequestHeader = SignupRequest.Header

SignupRequest.Body

This object can be used to access the signup request body and pass the information to the IDV solution or it can be used to create users, or generate sign-up approvals.

All the user standard and custom attributes passed (as a request of the signup API) .

var name = SignupRequest.Body.Name var state_code = SignupRequest.Body. state_code (Where state_code is a custom attribute)

 

SignupRequest.Headers

This object can be used to access the signup request headers and pass the information to the IDV solution or it can be used to create users, or generate sign-up approvals.

All the headers that are passed as a request of signup API. For example, IPAddress.

SignUpRequest.Headers.IPAddress

Identity Verification script methods

Method

Function

Input parameters

Example

Sample response

addAttributeInResponse (String, Object)

This method is used to add attributes to the signup response (either to the user attributes, the IDVResponse object, or any additional attributes are returned using this method).

  • String - This string is the JSON field name in the signup API response.

  • Object - The object to return as part of signup API response.

  • addAttributeInResponse ("state_code", SignupRequest.Body.state_code) - (state_code is an additional attribute for the user)

  • addAttributeInResponse ("User Email Address", SignupRequest.Body.Mail)

  • addAttributeInResponse ("Network risk score", IDVResponse["identity_risk_score"]) - (IDVResponse is the response returned by the IDV solution)

Signup API response based on the example:

"Result": { "UserId": "user uuid", "IntegrationResult": { "IsManualApprovalTriggered": false, "IsIntegrationResponseReceived": false, "ErrorMessage": null, "IntegrationResponse": { "state_code": "state_code", "User Email Addres" : "Mail", "identity_risk_score" : 200 } } }

createWebRequest(string, string, number, object)

This method is used to create an HTTP web request and returns an HTTP response.

  • requestType - HTTP request type (GET, POST)

  • URI - URI of the API resource

  • timeout in seconds- Set this to configure the time out value to specify within how many seconds the request to the API should time out.

  • payload - the request payload.

IDVResponse = createWebRequest("GET", "https://api.ekata.com/1.0/account_opening?", 10)

Sample response of createWebRequest based on the example:

{ "Success": true, "Result": "EkataResponse", "Error": null, "HttpStatusCode": 200 }

getUUID()

This method generates a random string that is used as a unique identifier.

 N/A

uuid = getUUID()

The uuid variable contains a randomly generated string. For example: 95285489a80b059a7f0be7147ba211f

createUser(Object)

This method is used to create the user.

Pass SignupRequest.Body to this method.

user_uuid = createUser(SignupRequest.Body)

The UUID of the created user.

createUserForSignupApproval(Object)

See Identity Verification workflow for user approval for more information.

This method is used to create the user and then generate the sign-up approval process for that user.

Pass SignupRequest.Body to this method.

user_uuid = createUserForSignupApproval(SignupRequest.Body)

  • The UUID of the user is returned if the sign up is approved.

  • None is returned if the sign up is rejected.

Identity Verification workflow for user approval

When a user signs up to access an application and authenticate via CyberArk Identity, a request is sent to the IDV solution to determine the risk score for the user. If the risk score is above a specified threshold, then an approval process is activated before the user is added to CyberArk Identity. The approval process is generated based on the parameters you configure in the Identity Verification script. Based on the script configuration, one of the following workflows is implemented:

User Sign-up Approval Workflow
Not Required

If the user risk assessment is low (determined in the Identity Verification script configuration), a user can sign up to access an application without going through the approval process. In this case, an email is sent inviting the user to access CyberArk Identity. The user is created in the Identity Administration portal and the user status is changed to Invited.

Required

If the user risk assessment is high (determined in the Identity Verification script configuration), an approval process is generated for the high-risk user. If the approval process is required, then:

  • A user is created and visible in the Identity Administration portal Users page, but the user status is Locked.

  • The user is sent an email indicating that approval is pending.

  • The approvers are sent an email stating approval review is pending.

View sign-up requests

Designated approvers for sign-up requests can view request details in any of the following ways:

  • Click View Request in the email notification

  • Select the User Portal > Requests tab

  • Select Identity Administration portal > Core Services > Requests and then click the request

The Request Details page includes the following:

Detail

Description

Posted

Displays the date and time of the most recent activity for the request.

Description

Provides a brief summary of the request including the sign-up approval for the specified user name.

Requestor

Displays the name of the user that submitted the request.

Requestor’s Reason

Displays the reason why the request is being made. For example, user identity risk is high.

Approver

Displays the user(s) or role(s) designated for approving requests. If more than one approver is designated, then a list of approvers is indicated in the order added in the approvers lists page (for example, Approver 1, Approver 2 etc. is listed) .

Finished

The date and time the request was approved.

Status

Displays the current status of the request as Pending, Approved, Rejected, or Failed.

Respond to sign-up requests

In cases where more than one approver is configured, the request is approved or rejected and the status is changed only after all the designated approvers have responded. From the Actions menu on the Requests page you can:

Action Description
Approve requests

When a request is approved, the user status changes to Invited in the Identity Administration portal. An email invite stating that the request is approved with the external login URL is then sent to the user.
Reject requests

If a request is rejected, the designated approver is prompted to enter a reason for rejecting the request. Once the reason is submitted, the request is rejected, and the status of the request is changed to rejected. The user is deleted and no longer visible in the Identity Administration portal. An email message is sent to the user stating that the request is rejected.
Show Identity Verification Details Displays the Identity Verification Details page.
Delete

Removes the selected request from the Identity Administration portal.

To respond to sign-up requests

  1. Select Identity Administration portal > Core Services > Requests and then click the specific request.

  2. Click the Approve or Reject buttons from the main page or click the Actions menu and then select Approve or Reject.

After you respond to the request, the Requests tab is also updated with the latest activity and email is sent to the requester as notification of your response to the request.

View Identity Verification details

The User account page includes a tab for Identity Verification Details that provides the IDV API request and response. The Identity Verification Details page contains the following (the example below is for the Ekata solution):

Field

Description
Identity Verification Solution This is the solution selected in the Configure initial connection settings to a third-party IDV vendor in the Identity Administration portal. This is currently configured as Ekata.
User Sign-up Status The status can be: Sign up complete or Approval Pending.
Request IDV solution request details.
Response IDV solution response details.