You are on page 1of 11

How do I load user data from a database into

IdentityNow through JDBC?

Overview
If you want to load user data, you can create a direct connect source for JDBC and configure a SQL query in it
to load the data you want. To manage that data, either create an identity profile based on the source or verify
that the accounts you load are correlated to an existing identity.

If you want to load the database user accounts, use a direct connection to the database itself.

CAUTION: JDBC sources use the default correlation configuration which uses the Display Name attribute on
the identity to correlate with the displayName attribute on the source.

• Overview on page 1
• Source Features on page 1
• Prerequisites on page 2
• System Requirements on page 2
• Permissions on page 2
• Source Configuration Fields on page 2
• Accounts on page 4
• Discovering the Schema on page 4
• Loading Accounts on page 5
• Loading Entitlements on page 5
• Prerequisites on page 5
• Loading a Single Account or Entitlement on page 5
• Data Merging Support in Aggregation on page 6
• Delta Aggregation on page 7
• Aggregation Out of Memory Error and Resolution on page 8
• Provisioning on page 9
• • Prerequisites on page 9
• Create Profile / Provisioning Policy on page 10
• Password Management on page 10
• • Prerequisites on page 10
• Password Management on the Source on page 10
• Troubleshooting on page 11

Source Features

The JDBC source supports the following features:


• Accounts

1
How do I load user data from a database into IdentityNow through JDBC?

• Password Management(*)
• Provisioning(*)

NOTE: Features marked with an asterisk (*) must be purchased and activated. This is an advanced connector
for entitlements, provisioning, and password management. Please open a support ticket for assistance.

Prerequisites
• Configure at least one virtual appliance cluster and successfully test the connection.
• Identify or create a service account on the database you will access through JDBC.

System Requirements

JDBC is supported to access databases having JDBC Driver. For version requirements, see the version
requirements for direct database connections.
• IBM DB2 for Windows
• Oracle DB
• Sybase
• Microsoft SQL Sever
• MySQL

Back to Top on page

Permissions
The JDBC application will use the database user context to support the aggregation and other provisioning
operations. The database user mentioned in the application configuration must have appropriate rights to fetch
and set data related to the entities and attributes mentioned in the JDBC SQL query that is, Account, Group,
Entitlements and so on.

Source Configuration Fields


The JDBC connector uses the following attributes.

Attribute Description

2
How do I load user data from a database into IdentityNow through JDBC?

Used For
Accounts Creates accounts for identities based on this source.
In combination with Password Management, allows
you to select the source in the Accounts Created By
panel of an app's config page.
Password Management If this feature is enabled for your site, allows users to
change the password for the source and any related
directory password apps from the IdentityNow
Launchpad.
Provisioning If this feature is enabled for your site, allows users
to select associated app access profiles and source
access profiles from the Provisioning tab of identity
profiles.
Connection Credentials
User User (service account) making the connection to the
database
Password Password of the User
JDBC
JDBC URL URL to the database, in the form jdbc:dbtype://
ipaddress/databasename. Example -
jdbc:oracle:thin:@172.16.23.155:1521:orcl
JDBC Driver Class The driver class. Example -
oracle.jdbc.driver.OracleDriver
Test Connnection Query Settings
Test Connection SQL Query Enter a simple query to use to test the connection to
the database.
Account Query Settings
Account SQL Query Enter a query to use to load accounts.
Group Query Settings
Group SQL Query Enter a query to use to load groups. Groups are
used for entitlements.
Single Account Query Settings
Single Account SQL Query Enter a query to use to load a single account.
Single Group Query Settings
Single Group SQL Query Enter a query to use to load a single group.
Additional Settings for SQL Queries
Execute Stored Procedure Select this checkbox to execute a stored procedure
on the database.
Advanced Options

3
How do I load user data from a database into IdentityNow through JDBC?

Advanced Option Check to show the Delta Aggregation Mode and


Enable Account Delta Aggregation settings.
Delta Aggregation Mode Check to set the mode for loading in the Import
Data tab. When checked, loading accounts and
entitlements loads only those that have changed,
rather than all accounts or all entitlements. For more
details, see Delta Aggregation.
Enable Account Delta Aggregation Check to allow delta aggregation on accounts.
Custom Connector Files
Upload Click Upload to choose the JDBC driver for your
database. The current file and upload history are
listed below the button.
Back to Top on page

NOTE: If the data for a single object spans multiple lines, you must merge the data. When merging, you must
have the ORDER BY clause in your Account SQL Query statement to prevent the out of order errors.

After setting the attributes, click Test Connection. If the test is successful, you can then load account
information.

Accounts
After you create and test the connection, you can load accounts or entitlements.

You must first discover the schema and identify attributes to use for required identity data before loading
accounts or entitlements.

Best Practice: Test the SQL queries outside of IdentityNow to make sure you get the results you expect.

Discovering the Schema

You must discover the schema and identify the attributes to use for the required identity data before doing
anything else.
1. In the Config tab, enter the Account SQL Query to use to load account data.
2. Click the Import Data tab.
3. Click Account Schema in the left menu.
4. Click Discover. The Account SQL Query is executed and the discovered attribute names are presented.
5. Identify the attributes to be used for Name and Account ID. Mark them in the Account ID column.

