---
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: 8.1
page_id: pingidm:install-guide:repository-db2
canonical_url: https://docs.pingidentity.com/pingidm/8.1/install-guide/repository-db2.html
keywords: ["Installation", "IBM DB2"]
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`.

* You are using a supported version of DB2. Refer to [Supported repositories](../release-notes/before-you-install.html#prerequisites-repositories).

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. Download the DB2 JDBC driver for your database version from the [IBM download site](https://www-01.ibm.com/support/docview.wss?uid=swg21363866) and place it in the `openidm/bundle` directory.

   |   |                                                                                                                                                                                                                                                                                                                                                                   |
   | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | Ping recommends using the `db2jcc4.jar` driver, as the `db2jcc.jar` driver is deprecated. For more information, refer to the [DB2 JDBC Driver Versions](https://www-01.ibm.com/support/docview.wss?uid=swg21363866).For a list of supported DB2 versions, refer to [Supported repositories](../release-notes/before-you-install.html#prerequisites-repositories). |

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="-Xmx2048m -Xms2048m -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:   -Xmx2048m -Xms2048m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=50000
   > ...
   > Using boot properties at /path/to/openidm/resolver/boot.properties
   > -> OpenIDM version "8.1.0"
   > 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.