Amazon Cognito Credentials Provider

Amazon Cognito helps you create unique identifiers for your end users that are kept consistent across devices and platforms. Cognito also delivers temporary, limited-privilege credentials to your app to access AWS resources. With Amazon Cognito, your app can support unauthenticated guest users as well as users authenticated through a identity provider, such as Facebook, Google, Login with Amazon or with developer authenticated identity providers.

Version 2.3.1.0 of AWS SDK for .NET has added Amazon.CognitoIdentity.CognitoAWSCredentials, a credentials object that uses Cognito and the Security Token Service to retrieve credentials in order to make AWS calls.

The first step in setting up CognitoAWSCredentials is to create an ”identity pool”. (An identity pool is a store of user identity information specific to your account. The information is retrievable across client platforms, devices, and operating systems, so that if a user starts using the app on a phone and later switches to a tablet, the persisted app information is still available for that user.) You can create a new identity pool from the Amazon Cognito management console. If you are using the console, it will also provide you the other pieces of information we will need:

• Your account number: this is a 12-digit number, such as 123456789012, that is unique to your account.
• The unauthenticated role ARN: this is a role that unauthenticated users will assume. For instance, this role can provide read-only permissions to your data.
• The authenticated role ARN: authenticated users will assume this role. This role can have more extensive permissions to your data.

Here’s a simple code sample illustrating how this information is used to set up CognitoAWSCredentials, which can then be used to make a call to Amazon S3 as an unauthenticated user.

CognitoAWSCredentials credentials = new CognitoAWSCredentials(
    accountId,        // account number
    identityPoolId,   // identity pool id
    unAuthRoleArn,    // role for unauthenticated users
    null,             // role for authenticated users, not set
    region);
using (var s3Client = new AmazonS3Client(credentials))
{
    s3Client.ListBuckets();
}

As you can see, we are able to make calls with just a minimum amount of data required to authenticate the user. User permissions are controlled by the role, so you are free to configure access as you see fit.

The next example shows how you can start using AWS as an unauthenticated user, then authenticate through Facebook and update the credentials to use Facebook credentials. Using this approach, you can grant different capabilities to authenticated users via the authenticated role. For instance, you might have a Windows Phone application that permits users to view content anonymously, but allows them to post if they are logged on with one or more of the configured providers.

CognitoAWSCredentials credentials = new CognitoAWSCredentials(
    accountId, identityPoolId,
    unAuthRoleArn,    // role for unauthenticated users
    authRoleArn,      // role for authenticated users
    region);
using (var s3Client = new AmazonS3Client(credentials))
{
    // Initial use will be unauthenticated
    s3Client.ListBuckets();
    
    // Authenticate user through Facebook
    string facebookToken = GetFacebookAuthToken();
    
    // Add Facebook login to credentials. This will clear the current AWS credentials
    // and new AWS credentials using the authenticated role will be retrieved.
    credentials.AddLogin("graph.facebook.com", facebookAccessToken);

    // This call will be performed with the authenticated role and credentials
    s3Client.ListBuckets();
}

This new credentials object provides even more functionality if used with the AmazonCognitoSyncClient that is part of the .NET SDK: if you are using both AmazonCognitoSyncClient and CognitoAWSCredentials, you don’t have to specify the IdentityPoolId and IdentityId properties when making calls with the AmazonCognitoSyncClient. These properties are automatically filled in from CognitoAWSCredentials. Our final example illustrates this, as well as an event that notifies us whenever the IdentityId for CognitoAWSCredentials changes. (The IdentityId can change in some cases, such as going from an unauthenticated user to an authenticated one.)

CognitoAWSCredentials credentials = GetCognitoAWSCredentials();

// Log identity changes
credentials.IdentityChangedEvent += (sender, args) =>
{
    Console.WriteLine("Identity changed: [{0}] => [{1}]", args.OldIdentityId, args.NewIdentityId);
};

using(var syncClient = new AmazonCognitoSyncClient(credentials))
{
    var result = syncClient.ListRecords(new ListRecordsRequest
    {
        DatasetName = datasetName
        // No need to specify these properties
        //IdentityId = "...",
        //IdentityPoolId = "..."        
    });
}

For more information on Amazon Cognito, including use-cases and sample policies, visit the official Amazon Cognito page or the Cognito section of the Mobile Development blog.