Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

IAM Identity Center credential provider

This authentication mechanism uses Amazon IAM Identity Center to get single sign-on (SSO) access to Amazon Web Services for your code.

After you enable IAM Identity Center, you define a profile for its settings in your shared Amazon config file. This profile is used to connect to the IAM Identity Center access portal. When a user successfully authenticates with IAM Identity Center, the portal returns short-term credentials for the IAM role associated with that user. To learn how the SDK gets temporary credentials from the configuration and uses them for Amazon Web Service requests, see Understand IAM Identity Center authentication.

There are two ways to configure IAM Identity Center through the config file:

In both configurations, you need to sign in again when your session expires.

To set custom session durations, you must use the SSO token provider configuration.

The following two guides contain additional information about IAM Identity Center:

Prerequisites

You must first enable IAM Identity Center. For details about enabling IAM Identity Center authentication, see Getting Started in the Amazon IAM Identity Center User Guide.

Alternatively, follow the IAM Identity Center authentication instructions in this guide. These instructions provide complete guidance, from enabling IAM Identity Center to completing the necessary shared config file configuration that follows here.

SSO token provider configuration

When you use the SSO token provider configuration, your Amazon SDK or tool automatically refreshes your session up to your extended session period. For more information on session duration and maximum duration, see Configure the session duration of the Amazon access portal and IAM Identity Center integrated applications in the Amazon IAM Identity Center User Guide.

The sso-session section of the config file is used to group configuration variables for acquiring SSO access tokens, which can then be used to acquire Amazon credentials. For more details about formatting sections within a config file, see Format of the config file.

You define an sso-session section and associate it to a profile. sso_region and sso_start_url must be set within the sso-session section. Typically, sso_account_id and sso_role_name must be set in the profile section so that the SDK can request Amazon credentials.

The following example configures the SDK to request IAM Identity Center credentials. It also supports automated token refresh.

[profile dev]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access

You can reuse sso-session configurations across multiple profiles.

[profile dev]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole

[profile prod]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole2

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access

sso_account_id and sso_role_name aren't required for all scenarios of SSO token configuration. If your application only uses Amazon Web Services that support bearer authentication, then traditional Amazon credentials are not needed. Bearer authentication is an HTTP authentication scheme that uses security tokens called bearer tokens. In this scenario, sso_account_id and sso_role_name aren't required. See the individual guide for your Amazon Web Service to determine if it supports bearer token authorization.

Registration scopes are configured as part of an sso-session. Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, and the access token issued to the application is limited to the scopes granted. These scopes define the permissions requested to be authorized for the registered OIDC client and access tokens retrieved by the client. For the supported access scope options, see Access scopes in the Amazon IAM Identity Center User Guide. The following example sets sso_registration_scopes to provide access for listing accounts and roles.

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access

The authentication token is cached to disk under the ~/.aws/sso/cache directory with a file name based on the session name.

Legacy non-refreshable configuration

Automated token refresh isn't supported using the legacy non-refreshable configuration. We recommend using the SSO token provider configuration instead.

To use the legacy non-refreshable configuration, you must specify the following settings within your profile:

You specify the user portal for a profile with the sso_start_url and sso_region settings. You specify permissions with the sso_account_id and sso_role_name settings.

The following example sets the four required values in the config file.

[profile my-sso-profile]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-west-2
sso_account_id = 111122223333
sso_role_name = SSOReadOnlyRole

The authentication token is cached to disk under the ~/.aws/sso/cache directory with a file name based on the sso_start_url.

IAM Identity Center credential provider settings

Compatibility with Amazon SDKs

The following SDKs support the features and settings described in this topic. Any partial exceptions are noted. Any JVM system property settings are supported by the Amazon SDK for Java and the Amazon SDK for Kotlin only.