Token Vending Machine for Identity Registration - Sample Java Web Application

Sample Code & Libraries>Token Vending Machine for Identity Registration Sample Java Web Application
Community Contributed Software

  • Amazon Web Services provides links to these packages as a convenience for our customers, but software not authored by an "@AWS" account has not been reviewed or screened by AWS.
  • Please review this software to ensure it meets your needs before using it.

The token vending machine (TVM) is a server-based reference application that serves temporary credentials to remote clients to sign web requests to Amazon Web Services (AWS). The TVM is particularly useful for mobile client devices that use temporary credentials to access AWS. Both the AWS SDK for Android and the AWS SDK for iOS provide a sample client, which your mobile application can use to access the TVM and receive security tokens.

Details

Submitted By: Glen@AWS
AWS Products Used: AWS Elastic Beanstalk, AWS Identity and Access Management, Amazon SimpleDB
Language(s): Java
License: Apache 2.0
Created On: September 7, 2011 6:55 PM GMT
Last Updated: September 24, 2014 7:31 PM GMT
Download
Amazon Cognito

  • AWS has released Amazon Cognito. In many cases Amazon Cognito will replace the use of a Token Vending Machine as specified below. Please consider using Amazon Cognito in place of a TVM.
  • This content is being maintained for historical reference.

About This Sample

The token vending machine provides the following support to your mobile application.

Register a Mobile Device

A mobile application registers with the TVM with a user name and password to receive tokens.

Note: The TVM is also available in a version that supports anonymous registration. To download the TVM for Anonymous Registration go to Token Vending Machine for Anonymous Registration.

Securely transfer temporary security credentials

Once the mobile device is registered with the TVM, temporary security credentials are created through the AWS Security Token Service, a feature of Amazon Identity and Access Management, and then transferred to the mobile application. The mobile application uses these tokens to access Amazon Web Services.

Prerequisites

In order to use the TVM, you will need an AWS account. To sign up for AWS, go to http://aws.amazon.com.

We recommend that you install the TVM using AWS Elastic Beanstalk as described later in this article. AWS Elastic Beanstalk simplifies installation of any web application. For more information about AWS Elastic Beanstalk, see the AWS Elastic Beanstalk documentation.

Running the Sample

Download the TVM ZIP file

Click the Download button and follow the on-screen instructions. The TVM is stored in a compressed file named IdentityTVM.zip. The zip file contains the following:

/classes Contains the compiled Java classes for the TVM.
/lib Contains the library files of the AWS SDK for Java that the TVM uses to access AWS.
/src Contains the Java source code for the TVM.
/src/TokenVendingMachinePolicy.json Contains the policy applied by the TVM to the temporary credentials that are returned to the mobile device. You must modify this policy to be appropriate for your application.
/third-party Contains the third-party Java libraries (JAR) files used by the TVM.
/web Contains the Java Server Pages (JSP) pages for the TVM web user interface.
build.xml An ant project used to repackage the AnonymousTVM.war file.
clt.xml An ant project wrapper of TVM administration commands.
LICENSE.txt Text file containing the Apache 2.0 license the TVM is distributed under.
NOTICE.txt Text file containing the license notice of the AWS SDK for Java.
IdentityTVM.war The compiled WAR file for the TVM. Used for installation in AWS Elastic Beanstalk.

Create a folder on your computer to receive the contents of the zip file, and then extract the file.

Create an IAM User for the TVM

Before you install the TVM, add a new user to your AWS Account that will be used by the TVM. By using a dedicated user with the TVM, you can control the permissions and user rights of users who obtain security tokens from the TVM. For an overview of user permissions, see Overview of Permissions in Using IAM documentation.

Note: The access key ID and secret access key you generate in this step are needed when you install the token vending machine using AWS Elastic Beanstalk.

To add a user to your AWS account for the TVM

  1. Start the IAM page of the AWS Management Console. In a browser, go to https://console.aws.amazon.com/iam/home. Sign in if you are presented with a Sign In screen.

  2. On the Navigation pane of the console, click Users, and then click Create New Users.

    Create New User
  3. In the Create User dialog box, under Enter User Names, in the first box type the user name you want to create.

    Create User
  4. Select the Generate an access key for each User check box, and then click Create.

    Manage Access Keys
  5. Save the access key IDs and secret access keys to a credentials.csv file on your computer, click Download Credentials.

  6. When you are finished downloading your users' security credentials, click Close Window.

  7. Grant permissions to the TVM user. To attach a policy to the TVM user:

    1. Select the TVM user in the IAM User Console, Select the Permissions tab, and then click Attach User Policy.

      Attach User Policy
    2. In the Manage User Permissions dialog box, click Custom Policy, and then click Select.

      Custom Policy
    3. In the Edit Permissions dialog box, name the policy, and edit your policy document to contain the following then click Apply Policy.

      Edit Permissions

      Note

      The following policy statement is an example. You should modify this policy to suit the needs of your application. Use the TVM user policy to restrict the permissions of registered users. The TVM user policy establishes the broadest set of permissions for registered users. In the following example, the first two policies enable the TVM to retrieve and manage the temporary security credentials; you should not modify these unless you are making substantial changes to the TVM's architecture. The next five policies enable the mobile application itself to fully access Amazon SimpleDB, Amazon DynamoDB, Amazon SQS, Amazon S3, and Amazon SNS. The policy below is intended to enable the sample applications provided for the AWS SDK for iOS and the AWS SDK for Android. We strongly recommend that you restrict these permissions to the minimum set of services, actions, and resources necessary for your application. For more information on creating the appropriate policy for your application see the additional resources below.

      Also, the Token Vending Machine applies a policy on the temporary credentials it returns. As with the TVM user policy above, you should also update the policy for the temporary credentials to be appropriate for your application. This policy must be a subset of the policy defined for your IAM user. Otherwise, you will encounter an error. If you restrict the IAM user policy provided here you must also restrict the policy contained in the TVM. The policy applied to temporary credentials can be found in the file TokenVendingMachinePolicy.json.

      {
        "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": "*"
          }
        ]
      }
      

