SailPoint IdentityIQ connector for EPM-UL (BIUL)

This guide covers the steps to configure the SailPoint IdentityIQ Connector for EPM-UL (BIUL).

Overview

BeyondInsight for Unix & Linux (BIUL) must be configured with Endpoint Privilege Management for Unix and Linux (EPM-UL). This integration allows SailPoint IdentityIQ (IdentityIQ) to provision access for BIUL users and add/remove roles.

Account Creation is triggered by Add Entitlement for a User without a BIUL account.

Create and configure web services application

To create a new web services application:

1. As an Administrator, log in to IdentityIQ and navigate to Applications.
2. Click Add New Application.
3. Under Details:
   1. For Name, enter BeyondTrust Unix & Linux.
   2. For Owner, select Admin (or another user).
   3. For Application Type, select Web Services.
4. Click Save.

Under Configuration:

1. Select Settings, and then provide a Base URL.
2. For Authentication Method, select No / Custom Authentication.
3. Set the Schema Attribute for Account Enable status to active.
4. At the bottom of the screen, click Save.

Next, you must add and configure operations.

Add and configure operations

First, you must add and configure Authentication and Test Connection operations. You must also successfully test the connection before moving on to the creation of other operations.

Authentication

To create an Authentication operation:

1. Click the Add Operation button, and for the Operation type, select Custom Authentication.
2. Enter a Name for this operation.
3. At the right of the Custom Authentication operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, configure the Authentication URL to match your instance of BIUL, and set the Method to POST.

Header

1. Select Header.
2. At the far right, click Add Row, for each entry you need to add.
3. Configure Keys for Accept and Content-Type, and set the value to application/json for both.

Body

1. Select Body.
2. Ensure the Raw option is selected.
3. Configure Body with username and use $application.password_CA$ for the password value, as written below.

{"domain":"","dsDomain":"","dsID":0,"password":"$application.password_CA$","username":"admin"}

Response

1. Select Response. You must capture and save the access token.
2. For the Response Attribute Mapping:
   1. Set the Response Attribute Key to accesstoken_CA.
   2. Set the Response Attribute Value Path to $.token.
3. Under XPath Namespace Mapping, set the Successful Response Code to 200.
4. Click Save.

Use /debug for encrypted keys and password

We use an encrypted attribute to store the password.

ℹ️

Note

For more information, see https://documentation.sailpoint.com/connectors/identityiq/webservices/help/integrating_webservices/iiq_config_for_no_custom_authentication.html.

Access the /debug interface, and find your Application source.

ℹ️

Note

Access the /debug interface by modifying the URL in the browser manually. For example, if the Url is https://myServerName:8443/identityiq/home, replace /identityiq/home by /debug.

Modify the list of encrypted keys, as written below.

<entry key="encrypted" value="accesstoken,refresh_token,oauth_token_info,client_secret,private_key,private_key_password,clientCertificate,clientKeySpec,resourceOwnerPassword,custom_auth_token_info,password_CA"/>

1. You also must add the value for key(password), as written below.
2. Click Save.
3. Close the /debug interface.

<entry key="password_CA" value="Clear_Text_Value"/>

Back in the SailPoint IdentityIQ interface, click Save.

After you save the application, the clear text value for password is replaced with encrypted value.

Test connection

To create a Test Connection operation:

1. Click Add Operation, and for the Operation type, select Test Connection.
2. Enter a Name for this operation.
3. At the right of the Test Connection operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to generic_users endpoint, and set the Method to GET.

Header

1. Select Header.
2. Set the following Keys and Values:
   1. An Authorization key, with a value of Bearer $application.accesstoken_CA$.
   2. An Accept key, with a value of application/json.

Response

1. Select Response.

2. Under XPath Namespace Mapping, set the Successful Response Code to 200.

3. Click Save.

So far, your application should look like this.

1. At the bottom left, click Test Connection, and look for a Test Successful response.
2. Click Save.

Connector operations

Next, configure the following Connector Operations.

• Account aggregation
• Group Aggregation
• Create Account
• Add Entitlement
• Remove Entitlement
• Disable Account-1
• Disable Account-2
• Enable Account-1
• Enable Account-2
• Change Password
• Unlock Account
• Delete Account

Account aggregation

