Token authentication under the IBM Data Server Driver for JDBC and SQLJ

The IBM® Data Server Driver for JDBC and SQLJ provides client support for token authentication for IBM Data Server Driver for JDBC and SQLJ type 4 connectivity to Db2® on Linux®, UNIX, and Windows systems.

Token authentication allows an application to provide a generalized token that is used for authentication at the data server. A token type string identifies the type of the token so that the data server can validate the token. The token type must be supported by the data server. Currently, JWT (JSON Web Tokens) is the only supported token type. The token is used instead of a user ID and password, and contains all of the information that is needed to authenticate the user. Token authentication is available with Db2 on Linux, UNIX, and Windows systems, Version 11.5 Mod Pack 4 or later, and with the IBM Data Server Driver for JDBC and SQLJ, version 4.27.22 or later.

You enable IBM Data Server Driver for JDBC and SQLJ token authentication by specifying DB2BaseDataSource.TOKEN_SECURITY (19) as the value of the securityMechanism property. If the target data server supports token authentication, the driver passes a valid Connection object to the application. If the data server does not support token authentication, the driver throws a DisconnectException.

To enable token authentication for a connection, you must specify a token with the accessToken property, and a token type with the accessTokenType property. When you use token authentication, you cannot specify a value for the user property or the password property.

Use of SSL encryption with token authentication is recommended. To use SSL encryption with token authentication, set the sslConnection property to true.

The following example demonstrates how to enable token security for connections that use a DB2SimpleDataSource object. In the example, the accessToken, accessTokenType, and securityMechanism properties are set on the DB2SimpleDataSource object.

DB2SimpleDataSource dataSource;
dataSource.setDriverType(4);
dataSource.setDatabaseName("BLUDB");
dataSource.setServerName("host-name-or-IP-address");
dataSource.setPortNumber(50001);
dataSource.setSslConnection(true);
dataSource.setSecurityMechanism(com.ibm.db2.jcc.DB2BaseDataSource.TOKEN_SECURITY);
dataSource.setAccessToken("access-token");
dataSource.setAccessTokenType("JWT");
Connection conn = dataSource.getConnection();

The following example demonstrates how to use the DriverManager interface to create a connection that uses token authentication. In the example, the accessToken, accessTokenType, and securityMechanism properties are set in the url parameter of the DriverManager.getConnection method invocation.

Connection conn = DriverManager.getConnection(
"jdbc:db2://host-name-or-IP-address:50001/BLUDB:" +
"accessToken=access-token;accessTokenType=JWT;" +
"securityMechanism=19;sslConnection=true");

The following example demonstrates how to enable token security for connections that use a DB2XADataSource object. In the example, the accessToken, accessTokenType, and securityMechanism property values are set on the DB2XADataSource object. In the getDB2XAConnection method invocation, the user and password fields must be null.

DB2XADataSource xads = new DB2XADataSource();
props = new java.util.Properties();
xads.setDriverType(4);
xads.setDatabaseName("dbname");
xads.setServerName("hostname");
xads.setPortNumber(port);
xads.setSecurityMechanism(com.ibm.db2.jcc.DB2BaseDataSource.TOKEN_SECURITY);
xads.setAccessToken("access-token");
xads.setAccessTokenType("JWT");
DB2XAConnection xaconn = xads.getDB2XAConnection(null, null, props);

The following example demonstrates how to enable token security for connections that use a DB2XADataSource object. In the example, the securityMechanism property value for token security is set on the DB2XADataSource object, and the accessToken and accessTokenType property values are set on a java.util.Properties object that is passed to getDB2XAConnection. In the getDB2XAConnection method invocation, the user and password fields must be null.

DB2XADataSource xads = new DB2XADataSource();
props = new java.util.Properties();
xads.setDriverType(4);
xads.setDatabaseName("dbname");
xads.setServerName("hostname");
xads.setPortNumber(port);
xads.setSecurityMechanism(com.ibm.db2.jcc.DB2BaseDataSource.TOKEN_SECURITY);
props.put("accessToken","access-token");
props.put("accessTokenType","JWT");
DB2XAConnection xaconn = xads.getDB2XAConnection(null, null, props);