--- title: IBM DB2 repository description: This section makes the following assumptions about the DB2 environment. If these assumptions do not match your DB2 environment, adapt the subsequent instructions accordingly. component: pingidm version: 7.3 page_id: pingidm:install-guide:repository-db2 canonical_url: https://docs.pingidentity.com/pingidm/8.1/install-guide/repository-db2.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Installation", "IBM DB2"] superseded_by: https://docs.pingidentity.com/pingidm/8.1/install-guide/repository-db2.html section_ids: db2-kerberos-auth: Kerberos authentication with a DB2 repository --- # IBM DB2 repository This section makes the following assumptions about the DB2 environment. If these assumptions do not match your DB2 environment, adapt the subsequent instructions accordingly. * DB2 is running on the localhost, and is listening on the default port (50000). * The user `db2inst1` is configured as the DB2 instance owner, and has the password `Passw0rd1`. This section assumes that you will use basic username/password authentication. You can also [configure Kerberos authentication with a DB2 repository](#db2-kerberos-auth). Before you start, make sure that the server is stopped. ``` /path/to/openidm/shutdown.sh OpenIDM is not running, not stopping. ``` Configure IDM to use the DB2 repository, as described in the following steps: 1. Create an OSGi bundle for the DB2 JDBC driver, as follows: * Download the DB2 JDBC driver for your database version from the [IBM download site](http://www-01.ibm.com/support/docview.wss?uid=swg21363866) and place it in the `openidm/db/db2/scripts` directory. Use either the `db2jcc.jar` or `db2jcc4.jar`, depending on your DB2 version. For more information, refer to the [DB2 JDBC Driver Versions](http://www-01.ibm.com/support/docview.wss?uid=swg21363866). ``` ls /path/to/db/db2/scripts/ db2jcc.jar openidm.sql ``` * Create a `bnd` file and edit it to match the version information for your JDBC driver. You can use the sample `bnd` file located in `openidm/db/mssql/scripts`. Copy that file to the directory with the JDBC driver: ``` cd /path/to/openidm/db cp mssql/scripts/sqljdbc4.bnd db2/scripts/ ls db2/scripts db2jcc.jar openidm.sql sqljdbc4.bnd ``` The JDBC driver version information for your driver is located in the `Specification-Version` property in the MANIFEST file of the driver. ``` cd /path/to/openidm/db/db2/scripts unzip -q -c db2jcc.jar META-INF/MANIFEST.MF Manifest-Version: 1.0 Created-By: 1.4.2 (IBM Corporation) ``` Edit the `bnd` file to match the JDBC driver version: ``` **more sqljdbc4.bnd** ... version=1.0 Export-Package: *;version=${version} Bundle-Name: IBM JDBC DB2 Driver Bundle-SymbolicName: com.ibm.db2.jcc.db2driver Bundle-Version: ${version} ``` * Download the most recent `bnd` JAR file from . The [bnd](http://bnd.bndtools.org/) utility lets you create OSGi bundles for JDBC libraries that do not yet support OSGi. Place the `bnd` JAR file in the same directory as the JDBC driver: ``` ls /path/to/openidm/db/db2/scripts biz.aQute.bnd-version.jar db2jcc.jar ``` * Change to the directory in which the script files are located and run the following command to create the OSGi bundle: ``` cd /path/to/openidm/db/db2/scripts java -jar biz.aQute.bnd-version.jar wrap --properties sqljdbc4.bnd --output db2jcc-osgi.jar db2jcc.jar ``` This command creates an OSGi bundle, as defined by the `--output` option: `db2jcc-osgi.jar`: ``` ls /path/to/openidm/db/db2/scripts biz.aQute.bnd-version.jar db2jcc-osgi.jar db2jcc.jar ``` * Move the OSGi bundle fle to the `openidm/bundle` directory: ``` mv db2jcc-osgi.jar /path/to/openidm/bundle/ ``` 2. Remove the default DS repository configuration file (`repo.ds.json`) from your project's `conf/` directory. For example: ``` cd /path/to/openidm/my-project/conf/ rm repo.ds.json ``` 3. Copy the database connection configuration file for DB2 (`datasource.jdbc-default.json`) and the database table configuration file (`repo.jdbc.json`) to your project's configuration directory. For example: ``` cp /path/to/openidm/db/db2/conf/datasource.jdbc-default.json my-project/conf/ cp /path/to/openidm/db/db2/conf/repo.jdbc.json my-project/conf/ ``` 4. Update the connection configuration to reflect your DB2 deployment. The default connection configuration in the `datasource.jdbc-default.json` file is as follows: ```json { "driverClass" : "com.ibm.db2.jcc.DB2Driver", "jdbcUrl" : "jdbc:db2://&{openidm.repo.host}:&{openidm.repo.port}/dopenidm:retrieveMessagesFromServerOnGetMessage=true;", "databaseName" : "sopenidm", "username" : "openidm", "password" : "openidm", "connectionTimeout" : 30000, "connectionPool" : { "type" : "hikari", "minimumIdle" : 20, "maximumPoolSize" : 50 } } ``` Specify the values for `openidm.repo.host` and `openidm.repo.port` in one of the following ways: > **Collapse: Set in an IDM Properties File** > > Set the values in `resolver/boot.properties` or your project's `conf/system.properties` file, for example: > > ```json > openidm.repo.host = localhost > openidm.repo.port = 50000 > ``` > **Collapse: Set as an Environment Variable** > > Set the properties in the `OPENIDM_OPTS` environment variable and export that variable before startup. You must include the JVM memory options when you set this variable. For example: > > ``` > export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=50000" > /path/to/openidm/startup.sh -p my-project > Executing ./startup.sh... > Using OPENIDM_HOME: /path/to/openidm > Using PROJECT_HOME: /path/to/openidm > Using OPENIDM_OPTS: -Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=50000 > Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties > Using boot properties at /path/to/openidm/resolver/boot.properties > -> OpenIDM version "7.3.3" > OpenIDM ready > ``` 5. Create a user database for IDM (`dopenidm`). ``` db2 create database dopenidm ``` 6. Import the IDM data definition language script into your DB2 instance. ``` cd /path/to/openidm db2 -i -tf db/db2/scripts/openidm.sql ``` The database schema is defined in the `SOPENIDM` database. 7. You can show the list of tables in the repository, using the `db2 list` command, as follows: ``` db2 LIST TABLES for all Table/View Schema Type Creation time ------------------------------- --------------- ----- -------------------------- CLUSTEROBJECTPROPERTIES SOPENIDM T 2015-10-01-11.58.05.968933 CLUSTEROBJECTS SOPENIDM T 2015-10-01-11.58.05.607075 CONFIGOBJECTPROPERTIES SOPENIDM T 2015-10-01-11.58.01.039999 CONFIGOBJECTS SOPENIDM T 2015-10-01-11.58.00.570231 GENERICOBJECTPROPERTIES SOPENIDM T 2015-10-01-11.57.59.583530 GENERICOBJECTS SOPENIDM T 2015-10-01-11.57.59.152221 INTERNALUSER SOPENIDM T 2015-10-01-11.58.04.060990 LINKS SOPENIDM T 2015-10-01-11.58.01.349194 MANAGEDOBJECTPROPERTIES SOPENIDM T 2015-10-01-11.58.00.261556 MANAGEDOBJECTS SOPENIDM T 2015-10-01-11.57.59.890152 ... ``` 8. Connect to the `openidm` database, and run the script that creates the tables required by the workflow engine: ``` db2 connect to dopenidm db2 -i -tf /path/to/openidm/db/db2/scripts/flowable.db2.all.create.sql ``` 9. If you plan to direct audit logs to this repository, run the script that sets up the audit tables: ``` db2 -i -tf /path/to/openidm/db/db2/scripts/audit.sql ``` When you have set up DB2 for use as the internal repository, make sure that the server starts without errors. ## Kerberos authentication with a DB2 repository By default, IDM uses the username and password configured in the repository connection configuration file (`conf/datasource.jdbc-default.json`) to connect to the DB2 repository. You can configure IDM to use Kerberos authentication instead. In this scenario, IDM acts as a *client* and requests a Kerberos ticket for a *service*, which is DB2, through the JDBC driver. This section assumes that you have configured DB2 for Kerberos authentication. If that is not the case, follow the instructions in the corresponding [DB2 documentation](https://www-01.ibm.com/support/knowledgecenter/SSEPGG_10.1.0/com.ibm.db2.luw.admin.sec.doc/doc/c0058525.html) before you read this section. The following diagram shows how the ticket is obtained and how the keytab is referenced from IDM's `jaas.conf` file. ![db2-kerberos](_images/db2-kerberos.png)Figure 1. Using Kerberos to Connect to a DB2 Repository > **Collapse: Configure IDM for Kerberos Authentication** > > 1. Create a keytab file, specifically for use by IDM. > > A Kerberos keytab file (`krb5.keytab`) is an encrypted copy of the host's key. The keytab enables DB2 to validate the Kerberos ticket that it receives from IDM. You must create a keytab file on the host that IDM runs on. The keytab file must be secured in the same way that you would secure any password file. Specifically, only the user running IDM should have read and write access to this file. > > Create a keytab for DB2 authentication, in the file `openidm/security/idm.keytab/`: > > ``` > kadmin -p kadmin/admin -w password > kadmin: ktadd -k /path/to/openidm/security/idm.keytab db2/idm.example.com > ``` > > 2. Make sure that the DB2 user has read access to the keytab. > > 3. Copy the DB2 Java Authentication and Authorization Service (JAAS) configuration file to the IDM `security` directory: > > ``` > cp /path/to/openidm/db/db2/conf/jaas.conf /path/to/openidm/security/ > ``` > > By default, IDM assumes that the keytab is in the file `openidm/security/idm.keytab` and that the principal identity is `db2/idm.example.com@EXAMPLE.COM`. Change the following lines in the `jaas.conf` file if you are using a different keytab: > > ``` > keyTab="security/idm.keytab" > principal="db2/idm.example.com@EXAMPLE.COM" > ``` > > 4. Adjust the authentication details in your DB2 connection configuration file (`conf/datasource.jdbc-default.json`) to remove the `password` field and change the username to the instance owner (`db2`). The following excerpt shows the modified file: > > ```json > { > ... > "databaseName" : "sopenidm", > "username" : "db2", > "connectionTimeout" : 30000, > ... > } > ``` > > 5. Edit your project's `conf/system.properties` file, to add the required Java options for Kerberos authentication. > > In particular, add the following two lines to that file: > > ```none > db2.jcc.securityMechanism=11 > java.security.auth.login.config=security/jaas.conf > ``` > > 6. Restart IDM.