全部产品
Search

搜索本产品

    对象存储 OSS：Java配置访问凭证

    文档中心

    对象存储 OSS：Java配置访问凭证

    更新时间：Sep 16, 2023

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

    前提条件

    在配置访问凭证前，您需要安装OSS Java SDK。详情请参见Java安装。

    访问凭证

    您可以选择以下类型的访问凭证。

    • 临时访问凭证：对于需要高安全性的场景，例如临时授权应用访问OSS，建议使用临时访问凭证。临时访问凭证可以限制访问的有效期，从而减少访问凭证泄露的风险。此外，临时访问凭证支持权限控制，可以有效地避免权限过大的问题。更多信息，请参见使用临时访问凭证。

    • 长期访问凭证：出于安全性考虑，不建议您使用长期访问凭证，建议您使用临时访问凭证。对于需要便利性的场景，长期访问凭证可以在较长时间内免除多次刷新的麻烦。建议每三个月更换一次长期访问凭证，以提高账号的安全性。当长期访问凭证泄露或者不再使用时，应该及时删除或者禁用相关的访问凭证，以免造成安全风险。更多信息，请参见使用长期访问凭证。

    使用临时访问凭证

    当您准备临时使用Java SDK访问OSS服务时，您可以选择以下方式配置临时访问凭证。

    • 配置STS临时访问凭证：如果您需要在规定时间内访问您的OSS，您可以通过STS服务颁发一个STS临时访问凭证。临时访问凭证无需透露您的RAM用户访问密钥，使您的OSS访问更加安全。

    • 配置RAM角色：如果您需要授权访问或跨账号访问OSS，您可以通过RAM用户扮演对应RAM角色的方式授权访问或跨账号访问OSS。

    • 配置ECS的RAM角色：如果你需要在阿里云的云服务器ECS中访问您的OSS，您可以通过ECS实例RAM角色的方式访问OSS。实例RAM角色允许您将一个角色关联到云服务器实例，在实例内部基于STS临时凭证通过指定方法访问OSS。STS临时凭证由系统自动生成和更新，应用程序可以使用指定的实例元数据URL获取临时凭证，无需特别管理。

    配置STS临时访问凭证

    1. 创建RAM用户。

      具体操作，请参见创建RAM用户。

    2. 为RAM用户授予 AliyunSTSAssumeRoleAccess权限。

      具体操作，请参见为RAM用户授权。

    3. 使用RAM用户调用STS服务的AssumeRole接口获取STS临时访问凭证。

      具体操作，请参见AssumeRole。

    4. 配置STS临时访问凭证。

      环境变量

      1. 使用获取的STS临时访问凭证配置环境变量。

        macOS

        1. 打开终端。

        2. 执行以下命令。

          nano ~/.bash_profile

        3. 在文件末尾添加从STS服务获取的临时访问凭证（包括AccessKeyId、AccessKeySecret、SecurityToken）。

          export OSS_ACCESS_KEY_ID=STS.NV5ZCwphFSXqscqUHAKbH****
export OSS_ACCESS_KEY_SECRET=IrVTNZNy5yQelTETg0cZML3TQn**** 
export OSS_SESSION_TOKEN=CAES+wMIARKAAZhjH0EUOIhJMQBMjRywXq7MQ/cjLYg80Aho1ek0Jm63XMhr9Oc5s˙∂˙∂3qaPer8p1YaX1NTDiCFZWFkvlHf1pQhuxfKBc+mRR9KAbHUefqH+rdjZqjTF7p2m1wJXP8S6k+G2MpHrUe6TYBkJ43GhhTVFMuM3BZajY3VjZWOXBIODRIR1FKZjIiEjMzMzE0MjY0NzM5MTE4NjkxMSoLY2xpZGSSDgSDGAGESGTETqOio6c2RrLWRlbW8vKgoUYWNzOm9zczoqOio6c2RrLWRlbW9KEDExNDg5MzAxMDcyNDY4MThSBTI2ODQyWg9Bc3N1bWVkUm9sZVVzZXJgAGoSMzMzMTQyNjQ3MzkxMTg2OTExcglzZGstZGVt****

        4. 按Ctrl+X，按Y键确认保存，然后按Enter键退出文件。

        5. 执行以下命令以使更改生效。

          source ~/.bash_profile

        6. 执行以下命令验证环境变量配置。

          echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
echo $OSS_SESSION_TOKEN

          成功返回示例如下：

          STS.NV5ZCwphFSXqscqUHAKbH****