4
How do I load user data from a database into IdentityNow through JDBC?

CAUTION: Ifthis source is going to be used as an authoritative source for an


identity profile, the Account Name and Account ID both need to be unique. If
not, source accounts could correlate to the first Identity that includes that ID/
Name instead of creating an additional Identity.

Loading Accounts

After you have discovered the schema and identified required attributes, you can load accounts.
1. In the Config tab, enter the query to use in Account SQL Query. Leave other query settings blank.
2. In the Import Data tab, start a Manual Aggregation. Click Start.
3. Check the results in the Aggregation Activity log.

If the results do not seem right, try running the query as a database user and compare the number of rows
returned by the query.

NOTE: While aggregating the accounts, you must have the appropriate details of account query and group
SQL queries for the test connection SQL query so as to prevent aggregation failure while test connection is
successful.
Back to Top on page

Loading Entitlements

Prerequisites

Loading entitlements requires a Services engagement to help you set up IdentityNow and your database.

After you have discovered the schema and identified required attributes, you can load accounts.
1. In the Config tab, enter the query to use in Group SQL Query. Leave other query settings blank.
2. In the Import Data tab, start a Manual Aggregation. Click Start.
3. Check the results in the Aggregation Activity log.

If the results do not seem right, try running the query as a database user and compare the number of rows
returned by the query.

Loading a Single Account or Entitlement

Loading a single account is helpful when you want to check the status of an account or entitlement.

5
How do I load user data from a database into IdentityNow through JDBC?

1. In the Config tab, enter the query to use in Single Account SQL Query or Single Group SQL Query.
Leave other query settings blank.
2. In the Import Data tab, start a Manual Aggregation. Click Start.
3. Check the results in the Aggregation Activity log.

If the results do not seem right, try running the query as a database user and compare the number of rows
returned by the query.

Data Merging Support in Aggregation

For the JDBC source, if the data for a single account spans multiple rows of database table, you can merge the
data for successful aggregation.
For example, if you want to merge data of the attributes such as email and phone, you can use the IdentityNow
REST API:

POST <url>/api/source/update/<sourceID>

Where:
• <url>: URL for the customer's IdentityNow instance
• <sourceID>: Source ID (number) obtained through the UI

In the body of the POST, set form-data values as follows:


• key: use the key connector_mergeRows
• value: use the value of the key as true

If you want to merge the columns, set form-data values as follows:

• key: use the key connector_indexColumns


• value: the value of this key must be the name of the column or list of columns that you want as index
column for merging.

For example, you can you use value in a format such as: [<IndexKey1>, <IndexKey2>,...<IndexKeyn>]

• key: use the key connector_mergeColumns


• value: the value of this key must be the name of the column or list of columns that you want to merge
with the index column.

For example, you can you use value in a format such as: [<MergeKey1>, <MergeKey2>,...<MergeKeyn>]

6
How do I load user data from a database into IdentityNow through JDBC?

Delta Aggregation

When delta aggregation is enabled, only accounts that have changed since the last aggregation are loaded. A
delta aggregation typically takes less time and fewer system resources than a full aggregation.
1. Perform a full aggregation as described in Loading Accounts.
2. In the Config tab, select the Advanced Settings checkbox.
3. In the Advanced Settings panel, select both Delta Aggregation Mode and Enable Account Delta
Aggregation checkbox.

Back to Top on page


The next time you load accounts, only accounts that have changed in the source database tables will be
loaded.

NOTE: Currently IdentityNow does not support delta aggregation for groups. Open a support ticket for
assistance.

The Database Table containing the delta changes attribute must be provided with the value of table name.
This table must have read and write permissions.

The steps for configuring the JDBC source for delta aggregation in IdentityNow are:

1. Create a table to capture the identities whose attributes, entitlements are modified on the master table for
accounts and the master table for entitlements.

The name of the table you create must be USER_DELTA.

The table must contain two columns such that:

- The first column stores the identity attribute defined in IdentityNow.

-The second column stores the action. The values of the action can be Insert, Update, or Delete.

For example, the SQL to create such a table in Oracle is as follows:


CREATE TABLE USER_DELTA (USER_ID VARCHAR2(20), ACTION VARCHAR2(10));

2. Assign the privileges to read and delete the records from the tables created in Step 1 above to the
connection user whose credentials you entered in the source configuration page within IdentityNow.

3. Create the triggers on the following master tables:


- Account table

- Entitlements table for Account

- Permissions table for Account

7
How do I load user data from a database into IdentityNow through JDBC?

The triggers on the Account table, the Entitlements table for the Account, and the Permissions table for the
Account write the Account Identity attribute in the USER_DELTA table in Step 1 when attributes, entitlements,
or permissions have changed in the master tables.
For example, in Oracle databases the following trigger writes the user IDs in the USER_DELTA table, which
has undergone some modifications, along with the respective action:

CREATE or REPLACE TRIGGER T1


