通過PHP配置訪問憑證以驗證使用者的身份資訊和存取權限（PHP SDK V1） - Object Storage Service

使用PHP SDK發起OSS請求，您需要配置訪問憑證。阿里雲服務會通過訪問憑證驗證您的身份資訊和存取權限。您可以根據使用情境對認證和授權的要求，選擇不同類型的訪問憑證。本文介紹如何配置臨時訪問憑證和長期訪問憑證。

前提條件

在配置訪問憑證前，您需要安裝OSS PHP SDK。詳情請參見安裝（PHP SDK V1）。

初始化憑證提供者

憑證提供者選型

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

憑證提供者初始化方式	適用情境	是否需要提供前置的AK或STS Token	底層實現基於的憑證	憑證有效期間	憑證輪轉或重新整理方式
方式一：使用AK	部署運行在安全、穩定且不易受外部攻擊的環境的應用程式，無需頻繁輪轉憑證就可以長期訪問雲端服務	是	AK	長期	手動輪轉
方式二：使用STS Token	部署運行在不可信的環境的應用程式，希望能控制訪問的有效期間、許可權	是	STS Token	臨時	手動重新整理
方式三：使用RAMRoleARN	需要授權訪問雲端服務，例如跨阿里雲帳號訪問雲端服務的應用程式	是	STS Token	臨時	自動重新整理
方式四：使用ECSRAMRole	部署運行在阿里雲的ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中的應用程式	否	STS Token	臨時	自動重新整理
方式五：使用Function Compute上下文中的Credentials	部署運行在阿里雲Function Compute中的應用程式的函數	否	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。

使用AK設定環境變數。

Mac OS X/Linux/Unix

export OSS_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
export OSS_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>

Windows

set OSS_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
set OSS_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>

使用環境變數來傳遞憑證資訊。

<?php
require_once __DIR__ . '/vendor/autoload.php';
use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\Core\OssException;

try {
    // 從環境變數中擷取訪問憑證,並儲存在provider中。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
    $provider = new EnvironmentVariableCredentialsProvider();
    // 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
    $endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    $bucket = "bucket";
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    var_dump($ossClient);
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

靜態憑證

您可以在代碼中使用變數來引用憑證，這些變數在運行時會被環境變數、設定檔或其他外部資料源中的實際憑證值填充。

以下操作步驟以設定檔為例。

建立設定檔config.ini。

[credentials]
alibaba_cloud_access_key_id = <ALIBABA_CLOUD_ACCESS_KEY_ID>
alibaba_cloud_access_key_secret = <ALIBABA_CLOUD_ACCESS_KEY_SECRET>

使用設定檔來傳遞憑證資訊。

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}
use OSS\Credentials\StaticCredentialsProvider;
use OSS\OssClient;
use OSS\Core\OssException;

