Connecting and authenticating to the Watson Query service

Watson Query uses your Cloud Pak for Data credentials to connect to the service.

Authorization

Cloud Pak for Data users who are authorized can connect to and use Watson Query. For more information, see Managing roles for users and groups in Watson Query.

Watson Query roles are used for authorization, independently of group membership. Watson Query uses role-based access control for database-level and object-level authorization. Watson Query follows authorization based on the Db2® Authorities and Privilege model. For more information, see Privileges.

Authentication

If you authenticate to Watson Query by using JDBC client applications or you are prompted when you preview assets in the catalog or project, you must specify the Cloud Pak for Data credentials.

A Watson Query Admins must explicitly add Cloud Pak for Data users to the Watson Query service in order for these users to authenticate to the service directly. When the Watson Query Admins adds a Cloud Pak for Data user to the service, a Watson Query role is assigned to the user.

Watson Query supports the following authentication methods.

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

Username and password

You can connect with a username and password.

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 Cloud Pak for Data instance.
`DV_SSL_port`	The port number of the Watson Query SSL instance.
`DV_port`	The port number of the Watson Query instance.
`Database_name`	The name of the database.
`User_name`	The Cloud Pak for Data username.
`Password`	The Cloud Pak for Data 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 Cloud Pak for Data 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 Cloud Pak for Data credentials by running the following command from a CLPPLUS interface or from a script.

CONNECT User_name/Password@Data_source_name

Username requirements

Watson Query 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 Cloud Pak for Data, or any external user management system configured for Cloud Pak for Data.

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

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

JWT tokens

You can connect with 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 Cloud Pak for Data 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 by providing an API key.

ODBC API Key

Use ODBC to connect to Watson Query.

Run the following commands to add configuration details to the db2dsdriver.cfg driver configuration file:

db2cli writecfg add -database bludb -host <HOSTNAME> -port <SSL PORT>
db2cli writecfg add -database bludb -host <HOSTNAME> -port <SSL PORT> -parameter "SecurityTransportMode=SSL"
db2cli writecfg add -database bludb -host <HOSTNAME> -port <SSL PORT> -parameter "Authentication=GSSPLUGIN"
db2cli writecfg add -dsn watsonquery -database bludb -host <HOSTNAME> -port <SSL PORT>

Run the following command to validate the ODBC configuration:

db2cli validate -dsn watsonquery -connect -user IBM_SUBSTTOKEN_APIKEY -passwd <API_key>

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 Cloud Pak for Data 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: Watson Query supports LDAP that is used to manage access to the Cloud Pak for Data platform. For more information, see Connecting to your LDAP server.

Developers

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