AFTER DELETE OR INSERT OR UPDATE ON USER_MASTER
FOR EACH ROW
BEGIN
IF INSERTING THEN
INSERT INTO USER_DELTA (USER_ID, ACTION)
VALUES (:NEW.USER_ID, 'Insert');
END IF;
IF UPDATING THEN
INSERT INTO USER_DELTA (USER_ID, ACTION)
VALUES (:NEW.USER_ID, 'Update');
END IF;
IF DELETING THEN
INSERT INTO USER_DELTA (USER_ID, ACTION)
VALUES (:OLD.USER_ID, 'Delete');
END IF;
END;
/

4. Configure the JDBC Source and enable delta aggregation. After you finish the delta aggregation the tables
are reset/re-initialized and start capturing changes again.
Back to Top on page
For more information, see How do I configure delta aggregations for my source?

Aggregation Out of Memory Error and Resolution

For the JDBC source if there is very big data for aggregation, there can be an 'out of memory' error.

Possible solutions can be:


• use TYPE_FORWARD_ONLY ResultSet type, or
• increase RAM of the Java heap size (memory) for Java virtual machine for the JDBC drivers that do
not support the TYPE_FORWARD_ONLY ResultSet type

For the JDBC drivers that support the TYPE_FORWARD_ONLY ResultSet type, it ensures the reading of data
in forward direction only which reduces the data caching and results in less memory.

8
How do I load user data from a database into IdentityNow through JDBC?

For the JDBC drivers that support the forward ResultSet type - to add an entry to the application, use the
IdentityNow REST API:

POST <url>/api/source/update/<sourceID>

Where:
• <url>: URL for the customer's IdentityNow instance
• <sourceID>: Source ID (number) obtained through the UI

In the body of the POST, set form-data values as follows:


• Use the following keys with their suggested values:

Keys Values
connector_resultSetFetchSize 1000
connector_statementFetchSize 1000
connector_resultSetType TYPE_FORWARD_ONLY

All JDBC drivers do not support the TYPE_FORWARD_ONLY ResultSet type. In such cases, one of the
options is to increase the RAM of the Java heap size (memory) for Java virtual machine. The steps are:

1. Logon to the Virtual Appliance.


2. Execute the command sudo su
3. Access the file: vi /opt/sailpoint/ccg/bin/startup.sh.
4. Update the java options to enable the axis logs. For example, update the new value as:
JAVA_OPTS="$JAVA_OPTS -Xms256m -Xmx896m -Dsun.lang.ClassLoader.allowArraySyntax=true"
to JAVA_OPTS="$JAVA_OPTS -Xms256m -Xmx<new_value>m -
Dsun.lang.ClassLoader.allowArraySyntax=true"
5. Save the file.
6. Execute the command service ccg restart.
7. Check if the Virtual Appliance is configured properly on IdentityNow.
8. Check if the test connection is working correctly.

Provisioning

Prerequisites

9
How do I load user data from a database into IdentityNow through JDBC?

• Purchase of the Provisioning feature


• Services engagement to implement the feature for your environment

Create Profile / Provisioning Policy

When IdentityNow provisions new accounts to an JDBC direct connect source, it uses the attributes on the
Create Profile page as instructions or a template for what to include in the account. This page is also referred
to as the provisioning policy. You can create profile based on your database having JDBC Driver.

IMPORTANT: This page describes the configuration of the default Create Profile. However, SailPoint
recommends that you work with Services to define a Create Profile specific to your company's needs.

NOTE: JDBC source do not generate out-of-memory errors when processing provisioning requests. The pool
size for BSF tokens in the BSF Manager is changed to optimum level to overcome the out-of-memory issue
without having impact on performance.

Password Management

Prerequisites

• Purchase of the Password Management feature


• Services engagement to implement the feature for your environment

NOTE: After making password management on the source, be aware of the following:
• • The password policy defined in IdentityNow applies to accounts on this source.
• If you change the password for apps connected to this source, the change will automatically be
made to the source itself.

Back to Top on page

Password Management on the Source

The following source configuration is required:


• In the Used For panel, select Password Management.

10
How do I load user data from a database into IdentityNow through JDBC?

Troubleshooting
• Connection getting locked up

By default the JDBC Connector works in pooling connection mode. The connection gets locked up for already
configured application account when password of the account changes dynamically from managed system
without displaying any warning message.

Resolution: Add the following xml in the application.xml file:


<entry key="pool.disablePooling">
<value>
<Boolean>true</Boolean>
</value>
</entry>

• For the JDBC source there is a java.lang.RuntimeException error with the following reason:

java.lang.RuntimeException: sailpoint.connector.ConnectorException: Data out of order exception. Data should


be sorted in ascending order. Last identifier '7' current '15'.

Resolution:To solve, use the IdentityNow REST API:

POST <url>/api/source/update/<sourceID>

Where:
• <url> is the URL for the customer's IdentityNow instance

• <sourceID> is the Source ID (number) obtained through the UI

In the body of the POST, set form-data values as follows:


• key - key name of the entry. Use connector_disableOrderingCheck
• value - the value of the key. Value is: true

Back to Top on page

11

You might also like