Hologres RAM role authorization mode - Hologres - Alibaba Cloud Documentation Center

This topic describes how to use role-based single sign-on (SSO) to access Hologres.

Background information

Enterprise users can log on to the Alibaba Cloud Management Console with an account and password to manage and use cloud resources. However, due to increasingly strict enterprise security requirements, some enterprises prefer to use role-based SSO to log on to Alibaba Cloud. For more information, see Overview of SAML-based role SSO.

Scenarios

Typically, enterprise users log on to the Alibaba Cloud Management Console with an account and password to manage and use cloud resources. However, due to stricter security and regulatory requirements, enterprises that want to centrally manage logon authentication often choose to use SSO to log on to applications. SSO allows a user to log on once to access all mutually trusted application systems. Hologres now supports a role-based SSO logon mode. For more information, see Overview of SAML-based role SSO. This feature lets you use an enterprise account to assume a Resource Access Management (RAM) role to access a Hologres instance. The RAM role controls the access permissions. The following example shows how this works. 适用场景

A user uses a browser to select Alibaba Cloud as the target service on the logon page of the identity provider (IdP).
For example, if the enterprise IdP uses Microsoft Active Directory Federation Services (AD FS), the logon URL is https://ADFSServiceName/adfs/ls/IdpInitiatedSignOn.aspx.
Note
Some IdPs require users to log on before they can select the SSO application that represents Alibaba Cloud.
The IdP generates a Security Assertion Markup Language (SAML) response and returns it to the browser.
The browser redirects to the SSO service page and forwards the SAML response to the SSO service.
The SSO service uses the SAML response to request a temporary security credential from Alibaba Cloud Security Token Service (STS) and generates a URL that can be used to log on to the Alibaba Cloud Management Console.
Note
If the SAML response contains attributes that map to multiple RAM roles, the system first prompts the user to select a role to access Alibaba Cloud.
The SSO service returns the URL to the browser.
The browser redirects to the URL. The user logs on to the Alibaba Cloud Management Console with the specified RAM role and can then use an enterprise account to assume the RAM role to log on to the Hologres instance.

User access methods supported by Hologres

Hologres supports the following two access methods:

Access Hologres using an Alibaba Cloud account or a RAM user.
You can log on to the Alibaba Cloud Management Console by entering an account and password, and then access Hologres as the logged-on user. In this case, the Alibaba Cloud account becomes a member of a Hologres instance and is granted permissions to use the Hologres product.
Log on to Hologres using role-based SSO.
You can also log on to Alibaba Cloud using role-based SSO and then access Hologres. For more information, see Overview of SAML-based role SSO. In this case, the RAM role becomes a member of a Hologres instance. The user who assumes this RAM role has the same permissions to use the product as a member who uses an Alibaba Cloud account. For more information about RAM roles, see RAM role overview.

In Hologres, RAM roles and Alibaba Cloud accounts, including root accounts and RAM users, are treated as equals. Therefore, a RAM role is treated as a standard logon account in Hologres. A superuser must grant permissions, such as SELECT, INSERT, and UPDATE, to this RAM role, not the underlying Alibaba Cloud account. The RAM role can then access Hologres within the scope of the granted permissions.

Introduction to role-based SSO (STS)

Logging on to and accessing Hologres using role-based SSO is implemented based on the Alibaba Cloud STS. STS is a cloud service that provides short-term access permission management for Alibaba Cloud accounts or RAM users. Using STS, you can issue an access credential with a custom validity period and access permissions to users managed by your on-premises account system. Users can use the short-term STS access credential to directly connect to Hologres and access authorized resources.

Using an STS token provides the following benefits:

You can generate temporary access credentials for users, which reduces the risk of long-term AccessKey ID and AccessKey secret exposure.
It enables flexible access control. Because STS tokens have a limited duration, the temporary access credential automatically becomes invalid after it expires, which eliminates the need to manually revoke permissions.

The following steps guide you through creating a RAM role and granting it permissions to access Hologres.

Step 1: Create a RAM role
Step 2: Add the RAM role to a Hologres instance and grant permissions
Step 3: Log on to Alibaba Cloud and use Hologres

