1English | [简体中文](README-CN.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 is a tool for Go developers to manage credentials.
14
15This document introduces how to obtain and use Alibaba Cloud Credentials for Go.
16
17## Requirements
18- It's necessary for you to make sure your system have installed a Go environment which is new than 1.10.x.
19
20## Installation
21Use `go get` to install SDK：
22
23```sh
24$ go get -u github.com/aliyun/credentials-go
25```
26
27If you use `dep` to manage your dependence, you can use the following command:
28
29```sh
30$ dep ensure -add github.com/aliyun/credentials-go
31```
32
33## Quick Examples
34Before you begin, you need to sign up for an Alibaba Cloud account and retrieve your [Credentials](https://usercenter.console.aliyun.com/#/manage/ak).
35
36### Credential Type
37
38#### AccessKey
39Setup access_key credential through [User Information Management][ak], it have full authority over the account, please keep it safe. Sometimes for security reasons, you cannot hand over a primary account AccessKey with full access to the developer of a project. You may create a sub-account [RAM Sub-account][ram] , grant its [authorization][permissions]，and use the AccessKey of RAM Sub-account.
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
68Create a temporary security credential by applying Temporary Security Credentials (TSC) through the Security Token Service (STS).
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#### RamRoleArn
100By specifying [RAM Role][RAM Role], the credential will be able to automatically request maintenance of STS Token. If you want to limit the permissions([How to make a policy][policy]) of STS Token, you can assign value for `Policy`.
101```go
102import (
103 "fmt"
104
105 "github.com/aliyun/credentials-go/credentials"
106)
107
108func main(){
109 config := new(credentials.Config).
110 // Which type of credential you want
111 SetType("ram_role_arn").
112 // AccessKeyId of your account
113 SetAccessKeyId("AccessKeyId").
114 // AccessKeySecret of your account
115 SetAccessKeySecret("AccessKeySecret").
116 // Format: acs:ram::USER_Id:role/ROLE_NAME
117 SetRoleArn("RoleArn").
118 // Role Session Name
119 SetRoleSessionName("RoleSessionName").
120 // Not required, limit the permissions of STS Token
121 SetPolicy("Policy").
122 // Not required, limit the Valid time of STS Token
123 SetRoleSessionExpiration(3600)
124
125 arnCredential, err := credentials.NewCredential(config)
126 if err != nil {
127 return
128 }
129 accessKeyId, err := arnCredential.GetAccessKeyId()
130 accessSecret, err := arnCredential.GetAccessKeySecret()
131 securityToken, err := arnCredential.GetSecurityToken()
132 credentialType := arnCredential.GetType()
133 fmt.Println(accessKeyId, accessSecret, securityToken, credentialType)
134}
135```
136#### uriCredential
137```go
138import (
139 "fmt"
140
141 "github.com/aliyun/credentials-go/credentials"
142)
143
144func main(){
145 config := new(credentials.Config).SetType("credentials_uri").SetURL("http://127.0.0.1")
146 credential, err := credentials.NewCredential(config)
147 if err != nil {
148 return
149 }
150 accessKeyId, err := credential.GetAccessKeyId()
151 accessKeySecret, err := credential.GetAccessKeySecret()
152 fmt.Println(accessKeyId, accessKeySecret)
153}
154```
155
156
157#### EcsRamRole
158By specifying the role name, the credential will be able to automatically request maintenance of STS Token.
159```go
160import (
161 "fmt"
162
163 "github.com/aliyun/credentials-go/credentials"
164)
165
166func main(){
167 config := new(credentials.Config).
168 // Which type of credential you want
169 SetType("ecs_ram_role").
170 // `roleName` is optional. It will be retrieved automatically if not set. It is highly recommended to set it up to reduce requests
171 SetRoleName("RoleName")
172
173 ecsCredential, err := credentials.NewCredential(config)
174 if err != nil {
175 return
176 }
177 accessKeyId, err := ecsCredential.GetAccessKeyId()
178 accessSecret, err := ecsCredential.GetAccessKeySecret()
179 securityToken, err := ecsCredential.GetSecurityToken()
180 credentialType := ecsCredential.GetType()
181 fmt.Println(accessKeyId, accessSecret, securityToken, credentialType)
182}
183```
184
185#### RsaKeyPair
186By 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.
187```go
188import (
189 "fmt"
190
191 "github.com/aliyun/credentials-go/credentials"
192)
193
194func main(){
195 config := new(credentials.Config).
196 // Which type of credential you want
197 SetType("rsa_key_pair").
198 // The file path to store the PrivateKey
199 SetPrivateKeyFile("PrivateKeyFile").
200 // PublicKeyId of your account
201 SetPublicKeyId("PublicKeyId")
202
203 rsaCredential, err := credentials.NewCredential(config)
204 if err != nil {
205 return
206 }
207 accessKeyId, err := rsaCredential.GetAccessKeyId()
208 accessSecret, err := rsaCredential.GetAccessKeySecret()
209 securityToken, err := rsaCredential.GetSecurityToken()
210 credentialType := rsaCredential.GetType()
211 fmt.Println(accessKeyId, accessSecret, securityToken, credentialType)
212}
213```
214
215#### Bearer Token
216If credential is required by the Cloud Call Centre (CCC), please apply for Bearer Token maintenance by yourself.
217```go
218import (
219 "fmt"
220
221 "github.com/aliyun/credentials-go/credentials"
222)
223
224func main(){
225 config := new(credentials.Config).
226 // Which type of credential you want
227 SetType("bearer").
228 // BearerToken of your account
229 SetBearerToken("BearerToken").
230
231 bearerCredential, err := credentials.NewCredential(config)
232 if err != nil {
233 return
234 }
235 bearerToken := bearerCredential.GetBearerToken()
236 credentialType := bearerCredential.GetType()
237 fmt.Println(bearerToken, credentialType)
238}
239```
240
241#### AssumeRoleWithOIDC
242When performing oidc role SSO, obtain the temporary identity credential (STS Token) that plays the role of RAM by calling the AssumeRoleWithOIDC interface.
243``` go
244package main
245
246import (
247 "fmt"
248 "net/http"
249
250 "github.com/aliyun/credentials-go/credentials"
251)
252
253func main() {
254 config := new(credentials.Config).
255 SetType("oidc_role_arn").
256 SetOIDCProviderArn("OIDCProviderArn").
257 SetOIDCTokenFilePath("OIDCTokenFilePath").
258 SetRoleSessionName("RoleSessionName").
259 SetPolicy("Policy").
260 SetRoleArn("RoleArn").
261 SetSessionExpiration(3600)
262 oidcCredential, err := credentials.NewCredential(config)
263 if err != nil {
264 return
265 }
266 accessKeyId, err := oidcCredential.GetAccessKeyId()
267 accessKeySecret, err := oidcCredential.GetAccessKeySecret()
268 token, err := oidcCredential.GetSecurityToken()
269 fmt.Println(accessKeyId, accessKeySecret, token)
270}
271```
272
273
274### Provider
275If you call `NewCredential()` with nil, it will use provider chain to get credential for you.
276
277#### 1. Environment Credentials
278The program first looks for environment credentials in the 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 the default credential. If not, the program loads and looks for the client in the configuration file.
279
280#### 2. Config File
281If there is `~/.alibabacloud/credentials` default file (Windows shows `C:\Users\USER_NAME\.alibabacloud\credentials`), the program will automatically create credential with the name of 'default'. The default file may not exist, but a parse error throws an exception. The specified files can also be loaded indefinitely: `AlibabaCloud::load('/data/credentials', 'vfs://AlibabaCloud/credentials', ...);` This configuration file can be shared between different projects and between different tools. Because it is outside the project and will not be accidentally committed to the version control. Environment variables can be used on Windows to refer to the home directory %UserProfile%. Unix-like systems can use the environment variable $HOME or ~ (tilde). The path to the default file can be modified by defining the `ALIBABA_CLOUD_CREDENTIALS_FILE` environment variable.
282
283```ini
284[default] # Default credential
285type = access_key # Certification type: access_key
286access_key_id = foo # access key id
287access_key_secret = bar # access key secret
288```
289
290#### 3. Instance RAM Role
291If 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 `http://100.100.100.200/latest/meta-data/ram/security-credentials/` to get the temporary Security credential.
292
293## License
294[Apache-2.0](/LICENSE)
295
296Copyright (c) 2009-present, Alibaba Cloud All rights reserved.
297
298[ak]: https://usercenter.console.aliyun.com/#/manage/ak
299[ram]: https://ram.console.aliyun.com/users
300[policy]: https://www.alibabacloud.com/help/doc-detail/28664.htm?spm=a2c63.p38356.a3.3.27a63b01khWgdh
301[permissions]: https://ram.console.aliyun.com/permissions
302[RAM Role]: https://ram.console.aliyun.com/#/role/list
View as plain text