本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 中使用登入資料提供者 AWS SDK for Java 2.x
登入資料提供者在 中的角色 AWS SDK for Java 2.x 是為開發套件的 AWS 服務 用戶端來源和提供登入資料。SDK 會使用其來源的登入資料，透過密碼編譯方式簽署每個請求來驗證服務。登入資料通常包含存取金鑰 - 存取金鑰 ID 和私密存取金鑰。
當您使用臨時登入資料時，當您設定 [SSO 權杖提供者組態](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#sso-token-config)或將執行時間設定為[擔任 IAM (AWS Identity and Access Management) 角色](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html#credOrSourceAssumeRole)做為範例時，工作階段權杖會新增至存取金鑰，以提供對 AWS 資源的限時存取。
本主題討論可讓您讓 SDK 存取憑證的多種方式。
**Topics**
+ [互動式開發工作](credentials-temporary.md)
+ [預設登入資料提供者鏈結](credentials-chain.md)
+ [登入資料快取](credential-caching.md)
+ [指定特定的登入資料提供者](credentials-providers.md)
+ [使用共用組態描述檔](credentials-profiles.md)
+ [使用外部程序](credentials-process.md)
+ [在程式碼中提供登入資料](credentials-explicit.md)
+ [在 Amazon EC2 上讀取 IAM 角色登入資料](ec2-iam-roles.md)
# 使用 存取互動式開發工作的登入資料 AWS SDK for Java 2.x
為了提高安全性， AWS 建議您將適用於 Java 的 SDK 設定為[使用暫時登入](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp)資料，而不是長期登入資料。暫時登入資料包含存取金鑰 （存取金鑰 ID 和私密存取金鑰） 和工作階段字符。
您可以使用數種方法來使用臨時登入資料。您使用的方法，以及您提供給 SDK 的組態，取決於您的使用案例。
當您使用 Java 開發套件進行互動式開發時，我們建議您使用 AWS 主控台登入憑證。
## 使用主控台登入憑證
您可以使用現有的 AWS 管理主控台登入憑證，以程式設計方式存取 AWS 服務。在瀏覽器型身分驗證流程之後， AWS 會產生臨時登入資料，可用於本機開發工具，例如 AWS CLI 和適用於 Java 的 SDK 2.x。
透過此程序，您可以使用在初始帳戶設定期間建立的根登入資料、IAM 使用者或身分提供者的聯合身分進行身分驗證，而 AWS CLI 會自動為您管理臨時登入資料。這種方法無需在本機存放長期登入資料，可增強安全性。
當您執行 `aws login`命令時，您可以從作用中主控台工作階段中選取 ，或透過瀏覽器型身分驗證流程登入，這會自動產生臨時登入資料。適用於 Java 的 SDK 2.x 會自動重新整理這些登入資料長達 12 小時。
**重要**
除了您在適用於所有專案的共用組態檔案中設定的組態之外，每個個別 Java 專案還需要 Maven `pom.xml` 檔案中的下列相依性：
```
software.amazon.awssdk
signin
```
`signin` 相依性提供的程式碼可讓適用於 Java 的 SDK 2.x 存取和使用主控台登入資料。
如需先決條件、登入和登出的詳細資訊，請參閱 *AWS SDK 和工具參考指南*中的[使用主控台登入進行 AWS 本機開發](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html)。
## Single-sign-on方法
當您使用 Java 開發套件進行互動式開發時，您也可以使用單一登入方法。此方法需要下列設定：
+ [透過 IAM Identity Center 設定](get-started-auth.md#setup-auth)
+ [在 AWS 共用組態檔案中設定設定檔](get-started-auth.md#setup-credentials)
+ 使用 AWS CLI 並[執行命令](get-started-auth.md#setup-login-sso)來登入和建立作用中工作階段
### IAM Identity Center 組態
當您將軟體開發套件設定為使用本指南[設定概觀](setup.md#setup-overview)中所述的 IAM Identity Center 單一登入存取時，軟體開發套件會使用臨時登入資料。
SDK 使用 IAM Identity Center 存取權杖來存取 IAM 角色，該角色是以 `config` 檔案中`sso_role_name`的設定所設定。軟體開發套件會擔任此 IAM 角色，並擷取臨時登入資料以簽署 AWS 服務 請求。
如需開發套件如何從組態取得臨時登入資料的詳細資訊，請參閱 AWS SDKs和工具參考指南中的[了解 IAM Identity Center 身分驗證](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html)一節。
**重要**
除了您在適用於所有專案的共用`config`檔案中設定的組態之外，每個個別 Java 專案還需要 Maven `pom.xml` 檔案中的下列相依性：
```
software.amazon.awssdk
sso
software.amazon.awssdk
ssooidc
```
`sso` 和 `ssooidc` 相依性提供的程式碼，可讓適用於 Java 的 SDK 2.x 存取暫時登入資料。
### 從 AWS 存取入口網站擷取臨時登入資料
作為 IAM Identity Center 單一登入組態的替代方案，您可以複製並使用 AWS 存取入口網站中提供的臨時憑證。您可以在設定檔中使用臨時憑證，或用作系統屬性和環境變數的值。
**為臨時登入資料設定本機登入資料檔案**
1. [建立共用登入資料檔案](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)
1. 在登入資料檔案中，貼上下列預留位置文字，直到您貼上運作中的臨時登入資料為止。
```
[default]
aws_access_key_id=
aws_secret_access_key=
aws_session_token=
```
1. 儲存檔案。檔案現在`~/.aws/credentials`應該存在於您的本機開發系統上。如果未指定特定具名[設定檔，此檔案包含適用於 Java 的 SDK 使用的 【預設】](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-profile) 設定檔。
1. [登入 AWS 存取入口網站](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosignin.html)
1. 請遵循[手動登入資料重新整理](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html#how-to-get-temp-credentials)標題下的這些指示，從 AWS 存取入口網站複製 IAM 角色登入資料。
1. 針對連結指示中的步驟 2，請`Access keys`針對授予您開發需求的存取權的 IAM 角色名稱選擇 。此角色通常具有 **PowerUserAccess** 或 ** Developer** 等名稱。
1. 在模態對話方塊中，選取您的作業系統，並將內容從**新增設定檔複製到您的 AWS 登入資料檔案**。
1. 將複製的登入資料貼到您的本機`credentials`檔案中，並移除產生的設定檔名稱。您的 檔案應該類似以下內容。
```
[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE
```
1. 儲存 `credentials` 檔案。
當適用於 Java 的 SDK 建立服務用戶端時，它會存取這些臨時登入資料，並將其用於每個請求。在步驟 5a 中選擇的 IAM 角色設定會決定[臨時憑證的有效時長](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosessionduration.html)。最長持續時間為 12 小時。
臨時憑證過期後，請重複步驟 4 至 7。
# 中的預設登入資料提供者鏈結 AWS SDK for Java 2.x
中的預設登入資料提供者鏈結 AWS SDK for Java 2.x 會自動在預先定義的位置序列中搜尋 AWS 登入資料，允許應用程式使用 進行身分驗證， AWS 服務 而無需明確指定登入資料來源。
預設憑證提供者鏈由 [DefaultCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html) 類別實作。它會依序委派給其他登入資料提供者實作，以檢查不同位置中的組態。第一個可以尋找所有必要組態元素的登入資料提供者會導致鏈結結束。
若要使用預設登入資料提供者鏈來提供臨時登入資料，請建立服務用戶端建置器，但不指定登入資料提供者。下列程式碼片段會建立`DynamoDbClient`使用預設登入資料提供者鏈結來尋找和擷取組態設定的 。
```
// Any external Region configuration is overridden.
// The SDK uses the default credentials provider chain because no specific credentials provider is specified.
Region region = Region.US_WEST_2;
DynamoDbClient ddb =
DynamoDbClient.builder()
.region(region)
.build();
```
## 登入資料設定擷取順序
適用於 Java 的 SDK 2.x 的預設登入資料提供者鏈結會使用預先定義的序列搜尋您環境中的組態。
1. Java 系統屬性
+ SDK 使用 [SystemPropertyCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/SystemPropertyCredentialsProvider.html) 類別從 `aws.accessKeyId`、 `aws.secretAccessKey`和 `aws.sessionToken` Java 系統屬性載入臨時憑證。
**注意**
如需有關如何設定 Java 系統屬性的資訊，請參閱官方 *Java 教學*課程網站上的[系統屬性](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html)教學課程。
1. 環境變數
+ SDK 使用 [EnvironmentVariableCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/EnvironmentVariableCredentialsProvider.html) 類別從 `AWS_ACCESS_KEY_ID`、 `AWS_SECRET_ACCESS_KEY`和 `AWS_SESSION_TOKEN`環境變數載入臨時憑證。
1. Web 身分字符和 IAM 角色 ARN
+ SDK 使用 [WebIdentityTokenFileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/WebIdentityTokenFileCredentialsProvider.html) 類別，透過使用 Web 身分字符擔任角色來載入憑證。
+ 登入資料提供者會尋找下列環境變數或 JVM 系統屬性：
+ `AWS_WEB_IDENTITY_TOKEN_FILE or aws.webIdentityTokenFile`
+ `AWS_ROLE_ARN` 或 `aws.roleArn`
+ `AWS_ROLE_SESSION_NAME` 或 `aws.roleSessionName`（選用）
+ 開發套件取得值後，它會呼叫 AWS Security Token Service (STS)，並使用其傳回的臨時登入資料來簽署請求。
+ Amazon Elastic Kubernetes Service (EKS) 等執行期環境會自動提供 Web 身分字符給 AWS SDKs，讓應用程式能夠取得臨時 AWS 憑證。
1. 共用 `credentials`和 `config` 檔案
+ SDK 使用 [ProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProfileCredentialsProvider.html) 從共用 `credentials`和 `config` 檔案中的`[default]`設定檔載入 IAM Identity Center 單一登入設定或暫時登入資料。
AWS SDKs和工具參考指南[提供有關](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html#idccredres)適用於 Java 的 SDK 如何與 IAM Identity Center 單一登入字符搭配使用的詳細資訊，以取得 SDK 用於呼叫的臨時登入資料 AWS 服務。
**注意**
`credentials` 和 `config` 檔案由 AWS SDKs和工具共用。如需詳細資訊，請參閱 SDK [和工具參考指南中的 .aws/credentials 和 .aws/config 檔案](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html)。 AWS SDKs
+ 由於共用`credentials`和`config`檔案中的描述檔可以包含許多不同的設定集，因此`ProfileCredentialsProvider`委派給一系列其他供應商，以在`[default]`描述檔下尋找設定：
+ **Web 身分字符登入**資料 （類別 `WebIdentityTokenCredentialsProvider`)：當設定檔包含 `role_arn`和 時`web_identity_token_file`。
+ **SSO 登入**資料 （類別 `SsoCredentialsProvider`)：當設定檔包含 SSO 相關屬性時，例如 `sso_role_name`、`sso_account_id`。
+ **具有來源描述檔的角色型登入**資料 （類別 `StsAssumeRoleCredentialsProvider`)：當描述檔包含 `role_arn`和 時`source_profile`。
+ **具有登入資料來源的角色型登入**資料 （類別 `StsAssumeRoleWithSourceCredentialsProvider`)：當設定檔包含 `role_arn`和 時`credential_source`。
+ 當 `credential_source = Environment`：它使用 `SystemPropertyCredentialsProvider`和 的鏈 `EnvironmentVariableCredentialsProvider`
+ 當 `credential_source = Ec2InstanceMetadata`：它使用 `InstanceProfileCredentialsProvider`
+ 當 `credential_source = EcsContainer`：它使用 `ContainerCredentialsProvider`
+ **主控台登入憑證** （類別 `LoginCredentialsProvider`)：當設定檔包含 `login_session`
+ **處理登入**資料 （類別 `ProcessCredentialsProvider`)：當設定檔包含 時`credential_process`。
+ **工作階段登入**資料 （類別 `StaticSessionCredentialsProvider`)：當設定檔包含 `aws_access_key_id`、 `aws_secret_access_key`和 時`aws_session_token`。
+ **基本登入**資料 （類別 `StaticCredentialsProvider`)：當設定檔包含 `aws_access_key_id`和 時`aws_secret_access_key`。
1. Amazon ECS 容器憑證
+ SDK 使用 [ContainerCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ContainerCredentialsProvider.html) 類別，使用以下環境變數載入臨時憑證：
1. `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` 或 `AWS_CONTAINER_CREDENTIALS_FULL_URI`
1. `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` 或 `AWS_CONTAINER_AUTHORIZATION_TOKEN`
ECS 容器代理程式會自動設定 `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`環境變數，指向 ECS 登入資料端點。其他環境變數通常會在不使用標準 ECS 登入資料端點的特定案例中設定。
1. Amazon EC2 執行個體 IAM 角色提供的登入資料
+ SDK 使用 [InstanceProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/InstanceProfileCredentialsProvider.html) 類別從 Amazon EC2 中繼資料服務載入臨時憑證。
1. 如果軟體開發套件無法透過上述所有步驟找到必要的組態設定，則會擲回例外狀況，其輸出類似如下：
```
software.amazon.awssdk.core.exception.SdkClientException: Unable to load credentials from any of the providers
in the chain AwsCredentialsProviderChain(credentialsProviders=[SystemPropertyCredentialsProvider(),
EnvironmentVariableCredentialsProvider(), WebIdentityTokenCredentialsProvider(), ProfileCredentialsProvider(),
ContainerCredentialsProvider(), InstanceProfileCredentialsProvider()])
```
## 在程式碼`DefaultCredentialsProvider`中使用
您可以在程式碼中明確使用預設登入資料提供者鏈結。這功能等同於您完全不指定登入資料提供者，因為軟體開發套件`DefaultCredentialsProvider`預設會使用 。不過，明確使用它可以讓您的程式碼更易於讀取和自我記錄。它清楚地顯示您使用預設登入資料鏈的意圖。
```
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
public class ExplicitDefaultCredentialsExample {
public static void main(String[] args) {
// Explicitly create the DefaultCredentialsProvider.
DefaultCredentialsProvider defaultCredentialsProvider = DefaultCredentialsProvider
.builder().build();
// Use it with any service client.
S3Client s3Client = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(defaultCredentialsProvider)
.build();
// Now you can use the client with the default credentials chain.
s3Client.listBuckets();
}
}
```
當您建置預設登入資料提供者時，您可以提供更多組態：
```
DefaultCredentialsProvider customizedProvider = DefaultCredentialsProvider.builder()
.profileName("custom-profile") // Use a specific profile if the chain gets to the `ProfileCredentialsProvider` stage.
.asyncCredentialUpdateEnabled(true) // Enable async credential updates.
.build();
```
此方法可讓您擁有更多控制權，同時仍提供預設登入資料鏈的便利性。
# 中的登入資料快取 AWS SDK for Java 2.x
AWS SDK for Java 2.x 實作登入資料快取，以改善效能並減少對登入資料來源的呼叫。本節說明登入資料快取的運作方式，以及如何為您的應用程式設定登入資料快取。
## 了解登入資料提供者快取
適用於 Java 的 SDK 2.x 中的登入資料提供者使用不同的快取策略：
+ **內部登入資料快取**：許多供應商會快取他們擷取的登入資料。
+ **自動重新整理**：具有快取登入資料的提供者會實作重新整理機制。
### 具有內部登入資料快取的提供者
即使您建立新的執行個體，下列登入資料供應商也會在內部快取登入資料：
+ **執行個體描述檔登入資料提供者**：從 Amazon EC2 中繼資料服務快取登入資料。
+ **容器憑證提供者**：從容器中繼資料端點快取憑證。
+ **STS 型供應商**：從 AWS Security Token Service (STS) 快取臨時憑證。
+ **Web 身分字符提供者**：快取從 Web 身分字符取得的憑證。
+ **程序登入資料提供者**：從外部程序快取登入資料。
### 沒有內部快取的提供者
下列提供者不會實作內部快取：
+ **環境變數登入資料提供者**
+ **系統屬性登入資料提供者**
+ **靜態登入資料提供者**
## 設定登入資料快取
您可以在建置登入資料提供者時自訂快取行為：
### 過時時間
控制何時將登入資料視為過時且需要重新整理：
```
.staleTime(Duration.ofMinutes(2)) // Consider stale 2 minutes before expiration.
```
### 預先擷取時間
決定何時在憑證過期前開始重新整理憑證：
```
.prefetchTime(Duration.ofMinutes(10)) // Start refresh 10 minutes before expiration.
```
### 非同步更新
啟用背景登入資料重新整理：
```
.asyncCredentialUpdateEnabled(true) // Refresh credentials in background thread.
```
### 工作階段持續時間
對於 STS 型供應商， 會控制暫時登入資料保持有效的時間長度：
```
.refreshRequest(r -> r.durationSeconds(3600)) // 1 hour session.
```
## 快取登入資料組態範例
作為為登入資料提供者實作設定快取的範例，您可能希望 SDK 使用背景執行緒在登入資料過期之前預先擷取 （事先擷取）。如此一來，您就可以避免擷取新登入資料的封鎖呼叫。
以下範例會建立 `[StsAssumeRoleCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsAssumeRoleCredentialsProvider.html)`，該 使用背景執行緒，透過將 `[asyncCredentialUpdateEnabled](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#asyncCredentialUpdateEnabled(java.lang.Boolean))` 屬性設定為建置器`true`上的 來預先擷取登入資料：
```
StsAssumeRoleCredentialsProvider provider = StsAssumeRoleCredentialsProvider.builder()
.refreshRequest(r -> r
.roleArn("arn:aws:iam::111122223333:role/example-role")
.roleSessionName("example-session")
.durationSeconds(3600)) // 1 hour session
.staleTime(Duration.ofMinutes(5)) // Consider stale 5 minutes before expiration
.prefetchTime(Duration.ofMinutes(10)) // Start refresh 10 minutes before expiration
.asyncCredentialUpdateEnabled(true) // Refresh in background
.build();
S3Client s3 = S3Client.builder()
.credentialsProvider(provider)
.build();
```
當您`s3Client`第一次在 上叫用 操作時， `[AssumeRoleRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/model/AssumeRoleRequest.html)` 會傳送到 AWS Security Token Service (STS)。STS 會傳回有效時間為 15 分鐘 (900 秒） 的臨時登入資料。`s3Client` 執行個體會使用快取的登入資料，直到 15 分鐘前需要重新整理為止。根據預設，軟體開發套件會嘗試擷取目前工作階段過期時間前 5 分鐘到 1 分鐘之間新工作階段的新登入資料。您可以使用 `[prefetchTime](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#prefetchTime(java.time.Duration))`和 `[staleTime](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#staleTime(java.time.Duration))` 屬性來設定預先擷取時段。
您可以類似地設定下列工作階段型登入資料提供者：
+ `StsWebIdentityTokenFileCredentialsProvider`
+ `StsGetSessionTokenCredentialsProvider`
+ `StsGetFederationTokenCredentialsProvider`
+ `StsAssumeRoleWithWebIdentityCredentialsProvider`
+ `StsAssumeRoleWithSamlCredentialsProvider`
+ `StsAssumeRoleCredentialsProvider`
+ `DefaultCredentialsProvider` （委派給使用工作階段的登入資料提供者時）
+ `ProcessCredentialsProvider`
+ `WebIdentityTokenFileCredentialsProvider`
+ `ContainerCredentialsProvider`
+ `InstanceProfileCredentialsProvider`
了解登入資料快取可協助您在使用 時最佳化應用程式的效能和可靠性 AWS 服務。
# 在 中指定特定的登入資料提供者 AWS SDK for Java 2.x
雖然預設登入資料提供者鏈結在許多案例中都很方便，但明確指定登入資料提供者可讓您更好地控制身分驗證行為、效能和安全性。
您可能想要指定登入資料提供者的原因可能包括：
+ 預設供應商鏈結會依序檢查多個來源，這會新增延遲：
```
// The default provider chain checks might check multiple sources until it finds
// sufficient configuration.
S3Client s3Client = S3Client.builder().build();
// You can specify exactly where to look.
S3Client optimizedClient = S3Client.builder()
.credentialsProvider(InstanceProfileCredentialsProvider.create())
.build();
```
+ 您需要使用非標準位置來存取登入資料組態：
```
// Use configuration from a custom file location.
S3Client s3Client = S3Client.builder()
.credentialsProvider(ProfileCredentialsProvider.builder()
.profileFile(ProfileFile.builder()
.content(Paths.get("/custom/path/to/configuration/file"))
.type(ProfileFile.Type.CONFIGURATION) // Expects all non-default profiles to be prefixed with "profile".
.build())
.profileName("custom")
.build())
.build();
```
+ 針對不同的服務用戶端使用不同的登入資料。例如，如果您的應用程式需要存取多個 AWS 帳戶或使用不同 服務的不同許可：
```
// S3 client using one set of credentials.
S3Client s3Client = S3Client.builder()
.credentialsProvider(ProfileCredentialsProvider.create("s3-readonly"))
.build();
// DynamoDB client using different credentials.
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.credentialsProvider(ProfileCredentialsProvider.create("dynamodb-admin"))
.build();
```
+ 控制登入資料重新整理行為：
```
// Create a provider with custom refresh behavior.
StsAssumeRoleCredentialsProvider customRefreshProvider =
StsAssumeRoleCredentialsProvider.builder()
.refreshRequest(AssumeRoleRequest.builder()
.roleArn("arn:aws:iam::123456789012:role/my-role")
.roleSessionName("custom-session")
.build())
.stsClient(StsClient.create())
.asyncCredentialUpdateEnabled(true) // Use a background thread to prefetch credentials.
.build();
S3Client s3Client = S3Client.builder()
.credentialsProvider(customRefreshProvider)
.build();
```
# 在 中使用 AWS 共用組態設定檔 AWS SDK for Java 2.x
您可以使用共用 `config`和 `credentials` 檔案來設定多個設定檔。這可讓您的應用程式使用多組登入資料組態。先前提到了`[default]`設定檔。SDK 使用 [ProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProfileCredentialsProvider.html) 類別，從共用`credentials`檔案中定義的設定檔載入設定。
下列程式碼片段示範如何建置服務用戶端，使用在名為 的設定檔中定義的設定`my_profile`。
```
Region region = Region.US_WEST_2;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.credentialsProvider(ProfileCredentialsProvider.create("my_profile"))
.build();
```
## 將不同的設定檔設定為預設值
若要將設定檔以外的`[default]`設定檔設定為應用程式的預設值，請將`AWS_PROFILE`環境變數設定為自訂設定檔的名稱。
若要在 Linux、macOS 或 Unix 上設定此變數，請使用 `export`：
```
export AWS_PROFILE="other_profile"
```
若要在 Windows 上設定這些變數，請使用 `set`：
```
set AWS_PROFILE="other_profile"
```
或者，將 `aws.profile` Java 系統屬性設定為設定檔的名稱。
## 重新載入設定檔登入資料
您可以設定在其建置器上具有 `profileFile()`方法的任何登入資料提供者，以重新載入設定檔登入資料。這些登入資料設定檔類別包括：`ProfileCredentialsProvider`、`InstanceProfileCredentialsProvider`、 `DefaultCredentialsProvider`和 `ProfileTokenProvider.`
**注意**
設定檔登入資料重新載入僅適用於設定檔檔案中的下列設定：`aws_access_key_id`、 `aws_secret_access_key`和 `aws_session_token`。
`source_profile` 會忽略 `region`、`sso_account_id`、 `sso_session`和 等設定。
若要設定支援的登入資料提供者重新載入設定檔設定，[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html)請將 執行個體提供給`profileFile()`建置器方法。下列程式碼範例示範從 `[default]` 設定檔`ProfileCredentialsProvider`重新載入登入資料設定的 。
```
ProfileCredentialsProvider provider = ProfileCredentialsProvider
.builder()
.profileFile(ProfileFileSupplier.defaultSupplier())
.build();
// Set up a service client with the provider instance.
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.region(Region.US_EAST_1)
.credentialsProvider(provider)
.build();
/*
Before dynamoDbClient makes a request, it reloads the credentials settings
by calling provider.resolveCredentials().
*/
```
`ProfileCredentialsProvider.resolveCredentials()` 呼叫 時，適用於 Java 的 開發套件會重新載入設定。 `ProfileFileSupplier.defaultSupplier()`是 SDK [提供的數種便利實作](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html)之一。 `ProfileFileSupplier`如果您的使用案例需要，您可以提供自己的實作。
下列範例顯示使用 `ProfileFileSupplier.reloadWhenModified()` 便利方法。 `reloadWhenModified()`採用 `Path` 參數，可讓您靈活地指定組態的來源檔案，而非標準 `~/.aws/credentials`（或 `config`) 位置。
只有在 SDK 判斷檔案的內容已修改時，才會在`resolveCredentials()`呼叫 時重新載入設定。
```
Path credentialsFilePath = ...
ProfileCredentialsProvider provider = ProfileCredentialsProvider
.builder()
.profileFile(ProfileFileSupplier.reloadWhenModified(credentialsFilePath, ProfileFile.Type.CREDENTIALS))
.profileName("my-profile")
.build();
/*
A service client configured with the provider instance calls provider.resolveCredential()
before each request.
*/
```
`ProfileFileSupplier.aggregate()` 方法會合併多個組態檔案的內容。您可以決定是否在每次呼叫時重新載入檔案，`resolveCredentials()`或在第一次讀取時修正檔案的設定。
下列範例顯示的 `DefaultCredentialsProvider`會合併包含設定檔設定的兩個檔案的設定。開發套件會在每次呼叫 且設定已變更`resolveCredentials()`時，重新載入`credentialsFilePath`變數指向的 檔案中的設定。物件的設定`profileFile`保持不變。
```
Path credentialsFilePath = ...;
ProfileFile profileFile = ...;
DefaultCredentialsProvider provider = DefaultCredentialsProvider
.builder()
.profileFile(ProfileFileSupplier.aggregate(
ProfileFileSupplier.reloadWhenModified(credentialsFilePath, ProfileFile.Type.CREDENTIALS),
ProfileFileSupplier.fixedProfileFile(profileFile)))
.profileName("my-profile")
.build();
/*
A service client configured with the provider instance calls provider.resolveCredential()
before each request.
*/
```
# 使用 從外部程序載入登入資料 AWS SDK for Java 2.x
**警告**
以下說明從外部程序取得臨時登入資料的方法。這可能很危險，因此請謹慎處理。如果可能，我們建議您使用其他登入資料提供者。如果使用此選項，我們建議您使用作業系統的安全最佳實務，確保`config`檔案盡可能鎖定。
請確定您的自訂登入資料工具不會將任何秘密資訊寫入 `StdErr`。SDKs AWS CLI 可以擷取並記錄這類資訊，並可能將其公開給未經授權的使用者。
使用適用於 Java 的 SDK 2.x，您可以從自訂使用案例的外部程序取得臨時登入資料。有兩種方式可設定此功能。
## 使用 `credential_process`設定
如果您有提供臨時登入資料的方法，您可以透過在 `config` 檔案中新增 `credential_process`設定做為設定檔定義的一部分來進行整合。您指定的值必須使用命令檔案的完整路徑。如果檔案路徑包含任何空格，您必須用引號括住它。
SDK 會完全依照指定方式呼叫命令，然後從 讀取 JSON 資料`stdout`。
下列範例顯示將此設定用於不含空格的檔案路徑和含空格的檔案路徑。
------
#### [ Linux/macOS ]
**檔案路徑中沒有空格**
```
[profile process-credential-profile]
credential_process = /path/to/credential/file/credential_file.sh --custom-command custom_parameter
```
**檔案路徑中的空格**
```
[profile process-credential-profile]
credential_process = "/path/with/space to/credential/file/credential_file.sh" --custom-command custom_parameter
```
------
#### [ Windows ]
**檔案路徑中沒有空格**
```
[profile process-credential-profile]
credential_process = C:\Path\To\credentials.cmd --custom_command custom_parameter
```
**檔案路徑中的空格**
```
[profile process-credential-profile]
credential_process = "C:\Path\With Space To\credentials.cmd" --custom_command custom_parameter
```
------
下列程式碼片段示範如何建置服務用戶端，該用戶端使用在名為 的設定檔中定義的暫時登入資料`process-credential-profile`。
```
Region region = Region.US_WEST_2;
S3Client s3Client = S3Client.builder()
.region(region)
.credentialsProvider(ProfileCredentialsProvider.create("process-credential-profile"))
.build();
```
如需使用外部程序做為暫時登入資料來源的詳細資訊，請參閱《 AWS SDKs和工具參考指南》中的[程序登入資料一節](https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html)。
## 使用 `ProcessCredentialsProvider`
除了使用 `config` 檔案中的設定之外，您也可以使用 SDK 的 `[ProcessCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProcessCredentialsProvider.html)` 使用 Java 載入臨時登入資料。
下列範例示範如何使用 指定外部程序，`ProcessCredentialsProvider`以及設定使用臨時憑證的服務用戶端的各種版本。
------
#### [ Linux/macOS ]
**檔案路徑中沒有空格**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("/path/to/credentials.sh optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
**檔案路徑中的空格**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("/path\\ with\\ spaces\\ to/credentials.sh optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
------
#### [ Windows ]
**檔案路徑中沒有空格**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("C:\\Path\\To\\credentials.exe optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
**檔案路徑中的空格**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("\"C:\\Path\\With Spaces To\\credentials.exe\" optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
------
## 使用 IAM Roles Anywhere 進行身分驗證
[IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html) 是 AWS 服務 ，可讓您取得在 外部執行之工作負載的臨時 AWS 登入資料 AWS。它可讓您從內部部署或其他雲端環境安全地存取 AWS 資源。
您必須先收集必要資訊並下載[登入資料協助程式工具](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/credential-helper.html)，才能向 IAM Roles Anywhere 驗證請求。遵循 IAM Roles Anywhere 使用者指南中的[入門](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html)說明，即可建立必要的成品。
適用於 Java 的 SDK 沒有專用登入資料提供者可從 IAM Roles Anywhere 擷取臨時登入資料，但您可以使用登入資料協助程式工具以及其中一個選項，[從外部程序擷取登入](#credentials-process)資料。
### 在設定檔中使用 `credential_process`設定
共用組態檔案中的下列程式碼片段顯示使用 `credential_process`設定的名為 AWS `roles_anywhere`的設定檔：
```
[profile roles_anywhere]
credential_process = ./aws_signing_helper credential-process \
--certificate /path/to/certificate \
--private-key /path/to/private-key \
--trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \
--profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \
--role-arn arn:aws:iam::account:role/role-name-with-path
```
組裝所有成品之後，您需要將紅色顯示的文字取代為您的值。設定中的第一個元素 是登入資料協助程式工具的可執行檔`aws_signing_helper`，而 `credential-process`是 命令。
當您設定服務用戶端使用`roles_anywhere`設定檔時，如下列程式碼所示，開發套件會快取暫時登入資料，並在過期之前重新整理它們：
```
S3Client s3Client = S3Client.builder()
.credentialsProvider(ProfileCredentialsProvider.builder()
.profileName("roles_anywhere").build())
.build();
```
### 設定 `ProcessCredentialsProvider`
如下所示，您可以搭配 使用僅限程式碼的方法，`ProcessCredentialsProvider`而不是使用設定檔設定：
```
ProcessCredentialsProvider processCredentialsProvider = ProcessCredentialsProvider.builder()
.command("""
./aws_signing_helper credential-process \
--certificate /path/to/certificate \
--private-key /path/to/private-key \
--trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \
--profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \
--role-arn arn:aws:iam::account:role/role-name-with-path
""").build();
S3Client s3Client = S3Client.builder()
.credentialsProvider(processCredentialsProvider)
.build();
```
在您組合所有成品之後，請將紅色顯示的文字取代為您的值。
# 使用 在程式碼中提供登入資料 AWS SDK for Java 2.x
如果預設登入資料鏈或特定或自訂提供者或提供者鏈不適用於您的應用程式，您可以直接在程式碼中提供臨時登入資料。這些可以是[上述](credentials-temporary.md#credentials-temporary-from-portal)的 [IAM 角色登入](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html)資料，或從 AWS Security Token Service () 擷取的臨時登入資料AWS STS。如果您使用 擷取臨時登入資料 AWS STS，請將它們提供給 AWS 服務 用戶端，如下列程式碼範例所示。
1. 呼叫 以擔任角色`StsClient.assumeRole()`。
1. 建立 [StaticCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/StaticCredentialsProvider.html) 物件，並提供該`AwsSessionCredentials`物件。
1. 使用 設定服務用戶端建置器，`StaticCredentialsProvider`並建置用戶端。
下列範例使用 為 IAM 擔任的角色傳回 AWS STS 的臨時憑證建立 Amazon S3 服務用戶端。
```
// The AWS IAM Identity Center identity (user) who executes this method does not have permission to list buckets.
// The identity is configured in the [default] profile.
public static void assumeRole(String roleArn, String roleSessionName) {
// The IAM role represented by the 'roleArn' parameter can be assumed by identities in two different accounts
// and the role permits the user to only list buckets.
// The SDK's default credentials provider chain will find the single sign-on settings in the [default] profile.
// The identity configured with the [default] profile needs permission to call AssumeRole on the STS service.
try {
Credentials tempRoleCredentials;
try (StsClient stsClient = StsClient.create()) {
AssumeRoleRequest roleRequest = AssumeRoleRequest.builder()
.roleArn(roleArn)
.roleSessionName(roleSessionName)
.build();
AssumeRoleResponse roleResponse = stsClient.assumeRole(roleRequest);
tempRoleCredentials = roleResponse.credentials();
}
// Use the following temporary credential items for the S3 client.
String key = tempRoleCredentials.accessKeyId();
String secKey = tempRoleCredentials.secretAccessKey();
String secToken = tempRoleCredentials.sessionToken();
// List all buckets in the account associated with the assumed role
// by using the temporary credentials retrieved by invoking stsClient.assumeRole().
StaticCredentialsProvider staticCredentialsProvider = StaticCredentialsProvider.create(
AwsSessionCredentials.create(key, secKey, secToken));
try (S3Client s3 = S3Client.builder()
.credentialsProvider(staticCredentialsProvider)
.build()) {
List buckets = s3.listBuckets().buckets();
for (Bucket bucket : buckets) {
System.out.println("bucket name: " + bucket.name());
}
}
} catch (StsException | S3Exception e) {
logger.error(e.getMessage());
System.exit(1);
}
}
```
## 許可集
中定義的下列許可集 AWS IAM Identity Center 允許身分 （使用者） 執行下列兩個操作
1. Amazon Simple Storage Service `GetObject`的操作。
1. `AssumeRole` 的操作 AWS Security Token Service。
如果不擔任角色，範例中顯示`s3.listBuckets()`的方法將會失敗。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"sts:AssumeRole"
],
"Resource": [
"*"
]
}
]
}
```
------
## 擔任的角色
### 擔任的角色許可政策
下列許可政策會連接到先前範例中擔任的角色。此許可政策允許列出與角色相同帳戶中的所有儲存貯體。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets"
],
"Resource": [
"*"
]
}
]
}
```
------
### 擔任的角色信任政策
下列信任政策會連接到先前範例中擔任的角色。此政策允許兩個帳戶中的身分 （使用者） 擔任該角色。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:root",
"arn:aws:iam::555555555555:root"
]
},
"Action": "sts:AssumeRole",
"Condition": {}
}
]
}
```
------
# 使用適用於 Java 的 SDK 2.x 在 Amazon EC2 上讀取 IAM 角色憑證
您可以使用 IAM 角色來管理在 EC2 執行個體上執行之應用程式的臨時登入資料，以及提出 AWS CLI 或 AWS API 請求。這是在 EC2 執行個體內儲存存取金鑰的較好方式。若要將 AWS 角色指派給 EC2 執行個體並將其提供給其所有應用程式，您可以建立連接至執行個體的執行個體描述檔。執行個體設定檔包含該角色，並且可讓 EC2 執行個體上執行的程式取得臨時憑證。如需詳細資訊，請參閱 *IAM 使用者指南*中的[使用 IAM 角色來授予許可權給 Amazon EC2 執行個體上執行的應用程式](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html)。
本主題提供如何設定您的 Java 應用程式以在 EC2 執行個體上執行，並讓 AWS SDK for Java 2.x 取得 IAM 角色登入資料的相關資訊。
## 從環境取得 IAM 角色登入資料
如果您的應用程式使用 `create`方法 （或 `builder().build()`方法） 建立 AWS 服務用戶端，適用於 Java 的 SDK 會使用*預設憑證提供者鏈結*。預設登入資料提供者鏈結會搜尋執行環境，尋找 SDK 可以用來交換臨時登入資料的組態元素。[中的預設登入資料提供者鏈結 AWS SDK for Java 2.x](credentials-chain.md) 本節說明完整的搜尋程序。
預設提供者鏈中的最後一個步驟只有在您的應用程式在 Amazon EC2 執行個體上執行時才能使用。在此步驟中，軟體開發套件會使用 `InstanceProfileCredentialsProvider`來讀取 EC2 執行個體描述檔中定義的 IAM 角色。開發套件接著會取得該 IAM 角色的臨時登入資料。
雖然這些登入資料是暫時的，最終會過期， `InstanceProfileCredentialsProvider`會定期為您重新整理這些登入資料，以便繼續允許存取 AWS。
## 以程式設計方式取得 IAM 角色登入資料
作為最終在 EC2 `InstanceProfileCredentialsProvider` 上使用 的預設登入資料提供者鏈的替代方案，您可以使用 明確設定服務用戶端`InstanceProfileCredentialsProvider`。此方法會顯示在下列程式碼片段中。
```
S3Client s3 = S3Client.builder()
.credentialsProvider(InstanceProfileCredentialsProvider.create())
.build();
```
## 安全地取得 IAM 角色登入資料
根據預設，EC2 執行個體會執行 [IMDS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) (Instance Metadata Service)，允許 SDK `InstanceProfileCredentialsProvider`存取資訊，例如已設定的 IAM 角色。EC2 執行個體預設會執行兩個版本的 IMDS：
+ 執行個體中繼資料服務第 1 版 (IMDSv1) – 請求/回應方法
+ 執行個體中繼資料服務第 2 版 (IMDSv2) – 工作階段導向方法
[IMDSv2 是比 IMDSv1 更安全的方法](https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/)。 IMDSv1
根據預設，Java 開發套件會先嘗試 IMDSv2 來取得 IAM 角色，但如果失敗，則會嘗試 IMDSv1。不過，由於 IMDSv1 較不安全， AWS 因此建議僅使用 IMDSv2，並停用 SDK 來嘗試 IMDSv1。
若要使用更安全的方法，請透過提供下列其中一個值為 的設定，停用 SDK 來停用 IMDSv1`true`。
+ 環境變數： `AWS_EC2_METADATA_V1_DISABLED`
+ JVM 系統屬性：aws。`disableEc2MetadataV1`
+ 共用組態檔案設定： `ec2_metadata_v1_disabled`
當其中一個設定設為 時`true`，如果初始 IMDSv2 呼叫失敗，開發套件不會使用 IMDSv1 載入 IMDSv2角色登入資料。