Step 1: Create a RAM role

You can log on to the RAM console to create a RAM role. For the trusted entity type, you can select Alibaba Cloud Account or Identity Provider.

To assume the role by switching identities in the Alibaba Cloud Management Console, select the Alibaba Cloud Account role type. For more information, see Assume a role as a RAM user and add permissions.
To assume the role by logging on to Alibaba Cloud with an on-premises IdP account, select the Identity Provider role type. For more information, see Assume a role as an IdP user and add permissions.

Assume a role as a RAM user and add permissions

To allow a RAM user to assume a RAM role by switching identities in the Alibaba Cloud Management Console, you can log on to the RAM console and create a RAM role. For the trusted entity type, select Alibaba Cloud Account.

Create a RAM role for a trusted Alibaba Cloud account.
1. Log on to the RAM console. In the navigation pane on the left, click Identity Management > Roles.
2. On the Create Role 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.
Create and add an access policy.
1. On the RAM Roles page, click the name of the target role to open the role details page.
2. On the Trust Policy tab, click Edit Trust Policy. Replace the policy content with the following script.
  - Parameters
    When you configure the policy, replace `Alibaba Cloud account ID` in acs:ram::Alibaba Cloud account ID:root with the ID of the account to which you want to grant permissions. You can obtain the account ID from the User Information page.
  - Script configuration
```
{
    "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"
}
```
3. Click OK to complete the policy configuration.
Create a RAM user and grant the permission to assume the role.
To allow a RAM user to assume a RAM role, you must create a RAM user and grant it the permission to assume the role.
1. Log on to the RAM console. In the navigation pane on the left, choose Identity Management > Users.
2. (Optional) If you already have a RAM user, you can skip this step. You can click Create User to create multiple RAM users at once. For more information, see Create a RAM user.
3. In the Actions column of the target RAM user, click Add Permissions.
4. On the Add Permissions page, attach the AliyunSTSAssumeRoleAccess policy to the RAM user to grant permission to call the AssumeRole API operation of STS.
5. Click OK to confirm the role settings.

Assume a role as an IdP user and add permissions

To assume a RAM role by logging on to Alibaba Cloud with an on-premises IdP account, you can log on to the RAM console and create a RAM role. For the trusted entity type, select Identity Provider.

Create a RAM role for a trusted identity provider.
1. Log on to the RAM console. In the navigation pane on the left, click Identity Management > Roles.
2. On the Roles page, click Create Role. Select Identity Provider as the trusted entity type.
3. Click OK. Enter the Role Name and Note.
4. Select an IdP Type and an IdP. After you review the conditions, click Finish. A message appears to confirm that the role is created.

Create and add an access policy.

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

On the Trust Policy tab, click Edit Trust Policy and replace the policy with the following script.

Parameters
When you configure the policy, replace `Alibaba Cloud account ID` in acs:ram::Alibaba Cloud account ID:saml-provider/IDP with the ID of the account to which you want to grant permissions. You can obtain the account ID from the User Information page.

Script configuration

{
    "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"
}

Click OK to complete the policy configuration.

Step 2: Add the RAM role to a Hologres instance and grant permissions

The RAM role needs development permissions on the Hologres instance. By default, a RAM role cannot view or manage instances in the Hologres console. The Alibaba Cloud account must first grant the necessary permissions to the RAM role. For more information, see Grant permissions to a RAM user. After you add the RAM role to a Hologres instance, you can grant permissions in one of the following ways.

Log on to the Hologres console to grant permissions.
1. In the navigation pane on the left, navigate to the Instance List page and click the target instance. On the User Management tab, find the RAM role and add it as a new user to the instance.
2. On the DB Authorization tab, grant development permissions for specific instances to the RAM role.
Grant permissions using SQL.
You can grant permissions using SQL statements. For more information, see Permission management overview.
If a RAM user assumes a RAM role, the role does not have permissions on the Hologres console by default. To enable the role to perform operations in the Hologres console, the Alibaba Cloud account must grant the AliyunRAMReadOnlyAccess permission to the RAM user in the RAM console. For more information, see Grant permissions to a RAM user.