To create an Account Aggregation operation:

1. Click Add Operation, and for the Operation type, select Account Aggregation.
2. Enter a Name for this operation.
3. At the right of the Account Aggregation operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to generic_users endpoint, and set the Method to GET.

Header

1. Select Header.
2. At the right of the Header section, click Add Row, and set the following Keys and Values:
   1. An Authorization key, with a value of Bearer $application.accesstoken_CA$.
   2. An Accept key, with a value of application/json.

Response

1. Select Response.
2. Configure the Response Attribute Mappings by clicking the Response Attribute Mapping Add Row button, and setting the following Schema Attributes and Attribute Paths.
   • firstname - firstname
   • created - created
   • roles - roles[*].rolename
   • active - active
   • admin - admin
   • cn - cn
   • requiresGroup - requiresGroup
   • lastname - lastname
   • path - path
   • externalApiID - externalApiID
   • name - name
   • guid - guid
   • remoteUserID - remoteUserID
   • userType - userType
   • localUserID - localUserID
   • updated - updated
   • email - email
   • username - username
3. Click Save.

Group aggregation

To create a Group Aggregation operation:

1. Click Add Operation, and for the Operation type, select Group Aggregation.
2. Enter a Name for this operation.
3. At the right of the Group Aggregation operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v1/auth/roles endpoint, and set the Method to GET.

Header

1. Select Header.
2. At the right of the Header section, click Add Row, and set the following Keys and Values:
   1. An Authorization key, with a value of Bearer $application.accesstoken_CA$.
   2. An Accept key, with a value of application/json.

Response

1. Select Response.

2. At the right of Response Attribute Mapping, click Add Row.

   1. Set the Schema Attribute to rolename.
   2. Set the Attribute Path to rolename.

3. Under XPath Namespace Mapping, set the Successful Response Code to 200.

4. Click Save.

Create account

To create a Create Account operation:

1. Click Add Operation, and for the Operation type, select Create Account.
2. Enter a Name for this operation.
3. At the right of the Create Account operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v1/users endpoint, and set the Method to POST.

Header

1. Select Header.
2. At the right of Header, click Add Row to add each of the following Keys and Values:
   1. For Authorization, set the value as Bearer $application.accesstoken_CA$.
   2. For Content-type, set the value as application/json.
   3. For Accept, set the value as application/json.

Body

1. Select Body.
2. Ensure the Raw option is selected.
3. Configure Body using the text as written below.

{
 "active": $plan.active$,
 "email": "$plan.email$",
 "firstname": "$plan.firstname$",
 "lastname": "$plan.lastname$",
 "password": "$plan.password$",
 "passwordConfirm": "$plan.password$",
 "username": "$plan.username$"
}

Response

1. Select Response.
2. Configure the Response Attribute Mappings by clicking the Response Attribute Mapping Add Row button, and setting the following Schema Attributes and Attribute Paths.
   • firstname - firstname
   • roles - roles[*].rolename
   • active - active
   • admin - admin
   • remoteUserID - remoteUserID
   • localUserID - localUserID
   • email - email
   • lastname - lastname
   • username - username
3. UnderXPath Namespace Mapping, set the Successful Response Code to 2**.
4. Click Save.

Add entitlement

To create an Add Entitlement operation:

1. Click Add Operation, and for the Operation type, select Add Entitlement.
2. Enter a Name for this operation.
3. At the right of the Add Entitlement operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v1/users/$plan.nativeIdentity$/roles/$plan.roles$ endpoint, and set the Method to PUT.

Header

1. Select Header.
2. At the right of Header, click Add Row to add each of the following Keys and Values:
   1. For Authorization, set the value as Bearer $application.accesstoken_CA$.
   2. For Accept, set the value as application/json.

Response

1. Select Response.
2.  Configure the Response Attribute Mappings by clicking the Response Attribute Mapping Add Row button, and setting the following Schema Attributes and Attribute Paths.
   • firstname - firstname
   • roles - roles[*].rolename
   • active - active
   • admin - admin
   • remoteUserID - remoteUserID
   • localUserID - localUserID
   • email - email
   • lastname - lastname
   • username - username
3. UnderXPath Namespace Mapping, set the Successful Response Code to 2**.
4. Click Save.

Remove entitlement

