Simplifying Token Vending Machine Deployment with AWS CloudFormation

Managing credentials in mobile apps is an important concept to get right. Embedding credentials directly into your app is not secure and can lead to your credentials becoming compromised. Two methods we recommend are to use a token vending machine (TVM) or to use web identity federation. Both of these methods provide your app with temporary resource-bound credentials. Deploying a TVM requires several steps. It involves creating a new AWS Identity and Access Management (IAM) user with an access policy and key, deploying a TVM using AWS Elastic Beanstalk and then configuring everything. If you decide you want to tear down your TVM, you need to delete all of these resources individually just like you created them. To make this process easier, we have developed some AWS CloudFormation templates that will automate everything necessary to deploy our reference TVM implementations.

Deploying the TVM

If you want your mobile app to register with the TVM anonymously, use the anonymous TVM. This TVM associates tokens only with a unique identifier for each mobile device. It doesn’t store the identity of the mobile device user.

If you want your mobile app to register with the TVM with a username and password, use the identity TVM. This TVM associates tokens with mobile device users.

A good write-up on the differences between the two implementations is available here, in the section titled Anonymous TVM and Identity TVM.

To deploy the TVM

1. Click this button to launch the anonymous TVM in the US East (N. Virginia) Region

or click this button to launch the identity TVM in the US East (N. Virginia) Region.

If you need to customize the template or use a different region, download the anonymous TVM template or the identity TVM template and use the CloudFormation Console.

2. Click Continue.

3. On the next page, only the identity TVM template will prompt you for parameters. You can leave this set to the default MyMobileAppName if you want to test it against our sample app. Otherwise, set it to the name of the app you will provide to the TVM when you connect.

4. Click the checkbox I acknowledge that this template may create IAM resources.

5. Click Continue.

6. Click Continue on the tags page.

7. Click Create Stack on the final page.

At this point CloudFormation will create all of the necessary resources and deploy your TVM. It will create an IAM user with an access key and policy granting access to DynamoDB, S3, SQS and SNS. It will then launch a TVM capable of vending credentials tied to that IAM user on an EC2 micro instance running Tomcat 7.

8. In order to connect your app to the TVM, you will need its URL. Once the stack has completed, click on the Outputs tab where it will list the URL. Specify this URL in your mobile app so it can connect.

Customizing

Chances are you will need to customize your TVM for use in production, either to tighten the resources your policy allows, to run it on multiple hosts with an elastic load balancer fronting it, to allow direct ssh access to the host it is running on, binding a SSL certificate to your TVM or a multitude of other things. If you need to change the policy you should read this article for the Anonymous TVM or this article for the Identity TVM. This article is also important in understanding how the TVM works. You will need to modify the .war file for the TVM, upload it to a S3 bucket you own, update the template to reference that bucket location, and modify the policy associated with the TVMUser in the template.

Here is where you would change the .war file location:

"SourceBundle" : {
    "S3Bucket" : "tvm-identity",
    "S3Key" : "latest/IdentityTVM.war"
}

Here is where you would modify the policy:

"Statement" : [ {
     "Effect" : "Allow",
     "Action" : "sts:GetFederationToken",
     "Resource" : "*"
  }, {
     "Effect" : "Allow",
     "Action" : "iam:GetUser",
     "Resource" : "*"
  }, {
     "Effect" : "Allow",
     "Action" : "sdb:*",
     "Resource" : "*"
  }, {
     "Effect" : "Allow",
     "Action" : "dynamodb:*",
     "Resource" : "*"
  }, {
     "Effect" : "Allow",
     "Action" : "sqs:*",
     "Resource" : "*"
  }, {
      "Effect" : "Allow",
      "Action" : "s3:*",
      "Resource" : "*"
  }, {
      "Action" : "sns:*",
      "Effect" : "Allow",
      "Resource" : "*"
  } ]

If you want to tweak the template to run the TVM on multiple hosts or do some of the more advanced ideas mentioned above, the AWS CloudFormation User Guide is a useful resource on the syntax and what the available options are. Also, the Resources tab in the CloudFormation console lists all of the resources that were created as part of the stack creation. This is useful if you need to edit these resources directly in either the Elastic Beanstalk or IAM portions of the AWS Management Console.

Deleting the TVM

Click the checkbox next to your CloudFormation name and click the Delete Stack button. You do not need to also select the Elastic Beanstalk environment, deleting the master stack will delete that as well.

Conclusion

CloudFormation simplifies deploying a TVM to a couple of steps and it is easy to tear down your stack if you no longer need it. We hope this makes it easier for you to experiment with the sample apps and allows you to spend more time making great apps of your own!

Front-End Web & Mobile