Step 3: Log on to Alibaba Cloud and use Hologres

Console and HoloWeb logon

After you grant the permissions, the user can assume the RAM role to log on and access Hologres.

Use the RAM role to log on to the Hologres console to manage Hologres instances.
In the navigation pane on the left of the Hologres console, click Go To HoloWeb to open the HoloWeb page. You can then perform schema design and data development. For more information, see Connect to HoloWeb and execute a query.

JDBC and PSQL client logon

Starting from Hologres V2.0, Hologres supports specifying a security token in the connection options of the PostgreSQL protocol. You can use a security token to log on to and access Hologres as a RAM role through a PostgreSQL client, such as Java Database Connectivity (JDBC) or PSQL.

Before you access Hologres, confirm that you have completed the following operations:

You have added the RAM role to the Hologres instance and granted permissions. For more information, see Step 2: Add the RAM role to a Hologres instance and grant permissions.

You have called the AssumeRole API operation in RAM to obtain the STS token trituple (AccessKeyId, AccessKeySecret, and SecurityToken). For more information, see STS SDK call examples. The following is sample STS token information:

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

After you confirm that the operations are complete, you can connect to and access Hologres in the following ways.

JDBC Java connection method: For more information, see Connect to Hologres using JDBC.

Sample code 1: Load the STS token trituple to complete identity verification using the properties of the PGProperty class provided by the PostgreSQL JDBC Driver.

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 {
         // This example shows how to save the AccessKey ID and AccessKey secret in environment variables. You can also save them in a configuration file as needed.
	// We strongly recommend that you do not hardcode the AccessKey ID and AccessKey secret in your code. This can cause key leaks.
        String accessKeyId = "ALIBABA_CLOUD_ACCESS_KEY_ID";
        String accessKeySecret = "ALIBABA_CLOUD_ACCESS_KEY_SECRET";
        String securityToken = "<SecurityToken>";
        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");
        // Process the resultSet
        while (resultSet.next()) {
            System.out.println("Result: " + resultSet.getInt(1));
            System.out.println("Result: " +  resultSet.getString(2));
        }
    }
}

Sample code 2: URL-encode the SecurityToken information and append it to the JDBC URL. Then, when obtaining the Hologres connection through the driver class, load the AccessKeyId and AccessKeySecret for identity verification.

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

public class JdbcLinkHologres2 {
    public static void main(String[] args) throws IOException, ClassNotFoundException, SQLException {
        // This example shows how to save the AccessKey ID and AccessKey secret in environment variables. You can also save them in a configuration file as needed.
	// We strongly recommend that you do not hardcode the AccessKey ID and AccessKey secret in your code. This can cause key leaks.
        String accessKeyId = "ALIBABA_CLOUD_ACCESS_KEY_ID";
        String accessKeySecret = "ALIBABA_CLOUD_ACCESS_KEY_SECRET";
        String securityToken = "<SecurityToken>";
                    
        String url = "jdbc:postgresql://<host>:<port>/<database>";
        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");

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

PSQL client connection method: The following is the statement for a Linux system. For more information, see Connect to Hologres using a PSQL client.
```
PGUSER=<AccessKeyId> PGPASSWORD=<AccessKeySecret> PGOPTIONS="sts_token=<SecurityToken>" psql -h <host> -p <port> -d <database>
```

FAQ

What do I do if the error password authentication failed for user "<AccessKeyId>" is reported when I log on as a RAM role?

This error indicates that the AccessKeyId, AccessKeySecret, or Security Token may be incorrect, or the logon user has not been created in the Hologres instance. We recommend that you perform the following checks in order:

Check whether the logon user exists in the instance. If not, add the RAM role to the instance. For more information, see Step 2: Add the RAM role to a Hologres instance and grant permissions.
Check whether the Security Token is passed correctly. If it is passed through a URL, it must be processed using URLEncoder.encode.
Check whether the AccessKeyId, AccessKeySecret, and Security Token are correct.