通過配置Credentials實現OpenAPI安全調用（PHP SDK） - Alibaba Cloud SDK

當您通過阿里雲SDK調用OpenAPI進行資源操作時，必須正確配置憑證資訊。阿里雲的Credentials工具提供了一套強大的功能，使您能夠輕鬆地擷取和管理這些訪問憑證。無論是利用預設憑證，AccessKey（AK），還是Security Token Service（STS）令牌等，Credentials工具都能為您提供相應支援。此外，本文檔將詳細闡述如何根據優先順序使用預設憑證。您將深入理解如何在阿里雲SDK中配置和維護憑證，從而確保您對雲資源的操作既有效率又具有高度安全性。

背景資訊

憑據是指使用者證明其身份的一組資訊。使用者在系統中進行登入時，需要提供正確的憑據才能驗證身份。常見的憑據類型有：

阿里雲主帳號和RAM使用者的永久憑據 AccessKey（簡稱AK）。一組由AccessKey ID和AccessKey Secret組成的金鑰組。
阿里雲RAM角色的STS臨時訪問Token，簡稱STS Token。它是可以自訂時效和存取權限的臨時身份憑據，詳情請參見臨時訪問憑證STS概念。
Bearer Token。它是一種身分識別驗證和授權的令牌類型。

前提條件

使用Credentials工具要求PHP版本 >= 5.6。強烈建議您使用cURL擴充，並使用TLS後端編譯cURL 7.16.2+。
使用V2.0版本的阿里雲SDK。
自建網關類產品的自研SDK無法使用。

安裝Credentials工具

如果已在系統上全域安裝 Composer，請直接在專案目錄中運行以下內容來安裝 Alibaba Cloud Credentials for PHP 作為依賴項：

composer require alibabacloud/credentials

建議使用最新發行的Credentials工具版本。
請查看CHANGELOG.md擷取所有發行的版本列表。

初始化憑據用戶端

Credentials工具支援多種方式初始化憑據用戶端。您可通過設定type指定類型。

使用預設憑據鏈

當您在初始化憑據用戶端不傳入任何參數時，Credentials工具會使用預設憑據鏈方式初始化用戶端。預設憑據的讀取邏輯請參見預設憑據鏈。

<?php

use AlibabaCloud\Credentials\Credential;

// 不指定參數
$credential = new Credential([]);
$credential->getAccessKeyId();
$credential->getAccessKeySecret();

介面調用方法

通過預設憑據提供鏈自動建立訪問憑證，並在不使用寫入程式碼AccessKey的情況下成功調用雲產品OpenAPI介面。

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝ECS SDK。

<?php

use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\Credentials\Credential;
use AlibabaCloud\SDK\Ecs\V20140526\Ecs as Ecs;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use AlibabaCloud\SDK\Ecs\V20140526\Models\DescribeRegionsRequest;

// composer 自動載入機制，require_once(vendor目錄下autoload.php檔案)
require_once('../vendor/autoload.php');

// 使用預設憑證初始化Credentials Client。
$credentialClient = new Credential([]);
$ecsConfig = new Config([
    // 使用 credential 配置憑證
    'credential'        => $credential,
    // 產品服務網域名稱
    'endpoint'          => 'ecs.aliyuncs.com'
]);
// 初始化ECS client
$ecsClient = new Ecs($config);
// 初始化 request
$describeRegionsRequest = new DescribeRegionsRequest([]);
// 初始化運行時配置
$runtime = new RuntimeOptions([]);
$resp = $ecsClient->describeRegionsWithOptions($describeRegionsRequest, $runtime);
// 輸出狀態代碼
echo $resp->statusCode;
// 輸出響應
var_dump($resp);

使用AK

阿里雲帳號、RAM使用者可產生調用OpenAPI的金鑰組AK。如何擷取AK請參見文檔建立AccessKey。您可使用AK初始化憑據用戶端。

警告

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

推薦使用最小化授權的RAM使用者的AK。

<?php

use AlibabaCloud\Credentials\Credential;

$ak = new Credential([
    'type'              => 'access_key',
    'access_key_id'     => getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    'access_key_secret' => getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
]);
$ak->getAccessKeyId();
$ak->getAccessKeySecret();

