Object Storage Service:How to configure access credentials by using OSS SDK for Node.js

Select a credential provider

OSS supports multiple methods to initialize a credential provider. You can select a suitable method based on the authentication and authorization requirements of your actual scenario.

Method 1: Use an AccessKey pair

If your application is deployed in a secure and stable environment that is not vulnerable to external attacks and requires long-term access to OSS, you can use an AccessKey pair of your Alibaba Cloud account or a RAM user to initialize a credential provider. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. Take note that this method requires you to manually maintain an AccessKey pair. This poses security risks and increases maintenance complexity. For more information about how to obtain an AccessKey pair, see CreateAccessKey.

1. Configure environment variables.

   Mac OS X/Linux/Unix

   export ALIBABA_CLOUD_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
   export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>

   Windows

   set ALIBABA_CLOUD_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
   set ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>

2. Use the AccessKey pair to initialize the client.

   const OSS = require("ali-oss");
   
   // Initialize the OSSClient instance.
   const client = new OSS({
     // Obtain the AccessKey ID from the environment variable.
     accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
     // Obtain the AccessKey secret from the environment variable.
     accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);
   

Method 2: Use a security token

You need to call the AssumeRole operation of STS as a RAM user and specify the maximum validity period of the security token. This way, you can obtain a security token.

1. Configure environment variables.

   Mac OS X/Linux/Unix

   export ALIBABA_CLOUD_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
   export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>
   export ALIBABA_CLOUD_SECURITY_TOKEN=<ALIBABA_CLOUD_SECURITY_TOKEN>

   Windows

   set ALIBABA_CLOUD_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
   set ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>
   set ALIBABA_CLOUD_SECURITY_TOKEN=<ALIBABA_CLOUD_SECURITY_TOKEN>

2. Use the temporary access credentials to initialize the OSSClient instance.

   const OSS = require("ali-oss");
   
   // Initialize the OSSClient instance.
   const client = new OSS({
     // Obtain the AccessKey ID from the environment variable.
     accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
     // Obtain the AccessKey secret from the environment variable.
     accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
     // Obtain the security token from the environment variable.
     stsToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

Method 3: Use RAMRoleARN

The underlying logic of this method is to use a security token obtained from STS to configure access credentials. After you specify the Alibaba Cloud Resource Name (ARN) of a RAM role, the Credentials tool obtains the security token from STS. You can also use the policy parameter to limit the permissions of the RAM role.

Use the AccessKey pair and RAMRoleARN to initialize the OSSClient instance.

const Credential = require("@alicloud/credentials");
const OSS = require("ali-oss");

// Use the ARN of your RAM role to initialize the Credentials client. 
const credentialsConfig = new Credential.Config({
  // Specify the credential type. 
  type: "ram_role_arn",
  // Obtain the AccessKey ID from the environment variable.
  accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
  // Obtain the AccessKey secret from the environment variable.
  accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
  // Specify the ARN of the RAM role that you want your application to assume by specifying the ALIBABA_CLOUD_ROLE_ARN environment variable. Example: acs:ram::123456789012****:role/adminrole.
  roleArn: '<RoleArn>',
  // Specify the role session name by specifying the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
  roleSessionName: '<RoleSessionName>',
  // Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
  // policy: '<Policy>',
  roleSessionExpiration: 3600
});
const credentialClient = new Credential.default(credentialsConfig);
const credential = await credentialClient.getCredential();

// Initialize the OSSClient instance.
const client = new OSS({
  accessKeyId:credential.accessKeyId,
  accessKeySecret: credential.accessKeySecret,
  stsToken: credential.securityToken,
  refreshSTSTokenInterval: 0, // Specify that Credential manages the update of the AccessKey ID, AccessKey secret, and security token.
  refreshSTSToken: async () => {
    const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
    return {
      accessKeyId,
      accessKeySecret,
      stsToken: securityToken,
    };
  }
});

// listBuckets
const buckets = await client.listBuckets();
console.log( buckets);

Method 4: Use the RAM role obtained by using the security hardening mode of the metadata of the ECS instance

The underlying logic of this method is to use a security token obtained from STS to configure access credentials. The Credentials tool automatically obtains the RAM role attached to an ECS instance and obtains the security token of the attached role by using the metadata server of the ECS instance. The security token is used to initialize a Credentials client. Use the Credentials tool to read the security token and initialize the Credentials client.

const Credential = require("@alicloud/credentials");
const OSS = require("ali-oss");

// Use the ARN of your RAM role to initialize the Credentials client. 
const credentialsConfig = new Credential.Config({
  // Specify the credential type. 
  type: "ecs_ram_role",
  // Optional. Specify the name of the RAM role attached to an ECS instance by specifying the ALIBABA_CLOUD_ECS_METADATA environment variable. If you do not specify this parameter, the name of the RAM role attached to an ECS instance is automatically obtained. We recommend that you specify this parameter to reduce the number of requests.
  roleName: '<RoleName>'
});
const credentialClient = new Credential.default(credentialsConfig);

const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();

// Initialize the OSSClient instance.
const client = new OSS({
  accessKeyId,
  accessKeySecret,
  stsToken: securityToken,
  refreshSTSTokenInterval: 0, // Specify that Credential manages the update of the AccessKey ID, AccessKey secret, and security token.
  refreshSTSToken: async () => {
    const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
    
    return {
      accessKeyId,
      accessKeySecret,
      stsToken: securityToken,
    };
  }
});

// listBuckets
const buckets = await client.listBuckets();
console.log(buckets);

Method 5: Use OIDCRoleARN

After a RAM role is configured on the ACK worker node, the application in a pod on the node can obtain the security token of the attached role by using the metadata server in the same manner as an application deployed on an ECS instance does. However, if an untrusted application is deployed on the worker node, such as an application that is submitted by your customer and whose code is unavailable to you, you may not want the application to use the metadata server to obtain a security token of the RAM role attached to the worker node. To ensure the security of cloud resources, allow untrusted applications to securely obtain the required security token, and minimize application-level permissions, you can use the RAM Roles for Service Account (RRSA) feature. ACK creates and mounts corresponding OpenID Connect (OIDC) token files for different application pods, and passes relevant configuration information to environment variables. The Credentials tool obtains the configurations of environment variables and calls the AssumeRoleWithOIDC operation of STS to obtain the security token of attached role. For more information, see Use RRSA to authorize different pods to access different cloud services.

Configure OIDCRoleARN as the access credential to initialize the client.

const OSS = require("ali-oss");
const Credential = require("@alicloud/credentials");

const credentialsConfig = new Credential.Config({
  // Specify the credential type. 
  type: "oidc_role_arn",
  // Specify the ARN of the RAM role by specifying the ALIBABA_CLOUD_ROLE_ARN environment variable.
  roleArn: '<RoleArn>',
  // Specify the ARN of the OIDC IdP by specifying the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
  oidcProviderArn: '<OidcProviderArn>',
  // Specify the path of the OIDC token file by specifying the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
  oidcTokenFilePath: '<OidcTokenFilePath>',
  // Specify the role session name by specifying the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
  roleSessionName: '<RoleSessionName>',
  // Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
  // policy: "<Policy>",
  // Specify the validity period of the session.
  roleSessionExpiration: 3600
});
const credentialClient = new Credential.default(credentialsConfig);
const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
const client = new OSS({
  accessKeyId,
  accessKeySecret,
  stsToken: securityToken,
  refreshSTSTokenInterval: 0, // Specify that Credential manages the update of the AccessKey ID, AccessKey secret, and security token.
  refreshSTSToken: async () => {
    const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
    
    return {
      accessKeyId,
      accessKeySecret,
      stsToken: securityToken,
    };
  }
});
const buckets = await client.listBuckets();

console.log(buckets);

Method 6: Use CredentialsURI

If your application needs to obtain an Alibaba Cloud credential from an external system to implement flexible credential management and keyless access, you can use the CredentialsURI to initialize a credential provider. The underlying logic of this method is to use a security token obtained from STS to configure access credentials. The Credentials tool obtains the security token by using the URI that you specify to initialize an OSSClient instance on the client. This method eliminates the risks that may arise when you manually maintain an AccessKey pair or a security token. Take note that the backend service that provides the CredentialsURI response must automatically refresh the security token to ensure that your application can always obtain a valid credential.

1. To allow the Credentials tool to correctly parse and use a security token, the URI must comply with the following response protocol:

   • Response status code: 200

   • Response body structure:

     {
       "Code": "Success",
       "AccessKeySecret": "AccessKeySecret",
       "AccessKeyId": "AccessKeyId",
       "Expiration": "2021-09-26T03:46:38Z",
       "SecurityToken": "SecurityToken"
     }

2. Configure the CredentialsURI as the access credential to initialize the client.

   const OSS = require("ali-oss");
   const Credential = require("@alicloud/credentials");
   
   // Use the URI of the credential to initialize the Credentials client. 
   const credentialsConfig = new Credential.Config({
     // Specify the credential type. 
     type: "credentials_uri",
     // Specify the URI of the credential in the http://local_or_remote_uri/ format by specifying the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
     credentialsURI: '<CredentialsUri>'
   });
   const credentialClient = new Credential.default(credentialsConfig);
   const credential = await credentialClient.getCredential();
   
   // Initialize the OSSClient instance.
   const client = new OSS({
     accessKeyId: credential.accessKeyId,
     accessKeySecret: credential.accessKeySecret,
     stsToken: credential.securityToken,
     refreshSTSTokenInterval: 0, // Specify that Credential manages the update of the AccessKey ID, AccessKey secret, and security token.
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
   
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);