To create a Remove Entitlement operation:

1. Click Add Operation, and for the Operation type, select Remove Entitlement.
2. Enter a Name for this operation.
3. At the right of the Remove Entitlement operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v1/users/$plan.nativeIdentity$/roles/$plan.roles$ endpoint, and set the Method to DELETE.

Header

1. Select Header.
2. At the right of Header, click Add Row to add each of the following Keys and Values:
   1. For Authorization, set the value as Bearer $application.accesstoken_CA$.
   2. For Accept, set the value as application/json.

Response

1. Select Response.
2. Configure the Response Attribute Mappings by clicking the Response Attribute Mapping Add Row button, and setting the following Schema Attributes and Attribute Paths.
   • firstname - firstname
   • roles - roles[*].rolename
   • active - active
   • admin - admin
   • remoteUserID - remoteUserID
   • localUserID - localUserID
   • email - email
   • lastname - lastname
   • username - username
3. UnderXPath Namespace Mapping, set the Successful Response Code to 2**.
4. Click Save.

Disable account-1

To create a Disable Account-1 operation:

1. Click Add Operation, and for the Operation type, select Disable Account-1.
2. Enter a Name for this operation.
3. At the right of the Disable Account-1 operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v1/users/$plan.nativeIdentity$ endpoint, and set the Method to GET.

Header

1. Select Header.
2. At the right of Header, click Add Row to add each of the following Keys and Values:
   1. For Authorization, set the value as Bearer $application.accesstoken_CA$.
   2. For Accept, set the value as application/json.

Response

1. Select Response.
2. Configure the Response Attribute Mappings by clicking the Response Attribute Mapping Add Row button, and setting the following Schema Attributes and Attribute Paths.
   • firstname - firstname
   • roles - roles[*].rolename
   • active - active
   • admin - admin
   • remoteUserID - remoteUserID
   • localUserID - localUserID
   • email - email
   • lastname - lastname
   • username - username
3. UnderXPath Namespace Mapping, set the Successful Response Code to 200.
4. Click Save.

Disable account-2

To create a Disable Account-2 operation:

1. Click Add Operation, and for the Operation type, select Disable Account-2.
2. Enter a Name for this operation.
3. At the right of the Disable Account-2 operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v1/users/$plan.nativeIdentity$ endpoint, and set the Method to PUT.

Header

1. Select Header.
2. At the right of Header, click Add Row to add each of the following Keys and Values:
   1. For Authorization, set the value as Bearer $application.accesstoken_CA$.
   2. For Accept, set the value as application/json.

Body

1. Select Body.
2. Ensure the Raw option is selected.
3. Configure Body using the text as written below.

{
 "username": "$response.username$",
 "email": "$response.email$",
 "firstname": "$response.firstname$",
 "lastname": "$response.lastname$",
 "active": false
}

Response

1. Select Response.
2. Configure the Response Attribute Mappings by clicking the Response Attribute Mapping Add Row button, and setting the following Schema Attributes and Attribute Paths.
   • firstname - firstname
   • roles - roles[*].rolename
   • active - active
   • admin - admin
   • remoteUserID - remoteUserID
   • localUserID - localUserID
   • email - email
   • lastname - lastname
   • username - username
3. UnderXPath Namespace Mapping, set the Successful Response Code to 200.
4. Click Save.

Enable account-1

To create an Enable Account-1 operation:

1. Click Add Operation, and for the Operation type, select Enable Account-1.
2. Enter a Name for this operation.
3. At the right of the Enable Account-1 operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v1/users/$plan.nativeIdentity$ endpoint, and set the Method to GET.

Header

1. Select Header.
2. At the right of Header, click Add Row to add each of the following Keys and Values:
   1. For Authorization, set the value as Bearer $application.accesstoken_CA$.
   2. For Accept, set the value as application/json.

Response

1. Select Response.
2. Configure the Response Attribute Mappings by clicking the Response Attribute Mapping Add Row button, and setting the following Schema Attributes and Attribute Paths.
   • firstname - firstname
   • roles - roles[*].rolename
   • active - active
   • admin - admin
   • remoteUserID - remoteUserID
   • localUserID - localUserID
   • email - email
   • lastname - lastname
   • username - username