介面調用方法

通過Credentials工具讀取AK，完成雲產品OpenAPI介面的調用。

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝ECS SDK。

<?php

namespace AlibabaCloud\SDK\Sample;
use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\Credentials\Credential;
use AlibabaCloud\SDK\Ecs\V20140526\Ecs as Ecs;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use AlibabaCloud\SDK\Ecs\V20140526\Models\DescribeRegionsRequest;

// composer 自動載入機制，require_once(vendor目錄下autoload.php檔案)
require_once('../vendor/autoload.php');
// 使用AK 初始化Credentials Client。
$credentialClient = new Credential([
    // 憑證類型。
    'type'              => 'access_key',
    // 設定為AccessKey ID值。
    'access_key_id'     => getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    // 設定為AccessKey Secret值。
    'access_key_secret' => getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
]);
$ecsConfig = new Config([
    // 使用 credential 配置憑證
    'credential'        => $credentialClient,
    // 產品服務網域名稱
    'endpoint'          => 'ecs.aliyuncs.com'
]);
// 初始化ECS client
$ecsClient = new Ecs($ecsConfig);
// 初始化 request
$describeRegionsRequest = new DescribeRegionsRequest([]);
// 初始化運行時配置
$runtime = new RuntimeOptions([]);
$resp = $ecsClient->describeRegionsWithOptions($describeRegionsRequest, $runtime);
// 輸出狀態代碼
echo $resp->statusCode;
// 輸出響應
var_dump($resp);

使用STS Token

以一個RAM使用者的身份調用STS服務的AssumeRole介面，設定Token的最大到期時間，即可換取到臨時憑據STS Token。以下樣本示範如何使用STS Token初始化憑據用戶端（不包含如何擷取到STS Token的過程）。

{
  "RequestId": "EA7A3526-F7DB-54A5-8300-9B742CFAA5EA",
  "AssumedRoleUser": {
    "Arn": "acs:ram::125499367423****:role/STStokenTestRole/STSsessionName",
    "AssumedRoleId": "35219123109646****:STSsessionName"
  },
  "Credentials": {
    "SecurityToken": "exampleToken",
    "AccessKeyId": "STS.exampleAccessKeyID",
    "AccessKeySecret": "exampleAccessKeySecret",
    "Expiration": "2023-03-26T05:26:06Z"
  }
}

<?php

use AlibabaCloud\Credentials\Credential;

$sts = new Credential([
    'type'             => 'sts',
  	// <ALIBABA_CLOUD_ACCESS_KEY_ID>需替換為返回資料中擷取的臨時AccessKeyId。
    'access_key_id'     => '<ALIBABA_CLOUD_ACCESS_KEY_ID>',
  	// <ALIBABA_CLOUD_ACCESS_KEY_SECRET>需替換為返回資料中擷取的臨時AccessKeySecret。
    'access_key_secret' => '<ALIBABA_CLOUD_ACCESS_KEY_SECRET>',
  	// <ALIBABA_CLOUD_SECURITY_TOKEN>需替換為返回資料中擷取的臨時SecurityToken。
    'security_token'   => '<ALIBABA_CLOUD_SECURITY_TOKEN>',
]);
$sts->getAccessKeyId();
$sts->getAccessKeySecret();
$sts->getSecurityToken();

介面調用方法

通過Credentials工具讀取臨時安全性權杖（STS Token），完成雲產品OpenAPI介面的調用。

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝Elastic Compute Service SDK和Security Token Service SDK。

<?php

namespace AlibabaCloud\SDK\Sample;
use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\Credentials\Credential;
use AlibabaCloud\SDK\Ecs\V20140526\Ecs as Ecs;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use AlibabaCloud\SDK\Ecs\V20140526\Models\DescribeRegionsRequest;

