本文中含有需要您注意的重要提示信息,忽略該信息可能對您的業務造成影響,請務必仔細閱讀。
使用Go SDK發起OSS請求,您需要配置訪問憑證。阿里云服務會通過訪問憑證驗證您的身份信息和訪問權限。您可以根據使用場景對認證和授權的要求,選擇不同類型的訪問憑證。本文介紹如何配置臨時訪問憑證和長期訪問憑證。
注意事項
如果您希望獲取關于OSS支持的Region與Endpoint的對應關系,請參見OSS地域和訪問域名。
初始化憑證提供者
憑證提供者選型
OSS支持多種方式初始化憑證提供者,您可以根據使用場景對認證和授權的要求,選擇對應的方式初始化憑證提供者。
憑證提供者初始化方式 | 適用場景 | 是否需要提供前置的AK或STS Token | 底層實現基于的憑證 | 憑證有效期 | 憑證輪轉或刷新方式 |
部署運行在安全、穩定且不易受外部攻擊的環境的應用程序,無需頻繁輪轉憑證就可以長期訪問云服務 | 是 | AK | 長期 | 手動輪轉 | |
部署運行在不可信的環境的應用程序,希望能控制訪問的有效期、權限 | 是 | STS Token | 臨時 | 手動刷新 | |
需要授權訪問云服務,例如跨阿里云賬號訪問云服務的應用程序 | 是 | STS Token | 臨時 | 自動刷新 | |
部署運行在阿里云的ECS實例、ECI實例、容器服務Kubernetes版的Worker節點中的應用程序 | 否 | STS Token | 臨時 | 自動刷新 | |
部署運行在阿里云的容器服務Kubernetes版的Worker節點中的不可信應用程序 | 否 | STS Token | 臨時 | 自動刷新 | |
如果以上憑證配置方式都不滿足要求時,您可以自定義獲取憑證的方式 | 自定義 | 自定義 | 自定義 | 自定義 | |
當您初始化憑據客戶端,且不傳入任何參數時,將會嘗試按照默認憑據鏈順序查找相關憑據信息 | 自定義 | 自定義 | 自定義 | 自定義 |
方式一:使用AK
如果您的應用程序部署運行在安全、穩定且不易受外部攻擊的環境中,需要長期訪問您的OSS,且不能頻繁輪轉憑證時,您可以使用阿里云主賬號或RAM用戶的AK(Access Key ID、Access Key Secret)初始化憑證提供者。需要注意的是,該方式需要您手動維護一個AK,存在安全性風險和維護復雜度增加的風險。如何獲取AK,請參見CreateAccessKey - 創建主賬號或RAM用戶訪問密鑰。
環境變量
阿里云賬號擁有資源的全部權限,AK一旦泄露,會給系統帶來巨大風險,不建議使用。推薦使用最小化授權的RAM用戶的AK。
如需創建RAM用戶的AK,請直接訪問創建AccessKey。RAM用戶的Access Key ID、Access Key Secret信息僅在創建時顯示,請及時保存,如若遺忘請考慮創建新的AK進行輪換。
使用RAM用戶AccessKey配置環境變量。
Linux
在命令行界面執行以下命令來將環境變量設置追加到
~/.bashrc
文件中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc
執行以下命令使變更生效。
source ~/.bashrc
執行以下命令檢查環境變量是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
macOS
在終端中執行以下命令,查看默認Shell類型。
echo $SHELL
根據默認Shell類型進行操作。
Zsh
執行以下命令來將環境變量設置追加到
~/.zshrc
文件中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc
執行以下命令使變更生效。
source ~/.zshrc
執行以下命令檢查環境變量是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
Bash
執行以下命令來將環境變量設置追加到
~/.bash_profile
文件中。echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile
執行以下命令使變更生效。
source ~/.bash_profile
執行以下命令檢查環境變量是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
Windows
CMD
在CMD中運行以下命令。
setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID" setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"
運行以下命令,檢查環境變量是否生效。
echo %OSS_ACCESS_KEY_ID% echo %OSS_ACCESS_KEY_SECRET%
PowerShell
在PowerShell中運行以下命令。
[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User) [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)
運行以下命令,檢查環境變量是否生效。
[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User) [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)
使用環境變量來傳遞憑證信息。
package main import ( "log" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials" ) func main() { // 請根據實際要求設置region,以實例華東1(杭州)為例,regionID為cn-hangzhou region := "cn-hangzhou" // 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET provider := credentials.NewEnvironmentVariableCredentialsProvider() // 加載默認配置并設置憑證提供者和region cfg := oss.LoadDefaultConfig(). WithCredentialsProvider(provider). WithRegion(region) // 創建OSS客戶端 client := oss.NewClient(cfg) log.Printf("ossclient: %v", client) }
靜態憑證
您可以在代碼中使用變量來引用憑證,這些變量在運行時會被環境變量、配置文件或其他外部數據源中的實際憑證值填充。
以下操作步驟以配置文件為例。
需要安裝go-ini
庫。如果尚未安裝,您可以使用以下命令安裝:
go get -u github.com/go-ini/ini
創建配置文件
config.ini
。[credentials] alibaba_cloud_access_key_id = <ALIBABA_CLOUD_ACCESS_KEY_ID> alibaba_cloud_access_key_secret = <ALIBABA_CLOUD_ACCESS_KEY_SECRET>
使用配置文件來傳遞憑證信息。
package main import ( "log" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials" "gopkg.in/ini.v1" ) func main() { // 請根據實際要求設置region,以實例華東1(杭州)為例,regionID為cn-hangzhou region := "cn-hangzhou" // 讀取配置文件 cfgFile, err := ini.Load("config.ini") if err != nil { log.Fatalf("Failed to load config file: %v", err) } // 獲取配置信息 accessKeyID := cfgFile.Section("oss").Key("alibaba_cloud_access_key_id").String() accessKeySecret := cfgFile.Section("oss").Key("alibaba_cloud_access_key_secret").String() // 創建憑證提供者 provider := credentials.NewStaticCredentialsProvider(accessKeyID, accessKeySecret) // 加載默認配置并設置憑證提供者和區域 cfg := oss.LoadDefaultConfig(). WithCredentialsProvider(provider). WithRegion(region) // 創建OSS客戶端 client := oss.NewClient(cfg) log.Printf("ossclient: %v", client) }
方式二:使用STS Token
如果您的應用程序需要臨時訪問OSS,您可以使用通過STS服務獲取的臨時身份憑證(Access Key ID、Access Key Secret和Security Token)初始化憑證提供者。需要注意的是,該方式需要您手動維護一個STS Token,存在安全性風險和維護復雜度增加的風險。此外,如果您需要多次臨時訪問OSS,您需要手動刷新STS Token。
如何獲取STS Token,請參見AssumeRole - 獲取扮演角色的臨時身份憑證。
如果您希望獲取關于STS服務的接入點列表,請參見服務接入點。
使用臨時身份憑證設置環境變量。
Mac OS X/Linux/Unix
警告請注意,此處使用的是通過STS服務獲取的臨時身份憑證(Access Key ID、Access Key Secret和Security Token),而非RAM用戶的AK(Access Key ID、Access Key Secret)。
請注意區分STS服務獲取的Access Key ID以STS開頭,例如“STS.L4aBSCSJVMuKg5U1****”。
export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID> export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET> export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>
Windows
警告請注意,此處使用的是通過STS服務獲取的臨時身份憑證(Access Key ID、Access Key Secret和Security Token),而非RAM用戶的AK(Access Key ID、Access Key Secret)。
請注意區分STS服務獲取的Access Key ID以STS開頭,例如“STS.L4aBSCSJVMuKg5U1****”。
set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID> set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET> set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>
通過環境變量來傳遞憑證信息。
package main import ( "log" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials" ) func main() { // 請根據實際要求設置region,以實例華東1(杭州)為例,regionID為cn-hangzhou region := "cn-hangzhou" // 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET,OSS_SESSION_TOKEN provider := credentials.NewEnvironmentVariableCredentialsProvider() // 加載默認配置并設置憑證提供者和region cfg := oss.LoadDefaultConfig(). WithCredentialsProvider(provider). WithRegion(region) // 創建OSS客戶端 client := oss.NewClient(cfg) log.Printf("ossclient: %v", client) }
方式三:使用RAMRoleARN
如果您的應用程序需要授權訪問OSS,例如跨阿里云賬號訪問OSS,您可以使用RAMRoleARN初始化憑證提供者。該方式底層實現是STS Token。通過指定RAM角色的ARN(Alibabacloud Resource Name),Credentials工具會前往STS服務獲取STS Token,并在會話到期前自動刷新STS Token。此外,您還可以通過為policy
賦值來限制RAM角色到一個更小的權限集合。需要注意的是,該方式需要您提供一個AK,存在安全性風險和維護復雜度增加的風險。如何獲取AK,請參見CreateAccessKey - 為RAM用戶創建訪問密鑰。如何獲取RAMRoleARN,請參見CreateRole - 創建角色。
添加credentials依賴。
go get github.com/aliyun/credentials-go/credentials
配置訪問憑證。
package main import ( "context" "log" "os" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials" openapicred "github.com/aliyun/credentials-go/credentials" ) func main() { // 請根據實際要求設置region,以實例華東1(杭州)為例,regionID為cn-hangzhou region := "cn-hangzhou" config := new(openapicred.Config). // 填寫Credential類型,固定值為ram_role_arn SetType("ram_role_arn"). // 從環境變量中獲取RAM用戶的訪問密鑰(AccessKeyId和AccessKeySecret) SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")). SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")). // 以下操作默認直接填入參數數值,您也可以通過添加環境變量,并使用os.Getenv("<變量名稱>")的方式來set對應參數 // 從環境變量中獲取RAM角色的ARN信息,即需要扮演的角色ID,格式為acs:ram::$accountID:role/$roleName SetRoleArn("ALIBABA_CLOUD_ROLE_ARN"). // RoleArn默認環境變量規范名稱ALIBABA_CLOUD_ROLE_ARN // 自定義角色會話名稱,用于區分不同的令牌 SetRoleSessionName("ALIBABA_CLOUD_ROLE_SESSION_NAME"). // RoleSessionName默認環境變量規范名稱ALIBABA_CLOUD_ROLE_SESSION_NAME //(可選)限制STS Token權限 SetPolicy("Policy"). //(可選)限制STS Token的有效時間 SetRoleSessionExpiration(3600) arnCredential, gerr := openapicred.NewCredential(config) provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) { if gerr != nil { return credentials.Credentials{}, gerr } cred, err := arnCredential.GetCredential() if err != nil { return credentials.Credentials{}, err } return credentials.Credentials{ AccessKeyID: *cred.AccessKeyId, AccessKeySecret: *cred.AccessKeySecret, SecurityToken: *cred.SecurityToken, }, nil }) // 加載默認配置并設置憑證提供者和region cfg := oss.LoadDefaultConfig(). WithCredentialsProvider(provider). WithRegion(region) // 創建OSS客戶端 client := oss.NewClient(cfg) log.Printf("ossclient: %v", client) }
方式四:使用ECSRAMRole
如果您的應用程序運行在ECS實例、ECI實例、容器服務Kubernetes版的Worker節點中,建議您使用ECSRAMRole初始化憑證提供者。該方式底層實現是STS Token。ECSRAMRole允許您將一個角色關聯到ECS實例、ECI實例或容器服務 Kubernetes 版的Worker節點,實現在實例內部自動刷新STS Token。該方式無需您提供一個AK或STS Token,消除了手動維護AK或STS Token的風險。如何獲取ECSRAMRole,請參見CreateRole - 創建角色。
添加credentials依賴。
go get github.com/aliyun/credentials-go/credentials
配置訪問憑證。
package main import ( "context" "log" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials" openapicred "github.com/aliyun/credentials-go/credentials" ) func main() { // 請根據實際要求設置region,以實例華東1(杭州)為例,regionID為cn-hangzhou region := "cn-hangzhou" config := new(openapicred.Config). // 指定Credential類型,固定值為ecs_ram_role SetType("ecs_ram_role"). // (可選項)指定角色名稱。如果不指定,OSS會自動獲取角色。強烈建議指定角色名稱,以降低請求次數 SetRoleName("RoleName") arnCredential, gerr := openapicred.NewCredential(config) provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) { if gerr != nil { return credentials.Credentials{}, gerr } cred, err := arnCredential.GetCredential() if err != nil { return credentials.Credentials{}, err } return credentials.Credentials{ AccessKeyID: *cred.AccessKeyId, AccessKeySecret: *cred.AccessKeySecret, SecurityToken: *cred.SecurityToken, }, nil }) // 加載默認配置并設置憑證提供者和region cfg := oss.LoadDefaultConfig(). WithCredentialsProvider(provider). WithRegion(region) // 創建OSS客戶端 client := oss.NewClient(cfg) log.Printf("ossclient: %v", client) }
方式五:使用OIDCRoleARN
在容器服務Kubernetes版中設置了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配置ServiceAccount的RAM權限實現Pod權限隔離。
添加credentials依賴。
go get github.com/aliyun/credentials-go/credentials
配置訪問憑證。
package main import ( "context" "log" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials" openapicred "github.com/aliyun/credentials-go/credentials" ) func main() { // 請根據實際要求設置region,以實例華東1(杭州)為例,regionID為cn-hangzhou region := "cn-hangzhou" config := new(openapicred.Config). // 指定Credential類型,固定值為oidc_role_arn SetType("oidc_role_arn"). // 指定 OIDC 提供者的 ARN(Amazon Resource Name),格式為 acs:ram::account-id:oidc-provider/provider-name SetOIDCProviderArn("OIDCProviderArn"). // 指定 OIDC 令牌的文件路徑,用于存儲 OIDC 令牌 SetOIDCTokenFilePath("OIDCTokenFilePath"). // 自定義角色會話名稱,用于區分不同的令牌 SetRoleSessionName("RoleSessionName"). // RoleSessionName默認環境變量規范名稱ALIBABA_CLOUD_ROLE_SESSION_NAME // (可選)指定訪問角色時要使用的策略 SetPolicy("Policy"). // 填寫角色的ARN信息,即需要扮演的角色ID。格式為acs:ram::113511544585****:oidc-provider/TestOidcProvider SetRoleArn("RoleArn"). // 設置會話有效期 SetSessionExpiration(3600) arnCredential, gerr := openapicred.NewCredential(config) provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) { if gerr != nil { return credentials.Credentials{}, gerr } cred, err := arnCredential.GetCredential() if err != nil { return credentials.Credentials{}, err } return credentials.Credentials{ AccessKeyID: *cred.AccessKeyId, AccessKeySecret: *cred.AccessKeySecret, SecurityToken: *cred.SecurityToken, }, nil }) // 加載默認配置并設置憑證提供者和region cfg := oss.LoadDefaultConfig(). WithCredentialsProvider(provider). WithRegion(region) // 創建OSS客戶端 client := oss.NewClient(cfg) log.Printf("ossclient: %v", client) }
方式六:自定義憑證提供者
當以上憑證配置方式不滿足要求時,您可以自定義獲取憑證的方式。SDK 支持多種實現方式。
通過credentials.CredentialsProviderFunc接口
package main import ( "context" "log" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials" ) func main() { // 請根據實際要求設置region,以實例華東1(杭州)為例,regionID為cn-hangzhou region := "cn-hangzhou" // 創建自定義憑證提供者 provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) { // 返回長期憑證 return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret"}, nil // 返回臨時憑證 //return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret", SecurityToken: "token"}, nil }) // 加載默認配置并設置憑證提供者和region cfg := oss.LoadDefaultConfig(). WithCredentialsProvider(provider). WithRegion(region) // 創建OSS客戶端 client := oss.NewClient(cfg) log.Printf("ossclient: %v", client) }
實現credentials.CredentialsProvider接口
package main import ( "context" "log" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss" "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials" ) type CustomerCredentialsProvider struct { // TODO } func NewCustomerCredentialsProvider() CustomerCredentialsProvider { return CustomerCredentialsProvider{} } func (s CustomerCredentialsProvider) GetCredentials(_ context.Context) (credentials.Credentials, error) { // 返回長期憑證 return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret"}, nil // 返回臨時憑證 //return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret", SecurityToken: "token"}, nil } func main() { // 請根據實際要求設置region,以實例華東1(杭州)為例,regionID為cn-hangzhou region := "cn-hangzhou" // 創建自定義憑證提供者 provider := NewCustomerCredentialsProvider() // 加載默認配置并設置憑證提供者和region cfg := oss.LoadDefaultConfig(). WithCredentialsProvider(provider). WithRegion(region) // 創建OSS客戶端 client := oss.NewClient(cfg) log.Printf("ossclient: %v", client) }
方式七:使用默認憑據鏈
當您在初始化憑據客戶端不傳入任何參數時,Credentials會使用默認憑據鏈方式初始化客戶端。默認憑據的讀取邏輯請參見默認憑據鏈。
package main
import (
"context"
"log"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
osscred "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
"github.com/aliyun/credentials-go/credentials"
)
func main() {
// 請根據實際要求設置region,以實例華東1(杭州)為例,regionID為cn-hangzhou
region := "cn-hangzhou"
// 傳nil,則會走默認憑證鏈模式,會自動獲取憑證
arnCredential, gerr := credentials.NewCredential(nil)
provider := osscred.CredentialsProviderFunc(func(ctx context.Context) (osscred.Credentials, error) {
if gerr != nil {
return osscred.Credentials{}, gerr
}
cred, err := arnCredential.GetCredential()
if err != nil {
return osscred.Credentials{}, err
}
return osscred.Credentials{
AccessKeyID: *cred.AccessKeyId,
AccessKeySecret: *cred.AccessKeySecret,
SecurityToken: *cred.SecurityToken,
}, nil
})
// 加載默認配置并設置憑證提供者和region
cfg := oss.LoadDefaultConfig().
WithCredentialsProvider(provider).
WithRegion(region)
// 創建ossClient
client := oss.NewClient(cfg)
log.Printf("ossclient: %v", client)
}
常見問題
在使用通過STS服務獲取的臨時身份憑證去初始化憑證提供者時,誤使用RAM用戶的AK
當您使用通過STS服務獲取的臨時身份憑證(Access Key ID、Access Key Secret和Security Token)初始化訪問憑證時,請勿混淆STS服務返回的AK與RAM用戶的AK,STS對應的AK是以STS開頭,示例如下:
如何查看RAM用戶的AK?是否可以查看舊的AccessKey Secret?
如需查看RAM用戶的AK,請直接參考文檔查看RAM用戶的AccessKey信息。
RAM用戶的AccessKey Secret僅在創建時顯示,之后無法查看,若已經遺忘則無法找回。您可以直接訪問RAM控制臺選擇具體用戶,并創建新的AccessKey進行輪換。詳細操作請參見創建AccessKey。