1[English](README.md) | 简体中文
2
3# Alibaba Cloud Credentials for Go
4[](https://badge.fury.io/gh/aliyun%2Fcredentials-go)
5[](https://goreportcard.com/report/github.com/aliyun/credentials-go)
6[](https://codecov.io/gh/aliyun/credentials-go)
7[](https://packagist.org/packages/alibabacloud/credentials)
8[](https://github.com/aliyun/credentials-go/actions/workflows/go.yml)[](https://ci.appveyor.com/project/aliyun/credentials-go)
9[](https://scrutinizer-ci.com/g/aliyun/credentials-go/?branch=master)
10
11
12
13Alibaba Cloud Credentials for Go 是帮助 GO 开发者管理凭据的工具。
14
15本文将介绍如何获取和使用 Alibaba Cloud Credentials for Go。
16
17## 要求
18- 请确保你的系统安装了不低于 1.10.x 版本的 Go 环境。
19
20## 安装
21使用 `go get` 下载安装
22
23```sh
24$ go get -u github.com/aliyun/credentials-go
25```
26
27如果你使用 `dep` 来管理你的依赖包，你可以使用以下命令:
28
29```sh
30$ dep ensure -add github.com/aliyun/credentials-go
31```
32
33##快速使用
34在您开始之前，您需要注册阿里云帐户并获取您的[凭证](https://usercenter.console.aliyun.com/#/manage/ak)。
35
36### 凭证类型
37
38#### AccessKey
39通过[用户信息管理][ak]设置 access_key，它们具有该账户完全的权限，请妥善保管。有时出于安全考虑，您不能把具有完全访问权限的主账户 AccessKey 交于一个项目的开发者使用，您可以[创建RAM子账户][ram]并为子账户[授权][permissions]，使用RAM子用户的 AccessKey 来进行API调用。
40```go
41import (
42 "fmt"
43
44 "github.com/aliyun/credentials-go/credentials"
45)
46
47func main(){
48 config := new(credentials.Config).
49 // Which type of credential you want
50 SetType("access_key").
51 // AccessKeyId of your account
52 SetAccessKeyId("AccessKeyId").
53 // AccessKeySecret of your account
54 SetAccessKeySecret("AccessKeySecret")
55
56 akCredential, err := credentials.NewCredential(config)
57 if err != nil {
58 return
59 }
60 accessKeyId, err := akCredential.GetAccessKeyId()
61 accessSecret, err := akCredential.GetAccessKeySecret()
62 credentialType := akCredential.GetType()
63 fmt.Println(accessKeyId, accessSecret, credentialType)
64}
65```
66
67#### STS
68通过安全令牌服务（Security Token Service，简称 STS），申请临时安全凭证（Temporary Security Credentials，简称 TSC），创建临时安全凭证。
69```go
70import (
71 "fmt"
72
73 "github.com/aliyun/credentials-go/credentials"
74)
75
76func main() {
77 config := new(credentials.Config).
78 // Which type of credential you want
79 SetType("sts").
80 // AccessKeyId of your account
81 SetAccessKeyId("AccessKeyId").
82 // AccessKeySecret of your account
83 SetAccessKeySecret("AccessKeySecret").
84 // Temporary Security Token
85 SetSecurityToken("SecurityToken")
86
87 stsCredential, err := credentials.NewCredential(config)
88 if err != nil {
89 return
90 }
91 accessKeyId, err := stsCredential.GetAccessKeyId()
92 accessSecret, err := stsCredential.GetAccessKeySecret()
93 securityToken, err := stsCredential.GetSecurityToken()
94 credentialType := stsCredential.GetType()
95 fmt.Println(accessKeyId, accessSecret, securityToken, credentialType)
96}
97```
98
99#### AssumeRoleWithOIDC
100在执行oidc角色SSO时，通过调用AssumeRoleWithOIDC接口获取扮演RAM角色的临时身份凭证（STS令牌）。
101``` go
102package main
103
104import (
105 "fmt"
106 "net/http"
107
108 "github.com/aliyun/credentials-go/credentials"
109)
110
111func main() {
112 config := new(credentials.Config).
113 SetType("oidc_role_arn").
114 SetOIDCProviderArn("OIDCProviderArn").
115 SetOIDCTokenFilePath("OIDCTokenFilePath").
116 SetRoleSessionName("RoleSessionName").
117 SetPolicy("Policy").
118 SetRoleArn("RoleArn").
119 SetSessionExpiration(3600)
120 oidcCredential, err := credentials.NewCredential(config)
121 if err != nil {
122 return
123 }
124 accessKeyId, err := oidcCredential.GetAccessKeyId()
125 accessKeySecret, err := oidcCredential.GetAccessKeySecret()
126 token, err := oidcCredential.GetSecurityToken()
127 fmt.Println(accessKeyId, accessKeySecret, token)
128}
129```
130
131#### RamRoleArn
132通过指定[RAM角色][RAM Role]，让凭证自动申请维护 STS Token。你可以通过为 `Policy` 赋值来限制获取到的 STS Token 的权限。
133```go
134import (
135 "fmt"
136
137 "github.com/aliyun/credentials-go/credentials"
138)
139
140func main(){
141 config := new(credentials.Config).
142 // Which type of credential you want
143 SetType("ram_role_arn").
144 // AccessKeyId of your account
145 SetAccessKeyId("AccessKeyId").
146 // AccessKeySecret of your account
147 SetAccessKeySecret("AccessKeySecret").
148 // Format: acs:ram::USER_Id:role/ROLE_NAME
149 SetRoleArn("RoleArn").
150 // Role Session Name
151 SetRoleSessionName("RoleSessionName").
152 // Not required, limit the permissions of STS Token
153 SetPolicy("Policy").
154 // Not required, limit the Valid time of STS Token
155 SetRoleSessionExpiration(3600)
156
157 arnCredential, err := credentials.NewCredential(config)
158 if err != nil {
159 return
160 }
161 accessKeyId, err := arnCredential.GetAccessKeyId()
162 accessSecret, err := arnCredential.GetAccessKeySecret()
163 securityToken, err := arnCredential.GetSecurityToken()
164 credentialType := arnCredential.GetType()
165 fmt.Println(accessKeyId, accessSecret, securityToken, credentialType)
166}
167```
168
169#### EcsRamRole
170通过指定角色名称，让凭证自动申请维护 STS Token
171```go
172import (
173 "fmt"
174
175 "github.com/aliyun/credentials-go/credentials"
176)
177
178func main(){
179 config := new(credentials.Config).
180 // Which type of credential you want
181 SetType("ecs_ram_role").
182 // `roleName` is optional. It will be retrieved automatically if not set. It is highly recommended to set it up to reduce requests
183 SetRoleName("RoleName")
184
185 ecsCredential, err := credentials.NewCredential(config)
186 if err != nil {
187 return
188 }
189 accessKeyId, err := ecsCredential.GetAccessKeyId()
190 accessSecret, err := ecsCredential.GetAccessKeySecret()
191 securityToken, err := ecsCredential.GetSecurityToken()
192 credentialType := ecsCredential.GetType()
193 fmt.Println(accessKeyId, accessSecret, securityToken, credentialType)
194}
195```
196
197#### RsaKeyPair
198通过指定公钥Id和私钥文件，让凭证自动申请维护 AccessKey。仅支持日本站。
199```go
200import (
201 "fmt"
202
203 "github.com/aliyun/credentials-go/credentials"
204)
205
206func main(){
207 config := new(credentials.Config).
208 // Which type of credential you want
209 SetType("rsa_key_pair").
210 // The file path to store the PrivateKey
211 SetPrivateKeyFile("PrivateKeyFile").
212 // PublicKeyId of your account
213 SetPublicKeyId("PublicKeyId")
214
215 rsaCredential, err := credentials.NewCredential(config)
216 if err != nil {
217 return
218 }
219 accessKeyId, err := rsaCredential.GetAccessKeyId()
220 accessSecret, err := rsaCredential.GetAccessKeySecret()
221 securityToken, err := rsaCredential.GetSecurityToken()
222 credentialType := rsaCredential.GetType()
223 fmt.Println(accessKeyId, accessSecret, securityToken, credentialType)
224}
225```
226
227#### Bearer Token
228如呼叫中心(CCC)需用此凭证，请自行申请维护 Bearer Token。
229```go
230import (
231 "fmt"
232
233 "github.com/aliyun/credentials-go/credentials"
234)
235
236func main(){
237 config := new(credentials.Config).
238 // Which type of credential you want
239 SetType("bearer").
240 // BearerToken of your account
241 SetBearerToken("BearerToken").
242 config := &credentials.Config{
243
244 bearerCredential, err := credentials.NewCredential(config)
245 if err != nil {
246 return
247 }
248 bearerToken := bearerCredential.GetBearerToken()
249 credentialType := bearerCredential.GetType()
250 fmt.Println(bearerToken, credentialType)
251}
252```
253
254### 凭证提供程序链
255如果你调用 `NewCredential()` 时传入空， 将通过凭证提供链来为你获取凭证。
256
257#### 1. 环境凭证
258程序首先会在环境变量里寻找环境凭证，如果定义了 `ALIBABA_CLOUD_ACCESS_KEY_ID` 和 `ALIBABA_CLOUD_ACCESS_KEY_SECRET` 环境变量且不为空，程序将使用他们创建凭证。如否则，程序会在配置文件中加载和寻找凭证。
259
260#### 2. 配置文件
261如果用户主目录存在默认文件 `~/.alibabacloud/credentials` （Windows 为 `C:\Users\USER_NAME\.alibabacloud\credentials`），程序会自动创建指定类型和名称的凭证。默认文件可以不存在，但解析错误会抛出异常。也可以手动加载指定文件： `AlibabaCloud::load('/data/credentials', 'vfs://AlibabaCloud/credentials', ...);` 不同的项目、工具之间可以共用这个配置文件，因为超出项目之外，也不会被意外提交到版本控制。Windows 上可以使用环境变量引用到主目录 %UserProfile%。类 Unix 的系统可以使用环境变量 $HOME 或 ~ (tilde)。 可以通过定义 `ALIBABA_CLOUD_CREDENTIALS_FILE` 环境变量修改默认文件的路径。
262
263```ini
264[default] # 默认凭证
265type = access_key # 认证方式为 access_key
266access_key_id = foo # access key id
267access_key_secret = bar # access key secret
268```
269
270#### 3. 实例 RAM 角色
271如果定义了环境变量 `ALIBABA_CLOUD_ECS_METADATA` 且不为空，程序会将该环境变量的值作为角色名称，请求 `http://100.100.100.200/latest/meta-data/ram/security-credentials/` 获取临时安全凭证。
272
273## 许可证
274[Apache-2.0](/LICENSE)
275
276Copyright (c) 2009-present, Alibaba Cloud All rights reserved.
277
278[ak]: https://usercenter.console.aliyun.com/#/manage/ak
279[ram]: https://ram.console.aliyun.com/users
280[policy]: https://www.alibabacloud.com/help/doc-detail/28664.htm?spm=a2c63.p38356.a3.3.27a63b01khWgdh
281[permissions]: https://ram.console.aliyun.com/permissions
282[RAM Role]: https://ram.console.aliyun.com/#/role/list
View as plain text