IrVTNZNy5yQelTETg0cZML3TQn**** 
CAES+wMIARKAAZhjH0EUOIhJMQBMjRywXq7MQ/cjLYg80Aho1ek0Jm63XMhr9Oc5s˙∂˙∂3qaPer8p1YaX1NTDiCFZWFkvlHf1pQhuxfKBc+mRR9KAbHUefqH+rdjZqjTF7p2m1wJXP8S6k+G2MpHrUe6TYBkJ43GhhTVFMuM3BZajY3VjZWOXBIODRIR1FKZjIiEjMzMzE0MjY0NzM5MTE4NjkxMSoLY2xpZGSSDgSDGAGESGTETqOio6c2RrLWRlbW8vKgoUYWNzOm9zczoqOio6c2RrLWRlbW9KEDExNDg5MzAxMDcyNDY4MThSBTI2ODQyWg9Bc3N1bWVkUm9sZVVzZXJgAGoSMzMzMTQyNjQ3MzkxMTg2OTExcglzZGstZGVt****

        Linux

        1. 打开终端。

        2. 执行以下命令。

          sudo vim /etc/profile

        3. 在文件末尾添加从STS服务获取的临时访问凭证（包括AccessKeyId、AccessKeySecret、SecurityToken）。

          export OSS_ACCESS_KEY_ID=STS.NV5ZCwphFSXqscqUHAKbH****
export OSS_ACCESS_KEY_SECRET=IrVTNZNy5yQelTETg0cZML3TQn****
export OSS_SESSION_TOKEN=CAES+wMIARKAAZhjH0EUOIhJMQBMjRywXq7MQ/cjLYg80Aho1ek0Jm63XMhr9Oc5s˙∂˙∂3qaPer8p1YaX1NTDiCFZWFkvlHf1pQhuxfKBc+mRR9KAbHUefqH+rdjZqjTF7p2m1wJXP8S6k+G2MpHrUe6TYBkJ43GhhTVFMuM3BZajY3VjZWOXBIODRIR1FKZjIiEjMzMzE0MjY0NzM5MTE4NjkxMSoLY2xpZGSSDgSDGAGESGTETqOio6c2RrLWRlbW8vKgoUYWNzOm9zczoqOio6c2RrLWRlbW9KEDExNDg5MzAxMDcyNDY4MThSBTI2ODQyWg9Bc3N1bWVkUm9sZVVzZXJgAGoSMzMzMTQyNjQ3MzkxMTg2OTExcglzZGstZGVt****

        4. 按ESC键退出编辑模式，输入:wq，然后按Enter键保存并退出文件。

        5. 执行以下命令以使更改生效。

          source /etc/profile

        6. 执行以下命令验证环境变量配置。

          echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
echo $OSS_SESSION_TOKEN

          成功返回示例如下：

          STS.NV5ZCwphFSXqscqUHAKbH****
IrVTNZNy5yQelTETg0cZML3TQn**** 
CAES+wMIARKAAZhjH0EUOIhJMQBMjRywXq7MQ/cjLYg80Aho1ek0Jm63XMhr9Oc5s˙∂˙∂3qaPer8p1YaX1NTDiCFZWFkvlHf1pQhuxfKBc+mRR9KAbHUefqH+rdjZqjTF7p2m1wJXP8S6k+G2MpHrUe6TYBkJ43GhhTVFMuM3BZajY3VjZWOXBIODRIR1FKZjIiEjMzMzE0MjY0NzM5MTE4NjkxMSoLY2xpZGSSDgSDGAGESGTETqOio6c2RrLWRlbW8vKgoUYWNzOm9zczoqOio6c2RrLWRlbW9KEDExNDg5MzAxMDcyNDY4MThSBTI2ODQyWg9Bc3N1bWVkUm9sZVVzZXJgAGoSMzMzMTQyNjQ3MzkxMTg2OTExcglzZGstZGVt****

        Windows

        1. 打开命令行。

        2. 执行以下命令配置从STS服务获取的临时访问凭证（包括AccessKeyId、AccessKeySecret、SecurityToken）。

          set OSS_ACCESS_KEY_ID=STS.NV5ZCwphFSXqscqUHAKbH****
