This documentation is for version 3.0 of the AWS SDK for .NET, which is mostly centered around .NET Framework and ASP.NET 4.x, Windows, and Visual Studio.

The latest version of the documentation at https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/ is mostly centered around .NET Core and ASP.NET Core. In addition to Windows and Visual Studio, it gives equal consideration to cross-platform development.

Configuring AWS Credentials

You must manage your AWS credentials securely and avoid practices that can unintentionally expose your credentials to the public. In this topic, we describe how you configure your application’s AWS credentials so that they remain secure.

The following are general guidelines for securely managing credentials:

The following topics describe how to manage credentials for an AWS SDK for .NET application. For a discussion of how to securely manage AWS credentials, see Best Practices for Managing AWS Access Keys.

Using the SDK Store

During development of your AWS SDK for .NET application, add a profile to the SDK Store for each set of credentials you want to use in your application. This prevents the accidental exposure of your AWS credentials. The SDK Store is located in the C:\Users\<username>\AppData\Local\AWSToolkit folder in the RegisteredAccounts.json file. The SDK Store provides the following benefits:

You can manage the profiles in the SDK Store in several ways.

The following examples show how to create a basic profile and SAML profile and add them to the SDK Store by using the RegisterProfile method.

Create a Profile and Save it to the .NET Credentials File

Create an Amazon.Runtime.CredentialManagement.CredentialProfileOptions object and set its AccessKey and SecretKey properties. Create an Amazon.Runtime.CredentialManagement.CredentialProfile object. Provide the name of the profile and the CredentialProfileOptions object you created. Optionally, set the Region property for the profile. Instantiate a NetSDKCredentialsFile object and call the RegisterProfile method to register the profile.

var options = new CredentialProfileOptions
{
    AccessKey = "access_key",
    SecretKey = "secret_key"
};
var profile = new Amazon.Runtime.CredentialManagement.CredentialProfile("basic_profile", options);
profile.Region = RegionEndpoint.USWest1;
var netSDKFile = new NetSDKCredentialsFile();
netSDKFile.RegisterProfile(profile);

The RegisterProfile method is used to register a new profile. Your application typically calls this method only once for each profile.

Create a SAMLEndpoint and an Associated Profile and Save it to the .NET Credentials File

Create an Amazon.Runtime.CredentialManagement.SAMLEndpoint object. Provide the name and endpoint URI parameters. Create an Amazon.Runtime.CredentialManagement.SAMLEndpointManager object. Call the RegisterEndpoint method to register the endpoint. Create an Amazon.Runtime.CredentialManagement.CredentialProfileOptions object and set its EndpointName and RoleArn properties. Create an Amazon.Runtime.CredentialManagement.CredentialProfile object and provide the name of the profile and the CredentialProfileOptions object you created. Optionally, set the Region property for the profile. Instantiate a NetSDKCredentialsFile object and call the RegisterProfile method to register the profile.

var endpoint = new SAMLEndpoint("endpoint1", new Uri("https://some_saml_endpoint"), SAMLAuthenticationType.Kerberos);
var endpointManager = new SAMLEndpointManager();
endpointManager.RegisterEndpoint(endpoint);
options = new CredentialProfileOptions
{
    EndpointName = "endpoint1",
    RoleArn = "arn:aws:iam::999999999999:role/some-role"
};
profile = new CredentialProfile("federated_profile", options);
netSDKFile = new NetSDKCredentialsFile();
netSDKFile.RegisterProfile(profile);

Using a Credentials File

You can also store profiles in your shared AWS credentials file. This file can be used by the other AWS SDKs, the AWS CLI and AWS Tools for Windows PowerShell. To reduce the risk of accidentally exposing credentials, store the credentials file separately from any project files, usually in the user’s home folder. Be aware that the profiles in credentials files are stored in plaintext.

By default, this file is located in the .aws directory within your home directory and is named credentials. For more information, see Where Are Configuration Settings Stored? in the AWS Command Line Interface User Guide.

