Identity and access management (IAM) on IBM Cloud

IBMid

Users with an IBMid must be added to each database service instance by the database administrator through the console or REST API before these users can connect to the particular database service instance. Like for a non-IBMid user, a user ID for the database service instance must be entered at the same time that the IBMid user is added. This user ID needs to be unique within the database service instance. This user ID is also the authorization (AUTH) ID within the database. The database administrator can grant and revoke permissions based on the AUTH ID.

Service IDs

A service ID identifies a service or application similar to how a user ID identifies a user. The service IDs are IDs that can be used by applications to authenticate with an IBM Cloud service. A service ID represents a separate entity from the owning IBMid. Therefore, different authorities and permissions can be granted specific to the service ID within the database. Service IDs do not have passwords. An API key must be created for each service ID for the service ID to connect to the database service instance. For more information about service IDs, see: Introducing IBM Cloud IAM Service IDs and API Keys and Increase Information Security for Db2 on IBM Cloud.

Access token

An access token can be obtained from the IAM service directly by the application through the REST API by using an API key. For more information, see: Getting an IBM Cloud IAM token by using an API key. The access token has a default validity period of 60 minutes before it expires. If the token has expired, the Db2 server won't allow the connection to be established. The token isn’t checked for expiry after the connection is established. Just as it was before IAM integration, the connection stays connected until the application disconnects or the connection is terminated due to other reasons.

curl -k -X POST \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Accept: application/json" \
  --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
  --data-urlencode "apikey=<apikey>" \
  "https://iam.cloud.ibm.com/identity/token"

An access token identifies an IBMid user or a service ID to the database. The database server verifies the validity of the access token before accepting it. This is the best method if the application needs to connect to more than one database service instance or other IBM Cloud service instances because it minimizes the communication to the IAM service to validate the access token.

API key

Multiple API keys can be created for each IBMid user or service ID. Each API key is typically created for a single application. It allows the application to connect to the database service instance as long as the owning IBMid or service ID is added as a user to the same database service instance. The API key has the same authorities and permissions within the database as the owning IBMid or service ID. If an application should no longer be allowed to connect to the database, the corresponding API key can be removed. This method of authentication requires fewer changes in the application than using an access token as it requires no direct interaction with the IAM service. For more information about creating and managing API keys, see: Managing user API keys.

IBMid/password

The IBMid/password can be used to log in to the console and can also be used within the application in the same ways that a user ID/password is allowed. The exception occurs when the IBMid is federated because a redirection to your organization’s login page cannot be done. However, the recommended method for an application to establish a connection to the database service instance is to use an access token.

ODBC, CLP, and CLPPLUS

For an ODBC application or a command-line client (CLP, CLPPLUS) to connect to a Db2 server by using IAM authentication, a data source name (DSN) needs to be configured first in a db2dsdriver.cfg configuration file by running the following command:

db2cli writecfg add -dsn <dsn_alias> -database <database_name> -host <host_name_or_IP_address> -port 50001 -parameter "Authentication=GSSPLUGIN;SecurityTransportMode=SSL"

The db2dsdriver.cfg configuration file is an XML file, typically located in the sqllib/cfg directory, that contains a list of DSN aliases and their properties.

The following example of a db2dsdriver.cfg configuration file shows the configurations that are used to establish a connection to a database service instance. The configuration file provides the DSN alias, the database name, the host name (or IP address), and the Authentication type and SecurityTransportMode parameter values:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<configuration>
        <dsncollection>
        <dsn alias="<data_source_name>" name="bludb" host="<host_name_or_IP_address>" port="50001">
            <parameter name="Authentication" value="GSSPLUGIN"/>
            <parameter name="SecurityTransportMode" value="SSL"/>
        </dsn>
        </dsncollection>
        <databases>
            <database name="bludb" host="<host_name_or_IP_address>" port="50001"/>
        </databases>
</configuration>

- **Access token**

`DSN=<dsn>;ACCESSTOKEN=<access_token>`

- **API key**

