Using the AmazonCredentialsProvider Protocol in the AWS SDK for iOS

As an AWS developer, you should already be aware of how credentials are necessary to make calls to our various services. As a mobile developer, you should also be aware of the dangers of embedding credentials in your application (see our previous post on this). In order to help developers deliver credentials to the service clients, the AWS SDK for iOS contains the AmazonCredentialsProvider protocol. The goal of this protocol is to standardize a method by which service clients in the SDK can consume temporary, refreshable credentials. The SDK contains two reference implementations for this protocol: AmazonStaticCredentialsProvider, which wraps long term credentials, and AmazonSTSCredentialsProvider, which makes a call to AWS Security Token Service (STS) when credentials expire. This protocol could also be used to fetch credentials from a custom Token Vending Machine (as shown in our Locations2 sample), or another credentials source.

Understanding the Protocol

The AmazonCredentialsProvider protocol contains two required methods:

• credentials – Returns the credentials to use for a call to AWS. This is called every time the SDK needs credentials, so implementations should keep this in mind when considering whether to cache credentials or fetch from a remote source every time.
• refresh – Forces a refresh of the stored/cache credentials. Depending on your implementation, this may or may not be necessary (for instance, the AmazonStaticCredentialsProvider treats this as a no-op).

The service clients make use of these two methods during the execution of a request like so:

1. The request is passed to the client for invocation.
2. The client calls credentials to fetch the current valid credentials. This may require an additional service call to fetch new, valid credentials.
3. The client uses the retrieved credentials to sign the request and send to AWS.

From here, the path diverges depending on whether or not the request is running asynchronously via delegates (see our series on asynchronous operation of the SDK for more info).

For synchronous requests, if the operation fails with an expired or invalid token, the client calls refresh on the provider and then retries the request.

For asynchronous requests, you need to handle this error in your delegate callbacks, and then refresh the provider and retry the request.

How the SDK Uses Providers

Using this provider protocol is the default for all service clients in the SDK. Using either of these existing methods below will create an instance of AmazonStaticCredentialsProvider internally.

// create the client
AmazonS3Client *s3 = [AmazonS3Client alloc];
// initialize with ACCESS and SECRET key
[s3 initWithAccessKey:ACCESS_KEY withSecretKey:SECRET_KEY];
// or with AmazonCredentials object
[s3 initWithCredentials:CREDENTIALS_OBJECT];

If creating your own provider, or using the AmazonSTSCredentialsProvider included in the SDK, you can use the following:

// create the client
AmazonS3Client *s3 = [AmazonS3Client alloc];
// create the Provider (using STS)
AmazonSecurityTokenServiceClient *sts = 
    [[AmazonSecurityTokenServiceClient alloc] initWithCredentials:CREDENTIALS_OBJECT];
AmazonSTSCredentialsProvider *provider = 
    [[AmazonSTSCredentialsProvider alloc] initWithClient:sts];
[s3 initWithCredentialsProvider:provider];

Note: These examples are using static credentials for demonstration, but we strongly recommend that you not embed credentials in your application.

Caveats

If you plan to implement your own AmazonCredentialsProvider, be aware of a few things:

• Providers are retained by the client, so if you are using the same provider instance for multiple clients, you need to be prepared to handle concurrent access.
• When operating synchronously, the SDK calls refresh when encountering an expired or invalid token, but we recommend that providers refresh internally prior to explicit expiration of temporary credentials to reduce retries of failed requests.

Future Development

AWS is committed to improving the development experience for our customers, so we will continue to add new providers to the AWS SDK for iOS where it makes sense. In the interim, please feel free to write your own provider, and if you believe it will be useful to the community, submit a pull request request to our GitHub repository.

If you like building mobile applications that use cloud services that our customers use on a daily basis, perhaps you would like to join the AWS Mobile SDK and Tools team. We are hiring Software Developers, Web Developers, and Product Managers.