try {
    $config = parse_ini_file('config.ini');
    // 擷取AK和SK資訊
    $accessKeyId = $config['alibaba_cloud_access_key_id'];
    $accessKeySecret = $config['alibaba_cloud_access_key_secret'];
    $provider = new StaticCredentialsProvider($accessKeyId,$accessKeySecret);
    $endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    printf($ossClient);
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

方式二：使用STS Token

如果您的應用程式需要臨時訪問OSS，您可以使用通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個STS Token，存在安全性風險和維護複雜度增加的風險。此外，如果您需要多次臨時訪問OSS，您需要手動重新整理STS Token。如何擷取STS Token，請參見AssumeRole - 擷取扮演角色的臨時身份憑證。

使用臨時身份憑證設定環境變數。

Mac OS X/Linux/Unix

export OSS_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
export OSS_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>
export OSS_SESSION_TOKEN=<ALIBABA_CLOUD_SECURITY_TOKEN>

Windows

set OSS_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
set OSS_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>
set OSS_SESSION_TOKEN=<ALIBABA_CLOUD_SECURITY_TOKEN>

通過環境變數來傳遞憑證資訊。

<?php
require_once __DIR__ . '/vendor/autoload.php';
use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\Core\OssException;

try {
    // 從環境變數中擷取訪問憑證,並儲存在provider中。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET,OSS_SESSION_TOKEN。
    $provider = new EnvironmentVariableCredentialsProvider();
    // 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
    $endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    $bucket = "bucket";
    $config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    var_dump($ossClient);
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

方式三：使用RAMRoleARN

重要

此方法需要使用alibabacloud/credentials 1.2.0及以上版本。

如果您的應用程式需要授權訪問OSS，例如跨阿里雲帳號訪問OSS，您可以使用RAMRoleARN初始化憑證提供者。該方式底層實現是STS Token。通過指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具會前往STS服務擷取STS Token，並在會話到期前自動重新整理STS Token。此外，您還可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。需要注意的是，該方式需要您提供一個AK，存在安全性風險和維護複雜度增加的風險。如何擷取AK，請參見CreateAccessKey - 為RAM使用者建立存取金鑰。如何擷取RAMRoleARN，請參見CreateRole - 建立角色。

添加憑據用戶端依賴。

composer require alibabacloud/credentials

配置訪問憑證。

<?php

require_once __DIR__ . '/vendor/autoload.php';

use AlibabaCloud\Credentials\Credential;
use OSS\Core\OssException;
use OSS\OssClient;
use OSS\Credentials\CredentialsProvider;
use OSS\Credentials\StaticCredentialsProvider;

class AlibabaCloudCredentialsWrapper implements CredentialsProvider
{
    /**
     * @var Credential
     */
    private $wrapper;

    public function __construct($wrapper)
    {
        $this->wrapper = $wrapper;
    }

    public function getCredentials()
    {
        $cred = $this->wrapper->getCredential();
        $ak = $cred->getAccessKeyId();
        $sk = $cred->getAccessKeySecret();
        $token = $cred->getSecurityToken();
        return new StaticCredentialsProvider($ak, $sk, $token);
    }
}

try {
    $config = new Credential\Config([
        // 填寫Credential類型，固定值為ram_role_arn。
        'type' => 'ram_role_arn',
        // 從環境變數中擷取RAM使用者的存取金鑰（AccessKey ID和AccessKey Secret）。
        'accessKeyId' => getenv('OSS_ACCESS_KEY_ID'),
        'accessKeySecret' => getenv('OSS_ACCESS_KEY_SECRET'),
        // 從環境變數中擷取RAM角色的RamRoleArn。即需要扮演的角色ID，格式為acs:ram::$accountID:role/$roleName。
        'roleArn' => getenv('OSS_STS_ROLE_ARN'),
        // 自訂角色會話名稱，用於區分不同的令牌。
        'roleSessionName' => 'yourRoleSessionName',
        // 自訂權限原則。
        'policy' => '',
    ]);

    $credential = new Credential($config);
    $providerWrapper = new AlibabaCloudCredentialsWrapper($credential);
    $provider = $providerWrapper->getCredentials();
    $config = array(
        'provider' => $provider,
        // 以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其他Region請按實際情況填寫。
        'endpoint' => 'https://oss-cn-hangzhou.aliyuncs.com'
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    var_dump($ossClient);
} catch (OssException $e) {
    print $e->getMessage();
}

方式四：使用ECSRAMRole

說明

請注意，此方法需要使用alibabacloud/credentials 1.2.0及以上版本。

如果您的應用程式運行在ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中，建議您使用ECSRAMRole初始化憑證提供者。該方式底層實現是STS Token。ECSRAMRole允許您將一個角色關聯到ECS執行個體、ECI執行個體或Container Service Kubernetes 版的Worker節點，實現在執行個體內部自動重新整理STS Token。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。如何擷取ECSRAMRole，請參見CreateRole - 建立角色。

添加憑據用戶端依賴。

composer require alibabacloud/credentials

配置ECSRAMRole作為訪問憑證。

<?php

require_once __DIR__ . '/vendor/autoload.php';

use AlibabaCloud\Credentials\Credential;
use OSS\Core\OssException;
use OSS\OssClient;
use OSS\Credentials\CredentialsProvider;
use OSS\Credentials\StaticCredentialsProvider;

class AlibabaCloudCredentialsWrapper implements CredentialsProvider
{
    /**
     * @var Credential
     */
    private $wrapper;

    public function __construct($wrapper)
    {
        $this->wrapper = $wrapper;
    }

    public function getCredentials()
    {
        $cred = $this->wrapper->getCredential();
        $ak = $cred->getAccessKeyId();
        $sk = $cred->getAccessKeySecret();
        $token = $cred->getSecurityToken();
        return new StaticCredentialsProvider($ak, $sk, $token);
    }
}

try {
    $config = new Credential\Config([
        // 填寫Credential類型，固定值為ecs_ram_role。
        'type' => 'ecs_ram_role',
        'roleName' => "<role_name>",
    ]);
    $credential = new Credential($config);
    $providerWrapper = new AlibabaCloudCredentialsWrapper($credential);
    $provider = $providerWrapper->getCredentials();
    $config = array(
        'provider' => $provider,
        // 以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其他Region請按實際情況填寫。
        'endpoint' => 'https://oss-cn-hangzhou.aliyuncs.com'
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    var_dump($ossClient);
} catch (OssException $e) {
    print $e->getMessage();
}

方式五：使用Function Compute上下文中的Credentials

如果您的應用程式的函數部署運行在Function Compute中，您可以使用Function Compute上下文中的Credentials初始化憑證提供者。該方式底層實現是STS Token。Function Compute根據函數配置的角色，通過扮演服務角色，而擷取一個STS Token，然後通過上下文中的參數Credentials將STS Token傳遞給您的應用程式。該STS Token的有效期間為36小時，且不支援修改。函數的最大執行時間為24小時，因此，執行函數過程中，STS Token不會到期，您無需考慮重新整理問題。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。如何授予Function Compute訪問OSS的許可權，請參見使用函數角色授予Function Compute訪問其他雲端服務的許可權。

使用Function Compute上下文中的Credentials初始化憑證提供者。

<?php

use OSS\OssClient;
use OSS\Core\OssException;

function handler($event, $context) {
    /*
      阿里雲帳號AccessKey擁有所有API的存取權限，建議您使用RAM使用者進行API訪問或日常營運。
      建議不要把AccessKey ID和AccessKey Secret儲存到工程代碼裡，否則可能導致AccessKey泄露，威脅您帳號下所有資源的安全。
      本樣本以從上下文中擷取AccessKey/AccessSecretKey為例。
    */
    $creds = $context["credentials"];
    $accessKeyId = $creds["accessKeyId"];
    $accessKeySecret = $creds["accessKeySecret"];
    $securityToken = $creds["securityToken"];
    $endpoint = "https://oss-cn-hangzhou-internal.aliyuncs.com";

    try{
        $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint, false, $securityToken);
        print_r($ossClient);
    } catch(OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return $e->getMessage();
    }
    return 'hello world';
}

方式六：使用OIDCRoleARN

說明

請注意，此方法需要使用alibabacloud/credentials 1.2.0及以上版本。

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

添加憑據用戶端依賴。

composer require alibabacloud/credentials

配置OIDC的RAM角色作為訪問憑證的樣本如下。

<?php

require_once __DIR__ . '/vendor/autoload.php';

use OSS\Credentials\CredentialsProvider;
use AlibabaCloud\Credentials\Credential;
use OSS\Credentials\StaticCredentialsProvider;
use OSS\Core\OssException;
use OSS\OssClient;

class AlibabaCloudCredentialsWrapper implements CredentialsProvider
{
    /**
     * @var Credential
     */
    private $wrapper;

    public function __construct($wrapper)
    {
        $this->wrapper = $wrapper;
    }

    public function getCredentials()
    {
        $cred = $this->wrapper->getCredential();
        $ak = $cred->getAccessKeyId();
        $sk = $cred->getAccessKeySecret();
        $token = $cred->getSecurityToken();
        return new StaticCredentialsProvider($ak, $sk, $token);
    }
}

try {
    // 使用OIDCRoleArn初始化Credentials Client。
    $config = new Credential\Config([
        // 憑證類型。
        'type' => 'oidc_role_arn',
        // OIDC供應商ARN，可以通過環境變數ALIBABA_CLOUD_OIDC_PROVIDER_ARN設定oidc_provider_arn
        'oidcProviderArn' => '<OidcProviderArn>',
        // OIDC Token檔案路徑，可以通過環境變數ALIBABA_CLOUD_OIDC_TOKEN_FILE設定oidc_token_file_path
        'oidcTokenFilePath' => '<OidcTokenFilePath>',
        // RAM角色名稱ARN，樣本值：acs:ram::123456789012****:role/adminrole，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定role_arn
        'roleArn' => '<RoleArn>',
        // 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定role_session_name
        'roleSessionName' => '<RoleSessionName>',
        // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
        'policy' => '<Policy>',
        # 設定session到期時間
        'durationSeconds' => 3600,
    ]);
    $credential = new Credential($config);
    $providerWrapper = new AlibabaCloudCredentialsWrapper($credential);
    $provider = $providerWrapper->getCredentials();
    $config = array(
        'provider' => $provider,
        // 以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其他Region請按實際情況填寫。
        'endpoint' => 'https://oss-cn-hangzhou.aliyuncs.com'
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    var_dump($ossClient);
} catch (OssException $e) {
    print $e->getMessage();
}

方式七：使用CredentialsURI

說明

請注意，此方法需要使用alibabacloud/credentials 1.2.0及以上版本。

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

添加憑據用戶端依賴。

composer require alibabacloud/credentials

配置CredentialsURI作為訪問憑證的樣本如下。

<?php

require_once __DIR__ . '/vendor/autoload.php';

use AlibabaCloud\Credentials\Credential;
use OSS\Core\OssException;
use OSS\Credentials\CredentialsProvider;
use OSS\Credentials\StaticCredentialsProvider;
use OSS\OssClient;

class AlibabaCloudCredentialsWrapper implements CredentialsProvider
{
    /**
     * @var Credential
     */
    private $wrapper;

    public function __construct($wrapper)
    {
        $this->wrapper = $wrapper;
    }

    public function getCredentials()
    {
        $cred = $this->wrapper->getCredential();
        $ak = $cred->getAccessKeyId();
        $sk = $cred->getAccessKeySecret();
        $token = $cred->getSecurityToken();
        return new StaticCredentialsProvider($ak, $sk, $token);
    }
}

try {
    $config = new Credential\Config([
        // 憑證類型。
        'type' => 'credentials_uri',
        // 憑證的 URI，格式為http://local_or_remote_uri/，可以通過環境變數ALIBABA_CLOUD_CREDENTIALS_URI設定credentials_uri
        'credentialsURI' => '<CredentialsUri>',
    ]);
    $credential = new Credential($config);
    $providerWrapper = new AlibabaCloudCredentialsWrapper($credential);
    $provider = $providerWrapper->getCredentials();
    $config = array(
        'provider' => $provider,
        // 以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其他Region請按實際情況填寫。
        'endpoint' => 'https://oss-cn-hangzhou.aliyuncs.com'
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);
    var_dump($ossClient);
} catch (OssException $e) {
    print $e->getMessage();
}

方式八：自訂訪問憑證

如果以上憑證配置方式都不滿足要求時，您還可以通過實現Credential Providers介面的方式，來自訂憑證提供方式。

<?php
  if (is_file(__DIR__ . '/../autoload.php')) {
  require_once __DIR__ . '/../autoload.php';
  }
  if (is_file(__DIR__ . '/../vendor/autoload.php')) {
  require_once __DIR__ . '/../vendor/autoload.php';
  }

use OSS\Credentials\CredentialsProvider;
use OSS\OssClient;
use OSS\Core\OssException;

class CustomerCredentialsProvider implements CredentialsProvider
{
  public function getCredentials()
  {
    // 返回長期憑證
    return [
      'AccessKeyId' => 'id',
      'AccessKeySecret' => 'secret',
      ];
    // 返回臨時憑證
    //return [
    //    'AccessKeyId' => 'id',
    //    'AccessKeySecret' => 'secret',
    //    'SecurityToken' => 'token',
    //];
  }
}

$provider = new CustomerCredentialsProvider();

try {
  $provider = new CustomerCredentialsProvider();
  $endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  $config = array(
    "provider" => $provider,
    "endpoint" => $endpoint,
    "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
    "region"=> "cn-hangzhou"
  );
  $ossClient = new OssClient($config);
  printf($ossClient);
} catch (OssException $e) {
  printf($e->getMessage() . "\n");
  return;
}

後續步驟

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