Node.js如何配置訪問憑證 - Object Storage Service

使用Node.js SDK發起OSS請求，您需要配置訪問憑證。阿里雲服務會通過訪問憑證驗證您的身份資訊和存取權限。您可以根據使用情境對認證和授權的要求，選擇不同的方式提供憑證。

前提條件

在配置訪問憑證前，您需要安裝OSS Node.js SDK。詳情請參見安裝。

初始化憑證提供者

憑證提供者選型

OSS支援多種方式初始化憑證提供者，您可以根據使用情境對認證和授權的要求，選擇對應的方式初始化憑證提供者。

憑證提供者初始化方式	適用情境	是否需要提供前置的AK或STS Token	底層實現基於的憑證	憑證有效期間	憑證輪轉或重新整理方式
方式一：使用AK	部署運行在安全、穩定且不易受外部攻擊的環境的應用程式，無需頻繁輪轉憑證就可以長期訪問雲端服務	是	AK	長期	手動輪轉
方式二：使用STS Token	部署運行在不可信的環境的應用程式，希望能控制訪問的有效期間、許可權	是	STS Token	臨時	手動重新整理
方式三：使用RAMRoleARN	需要授權訪問雲端服務，例如跨阿里雲帳號訪問雲端服務的應用程式	是	STS Token	臨時	自動重新整理
方式四：通過ECS執行個體中繼資料普通模式擷取RAM角色	部署運行在阿里雲的ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中的應用程式	否	STS Token	臨時	自動重新整理
方式五：使用OIDCRoleArn	部署運行在阿里雲的Container ServiceKubernetes版的Worker節點中的不可信應用程式	否	STS Token	臨時	自動重新整理
方式六：使用CredentialsURI	需要通過外部系統擷取訪問憑證的應用程式	否	STS Token	臨時	自動重新整理

方式一：使用AK

如果您的應用程式部署運行在安全、穩定且不易受外部攻擊的環境中，需要長期訪問您的OSS，且不能頻繁輪轉憑證時，您可以使用阿里雲主帳號或RAM使用者的AK（Access Key ID、Access Key Secret）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個AK，存在安全性風險和維護複雜度增加的風險。如何擷取AK，請參見CreateAccessKey - 建立主帳號或RAM使用者存取金鑰。

警告

阿里雲帳號擁有資源的全部許可權，AK一旦泄露，會給系統帶來巨大風險，不建議使用。推薦使用最小化授權的RAM使用者的AK。

設定環境變數。

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>

使用AK完成用戶端初始化。

const OSS = require("ali-oss");

// 初始化OSS
const client = new OSS({
  // 從環境變數中擷取AccessKey ID的值
  accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
  // 從環境變數中擷取AccessKey Secret的值
  accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET
});

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

方式二：使用STS Token

以一個RAM使用者的身份調用STS服務的AssumeRole - 擷取扮演角色的臨時身份憑證介面，設定Token的最大到期時間，即可換取到臨時憑證STS Token。

設定環境變數。

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>

使用臨時憑證完成用戶端初始化。

const OSS = require("ali-oss");

// 初始化OSS
const client = new OSS({
  // 從環境變數中擷取AccessKey ID的值
  accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
  // 從環境變數中擷取AccessKey Secret的值
  accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
  // 從環境變數中擷取STS Token的值
  stsToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN
});

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

方式三：使用RAMRoleARN

該方式底層實現是STS Token。通過指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具可以協助開發人員前往STS換取STS Token。您也可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。

使用AK和RAMRoleARN初始化Credentials，完成用戶端初始化。

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

// 使用RamRoleArn初始化Credentials Client。
const credentialsConfig = new Credential.Config({
  // 憑證類型。
  type: "ram_role_arn",
  // 從環境變數中擷取AccessKey ID的值
  accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
  // 從環境變數中擷取AccessKey Secret的值
  accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
  // 要扮演的RAM角色ARN，樣本值：acs:ram::123456789012****:role/adminrole，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定roleArn
  roleArn: '<RoleArn>',
  // 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定RoleSessionName
  roleSessionName: '<RoleSessionName>',
  // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
  // policy: '<Policy>',
  roleSessionExpiration: 3600
});
const credentialClient = new Credential.default(credentialsConfig);
const credential = await credentialClient.getCredential();

// 初始化OSS
const client = new OSS({
  accessKeyId:credential.accessKeyId,
  accessKeySecret: credential.accessKeySecret,
  stsToken: credential.securityToken,
  refreshSTSTokenInterval: 0, // 由Credential控制accessKeyId、accessKeySecret和stsToken值的更新
  refreshSTSToken: async () => {
    const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
    return {
      accessKeyId,
      accessKeySecret,
      stsToken: securityToken,
    };
  }
});

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

方式四：通過ECS執行個體中繼資料普通模式擷取RAM角色

