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).

Using Amazon SDK for C++ credential providers

To make requests to Amazon using the Amazon SDK for C++, the SDK uses cryptographically-signed credentials issued by Amazon. At runtime, the SDK retrieves configuration values for credentials by checking several locations.

Authentication with Amazon can be handled outside of your codebase. Many authentication methods can be automatically detected, used, and refreshed by the SDK using the credential provider chain.

For guided options for getting started on Amazon authentication for your project, see Authentication and access in the Amazon SDKs and Tools Reference Guide.

The credential provider chain

If you don't explicitly specify a credential provider when constructing a client, the SDK for C++ uses a credential provider chain that checks a series of places where you can supply credentials. Once the SDK finds credentials in one of these locations, the search stops.

Credential retrieval order

All SDKs have a series of places (or sources) that they check in order to get valid credentials to use to make a request to an Amazon Web Services service. After valid credentials are found, the search is stopped. This systematic search is called the credential provider chain.

For each step in the chain, there are different ways to set the values. Setting values directly in code always takes precedence, followed by setting as environment variables, and then in the shared Amazon config file. For more information, see Precedence of settings in the Amazon SDKs and Tools Reference Guide.

The SDK attempts to load credentials from the [default] profile in the shared Amazon config and credentials files. You can use the AWS_PROFILE environment variable to choose a named profile you want the SDK to load instead of using [default]. The config and credentials files are shared by Amazon SDKs and tools. The Amazon SDKs and Tools Reference Guide has information on SDK configuration settings used by all Amazon SDKs and the Amazon CLI. To learn more about how to configure the SDK through the shared Amazon config file, see Shared config and credentials files. To learn more about how to configure the SDK through setting environment variables, see Environment variables support.

To authenticate with Amazon, the SDK for C++ checks the credential providers in the following order.

The credential provider chain can be reviewed at AWSCredentialsProviderChain in the Amazon SDK for C++ source code on GitHub.

If you followed the recommended approach for new users to get started, you set up Amazon IAM Identity Center authentication during Authenticating the Amazon SDK for C++ with Amazon of the Getting started topic. Other authentication methods are useful for different situations. To avoid security risks, we recommend always using short-term credentials. For other authentication method procedures, see Authentication and access in the Amazon SDKs and Tools Reference Guide.

Explicit credential provider

Instead of relying on the credential provider chain to detect your authentication method, you can specify a specific credential provider that the SDK should use. You can do this by providing credentials in your service client's constructor.

The following example creates an Amazon Simple Storage Service client by directly providing temporary access credentials instead of using the chain.

    SDKOptions options;
    Aws::InitAPI(options);
    {
        const auto cred_provider = Aws::MakeShared<Auth::SimpleAWSCredentialsProvider>("TestAllocationTag",
            "awsAccessKeyId",
            "awsSecretKey",
            "sessionToken");
        S3Client client{cred_provider};
    }
    Aws::ShutdownAPI(options);

Identity caching

The SDK will cache credentials and other identity types such as SSO tokens. By default, the SDK uses a lazy cache implementation that loads credentials upon first request, caches them, and then attempts to refresh them during another request when they are close to expiring. Clients created from the same Aws::Client::ClientConfiguration share a cache.