You can manage the profiles in the shared credentials file in two ways:

Setting an Alternative Credentials Profile

The AWS SDK for .NET uses the default profile by default, but you can change which profile is used from the credentials file by using the AWS_Profile environment variable.

For example, on Linux, macOS, or Unix run the following command to change the profile to myProfile.

export AWS_PROFILE="myProfile"

On Windows use the following command.

set AWS_PROFILE=myProfile

Setting the AWS_PROFILE environment variable affects credential loading for all officially supported AWS SDKs and Tools, including the AWS CLI and the AWS CLI for PowerShell.

Create a Profile and Save it to the Shared Credentials File

Create an Amazon.Runtime.CredentialManagement.CredentialProfileOptions object and set its AccessKey and SecretKey properties. Create an Amazon.Runtime.CredentialManagement.CredentialProfile object. Provide the name of the profile and the CredentialProfileOptions you created. Optionally, set the Region property for the profile. Instantiate an Amazon.Runtime.CredentialManagement.SharedCredentialsFile object and call the RegisterProfile method to register the profile.

options = new CredentialProfileOptions
{
    AccessKey = "access_key",
    SecretKey = "secret_key"
};
profile = new CredentialProfile("shared_profile", options);
profile.Region = RegionEndpoint.USWest1;
var sharedFile = new SharedCredentialsFile();
sharedFile.RegisterProfile(profile);

The RegisterProfile method is used to register a new profile. Your application will normally call this method only once for each profile.

Create a Source Profile and an Associated Assume Role Profile and Save It to the Credentials File

Create an Amazon.Runtime.CredentialManagement.CredentialProfileOptions object for the source profile and set its AccessKey and SecretKey properties. Create an Amazon.Runtime.CredentialManagement.CredentialProfile object. Provide the name of the profile and the CredentialProfileOptions you created. Instantiate an Amazon.Runtime.CredentialManagement.SharedCredentialsFile object and call the RegisterProfile method to register the profile. Create another Amazon.Runtime.CredentialManagement.CredentialProfileOptions object for the assumed role profile and set the SourceProfile and RoleArn properties for the profile. Create an Amazon.Runtime.CredentialManagement.CredentialProfile object for the assumed role. Provide the name of the profile and the CredentialProfileOptions you created.

// Create the source profile and save it to the shared credentials file
var sourceProfileOptions = new CredentialProfileOptions
{
    AccessKey = "access_key",
    SecretKey = "secret_key"
};
var sourceProfile = new CredentialProfile("source_profile", sourceProfileOptions);
sharedFile = new SharedCredentialsFile();
sharedFile.RegisterProfile(sourceProfile);

// Create the assume role profile and save it to the shared credentials file
var assumeRoleProfileOptions = new CredentialProfileOptions
{
    SourceProfile = "source_profile",
    RoleArn = "arn:aws:iam::999999999999:role/some-role"
};
var assumeRoleProfile = new CredentialProfile("assume_role_profile", assumeRoleProfileOptions);
sharedFile.RegisterProfile(assumeRoleProfile);

Update an Existing Profile in the Shared Credentials File

Create an Amazon.Runtime.CredentialManagement.SharedCredentialsFile object. Set the Region, AccessKey and SecretKey properties for the profile. Call the TryGetProfile method. If the profile exists, use an Amazon.Runtime.CredentialManagement.SharedCredentialsFile instance to call the RegisterProfile method to register the updated profile.

sharedFile = new SharedCredentialsFile();
CredentialProfile basicProfile;
if (sharedFile.TryGetProfile("basicProfile", out basicProfile))
{
    basicProfile.Region = RegionEndpoint.USEast1;
    basicProfile.Options.AccessKey = "different_access_key";
    basicProfile.Options.SecretKey = "different_secret_key";

    sharedFile.RegisterProfile(basicProfile);
}

Accessing Credentials and Profiles in an Application

