Understand IAM Identity Center authentication
Relevant IAM Identity Center terms
The following terms help you understand the process and configuration behind Amazon IAM Identity Center. The documentation for Amazon SDK APIs uses different names than IAM Identity Center for some of these authentication concepts. It's helpful to know both names.
The following table shows how alternative names relate to each other.
| IAM Identity Center name | SDK API name | Description |
|---|---|---|
| Identity Center | sso
|
Although Amazon Single Sign-On is renamed, the sso API namespaces
will keep their original name for backward compatibility purposes. For more
information, see IAM Identity Center rename
in the Amazon IAM Identity Center User Guide. |
IAM Identity Center console Administrative console |
The console you use to configure single sign-on. | |
| Amazon access portal URL | A URL unique to your IAM Identity Center account, like
https://. You sign in
to this portal using your IAM Identity Center sign-in credentials. |
|
| IAM Identity Center Access Portal session | Authentication session | Provides a bearer access token to the caller. |
| Permission set session | The IAM session that the SDK uses internally to make the Amazon Web Service calls. In informal discussions, you might see this incorrectly referred to as "role session." | |
| Permission set credentials | Amazon credentials sigv4 credentials |
The credentials the SDK actually uses for most Amazon Web Service calls (specifically, all sigv4 Amazon Web Service calls). In informal discussions, you might see this incorrectly referred to as "role credentials." |
| IAM Identity Center credential provider | SSO credential provider | How you get the credentials, such as the class or module providing the functionality. |
Understand SDK credential resolution for Amazon Web Services
The IAM Identity Center API exchanges bearer token credentials for sigv4 credentials. Most Amazon Web Services are sigv4 APIs, with a few exceptions like Amazon CodeWhisperer and Amazon CodeCatalyst. The following describes the credential resolution process for supporting most Amazon Web Service calls for your application code through Amazon IAM Identity Center.
Start an Amazon access portal session
-
Start the process by signing in to the session with your credentials.
-
Use the
aws sso logincommand in the Amazon Command Line Interface (Amazon CLI). This starts a new IAM Identity Center session if you don't already have an active session.
-
-
When you start a new session, you receive a refresh token and access token from IAM Identity Center. The Amazon CLI also updates an SSO cache JSON file with a new access token and refresh token and makes it available for use by SDKs.
-
If you already have an active session, the Amazon CLI command reuses the existing session and will expire whenever the existing session expires. To learn how to set the length of an IAM Identity Center session, see Configure the duration of your users' Amazon access portal sessions in the Amazon IAM Identity Center User Guide.
-
The maximum session length has been extended to 90 days to reduce the need for frequent sign-ins.
-
How the SDK gets credentials for Amazon Web Service calls
SDKs provide access to Amazon Web Services when you instantiate a client object per service.
When the selected profile of the shared Amazon config file is configured for IAM Identity Center credential
resolution, IAM Identity Center is used to resolve credentials for your application.
-
The credential resolution process is completed during runtime when a client is created.
To retrieve credentials for sigv4 APIs using IAM Identity Center single sign-on, the SDK uses the IAM Identity Center access token to get an IAM session. This IAM session is called a permission set session, and it provides Amazon access to the SDK by assuming an IAM role.
-
The permission set session duration is set independently from the IAM Identity Center session duration.
-
To learn how to set the permission set session duration, see Set session duration in the Amazon IAM Identity Center User Guide.
-
-
Be aware that the permission set credentials are also referred to as Amazon credentials and sigv4 credentials in most Amazon SDK API documentation.
The permission set credentials are returned from a call to getRoleCredentials of the IAM Identity Center API to the SDK. The SDK’s client object uses that assumed IAM role to make calls to the Amazon Web Service, such as asking Amazon S3 to list the buckets in your account. The client object can continue to operate using those permission set credentials until the permission set session expires.
Session expiration and refresh
When using the SSO token provider configuration, the hourly access token obtained from IAM Identity Center is automatically refreshed using the refresh token.
-
If the access token is expired when the SDK tries to use it, the SDK uses the refresh token to try to get a new access token. The IAM Identity Center compares the refresh token to your IAM Identity Center access portal session duration. If the refresh token is not expired, the IAM Identity Center responds with another access token.
-
This access token can be used to either refresh the permission set session of existing clients, or to resolve credentials for new clients.
However, if the IAM Identity Center access portal session is expired, then no new access token is granted. Therefore, the permission set duration cannot be renewed. It will expire (and access will be lost) whenever the cached permission set session length times out for existing clients.
Any code that creates a new client will fail authentication as soon as the IAM Identity Center session expires. This is because the permission set credentials are not cached. Your code won't be able to create a new client and complete the credential resolution process until you have a valid access token.
To recap, when the SDK needs new permission set credentials, the SDK first checks for any valid, existing credentials and uses those. This applies whether the credentials are for a new client or for an existing client with expired credentials. If credentials aren't found or they're not valid, then the SDK calls the IAM Identity Center API to get new credentials. To call the API, it needs the access token. If the access token is expired, the SDK uses the refresh token to try to get a new access token from the IAM Identity Center service. This token is granted if your IAM Identity Center access portal session is not expired.