// composer 自動載入機制，require_once(vendor目錄下autoload.php檔案)
require_once('../vendor/autoload.php');
// 使用AK 初始化Credentials Client。
$credentialClient = new Credential([
    // 憑證類型。
    'type'             => 'sts',
  	// <ALIBABA_CLOUD_ACCESS_KEY_ID>需替換為返回資料中擷取的臨時AccessKeyId。
    'access_key_id'     => getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
  	// <ALIBABA_CLOUD_ACCESS_KEY_SECRET>需替換為返回資料中擷取的臨時AccessKeySecret。
    'access_key_secret' => getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
  	// <ALIBABA_CLOUD_SECURITY_TOKEN>需替換為返回資料中擷取的臨時SecurityToken。
    'security_token'   => getenv('ALIBABA_CLOUD_SECURITY_TOKEN'),
]);
$ecsConfig = new Config([
    // 使用 credential 配置憑證
    'credential'        => $credentialClient,
    // 產品服務網域名稱
    'endpoint'          => 'ecs.aliyuncs.com'
]);
// 初始化ECS client
$ecsClient = new Ecs($ecsConfig);
// 初始化 request
$describeRegionsRequest = new DescribeRegionsRequest([]);
// 初始化運行時配置
$runtime = new RuntimeOptions([]);
$resp = $ecsClient->describeRegionsWithOptions($describeRegionsRequest, $runtime);
// 輸出狀態代碼
echo $resp->statusCode;
// 輸出響應
var_dump($resp);

使用AK及RamRoleArn

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

<?php

use AlibabaCloud\Credentials\Credential;

$ramRoleArn = new Credential([
    'type'              => 'ram_role_arn',
    'access_key_id'     => getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    'access_key_secret' => getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
    // 要扮演的RAM角色ARN，樣本值：acs:ram::123456789012****:role/adminrole
    'role_arn'          => '<RoleArn>',
    // 角色會話名稱
    'role_session_name' => '<RoleSessionName>',
    // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    'policy'            => '<Policy>',
]);
$ramRoleArn->getAccessKeyId();
$ramRoleArn->getAccessKeySecret();
$ramRoleArn->getRoleArn();
$ramRoleArn->getRoleSessionName();
$ramRoleArn->getPolicy();

介面調用方法

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝ECS SDK。

<?php

namespace AlibabaCloud\SDK\Sample;
use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\Credentials\Credential;
use AlibabaCloud\SDK\Ecs\V20140526\Ecs as Ecs;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use AlibabaCloud\SDK\Ecs\V20140526\Models\DescribeRegionsRequest;

// composer 自動載入機制，require_once(vendor目錄下autoload.php檔案)
require_once('../vendor/autoload.php');
// 使用AK 初始化Credentials Client。
$credentialClient = new Credential([
    // 憑證類型。
    'type'              => 'ram_role_arn',
    // 設定為AccessKey ID值。
    'access_key_id'     => getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    // 設定為AccessKey Secret值。
    'access_key_secret' => getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
    // 要扮演的RAM角色ARN，樣本值：acs:ram::123456789012****:role/adminrole
    'role_arn'          => '<RoleArn>',
    // 角色會話名稱
    'role_session_name' => '<RoleSessionName>',
    // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    'policy'            => '<Policy>',
]);
$ecsConfig = new Config([
    // 使用 credential 配置憑證
    'credential'        => $credentialClient,
    // 產品服務網域名稱
    'endpoint'          => 'ecs.aliyuncs.com'
]);
// 初始化ECS client
$ecsClient = new Ecs($ecsConfig);
// 初始化 request
$describeRegionsRequest = new DescribeRegionsRequest([]);
// 初始化運行時配置
$runtime = new RuntimeOptions([]);
$resp = $ecsClient->describeRegionsWithOptions($describeRegionsRequest, $runtime);
// 輸出狀態代碼
echo $resp->statusCode;
// 輸出響應
var_dump($resp);

使用ECS執行個體RAM角色

該方式底層實現是STS Token。Credentials工具會自動擷取ECS執行個體綁定的RAM角色，調用ECS的中繼資料服務（Meta Data Server）換取STS Token，完成憑據用戶端初始化。ECI執行個體，Container Service for Kubernetes的Worker節點均支援綁定執行個體RAM角色。

<?php

use AlibabaCloud\Credentials\Credential;

