IAM Identity Center credential provider
This authentication mechanism uses AWS IAM Identity Center to get single sign-on (SSO) access to AWS services for your code.
Note
In the AWS SDK API documentation, the IAM Identity Center credential provider is called the SSO credential provider.
After you enable IAM Identity Center, you define a profile for its settings in your shared AWS
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 AWS service requests, see Understand IAM Identity Center authentication.
There are two ways to configure IAM Identity Center through the config
file:
-
SSO token provider configuration (recommended) – Extended session durations.
-
Legacy non-refreshable configuration – Uses a fixed, eight-hour session.
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 AWS 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
Note
To use the AWS CLI to create this configuration for you, see Configure your profile with the aws configure sso
wizard in the
AWS CLI.
When you use the SSO token provider configuration, your AWS 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 AWS access portal and IAM Identity Center integrated applications in the AWS 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 AWS 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 AWS credentials.
Note
For a deep dive on how the SDKs and tools use and refresh credentials using this configuration, see Understand IAM Identity Center authentication.
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-sessionmy-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-sessionmy-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 AWS services that
support bearer authentication, then traditional AWS 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 AWS 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 AWS 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:
-
sso_start_url
-
sso_region
-
sso_account_id
-
sso_role_name
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
Configure this functionality by using the following:
sso_start_url
- shared AWSconfig
file setting-
The URL that points to your organization's IAM Identity Center access portal. For more information on the IAM Identity Center access portal, see Using the AWS access portal in the AWS IAM Identity Center User Guide.
To find this value, open the IAM Identity Center console
, view the Dashboard, and find AWS access portal URL. sso_region
- shared AWSconfig
file setting-
The AWS Region that contains your IAM Identity Center portal host; that is, the Region you selected before enabling IAM Identity Center. This is independent from your default AWS Region, and can be different.
For a complete list of the AWS Regions and their codes, see Regional Endpoints in the Amazon Web Services General Reference. To find this value, open the IAM Identity Center console
, view the Dashboard, and find Region. sso_account_id
- shared AWSconfig
file setting-
The numeric ID of the AWS account that was added through the AWS Organizations service to use for authentication.
To see the list of available accounts, go to the IAM Identity Center console
and open the AWS accounts page. You can also see the list of available accounts using the ListAccounts API method in the AWS IAM Identity Center Portal API Reference. For example, you can call the AWS CLI method list-accounts . sso_role_name
- shared AWSconfig
file setting-
The name of a permission set provisioned as an IAM role that defines the user's resulting permissions. The role must exist in the AWS account specified by
sso_account_id
. Use the role name, not the role Amazon Resource Name (ARN).Permission sets have IAM policies and custom permissions policies attached to them and define the level of access that users have to their assigned AWS accounts.
To see the list of available permission sets per AWS account, go to the IAM Identity Center console
and open the AWS accounts page. Choose the correct permission set name listed in the AWS accounts table. You can also see the list of available permission sets using the ListAccountRoles API method in the AWS IAM Identity Center Portal API Reference. For example, you can call the AWS CLI method list-account-roles . sso_registration_scopes
- shared AWSconfig
file setting-
A comma-delimited list of valid scope strings to be authorized for the
sso-session
. Scopes authorize access to IAM Identity Center bearer token authorized endpoints. A minimum scope ofsso:account:access
must be granted to get a refresh token back from the IAM Identity Center service. For the supported access scope strings, see Access scopes in the AWS IAM Identity Center User Guide. This setting doesn't apply to the legacy non-refreshable configuration. Tokens issued using the legacy configuration are limited to scopesso:account:access
implicitly.
Compatibility with AWS 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 AWS SDK for Java and the AWS SDK for Kotlin only.
SDK | Supported | Notes or more information |
---|---|---|
AWS CLI v2 | Yes | |
SDK for C++ | Yes | |
SDK for Go V2 (1.x) |
Yes | |
SDK for Go 1.x (V1) | Yes | To use shared config file settings, you must turn on loading from the config file; see Sessions. |
SDK for Java 2.x | Yes | Configuration values also supported in credentials
file. |
SDK for Java 1.x | No | |
SDK for JavaScript 3.x | Yes | |
SDK for JavaScript 2.x | Yes | |
SDK for Kotlin | Yes | |
SDK for .NET 3.x | Yes | |
SDK for PHP 3.x | Yes | |
SDK for Python (Boto3) |
Yes | |
SDK for Ruby 3.x | Yes | |
SDK for Rust | Partial | Legacy non-refreshable configuration only. |
Tools for PowerShell | Yes |