Create the AWS Elastic Beanstalk application

To launch the AWS Elastic Beanstalk application:

Create Beanstalk Application
  1. In the AWS Management Console, sign in, and navigate to AWS Elastic Beanstalk.

  2. Click Customize... and then Start to create a new application.

Provide the application details.

Application Details
  1. In the Upload New Version dialog box, in the Version Label text box, type a name for the TVM application.

    Note: The Application Name is not the same as the mobile sample APP_NAME value entered into the PARAM1 configuration value described later.
  2. In the Description field, type a brief description for the TVM application.

  3. Under Container Type, select the container type that you want. However, the container must be running Tomcat. The TVM will run on any of the Tomcat container types available.

  4. Select Upload Application.

  5. Click Browse, and then select the IdentityTVM.war file.

  6. Click Continue.

Provide the environment details.

Environment Details
  1. On the Environment Details page, ensure that the Launch a new environment running this application check box is selected.

    Do not select the Create an RDS DB Instance with this environment check box.

  2. In the Environment Name box, type a name for your environment.

    Note: The Environment URL field is automatically based on the Environment Name, and it must be unique.
  3. Click the Check Availability button to confirm that the URL is unique. If the environment URL is unavailable, change the Environment Name or Environment URL. You will need to use a different name that the one used in the screen capture.

  4. In the Description field, enter a brief description of the environment.

  5. Click Continue.

Provide the configuration details.

Configuration Details
  1. On the Configuration Details page, in the Instance Type box, select t1.micro. Any instance type will do, but the t1.micro is the best value and can be scaled up as needed.

  2. (Optional) In the Existing Key Pair box, type a key pair. The TVM does not require a key pair unless you are enabling remote access to the environment.

  3. (Optional) In the Email Address box, type your email address.

  4. In the Application Health Check URL box, accept the value /.

  5. Click Continue.

    Review the application information.

    Review application information
  6. On the Review page, confirm that the settings are correct, and then click Finish.

    AWS Elastic Beanstalk will launch the TVM. Once the TVM is up and running, configure it using the instructions in the next section.

Configure the TVM for your application

  1. In the AWS Management Console go to the AWS Elastic Beanstalk page.

    Edit/Load Configuration
  2. Click Actions, and then click Edit/Load Configuration.

  3. In the Edit Configuration dialog box, click the Container tab, and then scroll down to the Environment Properties section.

    Environment Properties
  4. In the AWS_ACCESS_KEY_ID and AWS_SECRET_KEY boxes, type the access key and secret key, respectively, that you obtained when you created the IAM user, and then click Apply Changes.

  5. In the PARAM1 box, type an application name to reflect the name of your mobile application. This value must be the same as the APP_NAME definition used in the TVMIdentity sample.

Run the TVM Mobile Samples

The AWS SDK for Android and the AWS SDK for iOS contain sample mobile client applications that demonstrate using the TVM in a typical application. For information about running the sample applications, see the SDK for the appropriate mobile platform.

Managing the TVM

Secure Sockets Layer (SSL)

For additional security, we recommend that you run the TVM using Secure Sockets Layer (SSL). To configure your TVM installation to use SSL:

  1. Obtain an SSL certificate. You must ensure that the certification authority that you use to sign your SSL certificate is one that is recognized as valid by your mobile operating system.

  2. Download and install the IAM command line tools. See IAM command line tools.

  3. Upload the SSL certificate using the iam-servercertupload command. The result of this command will give you an IAM ARN for your certificate. See iam-serverupload.
  4. Go to the AWS Elastic Beanstalk console to enable SSL support. Select a running environment and under Actions -> Edit Config -> Load Balancers, set the HTTPS port to either 443 or 8443 and then fill in the SSL Certificate Id with the ARN from the command executed above. See Configuring Elastic Load Balancing.

Once your configuration deployment finishes, you will have an AWS Elastic Beanstalk Environment whose ELB is using server-side HTTPS.

Resources

For more information about policies, please refer to the following documents:

©2014, Amazon Web Services, Inc. or its affiliates. All rights reserved.