set OSS_ACCESS_KEY_SECRET=IrVTNZNy5yQelTETg0cZML3TQn****
set OSS_SESSION_TOKEN=CAES+wMIARKAAZhjH0EUOIhJMQBMjRywXq7MQ/cjLYg80Aho1ek0Jm63XMhr9Oc5s˙∂˙∂3qaPer8p1YaX1NTDiCFZWFkvlHf1pQhuxfKBc+mRR9KAbHUefqH+rdjZqjTF7p2m1wJXP8S6k+G2MpHrUe6TYBkJ43GhhTVFMuM3BZajY3VjZWOXBIODRIR1FKZjIiEjMzMzE0MjY0NzM5MTE4NjkxMSoLY2xpZGSSDgSDGAGESGTETqOio6c2RrLWRlbW8vKgoUYWNzOm9zczoqOio6c2RrLWRlbW9KEDExNDg5MzAxMDcyNDY4MThSBTI2ODQyWg9Bc3N1bWVkUm9sZVVzZXJgAGoSMzMzMTQyNjQ3MzkxMTg2OTExcglzZGstZGVt****

        3. 执行以下命令以使更改生效。

          setx OSS_ACCESS_KEY_ID "%OSS_ACCESS_KEY_ID%"
setx OSS_ACCESS_KEY_SECRET "%OSS_ACCESS_KEY_SECRET%"
setx OSS_SESSION_TOKEN "%OSS_SESSION_TOKEN%"

        4. 执行以下命令验证环境变量配置。

          echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%
echo %OSS_SESSION_TOKEN%

          成功返回示例如下：

          STS.NV5ZCwphFSXqscqUHAKbH****
IrVTNZNy5yQelTETg0cZML3TQn**** 
CAES+wMIARKAAZhjH0EUOIhJMQBMjRywXq7MQ/cjLYg80Aho1ek0Jm63XMhr9Oc5s˙∂˙∂3qaPer8p1YaX1NTDiCFZWFkvlHf1pQhuxfKBc+mRR9KAbHUefqH+rdjZqjTF7p2m1wJXP8S6k+G2MpHrUe6TYBkJ43GhhTVFMuM3BZajY3VjZWOXBIODRIR1FKZjIiEjMzMzE0MjY0NzM5MTE4NjkxMSoLY2xpZGSSDgSDGAGESGTETqOio6c2RrLWRlbW8vKgoUYWNzOm9zczoqOio6c2RrLWRlbW9KEDExNDg5MzAxMDcyNDY4MThSBTI2ODQyWg9Bc3N1bWVkUm9sZVVzZXJgAGoSMzMzMTQyNjQ3MzkxMTg2OTExcglzZGstZGVt****

      2. 从环境变量中获取STS临时访问凭证。

        // 使用环境变量中获取的STS临时访问密钥和安全令牌配置访问凭证。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

      代码嵌入

      警告

      在代码中嵌入访问凭证会导致安全问题。如果访问凭证被泄漏，攻击者就可以使用该访问凭证来访问您的资源OSS，造成损失。因此，建议您使用更安全的方式，例如从环境变量中获取访问凭证，来提高安全性。

      // STS临时访问密钥AccessKey ID和AccessKey Secret。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// STS安全令牌SecurityToken。
String securityToken = "yourSecurityToken";
// 使用代码嵌入的STS临时访问密钥和安全令牌配置访问凭证。
CredentialsProvider credentialsProvider = new DefaultCredentialProvider(accessKeyId, accessKeySecret, securityToken);

    配置RAM角色

    1. 获取RAM用户的访问密钥。

      具体操作，请参见创建RAM用户的AccessKey。

      重要

      为降低RAM用户的访问密钥被泄露的风险，对于超过3个月的RAM用户的访问密钥，建议及时轮换。对于长期不用的RAM用户的访问密钥，建议及时禁用并删除。

    2. 获取目标RAM角色的RamRoleArn。

      说明

      RamRoleArn是RAM角色的ARN信息，即需要扮演的角色ID。格式为acs:ram::$accountID:role/$roleName。$accountID为阿里云账号ID。$roleName为RAM角色名称。

      具体操作，请参见查看RAM角色。

    3. 配置RAM用户的访问密钥和目标RAM角色的RAMRoleArn作为访问凭证。

      环境变量

      1. 使用获取的RAM用户的访问密钥和目标RAM角色的RamRoleArn配置环境变量。

        macOS

        1. 打开终端。

        2. 执行以下命令。

          nano ~/.bash_profile

        3. 在文件末尾添加获取的RAM用户的访问密钥和RAM角色的RamRoleArn。

          export OSS_ACCESS_KEY_ID=LTAI4GDty8ab9W4Y1D****
