如何为OSS Swift SDK配置访问凭证

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

使用 Swift SDK发起OSS请求,您需要配置访问凭证。阿里云服务会通过 访问凭证验证您的身份信息和访问权限。您可以根据使用场景对认证和授权的要求,选择不同类型的访问凭证。

注意事项

凭证提供者选型

OSS支持多种方式初始化凭证提供者,您可以根据使用场景对认证和授权的要求,选择对应的方式初始化凭证提供者。

凭证提供者初始化方式

适用场景

是否需要提供前置的AKSTS Token

底层实现基于的凭证

凭证有效期

凭证轮转或刷新方式

使用RAM用户的AK

部署运行在安全、稳定且不易受外部攻击的环境的应用程序,无需频繁轮转凭证就可以长期访问云服务

AK

长期

手动轮转

使用STS临时访问凭证

部署运行在不可信的环境的应用程序,希望能控制访问的有效期、权限

STS Token

临时

手动刷新

自定义凭证提供者

如果以上凭证配置方式都不满足要求时,您可以自定义获取凭证的方式

自定义

自定义

自定义

自定义

常用配置示例

使用RAM用户的AK

如果您的应用程序部署运行在安全、稳定且不易受外部攻击的环境中,需要长期访问您的OSS,且不能频繁轮转凭证时,您可以使用阿里云主账号或RAM用户的AK(Access Key ID、Access Key Secret)初始化凭证提供者。需要注意的是,该方式需要您手动维护一个AK,存在安全性风险和维护复杂度增加的风险。

警告
  • 阿里云账号拥有资源的全部权限,AK一旦泄露,会给系统带来巨大风险,不建议使用。推荐使用最小化授权的RAM用户的AK。

  • 如需创建RAM用户的AK,请直接访问创建AccessKey。RAM用户的Access Key ID、Access Key Secret信息仅在创建时显示,请及时保存,如若遗忘请考虑创建新的AK进行轮换。

环境变量

  1. 使用RAM用户AccessKey配置环境变量。

    Linux
    1. 在命令行界面执行以下命令来将环境变量设置追加到~/.bashrc 文件中。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc
      1. 执行以下命令使变更生效。

        source ~/.bashrc
      2. 执行以下命令检查环境变量是否生效。

        echo $OSS_ACCESS_KEY_ID
        echo $OSS_ACCESS_KEY_SECRET
    macOS
    1. 在终端中执行以下命令,查看默认Shell类型。

      echo $SHELL
      1. 根据默认Shell类型进行操作。

        Zsh
        1. 执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。

          echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
          echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc
        2. 执行以下命令使变更生效。

          source ~/.zshrc
        3. 执行以下命令检查环境变量是否生效。

          echo $OSS_ACCESS_KEY_ID
          echo $OSS_ACCESS_KEY_SECRET
        Bash
        1. 执行以下命令来将环境变量设置追加到 ~/.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
        2. 执行以下命令使变更生效。

          source ~/.bash_profile
        3. 执行以下命令检查环境变量是否生效。

          echo $OSS_ACCESS_KEY_ID
          echo $OSS_ACCESS_KEY_SECRET
    Windows
    CMD
    1. CMD中运行以下命令。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"
      1. 运行以下命令,检查环境变量是否生效。

        echo %OSS_ACCESS_KEY_ID%
        echo %OSS_ACCESS_KEY_SECRET%
    PowerShell
    1. 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)
      1. 运行以下命令,检查环境变量是否生效。

        [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
        [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)
  2. 参考上述方式修改系统环境变量后,请重启或刷新您的编译运行环境,包括IDE、命令行界面、其他桌面应用程序及后台服务,以确保最新的系统环境变量成功加载。

  3. 使用环境变量来传递凭证信息。

    import AlibabaCloudOSS
    import Foundation
    
    @main
    struct Main {
        static func main() async {
            // 填写Bucket所在地域(示例:华东1cn-hangzhou)
            let region = "cn-hangzhou"
            // 可选项,指定访问OSS服务的域名。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com
            let endpoint: String? = nil
    
            // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_IDOSS_ACCESS_KEY_SECRET。
            let credentialsProvider = EnvironmentCredentialsProvider()
    
            // 配置OSS客户端参数
            let config = Configuration.default()
                .withRegion(region)        // 设置Bucket所在地域
                .withCredentialsProvider(credentialsProvider)  // 设置访问凭证
                
            // 设置自定义Endpoint
            if let endpoint = endpoint {
                config.withEndpoint(endpoint)
            }
            
            // 创建OSS客户端实例
            let client = Client(config)
            
            // 使用Client发起请求,例如执行文件上传、下载或管理等操作...
        }
    }

静态凭证

以下示例代码展示了如何对访问凭据直接进行硬编码,显式设置要使用的访问密钥。

警告

请勿将访问凭据嵌入到生产环境的应用程序中,此方法仅用于测试目的。

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        // 填写Bucket所在地域(示例:华东1为cn-hangzhou)
        let region = "cn-hangzhou"
        // 可选项,指定访问OSS服务的域名。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com
        let endpoint: String? = nil

        // 填写RAM用户的Access Key ID和Access Key Secret
        let accessKeyId = "yourAccessKeyID"
        let accessKeySecret = "yourAccessKeySecret"
        
        // 使用StaticCredentialsProvider方法直接设置accessKeyId和accessKeySecret
        let credentialsProvider = StaticCredentialsProvider(accessKeyId: accessKeyId,
                                                            accessKeySecret: accessKeySecret)

        // 配置OSS客户端参数
        let config = Configuration.default()
            .withRegion(region)        // 设置Bucket所在地域
            .withCredentialsProvider(credentialsProvider)  // 设置访问凭证
            
        // 设置自定义Endpoint
        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }
        
        // 创建OSS客户端实例
        let client = Client(config)
        
        // 使用Client发起请求,例如执行文件上传、下载或管理等操作...
    }
}