該方式底層實現是STS Token。Credentials工具會自動擷取ECS執行個體綁定的RAM角色，調用ECS的中繼資料服務（Meta Data Server）換取STS Token，完成憑據用戶端初始化。通過Credentials工具讀取STS Token，完成用戶端初始化。

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

// 使用RamRoleArn初始化Credentials Client。
const credentialsConfig = new Credential.Config({
  // 憑證類型。
  type: "ecs_ram_role",
  // 選填，該ECS角色的角色名稱，不填會自動擷取，但是建議加上以減少請求次數，可以通過環境變數ALIBABA_CLOUD_ECS_METADATA設定roleName
  roleName: '<RoleName>'
});
const credentialClient = new Credential.default(credentialsConfig);

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

// 初始化OSS Client
const client = new OSS({
  accessKeyId,
  accessKeySecret,
  stsToken: securityToken,
  refreshSTSTokenInterval: 0, // 由Credential控制accessKeyId、accessKeySecret和stsToken值的更新
  refreshSTSToken: async () => {
    const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
    
    return {
      accessKeyId,
      accessKeySecret,
      stsToken: securityToken,
    };
  }
});

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

方式五：使用OIDCRoleArn

在Container Service Kubernetes 版中設定了Worker節點RAM角色後，對應節點內的Pod中的應用也就可以像ECS上部署的應用一樣，通過中繼資料服務（Meta Data Server）擷取關聯角色的STS Token。但如果容器叢集上部署的是不可信的應用（比如部署您的客戶提交的應用，代碼也沒有對您開放），您可能並不希望它們能通過中繼資料服務擷取Worker節點關聯執行個體RAM角色的STS Token。為了避免影響雲上資源的安全，同時又能讓這些不可信的應用安全地擷取所需的 STS Token，實現應用層級的許可權最小化，您可以使用RRSA（RAM Roles for Service Account）功能。阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，Credentials工具通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC - OIDC角色SSO時擷取扮演角色的臨時身份憑證介面換取綁定角色的STS Token。詳情請參見通過RRSA配置ServiceAccount的RAM許可權實現Pod許可權隔離。

配置OIDC的RAM角色作為訪問憑證，完成用戶端初始化。

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

const credentialsConfig = new Credential.Config({
  // 憑證類型。
  type: "oidc_role_arn",
  // RAM角色名稱ARN，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定roleArn
  roleArn: '<RoleArn>',
  // OIDC供應商ARN，可以通過環境變數ALIBABA_CLOUD_OIDC_PROVIDER_ARN設定oidcProviderArn
  oidcProviderArn: '<OidcProviderArn>',
  // OIDC Token檔案路徑，可以通過環境變數ALIBABA_CLOUD_OIDC_TOKEN_FILE設定oidcTokenFilePath
  oidcTokenFilePath: '<OidcTokenFilePath>',
  // 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定roleSessionName
  roleSessionName: '<RoleSessionName>',
  // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
  // policy: "<Policy>",
  // 設定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, // 由Credential控制accessKeyId、accessKeySecret和stsToken值的更新
  refreshSTSToken: async () => {
    const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
    
    return {
      accessKeyId,
      accessKeySecret,
      stsToken: securityToken,
    };
  }
});
const buckets = await client.listBuckets();

console.log(buckets);

方式六：使用CredentialsURI

如果您的應用程式需要通過外部系統擷取阿里雲憑證，從而實現靈活的憑證管理和無密鑰訪問，您可以使用CredentialsURI初始化憑證提供者。該方式底層實現是STS Token。Credentials工具通過您提供的URI擷取STS Token，完成憑證用戶端初始化。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。需要注意的是，提供CredentialsURI響應的後端服務需要實現STS Token的自動重新整理邏輯，確保您的應用程式始終能擷取到有效憑證。

為了使Credentials工具正確解析和使用STS Token，URI必須遵循以下響應協議：

響應狀態代碼：200

響應體結構：

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

配置CredentialsURI作為訪問憑證，完成用戶端初始化。

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

// 通過憑證的 URI 初始化Credentials Client。
const credentialsConfig = new Credential.Config({
  // 憑證類型。
  type: "credentials_uri",
  // 擷取憑證的 URI，格式為http://local_or_remote_uri/，可以通過環境變數ALIBABA_CLOUD_CREDENTIALS_URI設定credentialsUri
  credentialsURI: '<CredentialsUri>'
});
const credentialClient = new Credential.default(credentialsConfig);
const credential = await credentialClient.getCredential();

// 初始化OSS
const client = new OSS({
  accessKeyId: credential.accessKeyId,
  accessKeySecret: credential.accessKeySecret,
  stsToken: credential.securityToken,
  refreshSTSTokenInterval: 0, // 由Credential控制accessKeyId、accessKeySecret和stsToken值的更新
  refreshSTSToken: async () => {
    const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();

    return {
      accessKeyId,
      accessKeySecret,
      stsToken: securityToken,
    };
  }
});

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

後續步驟

初始化憑證提供者後，您需要使用憑證提供者來建立OSSClient執行個體。詳情請參見初始化。