`DSN=<dsn>;APIKEY=<api_key>`

- **IBMid/password**

`DSN=<dsn>;UID=<ibmid>;PWD=<password>`

- **Access token**

Connect to the database server `<database_server_name>` and pass the access token by running the following command at the CLP command prompt or script:

`CONNECT TO <database_server_name> ACCESSTOKEN <access_token_string>`

- **API key**

Connect to the database server `<database_server_name>` with an API key by running the following command at the CLP command prompt or script:

`CONNECT TO <database_server_name> APIKEY <api-key-string>`

- **IBMid/password**

Connect to the database server `<database_server_name>` with an IBMid/password by running the following command at the CLP command prompt or script:

`CONNECT TO <database_server_name> USER <IBMid> USING <password>`

- **Access token**

Connect to the DSN alias (`@<data_source_name>`) and pass the access token by running the following command at the CLPPLUS command prompt or script:

`connect @<data_source_name> using(accesstoken <access_token_string>)`

- **API key**

Connect to the DSN alias (`@<data_source_name>`) with an API key by running the following command at the CLPPLUS command prompt or script:

`connect @<data_source_name> using(apikey <api-key-string>)`

- **IBMid/password**

Connect to the DSN alias (`@<data_source_name>`) with an IBMid/password by running the following command at the CLPPLUS command prompt or script:

`connect <IBMid>/<password>@<data_source_name>`

JDBC

Type 4 JDBC Driver is supported for IAM authentication.

The following examples show connection snippets for the three methods:

• Access token

  DB2SimpleDataSource dataSource;
  
  dataSource.setDriverType( 4 );
  dataSource.setDatabaseName( "BLUDB" );
  dataSource.setServerName( "<host_name_or_IP_address>" );
  dataSource.setPortNumber( 50001 );
  dataSource.setSecurityMechanism( com.ibm.db2.jcc.DB2BaseDataSource.PLUGIN_SECURITY );
  dataSource.setPluginName( "IBMIAMauth" );
  dataSource.setAccessToken( "<access_token>" );
  Connection conn = dataSource.getConnection( );
  

  or

  Connection conn = DriverManager.getConnection( "jdbc:db2://<host_name_or_IP_address>:50001/BLUDB:accessToken=<access_token>;securityMechanism=15;pluginName=IBMIAMauth;sslConnection=true" );
  

• API key

  DB2SimpleDataSource dataSource;
  
  dataSource.setDriverType( 4 );
  dataSource.setDatabaseName( "BLUDB" );
  dataSource.setServerName( "<host_name_or_IP_address>" );
  dataSource.setPortNumber( 50001 );
  dataSource.setSecurityMechanism( com.ibm.db2.jcc.DB2BaseDataSource.PLUGIN_SECURITY );
  dataSource.setPluginName( "IBMIAMauth" );
  dataSource.setApiKey( "<api_key>" );
  Connection conn = dataSource.getConnection( );
  

  or

  Connection conn = DriverManager.getConnection( "jdbc:db2://<host_name_or_IP_address>:50001/BLUDB:apiKey=<api_key>;securityMechanism=15;pluginName=IBMIAMauth;sslConnection=true" );
  

• IBMid/password

  DB2SimpleDataSource dataSource;
  
  dataSource.setDriverType( 4 );
  dataSource.setDatabaseName( "BLUDB" );
  dataSource.setServerName( "<host_name_or_IP_address>" );
  dataSource.setPortNumber( 50001 );
  dataSource.setSecurityMechanism( com.ibm.db2.jcc.DB2BaseDataSource.PLUGIN_SECURITY );
  dataSource.setPluginName( "IBMIAMauth" );
  Connection conn = dataSource.getConnection( "<IBMid>", "<password>" );
  

  or

  Connection conn = DriverManager.getConnection( "jdbc:db2://<host_name_or_IP_address>:50001/BLUDB:user=<IBMid>;password=<password>;securityMechanism=15;pluginName=IBMIAMauth;sslConnection=true" );