$ecsRamRole = new Credential([
    'type'      => 'ecs_ram_role',
    // 選填，該ECS角色的角色名稱，不填會自動擷取，但是建議加上以減少請求次數
    'role_name' => '<RoleName>',
]);
$ecsRamRole->getRoleName();

介面調用方法

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝ECS SDK。

<?php

namespace AlibabaCloud\SDK\Sample;
use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\Credentials\Credential;
use AlibabaCloud\SDK\Ecs\V20140526\Ecs as Ecs;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use AlibabaCloud\SDK\Ecs\V20140526\Models\DescribeRegionsRequest;

// composer 自動載入機制，require_once(vendor目錄下autoload.php檔案)
require_once('../vendor/autoload.php');
// 使用AK 初始化Credentials Client。
$credentialClient = new Credential([
    // 憑證類型。
    'type'              => 'ecs_ram_role',
    // 可選項，不填會自動擷取，但是建議加上以減少請求次數
    'role_name' => '<RoleName>',
]);
$ecsConfig = new Config([
    // 使用 credential 配置憑證
    'credential'        => $credentialClient,
    // 產品服務網域名稱
    'endpoint'          => 'ecs.aliyuncs.com'
]);
// 初始化ECS client
$ecsClient = new Ecs($ecsConfig);
// 初始化 request
$describeRegionsRequest = new DescribeRegionsRequest([]);
// 初始化運行時配置
$runtime = new RuntimeOptions([]);
$resp = $ecsClient->describeRegionsWithOptions($describeRegionsRequest, $runtime);
// 輸出狀態代碼
echo $resp->statusCode;
// 輸出響應
var_dump($resp);

使用Bearer Token

目前只有Cloud Call CenterCCC這款產品支援Bearer Token的憑據初始化方式。

<?php

use AlibabaCloud\Credentials\Credential;

$bearerToken = new Credential([
    'type'         => 'bearer',
    // 填入您的Bearer Token
    'bearer_token' => '<BearerToken>',
]);
$bearerToken->getBearerToken();
$bearerToken->getSignature();

介面調用方法

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝。

<?php

namespace AlibabaCloud\SDK\Sample;
use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\Credentials\Credential;
use AlibabaCloud\SDK\Ecs\V20140526\Ecs as Ecs;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use AlibabaCloud\SDK\Ecs\V20140526\Models\DescribeRegionsRequest;

// composer 自動載入機制，require_once(vendor目錄下autoload.php檔案)
require_once('../vendor/autoload.php');
// 使用AK 初始化Credentials Client。
$credentialClient = new Credential([
    // 憑證類型。
    'type'         => 'bearer',
    // 填入您的Bearer Token
    'bearer_token' => '<BearerToken>',
]);
$ecsConfig = new Config([
    // 使用 credential 配置憑證
    'credential'        => $credentialClient,
    // 產品服務網域名稱
    'endpoint'          => 'ecs.aliyuncs.com'
]);
// 初始化ECS client
$ecsClient = new Ecs($ecsConfig);
// 初始化 request
$describeRegionsRequest = new DescribeRegionsRequest([]);
// 初始化運行時配置
$runtime = new RuntimeOptions([]);
$resp = $ecsClient->describeRegionsWithOptions($describeRegionsRequest, $runtime);
// 輸出狀態代碼
echo $resp->statusCode;
// 輸出響應
var_dump($resp);

預設憑據鏈

當您的程式開發環境和生產環境採用不同的憑據類型，常見做法是在代碼中擷取當前環境資訊，編寫擷取不同憑據的分支代碼。藉助Credentials工具的預設憑據鏈，您可以用同一套代碼，通過程式之外的配置來控制不同環境下的憑據擷取方式。當您在不傳入參數的情況下，直接使用$credential = new Credential();初始化憑據用戶端時，阿里雲SDK將會嘗試按照如下順序尋找相關憑據資訊。

1. 使用環境變數

Credentials工具優先在環境變數中擷取憑據資訊。如果系統內容變數ALIBABA_CLOUD_ACCESS_KEY_ID（密鑰Key）和 ALIBABA_CLOUD_ACCESS_KEY_SECRET（密鑰Value）不為空白，Credentials工具會優先使用它們作為預設憑據。

2. 使用設定檔