export OSS_ACCESS_KEY_SECRET=IrVTNZNy5yQelTETg0cZML3TQn****  
export OSS_STS_ROLE_ARN=acs:ram::17464958********:role/ossststest

        4. 按Ctrl+X，按Y键确认保存，然后按Enter键退出文件。

        5. 执行以下命令以使更改生效。

          source /etc/profile

        6. 执行以下命令验证环境变量配置。

          echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
echo $OSS_STS_ROLE_ARN

          成功返回示例如下：

          LTAI4GDty8ab9W4Y1D****
IrVTNZNy5yQelTETg0cZML3TQn****  
acs:ram::17464958********:role/ossststest

        Linux

        1. 打开终端。

        2. 执行以下命令。

          sudo vim /etc/profile

        3. 在文件末尾添加获取的RAM用户的访问密钥和RAM角色的RamRoleArn。

          export OSS_ACCESS_KEY_ID=LTAI4GDty8ab9W4Y1D****
export OSS_ACCESS_KEY_SECRET=IrVTNZNy5yQelTETg0cZML3TQn****  
export OSS_STS_ROLE_ARN=acs:ram::17464958********:role/ossststest

        4. 按ESC键退出编辑模式，输入:wq，然后按Enter键保存并退出文件。

        5. 执行以下命令以使更改生效。

          source /etc/profile

        6. 执行以下命令验证环境变量配置。

          echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
echo $OSS_STS_ROLE_ARN

          成功返回示例如下：

          LTAI4GDty8ab9W4Y1D****
IrVTNZNy5yQelTETg0cZML3TQn****  
acs:ram::17464958********:role/ossststest

        Windows

        1. 打开命令行。

        2. 执行以下命令配置RAM用户的访问密钥和RAM角色的RamRoleArn。

          set OSS_ACCESS_KEY_ID=LTAI4GDty8ab9W4Y1D****
set OSS_ACCESS_KEY_SECRET=IrVTNZNy5yQelTETg0cZML3TQn****  
set OSS_STS_ROLE_ARN=acs:ram::17464958********:role/ossststest

        3. 执行以下命令以使更改生效。

          setx OSS_ACCESS_KEY_ID "%OSS_ACCESS_KEY_ID%"
setx OSS_ACCESS_KEY_SECRET "%OSS_ACCESS_KEY_SECRET%"
setx OSS_STS_ROLE_ARN "%OSS_STS_ROLE_ARN%"

        4. 执行以下命令验证环境变量配置。

          echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%
echo %OSS_STS_ROLE_ARN%

          成功返回示例如下：

          LTAI4GDty8ab9W4Y1D****
IrVTNZNy5yQelTETg0cZML3TQn****  
acs:ram::17464958********:role/ossststest

      2. 从环境变量中获取RAM用户的访问密钥RAM角色的RamRoleArn。

        // 授权STSAssumeRole访问的Region。以华东1（杭州）为例，其它Region请根据实际情况填写。
String region = "cn-hangzhou";
// 从环境变量中获取RAM用户的访问密钥（AccessKey ID和AccessKey Secret）。
String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
// 从环境变量中获取RAM角色的RamRoleArn。
String roleArn = System.getenv("OSS_STS_ROLE_ARN");

// 使用环境变量中获取的RAM用户的访问密钥和RAM角色的RamRoleArn配置访问凭证。
STSAssumeRoleSessionCredentialsProvider credentialsProvider = CredentialsProviderFactory
        .newSTSAssumeRoleSessionCredentialsProvider(
                region, 
                accessKeyId, 
                accessKeySecret, 
                roleArn
        );

      代码嵌入

      警告

      在代码中嵌入访问凭证会导致安全问题。如果访问凭证被泄漏，攻击者就可以使用该访问凭证来访问您的资源OSS，造成损失。因此，建议您使用更安全的方式，例如从环境变量中获取访问凭证，来提高安全性。

      // 授权STSAssumeRole访问的Region。以华东1（杭州）为例，其它Region请根据实际情况填写。
String region = "cn-hangzhou";
// 填写RAM用户的访问密钥（AccessKey ID和AccessKey Secret）。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 填写RAM角色的ARN信息，即需要扮演的角色ID。
String roleArn = "acs:ram::17464958********:role/ossststest";