使用STS临时访问凭证

如果您的应用程序需要临时访问OSS,您可以使用通过STS服务获取的临时身份凭证(Access Key ID、Access Key SecretSecurity Token)初始化凭证提供者。需要注意的是,该方式需要您手动维护一个STS Token,存在安全性风险和维护复杂度增加的风险。此外,如果您需要多次临时访问OSS,您需要手动刷新STS Token。

重要

环境变量

  1. 使用临时身份凭证设置环境变量。

    Mac OS X/Linux/Unix

    警告
    • 请注意,此处使用的是通过STS服务获取的临时身份凭证(Access Key ID、Access Key SecretSecurity Token),而非RAM用户的Access KeyAccess Key Secret。

    • 请注意区分STS服务获取的Access Key IDSTS开头,例如“STS.****************”。

    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 SecretSecurity Token),而非RAM用户的AK(Access Key ID、Access Key Secret)。

    • 请注意区分STS服务获取的Access Key IDSTS开头,例如“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>
  2. 通过环境变量来传递凭证信息。

    import AlibabaCloudOSS
    import Foundation
    
    @main
    struct Main {
        static func main() async {
            // 填写Bucket所在地域(示例:华东1cn-hangzhou)
            let region = "cn-hangzhou"
            // 可选项,指定访问OSS服务的域名。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com
            let endpoint: String? = nil
    
            // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_IDOSS_ACCESS_KEY_SECRET。
            let credentialsProvider = EnvironmentCredentialsProvider()
    
            // 配置OSS客户端参数
            let config = Configuration.default()
                .withRegion(region)        // 设置Bucket所在地域
                .withCredentialsProvider(credentialsProvider)  // 设置访问凭证
                
            // 设置自定义Endpoint
            if let endpoint = endpoint {
                config.withEndpoint(endpoint)
            }
            
            // 创建OSS客户端实例
            let client = Client(config)
            
            // 使用Client发起请求,例如执行文件上传、下载或管理等操作...
        }
    }

静态凭证

以下示例代码展示了如何对访问凭据直接进行硬编码,显式设置要使用的临时访问密钥。