若不存在優先順序更高的憑據資訊，Credentials工具優先在如下位置尋找檔案是否存在。

Linux系統：~/.alibabacloud/credentials

Windows系統：C:\Users\USER_NAME\.alibabacloud\credentials

您也可通過指定 ALIBABA_CLOUD_CREDENTIALS_FILE 指定設定檔路徑。如果檔案存在，程式將會使用設定檔中default 指定的憑據資訊初始化憑據用戶端，當然您也可以通過設定 ALIBABA_CLOUD_PROFILE 環境變數修改預設讀取的憑據資訊。

[default]
type = access_key                  
access_key_id = foo               
access_key_secret = bar            

[project1]
type = ecs_ram_role               
role_name = EcsRamRoleTest         

[project2]
type = ram_role_arn                
access_key_id = foo
access_key_secret = bar
role_arn = role_arn
role_session_name = session_name

[project3]
type = rsa_key_pair                
public_key_id = publicKeyId        
private_key_file = /your/pk.pem

3. 使用ECS執行個體RAM角色

若不存在優先順序更高的憑據資訊，Credentials工具會在環境變數中擷取ALIBABA_CLOUD_ECS_METADATA（ECS執行個體RAM角色名稱），若存在，程式將會通過ECS的中繼資料服務（Meta Data Server）擷取ECS執行個體RAM角色的STS Token作為預設憑據資訊。

自訂憑證提供者鏈

可通過自訂程式鏈代替預設程式鏈的尋找順序，也可以自行編寫閉包傳入提供者。

<?php

use AlibabaCloud\Credentials\Providers\ChainProvider;

ChainProvider::set(
        ChainProvider::ini(),
        ChainProvider::env(),
        ChainProvider::instance()
);

如何保護憑據資訊

憑據資訊泄露導致系統被攻擊是雲上業務普遍存在的一種安全問題，您可通過如下方案避免在代碼中暴露明文憑據資訊，降低憑據泄露的風險。

推薦使用ECS執行個體RAM角色或者使用STS方式。
推薦使用預設憑據鏈，使用環境變數或者設定檔記錄憑據資訊。
如使用顯示初始化方案初始化憑據用戶端，推薦使用系統屬性及環境變數記錄憑據資訊，通過getenv及$_ENV擷取。

<?php

use AlibabaCloud\Credentials\Credential;

$ak = new Credential([
    'type'              => 'access_key',
    'access_key_id'     => getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    'access_key_secret' => getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
]);
$ak->getAccessKeyId();
$ak->getAccessKeySecret();

如何切換憑據

當您想要在程式中使用不同的訪問憑據調用不同OpenAPI時，可以通過如下方式。

使用多個憑據用戶端

通過初始化多個憑據用戶端，傳入到不同的介面請求用戶端。

<?php

use AlibabaCloud\Credentials\Credential;

$ak1 = new Credential([
    'type'              => 'access_key',
    'access_key_id'     => '<ALIBABA_CLOUD_ACCESS_KEY_ID>',
    'access_key_secret' => '<ALIBABA_CLOUD_ACCESS_KEY_SECRET>',
]);
$ak1->getAccessKeyId();
$ak1->getAccessKeySecret();

$ak2 = new Credential([
    'type'              => 'access_key',
    'access_key_id'     => '<ALIBABA_CLOUD_ACCESS_KEY_ID>',
    'access_key_secret' => '<ALIBABA_CLOUD_ACCESS_KEY_SECRET>',
]);
$ak2->getAccessKeyId();
$ak2->getAccessKeySecret();

Alibaba Cloud SDK：管理訪問憑據

背景資訊

前提條件

安裝Credentials工具

初始化憑據用戶端

使用預設憑據鏈

介面調用方法

使用AK

介面調用方法

使用STS Token

介面調用方法

使用AK及RamRoleArn

介面調用方法

使用ECS執行個體RAM角色

介面調用方法

使用Bearer Token

介面調用方法

預設憑據鏈

1. 使用環境變數

2. 使用設定檔

3. 使用ECS執行個體RAM角色

自訂憑證提供者鏈

如何保護憑據資訊

如何切換憑據

使用多個憑據用戶端

相關文檔