# Using IAM Identity Center to authenticate AWS SDK and tools
<a name="access-sso"></a>

 AWS IAM Identity Center can be used to provide AWS credentials when developing an AWS application on a non-AWS compute service environments. If you are developing on an AWS resource, such as Amazon Elastic Compute Cloud (Amazon EC2) or AWS Cloud9, we recommend getting credentials from that service instead.

Use IAM Identity Center authentication if you already use Identity Center for AWS account access or need to manage access for an organization. 

In this tutorial, you establish IAM Identity Center access and will configure it for your SDK or tool by using the AWS access portal and the AWS CLI.
+ The AWS access portal is the web location where you manually sign in to the IAM Identity Center. The format of the URL is `d-xxxxxxxxxx.awsapps.com/start`or `your_subdomain.awsapps.com/start`. When signed in to the AWS access portal, you can view AWS accounts and roles that have been configured for that user. This procedure uses the AWS access portal to get configuration values you need for the SDK/tool authentication process. 
+ The AWS CLI is used to configure your SDK or tool to use IAM Identity Center authentication for API calls made by your code. This one-time process updates your shared AWS `config` file, that is then used by your SDK or tool when you run your code. 

## Prerequisites
<a name="prereq-auth"></a>

Before starting this procedure, you should have completed the following:
+ If you do not have an AWS account, [sign up for an AWS account](https://portal.aws.amazon.com/billing/signup).
+ If you haven't enabled IAM Identity Center yet, [enable IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-set-up-for-idc.html) by following the instructions in the *AWS IAM Identity Center User Guide*.

## Configure programmatic access using IAM Identity Center
<a name="idcGettingStarted"></a>

### Step 1: Establish access and select appropriate permission set
<a name="establishAccess"></a>

Choose one of the following methods to access your AWS credentials.

#### I do not have established access through IAM Identity Center
<a name="idc-access"></a>

1. Add a user and add administrative permissions by following the [Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/quick-start-default-idc.html) procedure in the *AWS IAM Identity Center User Guide*. 

1. The `AdministratorAccess` permission set should not be used for regular development. Instead, we recommend using the predefined `PowerUserAccess` permission set, unless your employer has created a custom permission set for this purpose.

   Follow the same [Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/quick-start-default-idc.html) procedure again, but this time:
   + Instead of creating the `Admin team` group, create a `Dev team` group, and substitute this thereafter in the instructions.
   + You can use the existing user, but the user must be added to the new `Dev team` group.
   + Instead of creating the `AdministratorAccess` permission set, create a `PowerUserAccess` permission set, and substitute this thereafter in the instructions.

   When you are done, you should have the following:
   + A `Dev team` group.
   + An attached `PowerUserAccess` permission set to the `Dev team` group.
   + Your user added to the `Dev team` group.

1. Exit the portal and sign in again to see your AWS accounts and options for `Administrator` or `PowerUserAccess`. Select `PowerUserAccess` when working with your tool/SDK. 

#### I already have access to AWS through a federated identity provider managed by my employer (such as Microsoft Entra or Okta)
<a name="federated-access"></a>

Sign in to AWS through your identity provider's portal. If your Cloud Administrator has granted you `PowerUserAccess` (developer) permissions, you see the AWS accounts that you have access to and your permission set. Next to the name of your permission set, you see options to access the accounts manually or programmatically using that permission set. 

Custom implementations might result in different experiences, such as different permission set names. If you're not sure which permission set to use, contact your IT team for help. 

#### I already have access to AWS through the AWS access portal managed by my employer
<a name="accessportal-access"></a>

Sign in to AWS through the AWS access portal. If your Cloud Administrator has granted you `PowerUserAccess` (developer) permissions, you see the AWS accounts that you have access to and your permission set. Next to the name of your permission set, you see options to access the accounts manually or programmatically using that permission set. 

#### I already have access to AWS through a federated custom identity provider managed by my employer
<a name="customfederated-access"></a>

Contact your IT team for help.

### Step 2: Configure SDKs and tools to use IAM Identity Center
<a name="configureAccess"></a>

1.  On your development machine, install the latest AWS CLI. 

   1. See [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*. 

   1.  (Optional) To verify that the AWS CLI is working, open a command prompt and run the `aws --version` command. 

1. Sign in to the AWS access portal. Your employer may provide this URL or you may get it in an email following **Step 1: Establish access**. If not, find your **AWS access portal URL** on the **Dashboard** of [https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/). 

   1. In the AWS access portal, in the **Accounts** tab, select the individual account to manage. The roles for your user are displayed. Choose **Access keys** to get credentials for command line or programmatic access for the appropriate permission set. Use the predefined `PowerUserAccess` permission set, or whichever permission set you or your employer has created to apply least-privilege permissions for development. 

   1. In the **Get credentials** dialog box, choose either **MacOS and Linux** or **Windows**, depending on your operating system.

   1. Choose the **IAM Identity Center credentials** method to get the `Issuer URL` and `SSO Region` values that you need for the next step. Note: `SSO Start URL` can be used interchangeably with `Issuer URL`.

1. In the AWS CLI command prompt, run the `aws configure sso` command. When prompted, enter the configuration values that you collected in the previous step. For details on this AWS CLI command, see [Configure your profile with the `aws configure sso` wizard](https://docs.aws.amazon.com/cli/latest/userguide/sso-configure-profile-token.html#sso-configure-profile-token-auto-sso). 

   1. For the prompt `SSO Start URL`, enter the value you obtained for `Issuer URL`. 

   1.  For **CLI profile name**, we recommend entering *default* when you are getting started. For information about how to set non-default (named) profiles and their associated environment variable, see [Profiles](file-format.md#file-format-profile). 

1. (Optional) In the AWS CLI command prompt, confirm the active session identity by running the `aws sts get-caller-identity` command. The response should show the IAM Identity Center permission set that you configured. 

1. If you are using an AWS SDK, create an application for your SDK in your development environment.

   1. For some SDKs, additional packages such as `SSO` and `SSOOIDC` must be added to your application before you can use IAM Identity Center authentication. For details, see your specific SDK.

   1.  If you previously configured access to AWS, review your shared AWS `credentials` file for any [AWS access keys](feature-static-credentials.md). You must remove any static credentials before the SDK or tool will use the IAM Identity Center credentials because of the [Understand the credential provider chain](standardized-credentials.md#credentialProviderChain) precedence. 

 For a deep dive into how the SDKs and tools use and refresh credentials using this configuration, see [How IAM Identity Center authentication is resolved for AWS SDKs and tools](understanding-sso.md). 

To configure IAM Identity Center provider settings directly in the shared `config` file, see [IAM Identity Center credential provider](feature-sso-credentials.md) in this guide.

## Refreshing portal access sessions
<a name="refreshSession"></a>

Your access will eventually expire and the SDK or tool will encounter an authentication error. When this expiration occurs depends on your configured session lengths. To refresh the access portal session again when needed, use the AWS CLI to run the `aws sso login` command. 

You can extend both the IAM Identity Center access portal session duration and the permission set session duration. This lengthens the amount of time that you can run code before you need to manually sign in again with the AWS CLI. For more information, see the following topics in the *AWS IAM Identity Center User Guide*:
+ **IAM Identity Center session duration** – [Configure the duration of your users' AWS access portal sessions](https://docs.aws.amazon.com/singlesignon/latest/userguide/configure-user-session.html) 
+ **Permission set session duration** – [Set session duration ](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosessionduration.html)

# How IAM Identity Center authentication is resolved for AWS SDKs and tools
<a name="understanding-sso"></a>



## Relevant IAM Identity Center terms
<a name="ssoterms"></a>

The following terms help you understand the process and configuration behind AWS IAM Identity Center. The documentation for AWS 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 AWS 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](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html#renamed) in the AWS IAM Identity Center User Guide. | 
| IAM Identity Center consoleAdministrative console |   | The console you use to configure single sign-on.  | 
| AWS access portal URL  |  | A URL unique to your IAM Identity Center account, like https://xxx.awsapps.com/start. 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 AWS service calls. In informal discussions, you might see this incorrectly referred to as "role session." | 
| Permission set credentials  | AWS credentialssigv4 credentials  | The credentials the SDK actually uses for most AWS service calls (specifically, all sigv4 AWS 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 AWS services
<a name="idccredres"></a>

The IAM Identity Center API exchanges bearer token credentials for sigv4 credentials. Most AWS services are sigv4 APIs, with a few exceptions like Amazon CodeWhisperer and Amazon CodeCatalyst. The following describes the credential resolution process for supporting most AWS service calls for your application code through AWS IAM Identity Center. 

### Start an AWS access portal session
<a name="idccredres1"></a>
+ Start the process by signing in to the session with your credentials.
  + Use the `aws sso login` command in the AWS Command Line Interface (AWS 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 AWS 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 AWS 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' AWS access portal sessions](https://docs.aws.amazon.com/singlesignon/latest/userguide/configure-user-session.html) in the *AWS 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 AWS service calls
<a name="idccredres2"></a>

SDKs provide access to AWS services when you instantiate a client object per service. When the selected profile of the shared AWS `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](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html#credentialProviderChain) 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 AWS 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](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosessionduration.html) in the *AWS IAM Identity Center User Guide*.
+  Be aware that the permission set credentials are also referred to as *AWS credentials* and *sigv4 credentials* in most AWS SDK API documentation.

The permission set credentials are returned from a call to [getRoleCredentials](https://docs.aws.amazon.com/singlesignon/latest/PortalAPIReference/API_GetRoleCredentials.html) of the IAM Identity Center API to the SDK. The SDK's client object uses that assumed IAM role to make calls to the AWS 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
<a name="idccredres3"></a>

When using the [SSO token provider configuration](feature-sso-credentials.md#sso-token-config), 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.