警告

请勿将访问凭据嵌入到生产环境的应用程序中,此方法仅用于测试目的。

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        // 填写Bucket所在地域(示例:华东1为cn-hangzhou)
        let region = "cn-hangzhou"
        // 可选项,指定访问OSS服务的域名。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com
        let endpoint: String? = nil

        // 填写获取的临时访问密钥AccessKey ID和AccessKey Secret,非阿里云账号AccessKey ID和AccessKey Secret。
        // 请注意区分STS服务获取的Access Key ID是以STS开头,如下所示。
        let accessKeyId = "yourAccessKeyID"
        let accessKeySecret = "yourAccessKeySecret"
        let securityToken = "yourSecurityToken"
        
        // 使用StaticCredentialsProvider方法直接设置accessKeyId、accessKeySecret和securityToken。
        let credentialsProvider = StaticCredentialsProvider(accessKeyId: accessKeyId,
                                                            accessKeySecret: accessKeySecret,
                                                            securityToken: securityToken)

        // 配置OSS客户端参数
        let config = Configuration.default()
            .withRegion(region)        // 设置Bucket所在地域
            .withCredentialsProvider(credentialsProvider)  // 设置访问凭证
            
        // 设置自定义Endpoint
        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }
        
        // 创建OSS客户端实例
        let client = Client(config)
        
        // 使用Client发起请求,例如执行文件上传、下载或管理等操作...
    }
}

更多场景化配置示例

自定义凭证提供者

当以上凭证配置方式不满足要求时,您可以自定义获取凭证的方式。SDK 支持多种实现方式。

  1. 通过ClosureCredentialsProvider接口

您可以通过实现ClosureCredentialsProvider接口的方式,来自定义凭证的获取方式。

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        // 填写Bucket所在地域(示例:华东1为cn-hangzhou)
        let region = "cn-hangzhou"
        // 可选项,指定访问OSS服务的域名。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com
        let endpoint: String? = nil
        
        // 方式1:获取长期访问凭证
        let credentialsProvider = ClosureCredentialsProvider {
            // TODO
            // 您可以自定义长期访问凭证的获取方法...
            
            // 假设获取得到的值如下
            let accessKeyId = "yourAccessKeyID"
            let accessKeySecret = "yourAccessKeySecret"
            
            // 返回长期访问凭证
            return Credentials(accessKeyId: accessKeyId,
                        accessKeySecret: accessKeySecret)
        }
        
        // 方式2:获取临时凭证
        // let credentialsProvider = ClosureCredentialsProvider {
             // TODO
            // 您可以自定义临时访问凭证的获取方法...
        
            // 假设获取得到的值如下
            // let accessKeyId = "yourAccessKeyID"
            // let accessKeySecret = "yourAccessKeySecret"
            // let securityToken = "yourSecurityToken"
            
        // 返回临时访问凭证
        //  return Credentials(accessKeyId: accessKeyId,
        //               accessKeySecret: accessKeySecret,
        //                securityToken: securityToken)
        // }

        // 配置OSS客户端参数
        let config = Configuration.default()
            .withRegion(region)        // 设置Bucket所在地域
            .withCredentialsProvider(credentialsProvider)  // 设置访问凭证
            
        // 设置自定义Endpoint
        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }
        
        // 创建OSS客户端实例
        let client = Client(config)
        
        // 使用Client发起请求,例如执行文件上传、下载或管理等操作...
    }
}
  1. 通过RefreshCredentialsProvider接口

您可以通过RefreshCredentialsProvider接口来自定义访问凭证的获取和自动刷新逻辑。该机制支持两种模式:

  • 不自动刷新访问凭证:不在凭证闭包函数中设置过期时间(expiration),此时将不会自动刷新访问凭证。

  • 自动刷新访问凭证:在闭包函数中设置一个过期时间(expiration),此时RefreshCredentialsProvider接口将会结合refreshInterval刷新时间和过期时间,定期调用闭包函数以更新访问凭证。

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        // 填写Bucket所在地域(示例:华东1为cn-hangzhou)
        let region = "cn-hangzhou"
        // 可选项,指定访问OSS服务的域名。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com
        let endpoint: String? = nil

        // 自动刷新的访问凭证,根据过期时间刷新访问凭证
        // refreshInterval:刷新时间,默认300s。
        let credentialsProvider = RefreshCredentialsProvider(refreshInterval: 500) {
        
            // 您可以在此处自定义获取临时凭证的方法

            // TODO......

            // 假设获取得到的值如下
            let accessKeyId = "yourAccessKeyID"
            let accessKeySecret = "yourAccessKeySecret"
            let securityToken = "yourSecurityToken"
            
            // 您可以选择设置过期时间(可选)
            // 当不设置过期时间时,则不会自动刷新访问凭证。
            let expiration = Date() // 如果设置了过期时间,会结合refreshInterval和过期时间,定期调用该闭包,刷新凭证
            
            // 返回访问凭证对象
            return Credentials(accessKeyId: accessKeyId,
                               accessKeySecret: accessKeySecret,
                               securityToken: securityToken,
                               expiration: expiration)
        }

        // 配置OSS客户端参数
        let config = Configuration.default()
            .withRegion(region)        // 设置Bucket所在地域
            .withCredentialsProvider(credentialsProvider)  // 设置访问凭证
            
        // 设置自定义Endpoint
        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }
        
        // 创建OSS客户端实例
        let client = Client(config)
        
        // 使用Client发起请求,例如执行文件上传、下载或管理等操作...
    }
}

常见问题

在使用通过STS服务获取的临时身份凭证去初始化凭证提供者时,误使用RAM用户的AK

当您使用通过STS服务获取的临时身份凭证(Access Key ID、Access Key SecretSecurity Token)初始化访问凭证时,请勿混淆STS服务返回的AKRAM用户的AK,STS对应的AK是以STS开头,示例如下:

image

如何查看RAM用户的AK?是否可以查看旧的AccessKey Secret?

  1. 如需查看RAM用户的AK,请直接参考文档查看RAM用户的AccessKey信息

  2. RAM用户的AccessKey Secret仅在创建时显示,之后无法查看,若您已经遗忘了的话无法找回。您可以直接访问RAM控制台选择具体用户,并创建新的AccessKey进行轮换。详细请参见创建AccessKey

使用RAM用户的AK进行上传文件时,报错AccessDenied如何排查?

上传文件时出现AccessDenied的问题,通常是因为使用了错误的AK信息或没有给RAM用户添加上传文件的权限,您可以按照以下步骤检查:

  1. 检查您使用的RAM用户的AK是否正确,请直接参考文档查看RAM用户的AccessKey信息

  2. RAM用户的AccessKey Secret仅在创建时显示,之后无法查看,若您已经遗忘了的话无法找回。您可以直接访问RAM控制台选择具体用户,并创建新的AccessKey进行轮换。详细请参见创建AccessKey

  3. 登录RAM控制台选择具体用户,给RAM用户添加上传文件到OSS的权限。

在使用外网Endpoint访问OSS时,报错无法连接该如何排查?

出现外网Endpoint无法连接的问题,通常是因为使用了错误的Endpoint地址或Bucket所在地域与请求的Endpoint不匹配。请您按照以下步骤检查:

  1. 确认Bucket所在地域:登录阿里云控制台,找到您的Bucket,确认其所在地域。

  2. 使用正确的Endpoint:根据Bucket所在地域,使用对应的外网Endpoint。例如,如果Bucket位于华东1(杭州),则应使用oss-cn-hangzhou.aliyuncs.com。各地域的Endpoint信息请参见OSS地域和访问域名

  3. 检查网络连接:确保您的网络环境可以正常访问互联网,避免因网络问题导致连接失败。

如果遇到报错问题该如何查询具体的错误类型?

关于错误类型的查询,OSS文档提供了EC错误码供您参阅,例如关于认证方面的常见报错问题,请参见02-AUTH