3. UnderXPath Namespace Mapping, set the Successful Response Code to 200.
4. Click Save.

Enable account-2

To create an Enable Account-2 operation:

1. Click Add Operation, and for the Operation type, select Enable Account-2.
2. Enter a Name for this operation.
3. At the right of the Enable Account-2 operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v1/users/$plan.nativeIdentity$ endpoint, and set the Method to PUT.

Header

1. Select Header.
2. At the right of Header, click Add Row to add each of the following Keys and Values:
   1. For Authorization, set the value as Bearer $application.accesstoken_CA$.
   2. For Accept, set the value as application/json.

Body

1. Select Body.
2. Ensure the Raw option is selected.
3. Configure Body using the text as written below.

{
 "username": "$response.username$",
 "email": "$response.email$",
 "firstname": "$response.firstname$",
 "lastname": "$response.lastname$",
 "active": true
}

Response

1. Select Response.
2. Configure the Response Attribute Mappings by clicking the Response Attribute Mapping Add Row button, and setting the following Schema Attributes and Attribute Paths.
   • firstname - firstname
   • roles - roles[*].rolename
   • active - active
   • admin - admin
   • remoteUserID - remoteUserID
   • localUserID - localUserID
   • email - email
   • lastname - lastname
   • username - username
3. UnderXPath Namespace Mapping, set the Successful Response Code to 200.
4. Click Save.

Change password

To create a Change Password operation:

1. Click Add Operation, and for the Operation type, select Change Password.
2. Enter a Name for this operation.
3. At the right of the Change Password operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v1/users/$plan.nativeIdentity$/password endpoint, and set the Method to PUT.

Header

1. Select Header.
2. At the right of Header, click Add Row to add each of the following Keys and Values:
   1. For Authorization, set the value as Bearer $application.accesstoken_CA$.
   2. For Accept, set the value as application/json.

Body

1. Select Body.
2. Ensure the Raw option is selected.
3. Configure Body using the text as written below.

{"new_password":"$plan.password$"}

Response

1. Select Response.
2. Configure the Response Attribute Mappings by clicking the Response Attribute Mapping Add Row button, and setting the following Schema Attributes and Attribute Paths.
   • firstname - firstname
   • roles - roles[*].rolename
   • active - active
   • admin - admin
   • remoteUserID - remoteUserID
   • localUserID - localUserID
   • email - email
   • lastname - lastname
   • username - username
3. UnderXPath Namespace Mapping, set the Successful Response Code to 200.
4. Click Save.

Unlock account

To create an Unlock Account operation:

1. Click Add Operation, and for the Operation type, select Unlock Account.
2. Enter a Name for this operation.
3. At the right of the Unlock Account operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v3/users/$plan.nativeIdentity$/lock endpoint, and set the Method to DELETE.

Header

1. Select Header.
2. At the right of Header, click Add Row to add each of the following Keys and Values:
   1. For Authorization, set the value as Bearer $application.accesstoken_CA$.
   2. For Accept, set the value as application/json.

Response

1. Select Response.
2. Configure the Response Attribute Mappings by clicking the Response Attribute Mapping Add Row button, and setting the following Schema Attributes and Attribute Paths.
   • firstname - firstname
   • roles - roles[*].rolename
   • active - active
   • admin - admin
   • remoteUserID - remoteUserID
   • localUserID - localUserID
   • email - email
   • lastname - lastname
   • username - username
3. UnderXPath Namespace Mapping, set the Successful Response Code to 200.
4. Click Save.

Delete account

To create a Delete Account operation:

1. Click Add Operation, and for the Operation type, select Delete Account.
2. Enter a Name for this operation.
3. At the right of the Delete Account operation row, in the Actions column, click the Edit button (pencil).
4. Under Connection Settings, set the Context URL to /v1/users/$plan.nativeIdentity$/lock endpoint, and set the Method to DELETE.

Header

1. Select Header.
2. At the right of Header, click Add Row to add each of the following Keys and Values:
   1. For Authorization, set the value as Bearer $application.accesstoken_CA$.
   2. For Accept, set the value as application/json.

Response

1. Select Response.
2. UnderXPath Namespace Mapping, set the Successful Response Code to 2**.
3. Click Save.

Now that we have all Connector Operations configured, let’s configure the Schema.