You can easily locate credentials and profiles in the .NET credentials file or in the shared credentials file by using the Amazon.Runtime.CredentialManagement.CredentialProfileStoreChain class. This is the way the .NET SDK looks for credentials and profiles. The CredentialProfileStoreChain class automatically checks in both credentials files.

You can get credentials or profiles by using the TryGetAWSCredentials or TryGetProfile methods. The ProfilesLocation property determines the behavior of the CredentialsProfileChain, as follows:

Get Credentials from the SDK Credentials File or the Shared Credentials File in the Default Location.

Create a CredentialProfileStoreChain object and an Amazon.Runtime.AWSCredentials object. Call the TryGetAWSCredentials method. Provide the profile name and the AWSCredentials object in which to return the credentials.

var chain = new CredentialProfileStoreChain();
AWSCredentials awsCredentials;
if (chain.TryGetAWSCredentials("basic_profile", out awsCredentials))
{
    // use awsCredentials
}

Get a Profile from the SDK Credentials File or the Shared Credentials File in the Default Location

Create a CredentialProfileStoreChain object and an Amazon.Runtime.CredentialManagement.CredentialProfile object. Call the TryGetProfile method and provide the profile name and CredentialProfile object in which to return the credentials.

var chain = new CredentialProfileStoreChain();
CredentialProfile basicProfile;
if (chain.TryGetProfile("basic_profile", out basicProfile))
{
    // Use basicProfile
}

Get AWSCredentials from a File in the Shared Credentials File Format at a File Location

Create a CredentialProfileStoreChain object and provide the path to the credentials file. Create an AWSCredentials object. Call the TryGetAWSCredentials method. Provide the profile name and the AWSCredentials object in which to return the credentials.

var chain = new
    CredentialProfileStoreChain("c:\\Users\\sdkuser\\customCredentialsFile.ini");
AWSCredentials awsCredentials;
if (chain.TryGetAWSCredentials("basic_profile", out awsCredentials))
{
    // Use awsCredentials
}

How to Create an AmazonS3Client Using the SharedCredentialsFile Class

You can create an AmazonS3Client object that uses the credentials for a specific profile by using the Amazon.Runtime.CredentialManagement.SharedCredentialsFile class. The AWS SDK for .NET loads the credentials contained in the profile automatically. You might do this if you want to use a specific profile for a given client that is different from the profile you specify in App.Config.

CredentialProfile basicProfile;
AWSCredentials awsCredentials;
var sharedFile = new SharedCredentialsFile();
if (sharedFile.TryGetProfile("basic_profile", out basicProfile) &&
    AWSCredentialsFactory.TryGetAWSCredentials(basicProfile, sharedFile, out awsCredentials))
{
    using (var client = new AmazonS3Client(awsCredentials, basicProfile.Region))
    {
        var response = client.ListBuckets();
    }
}

If you want to use the default profile, and have the AWS SDK for .NET automatically use your default credentials to create the client object use the following code.

using (var client = new AmazonS3Client(RegionEndpoint.US-West2))
{
    var response = client.ListBuckets();
}

Credential and Profile Resolution

The AWS SDK for .NET searches for credentials in the following order and uses the first available set for the current application.

SDK Store profiles are specific to a particular user on a particular host. You can’t copy them to other hosts or other users. For this reason, you can’t reuse SDK Store profiles that are on your development machine on other hosts or developer machines. If your application is running on an Amazon EC2 instance, such as in a production environment, use an IAM role as described in Using IAM Roles for EC2 Instances with the AWS SDK for .NET. Otherwise, such as in pre-release testing, store your credentials in a credentials file that your web application has access to on the server.

Profile Resolution

With two different credentials file types, it’s important to understand how to configure the AWS SDK for .NET and AWS Tools for Windows PowerShell to use them. The AWSConfigs.AWSProfilesLocation (set explicitly or in AppConfig) controls how the AWS SDK for .NET finds credential profiles. The -ProfileLocation command line argument controls how AWS Tools for Windows PowerShell finds a profile. Here’s how the configuration works in both cases.

