Using JDBC to Connect to a Cluster (IAM Authentication Mode)

Overview

GaussDB(DWS) allows you to access databases using IAM authentication. When you use the JDBC application program to connect to a cluster, set the IAM username, credential, and other information as you configure the JDBC URL. After doing this, when you try to access a database, the system will automatically generate a temporary credential and a connection will be set up.

• Currently, only clusters 1.3.1 and later versions and their corresponding JDBC drivers can access the databases in IAM authentication mode. Download the JDBC driver. For details, see Downloading the JDBC or ODBC Driver.

IAM supports two types of user credential: password and Access Key ID/Secret Access Key (AK/SK). JDBC connection requires the latter.

The IAM account you use to access a database must be granted with the DWS Database Access permission. Only users with both the DWS Administrator and DWS Database Access permissions can connect to GaussDB(DWS) databases using the temporary database user credentials generated based on IAM users.

The DWS Database Access permission can only be granted to user groups. Ensure that your IAM account is in a user group with this permission.

On IAM, only users in the admin group have the permissions to manage users. This requires that your IAM account be in the admin user group. Otherwise, contact the IAM account administrator to grant your IAM account this permission.

The process of accessing a database is as follows:

1. Granting an IAM Account the GaussDB(DWS) Database Access Permission
2. Creating an IAM User Credential
3. Configuring the JDBC Connection to Connect to a Cluster Using IAM Authentication

Granting an IAM Account the GaussDB(DWS) Database Access Permission

1. Log in to the cloud management console. In the service list, choose Management & Governance > Identity and Access Management to enter the IAM management console.
2. Modify the user group to which your IAM user belongs. Set a policy for, grant the DWS Database Access permission to, and add your IAM user to it.

   Only users in the admin user group of IAM can perform this step. In IAM, only users in the admin user group can manage users, including creating user groups and users and setting user group rights.

   For details, see "User and User Group Management > Viewing or Modifying User Group Information" in the Identity and Access Management User Guide.

   You can also create an IAM user group, and set a policy for, grant the DWS Administrator and DWS Database Access permissions to, and add your IAM user to it. For details, see "User and User Group Management > Creating a User Group" in the Identity and Access Management User Guide.

Creating an IAM User Credential

You can log in to the management console to create an AK/SK pair or use an existing one.

1. Log in to the management console.
2. Move the cursor to the username in the upper right corner and choose My Credentials.
3. Choose Access Keys to view the existing access keys. You can also click Create Access Key to create a new one.
   The AK/SK pair is so important that you can download the private key file containing the AK/SK information only when you create the pair. On the management console, you can only view the AKs. If you have not downloaded the file, obtain it from your administrator or create an AK/SK pair again.

   

   Each user can create a maximum of two AK/SK pairs, which are valid permanently. To ensure account security, change your AK/SK pairs periodically and keep them safe.

Configuring the JDBC Connection to Connect to a Cluster Using IAM Authentication

Configuring JDBC Connection Parameters

jdbc:dws:iam://dws-IAM-demo:eu-de/gaussdb?AccessKeyID=XXXXXXXXXXXXXXXXXXXX&SecretAccessKey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&DbUser=user_test&AutoCreate=true

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

//The following uses gsjdbc4.jar as an example.
// The following code encapsulates the database connection obtaining operations into an API. You can connect to the database by specifying the region where the cluster is located, cluster name, access key ID, secret access key, and the corresponding IAM username.
public static Connection GetConnection(String clustername, String regionname, String AK, String SK,
    String username) {
    // Driver class.
    String driver = "org.postgresql.Driver";
    // Database connection descriptor.
    String sourceURL = "jdbc:dws:iam://" + clustername + ":" + regionname + "/postgresgaussdb?" + "AccessKeyID="
        + AK + "&SecretAccessKey=" + SK + "&DbUser=" + username + "&autoCreate=true";

    Connection conn = null;

    try {
        // Load the driver.
        Class.forName(driver);
    } catch (ClassNotFoundException e) {
        return null;
    }
    try {
        // Create a connection.
        conn = DriverManager.getConnection(sourceURL);
        System.out.println("Connection succeed!");
    } catch (SQLException e) {
        return null;
    }
    return conn;
}