Skip to content

docs: update README #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 16, 2024
+473 −116
Merged

docs: update README #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
307 changes: 244 additions & 63 deletions README-zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,28 +35,44 @@ composer require alibabacloud/credentials

### 凭证类型

#### AccessKey

通过[用户信息管理][ak]设置 access_key，它们具有该账户完全的权限，请妥善保管。有时出于安全考虑，您不能把具有完全访问权限的主账户 AccessKey 交于一个项目的开发者使用，您可以[创建RAM子账户][ram]并为子账户[授权][permissions]，使用RAM子用户的 AccessKey 来进行API调用。
#### 使用默认凭据链
当您在初始化凭据客户端不传入任何参数时，Credentials工具会使用默认凭据链方式初始化客户端。默认凭据的读取逻辑请参见[默认凭据链](#默认凭证提供程序链)。

```php
<?php

use AlibabaCloud\Credentials\Credential;

// Chain Provider if no Parameter
$credential = new Credential();
$client = new Credential();

$credential = $client->getCredential();
$credential->getAccessKeyId();
$credential->getAccessKeySecret();
$credential->getSecurityToken();
```

#### AccessKey

通过[用户信息管理][ak]设置 access_key，它们具有该账户完全的权限，请妥善保管。有时出于安全考虑，您不能把具有完全访问权限的主账户 AccessKey 交于一个项目的开发者使用，您可以[创建RAM子账户][ram]并为子账户[授权][permissions]，使用RAM子用户的 AccessKey 来进行API调用。

```php
<?php

use AlibabaCloud\Credentials\Credential;
namespace AlibabaCloud\Credentials\Credential\Config;

// Access Key
$ak = new Credential([
'type' => 'access_key',
'access_key_id' => '<access_key_id>',
'access_key_secret' => '<access_key_secret>',
$config = new Config([
'type' => 'access_key',
'accessKeyId' => '<access_key_id>',
'accessKeySecret' => '<access_key_secret>',
]);
$ak->getAccessKeyId();
$ak->getAccessKeySecret();
$client = new Credential($config);

$credential = $client->getCredential();
$credential->getAccessKeyId();
$credential->getAccessKeySecret();
```

#### STS
Expand All @@ -67,86 +83,244 @@ $ak->getAccessKeySecret();
<?php

use AlibabaCloud\Credentials\Credential;
namespace AlibabaCloud\Credentials\Credential\Config;

$sts = new Credential([
'type' => 'sts',
'access_key_id' => '<access_key_id>',
'accessKey_secret' => '<accessKey_secret>',
'security_token' => '<security_token>',
$config = new Config([
'type' => 'sts',
'accessKeyId' => '<access_key_id>',
'accessKeySecret' => '<access_key_secret>',
'securityToken' => '<security_token>',
]);
$sts->getAccessKeyId();
$sts->getAccessKeySecret();
$sts->getSecurityToken();
$client = new Credential($config);

$credential = $client->getCredential();
$credential->getAccessKeyId();
$credential->getAccessKeySecret();
$credential->getSecurityToken();
```

#### RamRoleArn

通过指定[RAM角色][RAM Role]，让凭证自动申请维护 STS Token。你可以通过为 `Policy` 赋值来限制获取到的 STS Token 的权限。
通过指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具可以帮助开发者前往STS换取STS Token。您也可以通过为 `Policy` 赋值来限制RAM角色到一个更小的权限集合。

```php
<?php

use AlibabaCloud\Credentials\Credential;

$ramRoleArn = new Credential([
'type' => 'ram_role_arn',
'access_key_id' => '<access_key_id>',
'access_key_secret' => '<access_key_secret>',
'role_arn' => '<role_arn>',
'role_session_name' => '<role_session_name>',
'policy' => '',
namespace AlibabaCloud\Credentials\Credential\Config;

$config = new Config([
'type' => 'ram_role_arn',
'accessKeyId' => '<access_key_id>',
'accessKeySecret' => '<access_key_secret>',
// 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置role_arn
'roleArn' => '<role_arn>',
// 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置role_session_name
'roleSessionName' => '<role_session_name>',
// 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
'policy' => '',
# 设置session过期时间
'roleSessionExpiration' => 3600,
]);
$ramRoleArn->getAccessKeyId();
$ramRoleArn->getAccessKeySecret();
$ramRoleArn->getRoleArn();
$ramRoleArn->getRoleSessionName();
$ramRoleArn->getPolicy();
$client = new Credential($config);

$credential = $client->getCredential();
$credential->getAccessKeyId();
$credential->getAccessKeySecret();
$credential->getSecurityToken();
```

#### EcsRamRole

通过指定角色名称，让凭证自动申请维护 STS Token
Credentials工具会自动获取ECS实例绑定的RAM角色，调用ECS的元数据服务（Meta Data Server）换取STS Token，完成凭据客户端初始化。ECI实例，容器服务 Kubernetes 版的Worker节点均支持绑定实例RAM角色。

```php
<?php

use AlibabaCloud\Credentials\Credential;
namespace AlibabaCloud\Credentials\Credential\Config;

$ecsRamRole = new Credential([
'type' => 'ecs_ram_role',
'role_name' => '<role_name>',
$config = new Config([
'type' => 'ecs_ram_role',
// 选填，该ECS角色的角色名称，不填会自动获取，但是建议加上以减少请求次数，可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置role_name
'roleName' => '<role_name>',
]);
$ecsRamRole->getRoleName();
// Note: `role_name` is optional. It will be retrieved automatically if not set. It is highly recommended to set it up to reduce requests.
$client = new Credential($config);

$credential = $client->getCredential();
$credential->getAccessKeyId();
$credential->getAccessKeySecret();
$credential->getSecurityToken();
```

#### Bearer Token
#### OIDCRoleArn

如呼叫中心(CCC)需用此凭证，请自行申请维护 Bearer Token。
在容器服务 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权限隔离](https://help.aliyun.com/zh/ack/ack-managed-and-ack-dedicated/user-guide/use-rrsa-to-authorize-pods-to-access-different-cloud-services#task-2142941)。

```php
<?php

use AlibabaCloud\Credentials\Credential;
namespace AlibabaCloud\Credentials\Credential\Config;

$config = new Config([
'type' => 'oidc_role_arn',
// OIDC提供商ARN，可以通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置oidc_provider_arn
'oidcProviderArn' => '<oidc_provider_arn>',
// OIDC Token文件路径，可以通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置oidc_token_file_path
'oidcTokenFilePath' => '<oidc_token_file_path>',
// 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置role_arn
'roleArn' => '<role_arn>',
// 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置role_session_name
'roleSessionName' => '<role_session_name>',
// 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
'policy' => '',
# 设置session过期时间
'roleSessionExpiration' => 3600,
]);
$client = new Credential($config);

$bearerToken = new Credential([
'type' => 'bearer',
'bearer_token' => '<bearer_token>',
$credential = $client->getCredential();
$credential->getAccessKeyId();
$credential->getAccessKeySecret();
$credential->getSecurityToken();
```

#### Credentials URI

通过指定提供凭证的自定义网络服务地址，让凭证自动申请维护 STS Token。

```php
<?php

use AlibabaCloud\Credentials\Credential;
namespace AlibabaCloud\Credentials\Credential\Config;

$config = new Config([
'type' => 'credentials_uri',
// 凭证的 URI，格式为http://local_or_remote_uri/，可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置credentials_uri
'credentialsURI' => '<credentials_uri>',
]);
$bearerToken->getBearerToken();
$client = new Credential($config);

$credential = $client->getCredential();
$credential->getBearerToken();
```

## 默认凭证提供程序链
#### Bearer Token

默认凭证提供程序链查找可用的凭证，寻找顺序如下：
目前只有云呼叫中心 CCC 这款产品支持 Bearer Token 的凭据初始化方式。

### 1. 环境凭证
```php
<?php

程序首先会在环境变量里寻找环境凭证，如果定义了 `ALIBABA_CLOUD_ACCESS_KEY_ID` 和 `ALIBABA_CLOUD_ACCESS_KEY_SECRET` 环境变量且不为空，程序将使用他们创建默认凭证。
use AlibabaCloud\Credentials\Credential;
namespace AlibabaCloud\Credentials\Credential\Config;

$config = new Config([
'type' => 'bearer',
// 填入您的Bearer Token
'bearerToken' => '<bearer_token>',
]);
$client = new Credential($config);

$credential = $client->getCredential();
$credential->getBearerToken();
```

## 默认凭证提供程序链

### 2. 配置文件
当您的程序开发环境和生产环境采用不同的凭据类型，常见做法是在代码中获取当前环境信息，编写获取不同凭据的分支代码。借助Credentials工具的默认凭据链，您可以用同一套代码，通过程序之外的配置来控制不同环境下的凭据获取方式。当您在不传入参数的情况下，直接使用$credential = new Credential();初始化凭据客户端时，阿里云SDK将会尝试按照如下顺序查找相关凭据信息。

### 1. 使用环境变量

Credentials工具会优先在环境变量中获取凭据信息。

- 如果系统环境变量 `ALIBABA_CLOUD_ACCESS_KEY_ID`（密钥Key） 和 `ALIBABA_CLOUD_ACCESS_KEY_SECRET`（密钥Value） 不为空，Credentials工具会优先使用它们作为默认凭据。

- 如果系统环境变量 `ALIBABA_CLOUD_ACCESS_KEY_ID`（密钥Key）、`ALIBABA_CLOUD_ACCESS_KEY_SECRET`（密钥Value）、`ALIBABA_CLOUD_SECURITY_TOKEN`（Token）均不为空，Credentials工具会优先使用STS Token作为默认凭据。

### 2. 使用OIDC RAM角色
若不存在优先级更高的凭据信息，Credentials工具会在环境变量中获取如下内容：

`ALIBABA_CLOUD_ROLE_ARN`：RAM角色名称ARN；

`ALIBABA_CLOUD_OIDC_PROVIDER_ARN`：OIDC提供商ARN；

`ALIBABA_CLOUD_OIDC_TOKEN_FILE`：OIDC Token文件路径；

若以上三个环境变量都已设置内容，Credentials将会使用变量内容调用STS服务的[AssumeRoleWithOIDC - OIDC角色SSO时获取扮演角色的临时身份凭证](https://help.aliyun.com/zh/ram/developer-reference/api-sts-2015-04-01-assumerolewithoidc)接口换取STS Token作为默认凭据。

### 3. 使用 Aliyun CLI 工具的 config.json 配置文件

若不存在优先级更高的凭据信息，Credentials工具会优先在如下位置查找 `config.json` 文件是否存在：
Linux系统：`~/.aliyun/config.json`
Windows系统： `C:\Users\USER_NAME\.aliyun\config.json`
如果文件存在，程序将会使用配置文件中 `current` 指定的凭据信息初始化凭据客户端。当然，您也可以通过环境变量 `ALIBABA_CLOUD_PROFILE` 来指定凭据信息，例如设置 `ALIBABA_CLOUD_PROFILE` 的值为 `AK`。

在config.json配置文件中每个module的值代表了不同的凭据信息获取方式：

- AK：使用用户的Access Key作为凭据信息；
- RamRoleArn：使用RAM角色的ARN来获取凭据信息；
- EcsRamRole：利用ECS绑定的RAM角色来获取凭据信息；
- OIDC：通过OIDC ARN和OIDC Token来获取凭据信息；
- ChainableRamRoleArn：采用角色链的方式，通过指定JSON文件中的其他凭据，以重新获取新的凭据信息。

配置示例信息如下：

```json
{
"current": "AK",
"profiles": [
{
"name": "AK",
"mode": "AK",
"access_key_id": "access_key_id",
"access_key_secret": "access_key_secret"
},
{
"name": "RamRoleArn",
"mode": "RamRoleArn",
"access_key_id": "access_key_id",
"access_key_secret": "access_key_secret",
"ram_role_arn": "ram_role_arn",
"ram_session_name": "ram_session_name",
"expired_seconds": 3600,
"sts_region": "cn-hangzhou"
},
{
"name": "EcsRamRole",
"mode": "EcsRamRole",
"ram_role_name": "ram_role_name"
},
{
"name": "OIDC",
"mode": "OIDC",
"ram_role_arn": "ram_role_arn",
"oidc_token_file": "path/to/oidc/file",
"oidc_provider_arn": "oidc_provider_arn",
"ram_session_name": "ram_session_name",
"expired_seconds": 3600,
"sts_region": "cn-hangzhou"
},
{
"name": "ChainableRamRoleArn",
"mode": "ChainableRamRoleArn",
"source_profile": "AK",
"ram_role_arn": "ram_role_arn",
"ram_session_name": "ram_session_name",
"expired_seconds": 3600,
"sts_region": "cn-hangzhou"
}
]
}
```

### 4. 使用配置文件
>
> 如果用户主目录存在默认文件 `~/.alibabacloud/credentials` （Windows 为 `C:\Users\USER_NAME\.alibabacloud\credentials`），程序会自动创建指定类型和名称的凭证。默认文件可以不存在，但解析错误会抛出异常。 凭证名称不分大小写，若凭证同名，后者会覆盖前者。不同的项目、工具之间可以共用这个配置文件，因为超出项目之外，也不会被意外提交到版本控制。Windows 上可以使用环境变量引用到主目录 %UserProfile%。类 Unix 的系统可以使用环境变量 $HOME 或 ~ (tilde)。 可以通过定义 `ALIBABA_CLOUD_CREDENTIALS_FILE` 环境变量修改默认文件的路径。
> 如果用户主目录存在默认文件 `~/.alibabacloud/credentials` （Windows 为 `C:\Users\USER_NAME\.alibabacloud\credentials`），程序会自动创建指定类型和名称的凭证。您也可通过环境变量 `ALIBABA_CLOUD_CREDENTIALS_FILE` 指定配置文件路径。如果文件存在，程序将会使用配置文件中 default 指定的凭据信息初始化凭据客户端。当然，您也可以通过环境变量 `ALIBABA_CLOUD_PROFILE` 来指定凭据信息，例如设置 `ALIBABA_CLOUD_PROFILE` 的值为 `client1`。

配置示例信息如下：

```ini
[default]
Expand All @@ -164,26 +338,33 @@ access_key_id = foo
access_key_secret = bar
role_arn = role_arn
role_session_name = session_name

[project3]
type=oidc_role_arn # 认证方式为 oidc_role_arn
oidc_provider_arn=oidc_provider_arn
oidc_token_file_path=oidc_token_file_path
role_arn=role_arn
role_session_name=session_name
```

### 3. 实例 RAM 角色
### 5. 使用 ECS 实例RAM角色

如果定义了环境变量 `ALIBABA_CLOUD_ECS_METADATA` 且不为空，程序会将该环境变量的值作为角色名称，请求 `http://100.100.100.200/latest/meta-data/ram/security-credentials/` 获取临时安全凭证作为默认凭证。

### 自定义凭证提供程序链
### 6. 使用外部服务 Credentials URI

可通过自定义程序链代替默认程序链的寻找顺序，也可以自行编写闭包传入提供者。

```php
<?php
若不存在优先级更高的凭据信息，Credentials工具会在环境变量中获取ALIBABA_CLOUD_CREDENTIALS_URI，若存在，程序将请求该URI地址，获取临时安全凭证作为默认凭据信息。

use AlibabaCloud\Credentials\Providers\ChainProvider;
外部服务响应结构应如下：

ChainProvider::set(
ChainProvider::ini(),
ChainProvider::env(),
ChainProvider::instance()
);
```json
{
"Code": "Success",
"AccessKeyId": "AccessKeyId",
"AccessKeySecret": "AccessKeySecret",
"SecurityToken": "SecurityToken",
"Expiration": "2024-10-26T03:46:38Z"
}
```

## 文档
Expand Down Expand Up @@ -217,7 +398,7 @@ ChainProvider::set(

Copyright (c) 2009-present, Alibaba Cloud All rights reserved.

[open-api]: https://next.api.aliyun.com
[open-api]: https://api.aliyun.com
[latest-release]: https://github.com/aliyun/credentials-php
[guzzle-docs]: https://guzzle-cn.readthedocs.io/zh_CN/latest/request-options.html
[composer]: https://getcomposer.org
Expand Down
Loading