Specifying a Profile

Profiles are the preferred way to use credentials in an AWS SDK for .NET application. You don’t have to specify where the profile is stored. You only reference the profile by name. The AWS SDK for .NET retrieves the corresponding credentials, as described in the previous section.

The preferred way to specify a profile is to define an AWSProfileName value in the appSettings section of your application’s App.config or Web.config file. The associated credentials are incorporated into the application during the build process.

The following example specifies a profile named development.

<configuration>
  <appSettings>
    <add key="AWSProfileName" value="development"/>
  </appSettings>
</configuration>

This example assumes the profile exists in the SDK Store or in a credentials file in the default location.

If your profiles are stored in a credentials file in another location, specify the location by adding a AWSProfilesLocation attribute value in the <appSettings> element. The following example specifies C:\aws_service_credentials\credentials as the credentials file.

<configuration>
  <appSettings>
    <add key="AWSProfileName" value="development"/>
    <add key="AWSProfilesLocation" value="C:\aws_service_credentials\credentials"/>
  </appSettings>
</configuration>

The deprecated alternative way to specify a profile is shown below for completeness, but we do not recommend it.

<configuration>
  <configSections>
    <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/>
  </configSections>
  <aws profileName="development" profilesLocation="C:\aws_service_credentials\credentials"/>
</configuration>

<configuration>
  <configSections>
    <section name="aws" type="Amazon.AWSSection,AWSSDK.Core"/>
  </configSections>
  <aws profileName="development" profilesLocation="C:\aws_service_credentials\credentials"/>
</configuration>

Using Federated User Account Credentials

Applications that use the AWS SDK for .NET (AWSSDK.Core version 3.1.6.0 and later) can use federated user accounts through Active Directory Federation Services (AD FS) to access AWS web services by using Security Assertion Markup Language (SAML).

Federated access support means users can authenticate using your Active Directory. Temporary credentials are granted to the user automatically. These temporary credentials, which are valid for one hour, are used when your application invokes AWS web services. The SDK handles management of the temporary credentials. For domain-joined user accounts, if your application makes a call but the credentials have expired, the user is reauthenticated automatically and fresh credentials are granted. (For non-domain-joined accounts, the user is prompted to enter credentials before reauthentication.)

To use this support in your .NET application, you must first set up the role profile by using a PowerShell cmdlet. To learn how, see the AWS Tools for Windows PowerShell documentation.

After you setup the role profile, reference the profile in your application’s app.config/web.config file with the AWSProfileName key in the same way you would with other credential profiles.

The SDK Security Token Service assembly (AWSSDK.SecurityToken.dll), which is loaded at runtime, provides the SAML support to obtain AWS credentials. Be sure this assembly is available to your application at run time.

Specifying Roles or Temporary Credentials

For applications that run on Amazon EC2 instances, the most secure way to manage credentials is to use IAM roles, as described in Using IAM Roles for EC2 Instances with the AWS SDK for .NET.

For application scenarios in which the software executable is available to users outside your organization, we recommend you design the software to use temporary security credentials. In addition to providing restricted access to AWS resources, these credentials have the benefit of expiring after a specified period of time. For more information about temporary security credentials, see the following:

Although the title of the second article refers specifically to mobile applications, the article contains information that is useful for any AWS application deployed outside of your organization.

Using Proxy Credentials

If your software communicates with AWS through a proxy, you can specify credentials for the proxy by using the ProxyCredentials property on the AmazonS3Config class for the service. For example, for Amazon S3 you could use code similar to the following, where {my-username} and {my-password} are the proxy user name and password specified in a NetworkCredential object.

AmazonS3Config config = new AmazonS3Config();
config.ProxyCredentials = new NetworkCredential("my-username", "my-password");

Earlier versions of the SDK used ProxyUsername and ProxyPassword, but these properties are deprecated.