Account schema

To configure the Account Schema:

1. Under Configuration, select Schema, and then click Add Object Type.
2. For the object type, select Account.

Details

Complete the Details section as follows:

1. For Native Object Type, enter user.
2. For Display Attribute, enter username.
3. For Identity Attribute, enter localUserID.

Attributes

Complete the Attributes section as follows:

1. Click Add New Schema Attribute and enter Name, Description, Type, and Properties (if any) for each:

2. LocalUserID, LocalUserID, string

3. username, username, string

4. name, name, string

5. remoteUserID, remoteUserID, string

6. active, active, boolean

7. created, created, string

8. updated, updated, string

9. email, email, string

10. firstname, firstname, string

11. lastname, lastname, string

12. admin, admin, boolean

13. roles, roles, group, Managed, Entitlement, Multi-Valued

14. externalApiID, externalApiID, string

15. guid, guid, string

16. path, path, string

17. cn, cn, string

18. userType, userType, string

19. requiresGroup, requiresGroup, boolean

Group schema

To configure the Group Schema:

1. Under Configuration, select Schema, and then click Add Object Type.
2. For the object type, select Group.

Details

Complete the Details section as follows:

1. For Native Object Type, enter group.
2. For Display Attribute, enter rolename.
3. For Identity Attribute, enter rolename.

Attributes

Complete the Attributes section as follows:

1. Click Add New Schema Attribute and enter Name, Description, Type, and Properties (if any) for each:

2. rolename, rolename, string

3. Click Save.

Provisioning policy

You also need a provisioning policy for account creation.

To configure the provisioning policy:

1. Under Configuration, select Provisioning Policies, and then click Add Object Type.
2. For the object type, select Account.

Account

1. To add a new policy, click Add Provisioning Policy.
2. For Name, enter Create Account.
3. For Description, enter Create Account.

User name

1. Click Add Section, and enter User Name.

2. Under the Edit Options > Settings, enter the following:

3. Name: username

4. Display Name: User Name

5. Type: String

6. Under Edit Options > Value Settings, enter the following:

7. Value: Script

8. Type in the script text as follows:

return identity.getAttribute("firstname")+'.'+identity.getAttribute("lastname");

9. Allowed Values: None

Email

1. Click Add Section, and enter Email.

2. Under the Edit Options > Settings, enter the following:

3. Name: email

4. Display Name: email

5. Type: String

6. Under Edit Options > Value Settings, enter the following:

7. Value: Script

8. Type in the script text as follows:

return identity.getAttribute("email");

9. Allowed Values: None

Firstname

1. Click Add Section, and enter firstname.

2. Under the Edit Options > Settings, enter the following:

3. Name: firstname

4. Display Name: firstname

5. Type: String

6. Under Edit Options > Value Settings, enter the following:

7. Value: Script

8. Type in the script text as follows:

return identity.getAttribute("firstname");

9. Allowed Values: None

Lastname

1. Click Add Section, and enter lastname.

2. Under the Edit Options > Settings, enter the following:

3. Name: lastname

4. Display Name: lastname

5. Type: String

6. Under Edit Options > Value Settings, enter the following:

7. Value: Script

8. Type in the script text as follows:

return identity.getAttribute("lastname");

9. Allowed Values: None

Password

For Password, you can start with a static value, then later configure a generated value.

1. Click Add Section, and enter Password.

2. Under the Edit Options > Settings, enter the following:

3. Name: password

4. Display Name: password

5. Type: String

6. Under Edit Options > Value Settings, enter the following:

7. Value: Value

8. Type in a static value such as [SomeSecurePassword] (example only).

9. Allowed Values: None

Active

1. Click Add Section, and enter active.

2. Under the Edit Options > Settings, enter the following:

3. Name: active

4. Display Name: active

5. Type: String

6. Under Edit Options > Value Settings, enter the following:

7. Value: Value, and enter true as value.

8. Allowed Values: None

9. At the top right, click Save.

Now you should have a fully configured application. You must create Setup tasks for Aggregating Accounts and Aggregating Groups and execute those tasks.

Accounts created and active

After aggregation, under the Application, you can now see the Accounts.

Requestable BIUL roles

Under Applications > Entitlement Catalog, you can see the Requestable BIUL Roles.