// 使用代码嵌入的RAM用户的访问密和RAM角色的RamRoleArn配置访问凭证。
STSAssumeRoleSessionCredentialsProvider credentialsProvider = CredentialsProviderFactory
        .newSTSAssumeRoleSessionCredentialsProvider(
                region, 
                accessKeyId, 
                accessKeySecret, 
                roleArn
        );

    配置ECS的RAM角色

    1. 为ECS实例授予RAM角色。

      具体操作，请参见授予实例RAM角色。

    2. 配置ECS的RAM角色作为访问凭证。

      // 通过ECS RAM角色获取访问凭证，例如以角色名（ecs-ram-role）访问为例。
InstanceProfileCredentialsProvider credentialsProvider = CredentialsProviderFactory.newInstanceProfileCredentialsProvider("ecs-ram-role");

    使用长期访问凭证

    当您准备在应用或服务中长期使用Java SDK访问OSS服务时，您可以通过以下方式配置长期访问凭证。

    配置RAM用户的访问密钥：如果您需要长期访问您的OSS，您可以通过RAM用户的访问密钥的方式访问您的OSS。

    配置RAM用户的访问密钥

    1. 获取RAM用户的访问密钥。

      如何获取RAM用户的访问密钥，请参见创建RAM用户的AccessKey。

      重要

      对于超过3个月的RAM用户的访问密钥，建议及时轮换。对于长期不用的RAM用户的访问密钥，建议及时禁用并删除。以此降低RAM用户的访问密钥被泄露的风险。

    2. 配置RAM用户的访问密钥。

      环境变量

      1. 配置环境变量。

        macOS

        1. 打开终端。

        2. 执行以下命令。 

          nano ~/.bash_profile

        3. 在文件末尾添加RAM用户的访问密钥。

          export OSS_ACCESS_KEY_ID=LTAI4GDty8ab9W4Y1D****
export OSS_ACCESS_KEY_SECRET=IrVTNZNy5yQelTETg0cZML3TQn****

        4. 按Ctrl+X，按Y键确认保存，然后按Enter键退出文件。

        5. 输入以下命令以使更改生效。

          source ~/.bash_profile

        6. 执行以下命令验证环境变量配置。

          echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

          成功返回示例如下：

          LTAI4GDty8ab9W4Y1D****
IrVTNZNy5yQelTETg0cZML3TQn****

        Linux

        1. 打开终端。

        2. 执行以下命令。

          sudo vim /etc/profile

        3. 在文件末尾添加RAM用户的访问密钥。

          export OSS_ACCESS_KEY_ID=LTAI4GDty8ab9W4Y1D****
export OSS_ACCESS_KEY_SECRET=IrVTNZNy5yQelTETg0cZML3TQn****

        4. 按ESC键退出编辑模式，输入:wq，然后按Enter键保存并退出文件。

        5. 输入以下命令以使更改生效。

          source /etc/profile

        6. 执行以下命令验证环境变量配置。

          echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

          成功返回示例如下：

          LTAI4GDty8ab9W4Y1D****
IrVTNZNy5yQelTETg0cZML3TQn****

        Windows

        1. 打开命令行。

        2. 执行以下命令配置RAM用户的访问密钥。

          set OSS_ACCESS_KEY_ID=LTAI4GDty8ab9W4Y1D****
set OSS_ACCESS_KEY_SECRET=IrVTNZNy5yQelTETg0cZML3TQn****

        3. 执行以下命令以使更改生效。

          setx OSS_ACCESS_KEY_ID "%OSS_ACCESS_KEY_ID%"
setx OSS_ACCESS_KEY_SECRET "%OSS_ACCESS_KEY_SECRET%"

        4. 执行以下命令验证环境变量配置。

          echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%

          成功返回示例如下：

          LTAI4GDty8ab9W4Y1D****
IrVTNZNy5yQelTETg0cZML3TQn****

      2. 从环境变量中获取RAM用户的访问密钥。

        // 使用环境变量中获取的RAM用户的访问密钥配置访问凭证。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

      代码嵌入

      警告

      在代码中嵌入访问凭证会导致安全问题。如果访问凭证被泄漏，攻击者就可以使用该访问凭证来访问您的资源OSS，造成损失。因此，建议您使用更安全的方式，例如从环境变量中获取访问凭证，来提高安全性。

      // RAM用户的访问密钥（AccessKey ID和AccessKey Secret）。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 使用代码嵌入的RAM用户的访问密钥配置访问凭证。
CredentialsProvider credentialsProvider = new DefaultCredentialProvider(accessKeyId, accessKeySecret);

    后续步骤

    配置访问凭证后，您需要初始化OSSClient。详情请参见Java初始化。