diff --git a/README-CN.md b/README-CN.md index 82438e8..f98f67e 100644 --- a/README-CN.md +++ b/README-CN.md @@ -1,6 +1,6 @@ [English](README.md) | 简体中文 -![](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg) +![Alibaba Cloud Logo](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg) # Alibaba Cloud Credentials for Python @@ -23,9 +23,9 @@ pip install alibabacloud_credentials 在您开始之前，您需要注册阿里云帐户并获取您的[凭证](https://usercenter.console.aliyun.com/#/manage/ak)。 -#### 凭证类型 +### 凭证类型 -##### Access Key +#### Access Key 通过[用户信息管理](https://usercenter.console.aliyun.com/#/manage/ak)设置 access_key，它们具有该账户完全的权限，请妥善保管。有时出于安全考虑，您不能把具有完全访问权限的主账户 AccessKey 交于一个项目的开发者使用，您可以[创建RAM子账户](https://ram.console.aliyun.com/users)并为子账户[授权](https://ram.console.aliyun.com/permissions)，使用RAM子用户的 AccessKey 来进行API调用。 @@ -45,7 +45,7 @@ access_key_secret = cred.get_access_key_secret() cred_type = cred.get_type() ``` -##### STS +#### STS 通过安全令牌服务（Security Token Service，简称 STS），申请临时安全凭证（Temporary Security Credentials，简称 TSC），创建临时安全凭证。 @@ -67,7 +67,7 @@ security_token = cred.get_security_token() cred_type = cred.get_type() ``` -##### RAM Role ARN +#### RAM Role ARN 通过指定[RAM角色](https://ram.console.aliyun.com/#/role/list)，让凭证自动申请维护 STS Token。你可以通过为 `Policy` 赋值来限制获取到的 STS Token 的权限。 @@ -93,7 +93,7 @@ security_token = cred.get_security_token() cred_type = cred.get_type() ``` -##### OIDC Role ARN +#### OIDC Role ARN 通过指定[OIDC角色]，让凭证自动申请维护 STS Token。你可以通过为 `Policy` 赋值来限制获取到的 STS Token 的权限。 @@ -121,7 +121,7 @@ security_token = cred.get_security_token() cred_type = cred.get_type() ``` -##### ECS RAM Role +#### ECS RAM Role 通过指定角色名称，让凭证自动申请维护 STS Token @@ -142,7 +142,7 @@ security_token = cred.get_security_token() cred_type = cred.get_type() ``` -##### Credentials URI +#### Credentials URI 通过指定一个 Credentials 地址，从外部服务申请并自动维护 STS Token @@ -162,28 +162,7 @@ security_token = cred.get_security_token() cred_type = cred.get_type() ``` -##### RSA Key Pair - -通过指定公钥ID和私钥文件，让凭证自动申请维护 AccessKey。仅支持日本站。 - -```python -from alibabacloud_credentials.client import Client -from alibabacloud_credentials.models import Config - -config = Config( - type='rsa_key_pair', # 凭证类型 - private_key_file='privateKeyFile', # PrivateKey文件路径 - public_key_id='publicKeyId' # 账户PublicKeyId -) -cred = Client(config) - -access_key_id = cred.get_access_key_id() -access_key_secret = cred.get_access_key_secret() -security_token = cred.get_security_token() -cred_type = cred.get_type() -``` - -##### Bearer +#### Bearer 如呼叫中心(CCC)需用此凭证，请自行申请维护 Bearer Token。 @@ -227,74 +206,72 @@ response = client.get_async_job_result(request, runtime_options) 默认凭证提供程序链查找可用的凭证，寻找顺序如下： -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 方式的临时凭证，注意：该 token 存在过期时间，推荐在临时环境中使用。 - -2.配置文件 - -如果用户主目录存在默认文件 `~/.alibabacloud/credentials.ini （Windows 为 C:\Users\USER_NAME\.alibabacloud\credentials.ini）`，程序会自动创建指定类型和名称的凭证。默认文件可以不存在，但解析错误会抛出异常。配置名小写。不同的项目、工具之间可以共用这个配置文件，因为不在项目之内，也不会被意外提交到版本控制。 -可以通过定义 `ALIBABA_CLOUD_CREDENTIALS_FILE` 环境变量修改默认文件的路径。不配置则使用默认配置 `default`，也可以设置环境变量 `ALIBABA_CLOUD_PROFILE` 使用配置。 - -```ini -[default] # 默认配置 -enable = true # 启用，没有该选项默认不启用 -type = access_key # 认证方式为 access_key -access_key_id = foo # Key -access_key_secret = bar # Secret - -[client1] # 命名为 `client1` 的配置 -type = ecs_ram_role # 认证方式为 ecs_ram_role -role_name = EcsRamRoleTest # Role Name - -[client2] # 命名为 `client2` 的配置 -enable = false # 不启用 -type = ram_role_arn # 认证方式为 ram_role_arn -region_id = cn-test # 获取session用的region -policy = test # 选填 指定权限 -access_key_id = foo -access_key_secret = bar -role_arn = role_arn -role_session_name = session_name # 选填 - -[client3] # 命名为 `client3` 的配置 -type = rsa_key_pair # 认证方式为 rsa_key_pair -public_key_id = publicKeyId # Public Key ID -private_key_file = /your/pk.pem # Private Key 文件 - -[client4] # 命名为 `client4` 的配置 -enable = false # 不启用 -type = oidc_role_arn # 认证方式为 oidc_role_arn -region_id = cn-test # 获取session用的region -policy = test # 选填 指定权限 -access_key_id = foo # 选填 -access_key_secret = bar # 选填 -role_arn = role_arn -oidc_provider_arn = oidc_provider_arn -oidc_token_file_path = /xxx/xxx # 可通过设置环境变量 ALIBABA_CLOUD_OIDC_TOKEN_FILE 来代替 -role_session_name = session_name # 选填 -``` +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 方式的临时凭证，注意：该 token 存在过期时间，推荐在临时环境中使用。 + +2. 配置文件 + + 如果用户主目录存在默认文件 `~/.alibabacloud/credentials.ini （Windows 为 C:\Users\USER_NAME\.alibabacloud\credentials.ini）`，程序会自动创建指定类型和名称的凭证。默认文件可以不存在，但解析错误会抛出异常。配置名小写。不同的项目、工具之间可以共用这个配置文件，因为不在项目之内，也不会被意外提交到版本控制。\ + + 可以通过定义 `ALIBABA_CLOUD_CREDENTIALS_FILE` 环境变量修改默认文件的路径。不配置则使用默认配置 `default`，也可以设置环境变量 `ALIBABA_CLOUD_PROFILE` 使用配置。 + + ```ini + [default] # 默认配置 + enable = true # 启用，没有该选项默认不启用 + type = access_key # 认证方式为 access_key + access_key_id = foo # Key + access_key_secret = bar # Secret -3.实例 RAM 角色 + [client1] # 命名为 `client1` 的配置 + type = ecs_ram_role # 认证方式为 ecs_ram_role + role_name = EcsRamRoleTest # Role Name -如果定义了环境变量 `ALIBABA_CLOUD_ECS_METADATA` 且不为空，程序会将该环境变量的值作为角色名称，请求 获取临时安全凭证。 + [client2] # 命名为 `client2` 的配置 + enable = false # 不启用 + type = ram_role_arn # 认证方式为 ram_role_arn + region_id = cn-test # 获取session用的region + policy = test # 选填 指定权限 + access_key_id = foo + access_key_secret = bar + role_arn = role_arn + role_session_name = session_name # 选填 + + [client3] # 命名为 `client3` 的配置 + enable = false # 不启用 + type = oidc_role_arn # 认证方式为 oidc_role_arn + region_id = cn-test # 获取session用的region + policy = test # 选填 指定权限 + access_key_id = foo # 选填 + access_key_secret = bar # 选填 + role_arn = role_arn + oidc_provider_arn = oidc_provider_arn + oidc_token_file_path = /xxx/xxx # 可通过设置环境变量 ALIBABA_CLOUD_OIDC_TOKEN_FILE 来代替 + role_session_name = session_name # 选填 + ``` + +3. 实例 RAM 角色 + + 如果定义了环境变量 `ALIBABA_CLOUD_ECS_METADATA` 且不为空，程序会将该环境变量的值作为角色名称，请求 获取临时安全凭证。 4. Credentials URI -如果定义了环境变量 `ALIBABA_CLOUD_CREDENTIALS_URI` 且不为空, 程序会将该环境变量的值作为 Credentials URI 地址，在调用时，获取临时安全凭证。 + 如果定义了环境变量 `ALIBABA_CLOUD_CREDENTIALS_URI` 且不为空, 程序会将该环境变量的值作为 Credentials URI 地址，在调用时，获取临时安全凭证。 ## 问题 [提交 Issue](https://github.com/aliyun/credentials-python/issues/new)，不符合指南的问题可能会立即关闭。 ## 发行说明 + 每个版本的详细更改记录在[发行说明](./ChangeLog.md)中。 ## 相关 -* [最新源码](https://github.com/aliyun/credentials-python) + +- [最新源码](https://github.com/aliyun/credentials-python) ## 许可证 + [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0) Copyright (c) 2009-present, Alibaba Cloud All rights reserved. - diff --git a/README.md b/README.md index 57b955f..1627a33 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ English | [简体中文](README-CN.md) -![](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg) + +![Alibaba Cloud Logo](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg) # Alibaba Cloud Credentials for Python @@ -8,6 +9,7 @@ English | [简体中文](README-CN.md) [![codecov](https://codecov.io/gh/aliyun/credentials-python/graph/badge.svg?token=Y0J1E7T35I)](https://codecov.io/gh/aliyun/credentials-python) ## Installation + - **Install with pip** Python SDK uses a common package management tool named `pip`. If pip is not installed, see the [pip user guide](https://pip.pypa.io/en/stable/installing/ "pip User Guide") to install pip. @@ -140,7 +142,7 @@ security_token = cred.get_security_token() cred_type = cred.get_type() ``` -##### Credentials URI +#### Credentials URI By specifying a credentials uri, get credential from the local or remote uri, the credential will be able to automatically request maintenance to keep it update. @@ -160,27 +162,6 @@ security_token = cred.get_security_token() cred_type = cred.get_type() ``` -#### RSA Key Pair - -By specifying the public key ID and the private key file, the credential will be able to automatically request maintenance of the AccessKey before sending the request. Only Japan station is supported. - -```python -from alibabacloud_credentials.client import Client -from alibabacloud_credentials.models import Config - -config = Config( - type='rsa_key_pair', # credential type - private_key_file='privateKeyFile', # The file path to store the PrivateKey - public_key_id='publicKeyId' # PublicKeyId of your account -) -cred = Client(config) - -access_key_id = cred.get_access_key_id() -access_key_secret = cred.get_access_key_secret() -security_token = cred.get_security_token() -cred_type = cred.get_type() -``` - #### Bearer If credential is required by the Cloud Call Centre (CCC), please apply for Bearer Token maintenance by yourself. @@ -227,70 +208,75 @@ The default credential provider chain looks for available credentials, with foll 1. Environment Credentials -Look for environment credentials in environment variable. If the `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET` environment variables are defined and are not empty, the program will use them to create default credentials. If the `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET` and `ALIBABA_CLOUD_SECURITY_TOKEN` environment variables are defined and are not empty, the program will use them to create temporary security credentials(STS). Note: This token has an expiration time, it is recommended to use it in a temporary environment. + Look for environment credentials in environment variable. If the `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET` environment variables are defined and are not empty, the program will use them to create default credentials. If the `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET` and `ALIBABA_CLOUD_SECURITY_TOKEN` environment variables are defined and are not empty, the program will use them to create temporary security credentials(STS). Note: This token has an expiration time, it is recommended to use it in a temporary environment. 2. Credentials File -If there is `~/.alibabacloud/credentials.ini default file (Windows shows C:\Users\USER_NAME\.alibabacloud\credentials.ini)`, the program automatically creates credentials with the specified type and name. The default file is not necessarily exist, but a parse error will throw an exception. The name of configuration item is lowercase.This configuration file can be shared between different projects and between different tools. Because it is outside of the project and will not be accidentally committed to the version control. The path to the default file can be modified by defining the `ALIBABA_CLOUD_CREDENTIALS_FILE` environment variable. If not configured, use the default configuration `default`. You can also set the environment variables `ALIBABA_CLOUD_PROFILE` to use the configuration. - -```ini -[default] # default setting -enable = true # Enable，Enabled by default if this option is not present -type = access_key # Certification type: access_key -access_key_id = foo # Key -access_key_secret = bar # Secret - -[client1] # configuration that is named as `client1` -type = ecs_ram_role # Certification type: ecs_ram_role -role_name = EcsRamRoleTest # Role Name - -[client2] # configuration that is named as `client2` -enable = false # Disable -type = ram_role_arn # Certification type: ram_role_arn -region_id = cn-test -policy = test # optional Specify permissions -access_key_id = foo -access_key_secret = bar -role_arn = role_arn -role_session_name = session_name # optional - -[client3] # configuration that is named as `client3` -type = rsa_key_pair # Certification type: rsa_key_pair -public_key_id = publicKeyId # Public Key ID -private_key_file = /your/pk.pem # Private Key file - -[client4] # configuration that is named as `client4` -enable = false # Disable -type = oidc_role_arn # Certification type: oidc_role_arn -region_id = cn-test -policy = test # optional Specify permissions -access_key_id = foo # optional -access_key_secret = bar # optional -role_arn = role_arn -oidc_provider_arn = oidc_provider_arn -oidc_token_file_path = /xxx/xxx # can be replaced by setting environment variable: ALIBABA_CLOUD_OIDC_TOKEN_FILE -role_session_name = session_name # optional -``` + If there is `~/.alibabacloud/credentials.ini default file (Windows shows C:\Users\USER_NAME\.alibabacloud\credentials.ini)`, the program automatically creates credentials with the specified type and name. The default file is not necessarily exist, but a parse error will throw an exception. The name of configuration item is lowercase.This configuration file can be shared between different projects and between different tools. Because it is outside of the project and will not be accidentally committed to the version control. The path to the default file can be modified by defining the `ALIBABA_CLOUD_CREDENTIALS_FILE` environment variable. If not configured, use the default configuration `default`. You can also set the environment variables `ALIBABA_CLOUD_PROFILE` to use the configuration. + + ```ini + [default] # default setting + enable = true # Enable，Enabled by default if this option is not present + type = access_key # Certification type: access_key + access_key_id = foo # Key + access_key_secret = bar # Secret + + [client1] # configuration that is named as `client1` + type = ecs_ram_role # Certification type: ecs_ram_role + role_name = EcsRamRoleTest # Role Name + + [client2] # configuration that is named as `client2` + enable = false # Disable + type = ram_role_arn # Certification type: ram_role_arn + region_id = cn-test + policy = test # optional Specify permissions + access_key_id = foo + access_key_secret = bar + role_arn = role_arn + role_session_name = session_name # optional + + [client3] # configuration that is named as `client3` + enable = false # Disable + type = oidc_role_arn # Certification type: oidc_role_arn + region_id = cn-test + policy = test # optional Specify permissions + access_key_id = foo # optional + access_key_secret = bar # optional + role_arn = role_arn + oidc_provider_arn = oidc_provider_arn + oidc_token_file_path = /xxx/xxx # can be replaced by setting environment variable: ALIBABA_CLOUD_OIDC_TOKEN_FILE + role_session_name = session_name # optional + ``` 3. Instance RAM Role -If the environment variable `ALIBABA_CLOUD_ECS_METADATA` is defined and not empty, the program will take the value of the environment variable as the role name and request to get the temporary Security credentials. + If the environment variable `ALIBABA_CLOUD_ECS_METADATA` is defined and not empty, the program will take the value of the environment variable as the role name and request to get the temporary Security credentials. 4. Credentials URI -If the environment variable `ALIBABA_CLOUD_CREDENTIALS_URI` is defined and not empty, the program will take the value of the environment variable as credentials uri to get the temporary Security credentials. + If the environment variable `ALIBABA_CLOUD_CREDENTIALS_URI` is defined and not empty, the program will take the value of the environment variable as credentials uri to get the temporary Security credentials. ## Issues [Opening an Issue](https://github.com/aliyun/credentials-python/issues/new), Issues not conforming to the guidelines may be closed immediately. ## Changelog + Detailed changes for each release are documented in the [release notes](./ChangeLog.md). ## References -* [Latest Release](https://github.com/aliyun/credentials-python) + +- [Latest Release](https://github.com/aliyun/credentials-python) ## License + [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0) Copyright (c) 2009-present, Alibaba Cloud All rights reserved. + +[ak]: https://usercenter.console.aliyun.com/#/manage/ak +[ram]: https://ram.console.aliyun.com/users +[permissions]: https://ram.console.aliyun.com/permissions +[RAM Role]: https://ram.console.aliyun.com/#/role/list +[OIDC Role]: https://help.aliyun.com/zh/ram/user-guide/role-based-sso-by-using-oidc +[policy]: https://help.aliyun.com/zh/ram/user-guide/policy-management/