如何为OSS Swift SDK配置访问凭证_对象存储(OSS)-阿里云帮助中心

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

注意事项

如果您希望获取关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。
如果您希望创建RAM用户的AccessKey，请参见创建AccessKey。

凭证提供者选型

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

凭证提供者初始化方式	适用场景	是否需要提供前置的AK或STS 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进行轮换。

环境变量

使用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)

参考上述方式修改系统环境变量后，请重启或刷新您的编译运行环境，包括IDE、命令行界面、其他桌面应用程序及后台服务，以确保最新的系统环境变量成功加载。

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

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

        // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_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 Secret和Security Token）初始化凭证提供者。需要注意的是，该方式需要您手动维护一个STS Token，存在安全性风险和维护复杂度增加的风险。此外，如果您需要多次临时访问OSS，您需要手动刷新STS Token。

重要

如果您希望通过OpenAPI的方式简单快速获取到STS临时访问凭证，请参见AssumeRole - 获取扮演角色的临时身份凭证。
如果您希望通过SDK的方式获取STS临时访问凭证，请参见使用STS临时访问凭证访问OSS。
请注意，STS Token在生成的时候需要指定过期时间，过期后自动失效不能再使用。
如果您希望获取关于STS服务的接入点列表，请参见服务接入点。

环境变量

使用临时身份凭证设置环境变量。
Mac OS X/Linux/Unix
警告
请注意，此处使用的是通过STS服务获取的临时身份凭证（Access Key ID、Access Key Secret和Security Token），而非RAM用户的Access Key和Access Key Secret。
请注意区分STS服务获取的Access Key ID以STS开头，例如“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 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>
```

通过环境变量来传递凭证信息。

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

        // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_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 支持多种实现方式。

通过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发起请求，例如执行文件上传、下载或管理等操作...
    }
}

通过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 Secret和Security Token）初始化访问凭证时，请勿混淆STS服务返回的AK与RAM用户的AK，STS对应的AK是以STS开头，示例如下：

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

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

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

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

检查您使用的RAM用户的AK是否正确，请直接参考文档查看RAM用户的AccessKey信息。
RAM用户的AccessKey Secret仅在创建时显示，之后无法查看，若您已经遗忘了的话无法找回。您可以直接访问RAM控制台选择具体用户，并创建新的AccessKey进行轮换。详细请参见创建AccessKey。
登录RAM控制台选择具体用户，给RAM用户添加上传文件到OSS的权限。

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

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

确认Bucket所在地域：登录阿里云控制台，找到您的Bucket，确认其所在地域。
使用正确的Endpoint：根据Bucket所在地域，使用对应的外网Endpoint。例如，如果Bucket位于华东1（杭州），则应使用oss-cn-hangzhou.aliyuncs.com。各地域的Endpoint信息请参见OSS地域和访问域名。
检查网络连接：确保您的网络环境可以正常访问互联网，避免因网络问题导致连接失败。

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

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

注意事项

凭证提供者选型

常用配置示例

使用RAM用户的AK

环境变量

Linux

macOS

Zsh

Bash

Windows

CMD

PowerShell

静态凭证

使用STS临时访问凭证

环境变量

Mac OS X/Linux/Unix

Windows

静态凭证

更多场景化配置示例

自定义凭证提供者

常见问题

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

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

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

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

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