Connecting and authenticating to the Data Virtualization service

Data Virtualization uses your IBM® Software Hub credentials to connect to the service.

Authorization

IBM Software Hub users who are authorized can connect to and use Data Virtualization. For more information, see Managing users in Data Virtualization.

Data Virtualization roles are used for authorization, independently of group membership. Data Virtualization uses role-based access control for database-level and object-level authorization. Data Virtualization follows authorization based on the Db2 Authorities and Privilege model. For more information, see Authorization, privileges, and object ownership.

Authentication

If you authenticate to Data Virtualization by using JDBC client applications or you are prompted when you preview assets in the catalog or project, you must specify the IBM Software Hub credentials.

A Data Virtualization Admins must explicitly add IBM Software Hub users to the Data Virtualization service for these users to authenticate to the service directly. When the Data Virtualization Admins adds a IBM Software Hub user to the service, a Data Virtualization role is assigned to the user.

Data Virtualization supports the following authentication methods.

Note: To connect to Data Virtualization using a username and password, you must have IBM Software Hub configured with LDAP as the identity provider. For OIDC and SAML identity providers with single sign-on, you can use either a IBM Software Hub JWT token, or a IBM Software Hub API key.

Username and password (See also Username requirements)
JWT tokens
API keys
External providers

Username and password

If your IBM Software Hub connection is configured with LADP as the identity provider, then you can connect to Data Virtualization with a username and password. For more information on LADP integration, see Integrating with the Identity Management Service.

JDBC username and password

When you connect with a username and password, three different security mechanisms are supported: clear text password, encrypted password, and encrypted user ID and password.

Table 1. JDBC username and password
Security Mechanism ID	Security method	Description
3	CLEAR_TEXT_PASSWORD_SECURITY	User ID and password
7	ENCRYPTED_PASSWORD_SECURITY	User ID and encrypted password
9	ENCRYPTED_USER_AND_PASSWORD_SECURITY	Encrypted user ID and encrypted password

If you are using security mechanism ENCRYPTED_PASSWORD_SECURITY or ENCRYPTED_USER_AND_PASSWORD_SECURITY, you must set the encryptionAlgorithm=2 property.

The following examples show the commands to connect with and without secure sockets layer (SSL):

SSL

"jdbc:db2://Host_name_or_IP_address:DV_SSL_port/Database_name:user=User_name;password=Password;securityMechanism=Security_mechanism_id;sslConnection=true"

Non-SSL

"jdbc:db2://Host_name_or_IP_address:DV_port/Database_name:user=User_name;password=Password;securityMechanism=Security_mechanism_id"

Where:

Table 2. Variables required to connect to the service
Variable name	Description
`Host_name_or_IP_address`	The hostname or IP address of the IBM Software Hub instance.
`DV_SSL_port`	The port number of the Data Virtualization SSL instance.
`DV_port`	The port number of the Data Virtualization instance.
`Database_name`	The name of the database.
`User_name`	The IBM Software Hub username.
`Password`	The IBM Software Hub password.
`Security_mechanism_id`	One of the values in the ID column from the JDBC username and password table.

Command line processor (CLP) username and password

Connect to the database server Database_server_name with IBM Software Hub credentials by running the following command from a CLP interface or from a script:

CONNECT TO Database_server_name USER User_name USING Password

CLPPlus username and password

Connect to the DSN alias (@Data_source_name) with IBM Software Hub credentials by running the following command from a CLPPLUS interface or from a script.

CONNECT User_name/Password@Data_source_name

Username requirements

Data Virtualization requires user names to conform to the Db2 authorization-name identifier requirements.

An authorization-name is defined as an identifier that designates a user, group, or role. For a user or a group, the following requirements apply.

Valid characters are A through Z, a through z, 0 through 9, #, @, $, _, !, (, ), {, }, -, ., and ^.
The following characters must be delimited with quotation marks when entered through the command line processor !, (, ), {, }, -, ., and ^.
The name must not begin with the characters SYS, IBM, or SQL. ^*
The name must not be ADMINS, GUESTS, LOCAL, PUBLIC, or USERS.^*
A delimited authorization ID must not contain lowercase letters.

If you attempt to add a user with a username that does not meet these requirements, you see the following error.

Error: There is an internal error. Please refresh this page if it does not behave properly.

If you attempt to add the user by using SQL with a username that does not meet these requirements, you see the following error.

The operation failed because the specified authorization name does not meet the identifier naming rules. Authorization name: <authorization >

In addition, the following usernames are reserved for functional IDs and must never be added as users in IBM Software Hub, or any external user management system that is configured for IBM Software Hub.

SYSIBM ^*
DB2INST1^*
CACHEADMIN^*
DMCUSER^*
DB2FENC1^*
ICP4D-DEV^*

Note: ^* These names are reserved irrespective of the case.

JWT tokens

You can connect to Data Virtualization with a IBM Software Hub JSON Web Tokens (JWT).

JDBC access token

"jdbc:db2://Host_name_or_IP_address/Database_name:accessToken=Access_token;securityMechanism=15;pluginName=IBMIAMauth;sslConnection=true"

Where Access_token is the IBM Software Hub platform or instance token.

CLP access token

Connect to the database server Database_server_name and pass the access token by running the following command from a CLP interface or from a script.

CONNECT TO Database_server_name ACCESSTOKEN Access_token

CLPPlus access token

Connect to the DSN alias (@Data_source_name) and pass the access token by running the following command from a CLPPLUS interface or from a script.

CONNECT @Data_source_name using(accesstoken Access_token)

API keys

You can connect to Data Virtualization with a IBM Software Hub API key.

Note: When you authenticate to Data Virtualization, you must provide the API key in this format: User_name:Api_key.

Where Api_key is the IBM Software Hub or instance API key.

For example: cpadmin:dxjkVzcJmWB5VkB5arhlqNIcrwwW00Xld0iPb2Eg

JDBC API key

"jdbc:db2://Host_name_or_IP_address:DV_SSL_port/Database_name:apiKey=User_name:API_key;securityMechanism=15;pluginName=IBMIAMauth;sslConnection=true"

Where API_key is the IBM Software Hub platform or instance API key.

CLP API key

Connect to the database server Database_server_name with an API key by running the following command from a CLP interface or from a script.

CONNECT TO Database_server_name APIKEY User_name:API_key

CLPPlus API key

Connect to the DSN alias (@data_source_name) with an API key by running the following command from a CLPPLUS interface or from a script.

CONNECT @Data_source_name using(apikey User_name:API_key)

External providers

You can connect by using external providers.

External LDAP: Data Virtualization supports LDAP that is used to manage access to the IBM Software Hub platform. For more information, see Connecting to your LDAP server.

Developers

An Admin can allow developers to connect to Data Virtualization so that they can develop applications that access and use the data in a Data Virtualization instance.