RAM role authorization mode

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

Background information

Alibaba Cloud allows enterprise users to manage and use cloud resources by logging on to the Alibaba Cloud management console with an account and password. As enterprise security and compliance requirements become stricter, many organizations prefer to use role-based single sign-on (SSO) to access 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, to meet increasingly strict security requirements and to centralize identity and access management, many enterprises adopt single sign-on (SSO). SSO allows users to log on once and access multiple trusted application systems. Hologres now supports role-based SSO. For more information, see Overview of SAML-based role SSO. This feature allows you to use your corporate identity to assume a RAM role and access a Hologres instance. The RAM role controls access permissions. The following diagram shows a sample call flow. 适用场景

A user opens a browser and selects Alibaba Cloud as the target service on the identity provider (IdP) logon page.
For example, if your enterprise IdP is 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 is redirected to the SSO service page and forwards the SAML response to the SSO service.
The SSO service uses the SAML response to request temporary security credentials from Alibaba Cloud Security Token Service (STS) and generates a URL to log on to the Alibaba Cloud management console.
Note
If the SAML response contains attributes that map to multiple RAM roles, the system prompts the user to select a role to access Alibaba Cloud.
The SSO service returns the URL to the browser.
The browser is redirected to the URL. The user logs on to the Alibaba Cloud management console as the specified RAM role and accesses the Hologres instance.

Supported access methods for Hologres

Hologres supports the following two access methods:

Access Hologres by using an Alibaba Cloud account or a RAM user.
You can log on to the Alibaba Cloud management console with your account and password and then use Hologres with that account. In this case, the Alibaba Cloud account becomes a member of a Hologres instance and receives permissions to use the product.
Access Hologres by using role-based SSO.
You can also log on to Alibaba Cloud by using role-based SSO (see Overview of SAML-based role SSO) to use Hologres. In this case, the RAM role becomes a member of a Hologres instance. Users who assume this RAM role have the same product permissions as account-based members. 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. A RAM role is a standard logon account. A superuser must grant permissions—such as SELECT, INSERT, and UPDATE—directly to the RAM role, not to the underlying account. A user who assumes the RAM role can then access Hologres with the granted permissions.

Role-based SSO (STS)

Role-based SSO access to Hologres uses Alibaba Cloud Security Token Service (STS). STS is a cloud service that provides temporary access management for Alibaba Cloud accounts or RAM users. You can use STS to issue access credentials with custom validity periods and permissions to your users, such as users managed by your local account system. Users can use the temporary security credentials from STS to directly connect to Hologres and access authorized resources.

Using STS tokens provides the following benefits:

Reduces the risk of credential leaks. You only need to generate temporary credentials for users, which eliminates the need to manage long-term AccessKey pairs.
Enables flexible access control. Temporary credentials expire automatically, which eliminates the need for manual revocation.

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

Log on to the Resource Access Management (RAM) console to create a RAM role. You can select Alibaba Cloud Account or Identity Provider as the trusted entity type.

If you want to assume the role by switching identities in the Alibaba Cloud management console, select Alibaba Cloud Account as the trusted entity. For more information, see Grant access to a RAM user by assuming a role.
If you want to log on to Alibaba Cloud as an on-premises IdP user and assume the role, select Identity Provider as the trusted entity. For more information, see Grant access to an IdP user by assuming a role.

Role assumption for RAM users

If you need a RAM user to assume a RAM role by switching identities in the Alibaba Cloud management console, log on to the Resource Access Management (RAM) console to create a RAM role. Select Alibaba Cloud Account as the trusted entity.

Create a RAM role whose trusted entity type is Alibaba Cloud account.
1. Log on to the Resource Access Management (RAM) console. In the left-side navigation pane, choose Identities > Roles.
2. On the Create Role page, click Create Role. For Select Trusted Entity, select Alibaba Cloud Account. Then, select Current Alibaba Cloud account. Click OK.
3. In the Create Role panel, enter a RAM Role Name and click OK.

Create and attach a permission policy.

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

Click the Trust Policy tab. Then, click Edit Trust Policy and replace the content of the policy with the following code.

Parameter description
When you configure the policy, replace <account_id> in acs:ram::<account_id>:root with the ID of your Alibaba Cloud account. You can find the account ID on the User Information page.

Policy content

{
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
                "RAM": [
                    "acs:ram::<account_id>:root"
                ]
            }
        },
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "dataworks.aliyuncs.com"
                ]
            }
        }
    ],
    "Version": "1"
}

Click OK to complete the policy configuration.

Create a RAM user and grant permissions to assume the role.
To allow a RAM user to assume a RAM role, you must grant that user the necessary permissions.
1. Log on to the Resource Access Management (RAM) console. In the left-side navigation pane, choose Identities > User.
2. (Optional) If you already have a RAM user, you can skip this step. Click Create User to create one or more RAM users at a time. For more information, see Create a RAM user.
3. Find the target RAM user and click Add Permissions in the Actions column.
4. On the Add Permissions page, attach the AliyunSTSAssumeRoleAccess policy to the RAM user. This policy grants the user the permission to call the AssumeRole API operation of STS.
5. Click OK.

