Hologres:RAM Role Authorization Mode

Prerequisites

Before you begin, ensure that you have:

• An Alibaba Cloud account with permission to create RAM roles

• A RAM user (existing or to be created) who will assume the role

• Your Alibaba Cloud account ID, available on the User Information page

Create a RAM role for a trusted Alibaba Cloud account

1. Log on to the RAM console. In the left navigation pane, click Identities > Roles.

2. On the Roles page, click Create Role. Set Principal Type to Cloud Account and Principal Name to Current Account. Click OK.

3. In the Create Role dialog box, enter a Role Name and click OK.

Configure the trust policy

1. On the RAM Roles page, click the target role name to open its details page.

2. On the Trust Policy tab, click Edit Trust Policy. Replace the policy content with the following JSON. Replace Alibaba Cloud account ID in acs:ram::Alibaba Cloud account ID:root with your actual account ID.

   Trust policy field reference:

   Field	Description
   Principal.RAM	The Alibaba Cloud account (or RAM user) permitted to assume this role. Set to acs:ram::Alibaba Cloud account ID:root to allow all RAM users in the account.
   Principal.Service	Alibaba Cloud services permitted to assume this role. dataworks.aliyuncs.com enables DataWorks to use this role.
   Version	Policy schema version. Must be "1".

      {
        "Statement": [
          {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
              "RAM": [
                "acs:ram::Alibaba Cloud account ID:root"
              ]
            }
          },
          {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
              "Service": [
                "dataworks.aliyuncs.com"
              ]
            }
          }
        ],
        "Version": "1"
      }

Grant the RAM user permission to call AssumeRole

The RAM user who will assume the role must have the AliyunSTSAssumeRoleAccess system policy attached. Without this policy, the user cannot call the STS AssumeRole API.

In the RAM console, navigate to the RAM user, click Add Permissions, and attach the AliyunSTSAssumeRoleAccess policy. For step-by-step instructions, see Grant permissions to a RAM user.

Obtain STS temporary security credentials

The RAM user calls the AssumeRole API operation to obtain short-lived credentials. For SDK examples, see Use the STS OpenAPI example.

Save the returned AccessKeyId, AccessKeySecret, and SecurityToken values — you will use them in Step 3.

Prerequisites

Before you begin, ensure that you have:

• A registered SAML identity provider in the RAM console. See Overview of SAML-based role SSO.

• The SAML provider ARN, visible in the RAM console after registering the IdP

• Your Alibaba Cloud account ID, available on the User Information page

How SAML-based role SSO works

The following diagram shows the authentication flow for Path B:

The end-to-end flow:

1. A user opens a browser and selects Alibaba Cloud as the target service on the IdP logon page (for example, Microsoft Active Directory Federation Services (AD FS) at https://ADFSServiceName/adfs/ls/IdpInitiatedSignOn.aspx).

   Some IdPs require users to log on before selecting the SSO application that represents Alibaba Cloud.

2. The IdP generates a Security Assertion Markup Language (SAML) response and returns it to the browser.

3. The browser forwards the SAML response to the Alibaba Cloud SSO service.

4. The SSO service exchanges the SAML response for STS temporary security credentials and generates a console logon URL.

   If the SAML response maps to multiple RAM roles, the system prompts the user to select a role before proceeding.

5. The SSO service returns the logon URL to the browser.

6. The browser redirects to the URL. The user is now logged on to the Alibaba Cloud Management Console as the RAM role and can access the Hologres instance within the permissions granted to that role.

Create a RAM role for a trusted identity provider

1. Log on to the RAM console. In the left navigation pane, click Identities > Roles.

2. On the Roles page, click Create Role. Set Principal Type to Identity Provider.

3. Click OK. In the dialog box, enter a role name.

4. Set IdP Type and Select IdP, review the conditions, and click OK. The role is created.

Configure the trust policy

1. On the Roles page, click the target role name to open its details page.

2. On the Trust Policy tab, click Edit Trust Policy. Replace the policy content with the following JSON. Replace Alibaba Cloud account ID with your actual account ID, and replace IDP with the name of your SAML provider as registered in the RAM console.

   In the ARN string acs:ram::Alibaba Cloud account ID:saml-provider/IDP, the value IDP is a placeholder for your SAML provider name (a user-defined string), not the abbreviation "IdP" (identity provider).

   Trust policy field reference:

   Field	Description
   saml:recipient	The SAML SSO endpoint. Must be exactly https://signin.aliyun.com/saml-role/sso.
   Principal.Federated	The registered SAML provider ARN. Replace Alibaba Cloud account ID with your account ID and IDP with your SAML provider name.
   Principal.Service	Alibaba Cloud services permitted to assume this role. dataworks.aliyuncs.com enables DataWorks to use this role.
   Version	Policy schema version. Must be "1".

      {
        "Statement": [
          {
            "Action": "sts:AssumeRole",
            "Condition": {
              "StringEquals": {
                "saml:recipient": "https://signin.aliyun.com/saml-role/sso"
              }
            },
            "Effect": "Allow",
            "Principal": {
              "Federated": [
                "acs:ram::Alibaba Cloud account ID:saml-provider/IDP"
              ]
            }
          },
          {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
              "Service": [
                "dataworks.aliyuncs.com"
              ]
            }
          }
        ],
        "Version": "1"
      }

