Alibaba Cloud SDK を使用してクラウド リソースを管理するための API 操作を呼び出す場合は、有効なクレデンシャル情報を構成する必要があります。 Alibaba Cloud の Credentials ツールは、使い易い機能セットを提供し、デフォルトクレデンシャル、AccessKey ペア、Security Token Service (STS) トークンなど、様々な種類のクレデンシャルをサポートしています。 Credentials ツールは、クレデンシャルの取得と管理に役立ちます。このトピックでは、異なるタイプのクレデンシャルを構成する方法と、Credentials ツールがデフォルトクレデンシャルを取得する順序について説明します。 Alibaba Cloud SDK でのクレデンシャルの構成と管理について、徹底的に理解することができます。これにより、クラウド リソースに対する操作を効率的かつ安全に実行できるようになります。
背景情報
クレデンシャルとは、ユーザーの身元を証明するために使用される一連の情報です。システムにログオンするときは、有効なクレデンシャルを使用して身元認証を完了する必要があります。一般的に使用されるクレデンシャルの種類は次のとおりです。
Alibaba Cloud アカウントまたは Resource Access Management (RAM) ユーザーの AccessKey ペア。 AccessKey ペアは永続的に有効で、AccessKey ID と AccessKey シークレットで構成されます。
RAM ロールの STS トークン。 STS トークンは一時的なクレデンシャルです。 STS トークンの有効期間とアクセス許可を指定できます。詳細については、「STS とは」をご参照ください。
ベアラトークン。ID 認証と承認に使用されます。
前提条件
Node.js 8.5.0 以降がインストールされている。
Alibaba Cloud SDK V2.0 がインストールされている。詳細については、「IDE で Alibaba Cloud SDK for Node.js を使用する」をご参照ください。
Credentials ツールのインストール
次の npm コマンドを実行して、Alibaba Cloud Credentials for Node.js をダウンロードしてインストールします。
npm install @alicloud/credentialsすべてのクレデンシャルがサポートされるように、Alibaba Cloud Credentials for Node.js の最新バージョンを使用することをお勧めします。バージョンのリストについては、「Releases · aliyun/credentials-nodejs · GitHub」をご参照ください。
Credentials ツールのパラメーター
Credentials ツールのパラメーターは、@alicloud/credentials モジュールの Config コンストラクターで定義されています。クレデンシャルタイプは、構成で必須パラメーターである type パラメーターによって指定されます。クレデンシャルタイプを決定したら、クレデンシャルタイプに基づいてパラメーターを構成します。次の表では、type の有効な値と、各クレデンシャルタイプでサポートされているパラメーターについて説明します。表では、チェックマーク (✓) はパラメーターが必須であることを示し、ハイフン (-) はパラメーターがオプションであることを示し、X マーク (×) はパラメーターがサポートされていないことを示します。
次の表に記載されていないパラメーターは使用しないことをお勧めします。
type | access_key | sts | ram_role_arn | ecs_ram_role | oidc_role_arn | credentials_uri | bearer |
accessKeyId: AccessKey ID です。 | ✓ | ✓ | ✓ | × | × | × | × |
accessKeySecret: AccessKey シークレット。 | ✓ | ✓ | ✓ | × | × | × | × |
securityToken: Security Token Service (STS) トークン。 | × | ✓ | - | × | × | × | × |
roleArn: Resource Access Management (RAM) ロールのAlibaba Cloud Resource Name (ARN)。 | × | × | ✓ | × | ✓ | × | × |
roleSessionName: カスタムセッションの名前。デフォルトのフォーマットは | × | × | - | × | - | × | × |
roleName: RAM ロールの名前を指定します。 | × | × | × | - | × | × | × |
disableIMDSv1: セキュリティ強化モード(IMDSv2)を強制的に使用するかどうかを指定します。このパラメーターを true に設定すると、セキュリティ強化モード(IMDSv2)が使用されます。デフォルト値: | × | × | × | - | × | × | × |
bearerToken: ベアラトークン。 | × | × | × | × | × | × | ✓ |
policy: カスタムポリシー。 | × | × | - | × | - | × | × |
roleSessionExpiration: セッションタイムアウト期間。デフォルト値:3600。単位:秒。 | × | × | - | × | - | × | × |
oidcProviderArn: OpenID Connect(OIDC)ID プロバイダー(IdP)の ARN です。 | × | × | × | × | ✓ | × | × |
oidcTokenFilePath: OIDC トークンへの絶対パス。 | × | × | × | × | ✓ | × | × |
externalId: ロールの外部 ID。Confused Deputy 問題を防ぐために使用されます。詳細については、「外部 ID を使用して Confused Deputy 問題を防ぐ」をご参照ください。 | × | × | - | × | × | × | × |
credentialsURI: 資格情報の URI です。 | × | × | × | × | × | ✓ | × |
STSEndpoint: STS のエンドポイント。仮想プライベートクラウド (VPC) エンドポイントとインターネットエンドポイントがサポートされています。デフォルト値: | × | × | - | × | - | × | × |
timeout: HTTP 読み取りリクエストのタイムアウト期間。デフォルト値:5000。単位:ミリ秒。 | × | × | - | - | - | - | × |
connectTimeout: HTTP 接続リクエストのタイムアウト期間。デフォルト値:10000。単位:ミリ秒。 | × | × | - | - | - | - | × |
Credentials クライアントの初期化
ビジネス要件に基づき、以下のいずれかの方法で Credentials クライアントを初期化できます:
プロジェクトでプレーンテキストの AccessKey ペアを使用すると、コードリポジトリの権限管理が不適切なために AccessKey ペアが漏洩する可能性があります。これにより、AccessKey ペアが属するアカウント内のすべてのリソースのセキュリティが脅かされる可能性があります。 AccessKey ペアは環境変数または構成ファイルに保存することをお勧めします。
Credentials クライアントはシングルインスタンスモードで初期化することをお勧めします。このモードでは、SDK の資格情報キャッシュ機能が有効になるだけでなく、複数回の API 呼び出しによって発生するトラフィック制御の問題とパフォーマンスリソースの浪費を効果的に防ぐことができます。 詳細については、この Topic の「セッション資格情報の自動更新メカニズム」セクションをご参照ください。
方法 1: デフォルトの認証情報プロバイダーチェーン
Credentials クライアントを初期化する方法を指定しない場合、デフォルトの認証情報プロバイダーチェーンが使用されます。詳細については、「デフォルトの認証情報プロバイダーチェーン」をご参照ください。
const Credential = require('@alicloud/credentials');
// メソッドを指定せずに Credentials クライアントを初期化します。
const credentialClient = new Credential.default();
const credential = credentialClient.getCredential();
credential.then(credential => {
console.log(credential);
});
import Credential from '@alicloud/credentials';
const credential = new Credential();
credential.getCredential().then(credential => {
console.log(credential);
});例
方法2:AccessKey ペアを使用する
この方法では、AccessKey ペアを使用して Credentials クライアントを初期化します。詳細については、「AccessKey ペアの作成」をご参照ください。
Alibaba Cloud アカウントは、アカウント内のリソースに対する完全な権限を持っています。Alibaba Cloud アカウントの AccessKey ペアの漏洩は、システムにとって重大な脅威となります。
そのため、最小権限の原則(PoLP)に基づいて権限が付与された RAM ユーザーの AccessKey ペアを使用して、Credentials クライアントを初期化することをお勧めします。
const Credential = require('@alicloud/credentials');
const credentialsConfig = new Credential.Config({
// 認証情報の種類を指定します。
type: 'access_key',
// AccessKey ID を指定します。この例では、AccessKey ID は環境変数から取得されます。
accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
// AccessKey シークレットを指定します。この例では、AccessKey シークレットは環境変数から取得されます。
accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
});
const credentialClient = new Credential.default(credentialsConfig);
import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
// 認証情報の種類を指定します。
type: 'access_key',
// AccessKey ID を指定します。この例では、AccessKey ID は環境変数から取得されます。
accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
// AccessKey シークレットを指定します。この例では、AccessKey シークレットは環境変数から取得されます。
accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
});
const credentialClient = new Credential(credentialsConfig);例
方法 3: STS トークンを使用する
このメソッドでは、静的 STS トークンを使用して Credentials クライアントを初期化します。STS トークンの取得方法の詳細については、「STS とは」をご参照ください。次の例では、STS トークンを使用して Credentials クライアントを初期化する方法を示します。この例では、STS トークンの取得方法は示しません。
const Credential = require('@alicloud/credentials');
const credentialsConfig = new Credential.Config({
type: 'sts',
// AccessKey ID を指定します。この例では、AccessKey ID は環境変数から取得されます。
accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
// AccessKey Secret を指定します。この例では、AccessKey Secret は環境変数から取得されます。
accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
// セキュリティトークンを指定します。この例では、セキュリティトークンは環境変数から取得されます。
securityToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
});
const cred = new Credential.default(credentialsConfig);import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
// 認証情報タイプを指定します。
type: 'access_key',
// AccessKey ID を指定します。この例では、AccessKey ID は環境変数から取得されます。
accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
// AccessKey Secret を指定します。この例では、AccessKey Secret は環境変数から取得されます。
accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
// セキュリティトークンを指定します。この例では、セキュリティトークンは環境変数から取得されます。
securityToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
});
const credentialClient = new Credential(credentialsConfig);
例
方法 4: AccessKey ペアと RAM ロールを使用する
このメソッドの基盤となるロジックは、STS トークンを使用して Credentials クライアントを初期化することです。 RAM ロールの ARN を指定すると、Credentials ツールは STS からセキュリティトークンを取得します。 また、policy パラメーターを使用して、RAM ロールの権限を制限することもできます。
const Credential = require('@alicloud/credentials');
const credentialsConfig = new Credential.Config({
type: 'ram_role_arn',
accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
// RAM ロール の ARN を指定します。ARN は ALIBABA_CLOUD_ROLE_ARN 環境変数で指定します。例: acs:ram::123456789012****:role/adminrole。
roleArn: '<RoleArn>',
// ロールのセッション名を指定します。ロールセッション名は ALIBABA_CLOUD_ROLE_SESSION_NAME 環境変数から取得できます。
roleSessionName: '<RoleSessionName>',
// オプション。RAM ロールの制限付き権限を指定します。例: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
policy: '<Policy>',
roleSessionExpiration: 3600,
});
const cred = new Credential.default(credentialsConfig);import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
type: 'ram_role_arn',
accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
// RAM ロール の ARN を指定します。ARN は ALIBABA_CLOUD_ROLE_ARN 環境変数で指定します。例: acs:ram::123456789012****:role/adminrole。
roleArn: '<RoleArn>',
// ロールのセッション名を指定します。ロールセッション名は ALIBABA_CLOUD_ROLE_SESSION_NAME 環境変数から取得できます。
roleSessionName: '<RoleSessionName>',
// オプション。RAM ロールの制限付き権限を指定します。例: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}。
policy: '<Policy>',
roleSessionExpiration: 3600,
});
const credentialClient = new Credential(credentialsConfig);例
方法 5: ECS インスタンスの RAM ロールを使用する
ECS インスタンスと Elastic Container Instance に RAM ロールを割り当てることができます。インスタンス上で実行されるプログラムは、Credentials ツールを使用して RAM ロールの STS トークンを自動的に取得できます。STS トークンは、Credentials クライアントを初期化するために使用できます。
デフォルトでは、Credentials ツールはセキュリティ強化モード (IMDSv2) で ECS のメタデータサーバーにアクセスします。例外がスローされた場合、Credentials ツールは通常モード (IMDSv1) に切り替わります。disableIMDSv1 パラメーターまたは ALIBABA_CLOUD_IMDSV1_DISABLE 環境変数を構成して、例外処理ロジックを指定することもできます。有効な値:
false (デフォルト): Credentials ツールは、通常モード (IMDSv1) でアクセス認証情報の取得を続行します。
true: 例外がスローされ、Credentials ツールはセキュリティ強化モード (IMDSv2) でアクセス認証情報の取得を続行します。
メタデータサーバーの構成によって、サーバーがセキュリティ強化モード (IMDSv2) をサポートするかどうかが決まります。
さらに、ALIBABA_CLOUD_ECS_METADATA_DISABLED=true を指定して、Credentials ツールから ECS のメタデータサーバーへのアクセスを無効にすることができます。
セキュリティ強化モード (IMDSv2) で STS トークンを取得する場合は、Credentials ツールのバージョンが 2.3.1 以降であることを確認してください。
詳細については、「インスタンスメタデータの取得」をご参照ください。
ECS インスタンスに RAM ロールをアタッチする方法の詳細については、「インスタンス RAM ロール」トピックの「インスタンス RAM ロールの作成と ECS インスタンスへのアタッチ」セクションをご参照ください。Elastic Container Instance に RAM ロールをアタッチする方法の詳細については、「API オペレーションを呼び出してインスタンス RAM ロールを使用する」トピックの「Elastic Container Instance へのインスタンス RAM ロールの割り当て」セクションをご参照ください。
const Credential = require('@alicloud/credentials');
const credentialsConfig = new Credential.Config({
type: 'ecs_ram_role',
// オプション。 ALIBABA_CLOUD_ECS_METADATA 環境変数を指定して、ECS インスタンスの RAM ロールの名前を指定します。 このパラメーターを指定しない場合、その値は自動的に取得されます。 リクエスト数を減らすために、このパラメーターを指定することをお勧めします。
roleName: '<RoleName>',
# デフォルト値: false。 このパラメーターはオプションです。 true: セキュリティ強化モード (IMDSv2) が強制的に使用されます。 false: システムは優先的にセキュリティ強化モード (IMDSv2) でアクセス認証情報を取得しようとします。 試行が失敗した場合、システムは通常モード (IMDSv1) に切り替えてアクセス認証情報を取得します。
// disableIMDSv1: true,
});
const cred = new Credential.default(credentialsConfig);
import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
type: 'ecs_ram_role',
// オプション。 ALIBABA_CLOUD_ECS_METADATA 環境変数を指定して、ECS インスタンスの RAM ロールの名前を指定します。 このパラメーターを指定しない場合、その値は自動的に取得されます。 リクエスト数を減らすために、このパラメーターを指定することをお勧めします。
roleName: '<RoleName>',
# デフォルト値: false。 このパラメーターはオプションです。 true: セキュリティ強化モード (IMDSv2) が強制的に使用されます。 false: システムは優先的にセキュリティ強化モード (IMDSv2) でアクセス認証情報を取得しようとします。 試行が失敗した場合、システムは通常モード (IMDSv1) に切り替えてアクセス認証情報を取得します。
// disableIMDSv1: true,
});
const credentialClient = new Credential(credentialsConfig);例
方法 6: OIDC IdP の RAM ロールを使用する
クラウド リソースのセキュリティを確保し、信頼されていないアプリケーションが必要な STS トークンを安全に取得できるようにするには、サービスアカウントの RAM ロール (RRSA) 機能を使用して、アプリケーションに必要な最小限の権限を付与できます。ACK は、異なるアプリケーション ポッドに対応する OpenID Connect (OIDC) トークン ファイルを作成およびマウントし、関連する構成情報を環境変数に渡します。資格情報ツールは、環境変数から構成情報を取得し、STS の AssumeRoleWithOIDC 操作を呼び出して、アタッチされたロールの STS トークンを取得します。
次の環境変数がポッドに挿入されます。
ALIBABA_CLOUD_ROLE_ARN: RAM ロールの ARN。
ALIBABA_CLOUD_OIDC_PROVIDER_ARN: OIDC ID プロバイダー (IdP) の ARN。
ALIBABA_CLOUD_OIDC_TOKEN_FILE: OIDC トークン ファイルのパス。
const Credential = require('@alicloud/credentials');
const credentialsConfig = new Credential.Config({
type: 'oidc_role_arn',
// ALIBABA_CLOUD_ROLE_ARN 環境変数を指定して、引き受けたい RAM ロールの ARN を指定します。
roleArn: '<RoleArn>',
// ALIBABA_CLOUD_OIDC_PROVIDER_ARN 環境変数を指定して、OIDC IdP の ARN を指定します。
oidcProviderArn: '<OidcProviderArn>',
// ALIBABA_CLOUD_OIDC_TOKEN_FILE 環境変数を指定して、OIDC トークンファイルのパスを指定します。
oidcTokenFilePath: '<OidcTokenFilePath>',
// ロールセッション名を指定します。ALIBABA_CLOUD_ROLE_SESSION_NAME 環境変数からロールセッション名を取得できます。
roleSessionName: '<RoleSessionName>',
// オプション。RAM ロールの制限付き権限を指定します。例: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}。
policy: '<Policy>',
// セッションの有効期間を指定します。
roleSessionExpiration: 3600,
});
const credentialClient = new Credential.default(credentialsConfig);import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
type: 'oidc_role_arn',
// ALIBABA_CLOUD_ROLE_ARN 環境変数を指定して、引き受けたい RAM ロールの ARN を指定します。
roleArn: '<RoleArn>',
// ALIBABA_CLOUD_OIDC_PROVIDER_ARN 環境変数を指定して、OIDC IdP の ARN を指定します。
oidcProviderArn: '<OidcProviderArn>',
// ALIBABA_CLOUD_OIDC_TOKEN_FILE 環境変数を指定して、OIDC トークンファイルのパスを指定します。
oidcTokenFilePath: '<OidcTokenFilePath>',
// ロールセッション名を指定します。ALIBABA_CLOUD_ROLE_SESSION_NAME 環境変数からロールセッション名を取得できます。
roleSessionName: '<RoleSessionName>',
// オプション。RAM ロールの制限付き権限を指定します。例: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}。
policy: '<Policy>',
// セッションの有効期間を指定します。
roleSessionExpiration: 3600,
});
const credentialClient = new Credential(credentialsConfig);例
方法7:資格情報 URI を使用する
この方法では、アプリケーションで STS トークンをカプセル化し、外部リソースにカスタム URI を提供できます。他のサービスは、この URI を介してのみ STS トークンを取得できます。これにより、AccessKey の漏洩リスクが最小限に抑えられます。Credentials ツールでは、サービス URI を呼び出して STS トークンを取得し、Credentials クライアントを初期化できます。
const Credential = require('@alicloud/credentials');
const config = new Credential.Config({
type: 'credentials_uri',
// 資格情報の URI を http://local_or_remote_uri/ 形式で、環境変数 ALIBABA_CLOUD_CREDENTIALS_URI を指定することで指定します。
credentialsURI: '<CredentialsUri>',
});
const credentialClient = new Credential(config);import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
type: 'credentials_uri',
// 資格情報の URI を http://local_or_remote_uri/ 形式で、環境変数 ALIBABA_CLOUD_CREDENTIALS_URI を指定することで指定します。
credentialsURI: '<CredentialsUri>',
});
const credentialClient = new Credential(credentialsConfig);URI は、以下の要件を満たす必要があります。
応答状態コードは 200 です。
以下の応答パラメータが返されます。
{ "Code": "Success", "AccessKeySecret": "AccessKeySecret", "AccessKeyId": "AccessKeyId", "Expiration": "2021-09-26T03:46:38Z", "SecurityToken": "SecurityToken" }
呼び出し例
方法8: ベアラートークンを使用する
ベアラートークンを使用して SDK クライアントを初期化できるのは、Cloud Call Center のみです。
const Credential = require('@alicloud/credentials');
const config = new Credential.Config({
type: 'bearer',
// ベアラトークンを指定します。
bearerToken: '<BearerToken>',
});
const credentialClient = new Credential(config);import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
type: 'bearer',
// ベアラトークンを指定します。
bearerToken: '<BearerToken>',
});
const credentialClient = new Credential(credentialsConfig);例
デフォルトの認証情報プロバイダーチェーン
アプリケーションで開発環境と本番環境に応じて異なるタイプの資格情報を使用する場合、一般的には、コードから環境情報を取得し、環境ごとに異なる資格情報を取得するためのコードブランチを記述する必要があります。 Alibaba Cloud Credentials for Java のデフォルトの資格情報プロバイダーチェーンを使用すると、アプリケーションから独立した構成に基づいて、同じコードで異なる環境の資格情報を取得できます。 初期化メソッドを指定せずにnew Credential()を使用して Credentials クライアントを初期化する場合、Credentials ツールは次の順序で資格情報を取得します。
1. 環境変数から資格情報を取得
システム属性にクレデンシャル情報が見つからない場合、クレデンシャルは引き続き環境変数を確認します。
ALIBABA_CLOUD_ACCESS_KEY_ID 環境変数と ALIBABA_CLOUD_ACCESS_KEY_SECRET 環境変数の両方が指定されている場合は、デフォルトのクレデンシャルとして使用されます。
ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET、および ALIBABA_CLOUD_SECURITY_TOKEN が指定されている場合は、STS トークンがデフォルトのクレデンシャルとして使用されます。
2. OIDC IdP の RAM ロールを使用して認証情報を取得する
優先度の高い認証情報が見つからない場合、Credentials ツールは、OIDC IdP の RAM ロールに関連する以下の環境変数を確認します。
ALIBABA_CLOUD_ROLE_ARN: RAM ロールの ARN。
ALIBABA_CLOUD_OIDC_PROVIDER_ARN: OIDC IdP の ARN。
ALIBABA_CLOUD_OIDC_TOKEN_FILE: OIDC トークンのファイルパス。
上記の 3 つの環境変数が指定され、有効な場合、Credentials ツールはこれらの環境変数を使用して STS の AssumeRoleWithOIDC 操作を呼び出し、STS トークンをデフォルト認証情報として取得します。
3. config.json ファイルから認証情報を取得
優先順位の高い認証情報が見つからない場合、認証情報ツールは config.json ファイルの読み込みを試みます。デフォルトのファイルパスは次のとおりです。
Linux:
~/.aliyun/config.jsonWindows:
C:\Users\USER_NAME\.aliyun\config.json
上記のデフォルトパスは変更しないでください。この方法を使用してアクセス認証情報を構成する場合は、対応するパスに config.json ファイルを手動で作成します。例:
{
"current": "default",
"profiles": [
{
"name": "default",
"mode": "AK",
"access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
"access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"
},
{
"name": "client",
"mode": "StsToken",
"access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
"access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
"sts_token": "<SECURITY_TOKEN>"
},
{
"name":"client1",
"mode":"RamRoleArn",
"access_key_id":"<ALIBABA_CLOUD_ACCESS_KEY_ID>",
"access_key_secret":"<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
"ram_role_arn":"<ROLE_ARN>",
"ram_session_name":"<ROLE_SESSION_NAME>",
"expired_seconds":3600
},
{
"name":"client2",
"mode":"EcsRamRole",
"ram_role_name":"<RAM_ROLE_ARN>"
},
{
"name":"client3",
"mode":"OIDC",
"oidc_provider_arn":"<OIDC_PROVIDER_ARN>",
"oidc_token_file":"<OIDC_TOKEN_FILE>",
"ram_role_arn":"<ROLE_ARN>",
"ram_session_name":"<ROLE_SESSION_NAME>",
"expired_seconds":3600
},
{
"name":"client4",
"mode":"ChainableRamRoleArn",
"source_profile":"<PROFILE_NAME>",
"ram_role_arn":"<ROLE_ARN>",
"ram_session_name":"<ROLE_SESSION_NAME>",
"expired_seconds":3600
}
]
}
config.json ファイルでは、mode を使用して認証情報のタイプを指定できます。
AK: RAM ユーザーの AccessKey ペアを使用して認証情報を取得します。
StsToken: STS トークンを認証情報として使用します。
RamRoleArn: RAM ロールの ARN を使用して認証情報を取得します。
EcsRamRole: ECS インスタンスにアタッチされた RAM ロールを使用して認証情報を取得します。
OIDC: OIDC IdP の ARN と OIDC トークンファイルを使用して認証情報を取得します。
ChainableRamRoleArn: ロールチェーンを使用して、別の JSON ファイルでアクセス認証情報を指定して認証情報を取得します。
name を認証情報名に設定し、ビジネス要件に基づいて他のパラメーターを構成します。
構成が完了すると、認証情報ツールは構成ファイルの current パラメーターで指定された認証情報を選択し、クライアントを初期化します。ALIBABA_CLOUD_PROFILE 環境変数を指定して、認証情報を指定することもできます。たとえば、ALIBABA_CLOUD_PROFILE 環境変数を client1 に設定できます。
4. ECS インスタンスの RAM ロールを使用した資格情報の取得
優先順位の高い認証情報が見つからない場合、Credentials ツールは ECS インスタンスに割り当てられた RAM ロールを使用して認証情報を取得しようとします。デフォルトでは、Credentials ツールはセキュリティ強化モード (IMDSv2) で ECS のメタデータサーバーにアクセスし、ECS インスタンスが使用する RAM ロールの STS トークンを取得し、STS トークンをデフォルトの認証情報として使用します。Credentials ツールは自動的に ECS のメタデータサーバーにアクセスして RAM ロールの名前 (RoleName) を取得し、認証情報を取得します。このプロセスでは 2 つのリクエストが送信されます。リクエストを 1 つだけ送信する場合は、ALIBABA_CLOUD_ECS_METADATA 環境変数を追加して RAM ロールの名前を指定します。セキュリティ強化モード (IMDSv2) で例外が発生した場合、Credentials ツールは通常モード (IMDSv1) でアクセス認証情報を取得します。また、ALIBABA_CLOUD_IMDSV1_DISABLE 環境変数を構成して、例外処理ロジックを指定することもできます。有効な値:
false: Credentials ツールは通常モード (IMDSv1) でアクセス認証情報の取得を続行します。
true: 例外がスローされ、Credentials ツールはセキュリティ強化モードでアクセス認証情報の取得を続行します。
メタデータサーバーの構成によって、サーバーがセキュリティ強化モード (IMDSv2) をサポートするかどうかが決まります。
さらに、ALIBABA_CLOUD_ECS_METADATA_DISABLED=true を指定して、Credentials ツールから ECS のメタデータサーバーへのアクセスを無効にすることができます。
ECS インスタンスメタデータの詳細については、「インスタンスメタデータの取得」をご参照ください。
RAM ロールを ECS インスタンスにアタッチする方法の詳細については、「インスタンス RAM ロール」トピックの「インスタンス RAM ロールの作成と ECS インスタンスへのアタッチ」セクションをご参照ください。RAM ロールを Elastic Container Instance にアタッチする方法の詳細については、「API オペレーションを呼び出してインスタンス RAM ロールを使用する」トピックの「インスタンス RAM ロールを Elastic Container Instance に割り当てる」セクションをご参照ください。
5. URI に基づく資格情報の取得
上記のメソッドを使用して有効な認証情報が取得されない場合、Credentials ツールは ALIBABA_CLOUD_CREDENTIALS_URI 環境変数を確認します。この環境変数が存在し、有効な URI が指定されている場合、Credentials ツールは HTTP リクエストを開始して、デフォルトの認証情報として STS トークンを取得します。
セッション資格情報の自動更新メカニズム
セッション資格情報には、RAM ロールの ARN(RamRoleArn)、ECS インスタンスの RAM ロール、OIDC IdP の RAM ロール(OIDCRoleArn)、および資格情報 URI が含まれます。 Credentials ツールは、セッション資格情報の組み込みの自動更新メカニズムを提供します。最初の呼び出しから資格情報を取得した後、 Credentials ツールは資格情報をキャッシュに保存します。後続の呼び出しでは、資格情報の有効期限が切れていない限り、資格情報はキャッシュから読み取られます。それ以外の場合、 Credentials ツールは資格情報を再度取得するために呼び出しを行い、キャッシュ内の資格情報を更新します。
ECS インスタンスの RAM ロールの場合は、 Credentials ツールはキャッシュの有効期限(TTL)が終了する 15 分前に資格情報を更新します。
次の例では、 Credentials クライアントは単一インスタンスモードで作成され、クラウドサービスクライアントの初期化に使用されます。その後、異なる期間中に API 操作が呼び出され、内部キャッシュが使用されているかどうか、およびキャッシュの有効期限が切れた後に資格情報が更新されるかどうかが確認されます。
const Credential = require('@alicloud/credentials');
const Ecs20140526 = require('@alicloud/ecs20140526');
const { Config } = require('@alicloud/openapi-client');
const { RuntimeOptions } = require('@alicloud/tea-util');
// 環境変数を取得します。
const accessKeyId = process.env.ALIBABA_CLOUD_ACCESS_KEY_ID;
const accessKeySecret = process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET;
const roleArn = process.env.ALIBABA_CLOUD_ROLE_ARN;
/**
* Credential シングルトンクラスは、Alibaba Cloud 資格情報インスタンスの管理に使用されます。
*/
class CredentialClient {
constructor() {
if (!CredentialClient.instance) {
var credentialsConfig = new Credential.Config({
type: 'ram_role_arn',
accessKeyId: accessKeyId,
accessKeySecret: accessKeySecret,
roleArn: roleArn,
roleSessionName: 'RoleSessionNameTest',
roleSessionExpiration: 3600,
});
this.credentialsClient = new Credential.default(credentialsConfig);
CredentialClient.instance = this;
}
return CredentialClient.instance;
}
static getInstance() {
return new CredentialClient().credentialsClient;
}
}
/**
* ECS Client シングルトンクラスは、ECS クライアントインスタンスの管理に使用されます。
*/
class EcsClient {
constructor(credentialClient) {
if (!EcsClient.instance) {
const config = new Config({
endpoint: 'ecs.cn-hangzhou.aliyuncs.com',
credential: credentialClient
});
this.ecsClient = new Ecs20140526.default(config);
EcsClient.instance = this;
}
return EcsClient.instance;
}
static getInstance(credentialClient) {
return new EcsClient(credentialClient).ecsClient;
}
}
/**
* タスクロジックを実行します。
*/
async function executeTask() {
try {
const credentialClient = CredentialClient.getInstance();
const credential = await credentialClient.getCredential();
console.log(new Date());
console.log(`AK ID: ${credential.accessKeyId}`);
console.log(`AK Secret: ${credential.accessKeySecret}`);
console.log(`STS Token: ${credential.securityToken}`);
// この例では、ECS API 操作が呼び出され、資格情報が有効かどうかがテストされます。呼び出す API 操作を指定できます。
const ecsClient = EcsClient.getInstance(credentialClient);
const request = new Ecs20140526.DescribeRegionsRequest();
const runtime = new RuntimeOptions({});
const response = await ecsClient.describeRegionsWithOptions(request, runtime);
console.log(`Invoke result: ${response.statusCode}`);
} catch (error) {
throw new Error(`ECS client execution failed: ${error.message}`, { cause: error });
}
}
/**
* タイマーを使用してタスク実行をスケジュールします。
*/
function scheduleTasks() {
// タスクをすぐに 1 回実行します。
executeTask();
// 後続のタスクの遅延を設定します。
setTimeout(executeTask, 600 * 1000); // 600 秒後にタスクを 2 回目に実行します。
setTimeout(executeTask, 4200 * 1000); // 4,200 秒後にタスクを 3 回目に実行します。
setTimeout(executeTask, 4300 * 1000); // 4,300 秒後にタスクを 4 回目に実行します。
}
// タスクのスケジュールを開始します。
scheduleTasks();
import Credential, { Config as CredentialsConfig } from '@alicloud/credentials';
import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import { Config } from '@alicloud/openapi-client';
import { RuntimeOptions } from '@alicloud/tea-util';
// 環境変数を取得します。
const accessKeyId: string | undefined = process.env.ALIBABA_CLOUD_ACCESS_KEY_ID;
const accessKeySecret: string | undefined = process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET;
const roleArn: string | undefined = process.env.ALIBABA_CLOUD_ROLE_ARN;
if (!accessKeyId || !accessKeySecret || !roleArn) {
throw new Error('必要な環境変数がありません。');
}
/**
* Credential シングルトンクラスは、Alibaba Cloud 資格情報インスタンスの管理に使用されます。
*/
class CredentialClient {
private static instance: CredentialClient;
private readonly credentialsClient: InstanceType<typeof Credential>;
private constructor() {
const credentialsConfig = new CredentialsConfig({
type: 'ram_role_arn',
accessKeyId,
accessKeySecret,
roleArn,
roleSessionName: 'RoleSessionNameTest',
roleSessionExpiration: 3600,
});
this.credentialsClient = new Credential(credentialsConfig);
}
static getInstance(): InstanceType<typeof Credential> {
if (!CredentialClient.instance) {
CredentialClient.instance = new CredentialClient();
}
return CredentialClient.instance.credentialsClient;
}
}
/**
* ECS Client シングルトンクラスは、ECS クライアントインスタンスの管理に使用されます。
*/
class EcsClient {
private static instance: EcsClient;
private readonly ecsClient: InstanceType<typeof Ecs20140526>;
private constructor(credentialClient: InstanceType<typeof Credential>) {
const config = new Config({
endpoint: 'ecs.cn-hangzhou.aliyuncs.com',
credential: credentialClient
});
this.ecsClient = new Ecs20140526(config);
}
static getInstance(credentialClient: InstanceType<typeof Credential>): InstanceType<typeof Ecs20140526> {
if (!EcsClient.instance) {
EcsClient.instance = new EcsClient(credentialClient);
}
return EcsClient.instance.ecsClient;
}
}
/**
* タスクロジックを実行します。
*/
async function executeTask(): Promise<void> {
try {
const credentialClient = CredentialClient.getInstance();
const credential = await credentialClient.getCredential();
console.log(new Date());
console.log(`AK ID: ${credential.accessKeyId}`);
console.log(`AK Secret: ${credential.accessKeySecret}`);
console.log(`STS Token: ${credential.securityToken}`);
// この例では、ECS API 操作が呼び出され、資格情報が有効かどうかがテストされます。呼び出す API 操作を指定できます。
const ecsClient = EcsClient.getInstance(credentialClient);
const request = new $Ecs20140526.DescribeRegionsRequest();
const runtime = new RuntimeOptions({});
const response = await ecsClient.describeRegionsWithOptions(request, runtime);
console.log(`Invoke result: ${response.statusCode}`);
} catch (error) {
throw new Error(`ECS client execution failed: ${error}`);
}
}
/**
* タイマーを使用してタスク実行をスケジュールします。
*/
function scheduleTasks(): void {
// タスクをすぐに 1 回実行します。
executeTask();
// 後続のタスクの遅延を設定します。
setTimeout(executeTask, 600 * 1000); // 600 秒後にタスクを 2 回目に実行します。
setTimeout(executeTask, 4200 * 1000); // 4,200 秒後にタスクを 3 回目に実行します。
setTimeout(executeTask, 4300 * 1000); // 4,300 秒後にタスクを 4 回目に実行します。
}
// タスクのスケジュールを開始します。
scheduleTasks();
ログ分析:
最初の呼び出しでは、資格情報がキャッシュされていないため、システムは構成に基づいて資格情報を取得します。システムが資格情報を取得した後、資格情報はキャッシュに保存されます。
2 回目の呼び出しは、最初の呼び出しと同じ資格情報を使用します。これは、資格情報がキャッシュから取得されたことを示します。
3 回目の呼び出しでは、資格情報の有効期限が切れています。これは、3 回目の呼び出しが最初の呼び出しから 4,200 秒後であるのに対し、資格情報の TTL(RoleSessionExpiration)は 3,600 秒に設定されているためです。SDK は自動更新メカニズムに基づいて資格情報を再度取得し、キャッシュに保存します。
4 回目の呼び出しは、3 回目の呼び出しと同じ資格情報を使用します。これは、キャッシュの有効期限が切れた後に資格情報が更新されたことを示します。
参考文献
RAM の詳細については、「用語」をご参照ください。
AccessKey ペアの作成方法の詳細については、「AccessKey ペアを作成する」をご参照ください。
RAM ユーザー、AccessKey ペア、RAM ロール、およびポリシーの作成方法と RAM ユーザーへの権限の付与方法の詳細については、「RAM SDK の概要」をご参照ください。
プログラムを使用してロールを引き受ける方法の詳細については、「STS SDK の概要」をご参照ください。
RAM および STS 関連の API 操作の詳細については、「API リファレンス」をご参照ください。