Role assumption for IdP users

If you need to log on to Alibaba Cloud as an on-premises IdP user and assume a RAM role, log on to the Resource Access Management (RAM) console to create a RAM role. Select Identity Provider as the trusted entity.

Create a RAM role with a trusted entity type of Identity Provider.
1. Log on to the Resource Access Management (RAM) console. In the left-side navigation pane, choose Identities > Role.
2. On the Role page, click Create Role. For Select Trusted Entity, select Identity Provider.
3. Click OK and configure Role Name and Remarks.
4. Select the IdP Type and Select IdP. After reviewing the conditions, click Complete. A message appears, indicating that the role is created.

Create and attach a permission policy.

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

Click the Trust Policy tab. Then, click Edit Trust Policy and replace the content of the policy with the following code.

Parameter description
When you configure the policy, you need to replace the root account ID in the script acs:ram::Root-Account-ID:saml-provider/IDP with your account ID. Go to the User Information page to obtain the account ID.

Policy content

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

Click OK to complete the policy configuration.

Step 2: Add and authorize the RAM role

A RAM role must have development permissions on a Hologres instance to use Hologres. By default, a RAM role does not have permissions to view or manage instances in the Hologres console. The root account must grant the required RAM permissions before you can proceed. For more information, see Grant permissions to a RAM user. You can use one of the following methods to add the RAM role to the Hologres instance and grant permissions.

Authorize the role in the Hologres management console.
1. In the left-side navigation pane, click Instances. Click the instance that you want to authorize. On the User Management tab, find the RAM role and add it as a user to the instance.
2. On the DB-level Authorization tab, grant the required development permissions to the RAM user.
Authorize the role by using SQL.
You can grant permissions by using SQL statements. For more information, see Permission management overview.
If a RAM user assumes a RAM role, the RAM role does not have permissions in the Hologres management console by default. The root account must grant the AliyunRAMReadOnlyAccess permission to the RAM user in the Resource Access Management (RAM) console. Otherwise, the RAM role cannot perform any operations in the Hologres console. For more information, see Grant permissions to a RAM user.

Step 3: Log on and use Hologres

Console and HoloWeb logon

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

Log on to the Hologres management console as the RAM role to manage the Hologres instance.
In the Hologres management console, click Go to HoloWeb in the left-side navigation pane to open HoloWeb. You can then perform schema design and data development. For more information, see Connect to HoloWeb and run a query.

JDBC and psql client logon

Starting from Hologres V2.0, you can specify a security token in the connection options of the PostgreSQL protocol. This allows you to log on to and access Hologres as a RAM role by using a PostgreSQL client, such as a JDBC or psql client, with a security token.

Before you access Hologres, ensure you have completed the following:

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 of Resource Access Management (RAM) to obtain temporary security credentials, which include an AccessKeyId, an AccessKeySecret, and a SecurityToken. For more information, see STS SDK examples. The following code shows a sample response:
```
"Credentials": {
    "SecurityToken": "CAISuwJ1q6Ft5B2yu****KiAA",
    "AccessKeyId": "STS.NTKaenSkmLhG4HpM5****76UV",
    "AccessKeySecret": "6itECZnhbG2RU6ktTSBSd6JxeLHKPWyBt****SS62",
    "Expiration": "2025-02-21T03:47:07Z"
  }
```

You can then use the following methods to connect to Hologres.

Connect by using JDBC. For more information, see Connect to Hologres by using JDBC.

Example 1: Load the STS temporary credentials by using the properties of the PGProperty class in the PostgreSQL JDBC Driver to complete identity verification.

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 store the AccessKeyId and AccessKeySecret in environment variables. You can also store them in a configuration file based on your business needs.
	// We strongly recommend that you do not hard-code the AccessKeyId and AccessKeySecret in your code to prevent credential 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));
        }
    }
}

Example 2: URL-encode the SecurityToken and append it to the JDBC URL. Then, load the AccessKeyId and AccessKeySecret for identity verification when the driver class obtains the Hologres connection.

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 store the AccessKeyId and AccessKeySecret in environment variables. You can also store them in a configuration file based on your business needs.
	// We strongly recommend that you do not hard-code the AccessKeyId and AccessKeySecret in your code to prevent credential 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));
        }
    }
}

Connect by using a psql client. The following command is for Linux systems. For more information, see Connect to Hologres by 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 SecurityToken may be incorrect, or the logon user does not exist in the Hologres instance. We recommend that you troubleshoot the issue in the following 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 SecurityToken is passed correctly. If it is passed in a URL, the token must be encoded by using URLEncoder.encode.
Check whether the AccessKeyId, AccessKeySecret, and SecurityToken are correct.