Prerequisites

Before you begin, ensure that you have:

• Completed Steps 1 and 2

• (Path A only) The RAM user has the AliyunRAMReadOnlyAccess permission

Connect via the console

1. Log on to the Hologres console using the RAM role identity to manage instances.

2. In the left navigation pane, click Go To HoloWeb. For details on schema design and data development, see Connect to HoloWeb and execute a query.

Prerequisites

Before you begin, ensure that you have:

• Completed Steps 1 and 2

• Called the AssumeRole API operation to obtain STS temporary security credentials: AccessKeyId, AccessKeySecret, and SecurityToken

• The Hologres instance endpoint (<host>), port (<port>), and database name (<database>), available in the Hologres console under Instances > Connection Info

Set credentials as environment variables

The following is a sample STS temporary credentials response:

"Credentials": {
    "SecurityToken": "CAISuwJ1q6Ft5B2yu****KiAA",
    "AccessKeyId": "STS.NTKaenSkmLhG4HpM5****76UV",
    "AccessKeySecret": "6itECZnhbG2RU6ktTSBSd6JxeLHKPWyBt****SS62",
    "Expiration": "2025-02-21T03:47:07Z"
}

Set the values from Credentials.AccessKeyId, Credentials.AccessKeySecret, and Credentials.SecurityToken as environment variables:

export ALIBABA_CLOUD_ACCESS_KEY_ID="<value of Credentials.AccessKeyId>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<value of Credentials.AccessKeySecret>"
export ALIBABA_CLOUD_SECURITY_TOKEN="<value of Credentials.SecurityToken>"

Security best practices: - Never hardcode STS credentials in source code or configuration files. - Set credentials as environment variables or use a secrets manager. - STS credentials expire automatically (see Expiration in the response). Implement logic to refresh credentials before expiry by calling AssumeRole again. - Grant the minimum permissions required. Avoid AdministratorAccess in the RAM role policy. - Audit access using Alibaba Cloud ActionTrail. Never log credential values.

Connect using JDBC (Java)

All examples read STS credentials from environment variables and pass the security token through the JDBC connection.

For the full JDBC configuration reference, see Connect to Hologres using JDBC.

Method 1: Pass the security token via `PGProperty.OPTIONS`

Use this method when your connection framework does not accept query parameters in the URL, or when you want to supply all credentials through a Properties object.

import org.postgresql.PGProperty;
import java.sql.*;
import java.io.IOException;
import java.util.Properties;

public class JdbcLinkHologres1 {
    public static void main(String[] args) throws IOException, ClassNotFoundException, SQLException {
        // Read credentials from environment variables — do not hardcode
        String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        String securityToken = System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN");
        String url = "jdbc:postgresql://<host>:<port>/<database>";

        Properties props = new Properties();
        PGProperty.USER.set(props, accessKeyId);
        PGProperty.PASSWORD.set(props, accessKeySecret);
        PGProperty.OPTIONS.set(props, "sts_token=" + securityToken);

        Class.forName("org.postgresql.Driver");
        Connection connection = DriverManager.getConnection(url, props);

        Statement statement = connection.createStatement();
        ResultSet resultSet = statement.executeQuery("SELECT * FROM tabletest");

        while (resultSet.next()) {
            System.out.println("Result: " + resultSet.getInt(1));
            System.out.println("Result: " + resultSet.getString(2));
        }
    }
}

Parameter reference – Method 1:

Method 2: Append the security token to the JDBC URL

Use this method when your connection framework requires the full connection string in URL format. URL-encode the SecurityToken value before appending it.

import java.net.URLEncoder;
import java.sql.*;
import java.io.IOException;

public class JdbcLinkHologres2 {
    public static void main(String[] args) throws IOException, ClassNotFoundException, SQLException {
        // Read credentials from environment variables — do not hardcode
        String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        String securityToken = System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN");

        String url = "jdbc:postgresql://<host>:<port>/<database>";
        // URL-encode the security token before appending it as a query parameter
        String urlWithOptions = url + "?options=sts_token=" + URLEncoder.encode(securityToken, "UTF-8");

        Class.forName("org.postgresql.Driver");
        Connection connection = DriverManager.getConnection(urlWithOptions, accessKeyId, accessKeySecret);

        Statement statement = connection.createStatement();
        ResultSet resultSet = statement.executeQuery("SELECT * FROM tabletest");

        while (resultSet.next()) {
            System.out.println("Result: " + resultSet.getInt(1));
            System.out.println("Result: " + resultSet.getString(2));
        }
    }
}

Parameter reference – Method 2:

Connect using psql (command line)

This command passes STS credentials as environment variables and the security token via PGOPTIONS. For Linux systems. For details, see Connect to Hologres using a psql client.

PGUSER=<AccessKeyId> \
PGPASSWORD=<AccessKeySecret> \
PGOPTIONS="sts_token=<SecurityToken>" \
  psql -h <host> -p <port> -d <database>

Parameter reference: