Setting up an Amazon API Gateway method as a custom identity provider - Amazon Transfer Family
PrerequisitesStep 1: Create a CloudFormation stackStep 2: Check the API Gateway method configuration for your serverStep 3: View the Transfer Family server detailsStep 4: Test that your user can connect to the serverStep 5: Test the SFTP connection and file transferStep 6: Limit access to the bucketUpdate Lambda if using Amazon EFS
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Setting up an Amazon API Gateway method as a custom identity provider

This tutorial illustrates how to set up an Amazon API Gateway method and use it as a custom identity provider to upload files to an Amazon Transfer Family server. This tutorial uses the Basic stack template, and other basic functionality as an example only.

Prerequisites

Before you create the Transfer Family resources in Amazon CloudFormation, create your storage and your user role.

To specify storage and create a user role

  1. Depending on which storage you are using, see the following documentation:

  2. To create a user role, see Create an IAM role and policy

You enter the details for your storage and your user role when you create your Amazon CloudFormation stack in the next section.

Step 1: Create a CloudFormation stack

To create an Amazon CloudFormation stack from the provided template

  1. Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

  2. Select Create stack, and choose With new resources (standard).

  3. In the Prerequisite - Prepare template pane, choose Template is ready.

  4. Copy this link, Basic stack template, and paste it into the Amazon S3 URL field.

  5. Click Next.

  6. Specify parameters, including a name for your stack. Be sure to do the following:

    • Replace the default values for UserName and UserPassword.

    • For UserHomeDirectory, enter the details for the storage (either an Amazon S3 bucket or an Amazon EFS filesystem) that you created earlier.

    • Replace the default UserRoleArn with the user role that you created earlier. The Amazon Identity and Access Management (IAM) role must have the appropriate permissions. For an example IAM role and bucket policy, see Step 6: Limit access to the bucket.

    • If you want to authenticate using a public key instead of a password, enter your public key in the UserPublicKey1 field. The first time that you connect to the server using SFTP, you then provide the private key instead of a password.

  7. Choose Next, and then choose Next again on the Configure stack options page.

  8. Review the details for the stack that you are creating, and then choose Create stack.

    Note

    At the bottom of the page, under Capabilities, you must acknowledge that Amazon CloudFormation might create IAM resources.

Step 2: Check the API Gateway method configuration for your server

Note

To improve security, you can configure a web application firewall. Amazon WAF is a web application firewall that lets you monitor the HTTP and HTTPS requests that are forwarded to an Amazon API Gateway. For details, see Add a web application firewall.

To check the API Gateway method configuration for your server and deploy it

  1. Open the API Gateway console at https://console.amazonaws.cn/apigateway/.

  2. Choose the Transfer Custom Identity Provider basic template API that the Amazon CloudFormation template generated.

  3. In the Resources pane, choose GET, and then choose Method Request.

  4. For Actions, choose Deploy API. For Deployment stage, choose prod, and then choose Deploy.

    After the API Gateway method is successfully deployed, view its performance in the Stage Editor section.

    Note

    Copy the Invoke URL address that appears at the top of the page. You will need it for the next step.

Step 3: View the Transfer Family server details

When you use the template to create an Amazon CloudFormation stack, a Transfer Family server is automatically created.

To view your Transfer Family server details

  1. Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

  2. Choose the stack that you created.

  3. Choose the Resources tab.

    Screen that shows the list of resources created during creation of the Amazon CloudFormation stack, with the details for the Transfer Family server highlighted.

    The server ARN is shown in the Physical ID column for the TransferServer row. The server ID is contained in the ARN, for example s-11112222333344445.

  4. Open the Amazon Transfer Family console at https://console.amazonaws.cn/transfer/, and on the Servers page, choose the new server.

    The server ID matches the ID displayed for the TransferServer resource in Amazon CloudFormation.

Step 4: Test that your user can connect to the server

To test that your user can connect to the server, using the Transfer Family console

  1. Open the Amazon Transfer Family console at https://console.amazonaws.cn/transfer/.

  2. On the Servers page, choose your new server, choose Actions, and then choose Test.

  3. Enter the text for your sign-in credentials into the Username field, and into the Password field. These are the values that you set when you deployed the Amazon CloudFormation stack.

  4. For Server Protocol, select SFTP, and for Source IP, enter 127.0.0.1.

  5. Choose Test.

    If user authentication succeeds, the test returns a StatusCode: 200 HTML response and a JSON object containing the details of the user's roles and permissions. For example:

    {
    "Response": "{\"Role\": \"arn:aws-cn:iam::123456789012:role/my-user-role\",\"HomeDirectory\": \"/${transfer:HomeBucket}/\"}",
    "StatusCode": 200,
    "Message": "",
    "Url": "https://1a2b3c4d5e.execute-api.us-east-2.amazonaws.com/prod/servers/s-1234abcd5678efgh0/users/myuser/config"
}

    If the test fails, add one of the API Gateway Amazon managed policies to the role that you are using for your API.

Step 5: Test the SFTP connection and file transfer

To test the SFTP connection

  1. On a Linux or macOS device, open a command terminal.

  2. Enter one of the following commands, depending on whether you are using a password or a key pair for authentication.

    • If you are using a password, enter this command:

      sftp -o PubkeyAuthentication=no myuser@server-ID.server.transfer.region-code.amazonaws.com

      When prompted, enter your password.

    • If you are using a key pair, enter this command:

      sftp -i private-key-file myuser@server-ID.server.transfer.region-code.amazonaws.com

    Note

    For these sftp commands, insert the code for the Amazon Web Services Region where your Transfer Family server is located. For example, if your server is in US East (Ohio), enter us-east-2.

  3. At the sftp> prompt, make sure that you can upload (put), download (get), and view directories and files (pwd and ls).

Step 6: Limit access to the bucket

You can limit who can access a specific Amazon S3 bucket. The following example shows the settings to use in your CloudFormation stack and in the policy that you select for your user.

In this example, we set the following parameters for the Amazon CloudFormation stack:

  • CreateServer: true

  • UserHomeDirectory: /amzn-s3-demo-bucket1

  • UserName: myuser

  • UserPassword: MySuperSecretPassword

    Important

    This is an example password. When you configure your API Gateway method, make sure that you enter a strong password.

  • UserPublicKey1: your-public-key

  • UserRoleArn: arn:aws-cn:iam::role-id:role/myuser-api-gateway-role

The UserPublicKey1 is a public key that you have generated as part of a public/private key pair.

The role-id is unique to the user role that you create. The policy attached to the myuser-api-gateway-role is the following: 

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws-cn:s3:::amzn-s3-demo-bucket1"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObjectAcl",
                "s3:GetObject",
                "s3:DeleteObjectVersion",
                "s3:DeleteObject",
                "s3:PutObjectAcl",
                "s3:GetObjectVersion"
            ],
            "Resource": "arn:aws-cn:s3:::amzn-s3-demo-bucket1/*"
        }
    ]
}

To connect to the server using SFTP, enter one of the following commands at the prompt.

  • If you are using a password to authenticate, run the following command:

    sftp -o PubkeyAuthentication=no myuser@transfer-server-ID.server.transfer.region-id.amazonaws.com

    When prompted, enter your password.

  • If you are using a key pair to authenticate, run the following command:

    sftp -i private-key-file myuser@transfer-server-ID.server.transfer.region-id.amazonaws.com

Note

For these sftp commands, use the ID for the Amazon Web Services Region where your Transfer Family server is located. For example, if your server is in US East (Ohio), use us-east-2.

At the sftp prompt, you are directed to your home directory, which you can view by running the pwd command. For example: 

sftp> pwd
Remote working directory: /amzn-s3-demo-bucket1

The user cannot view any directories above the home directory. For example: 

sftp> pwd
Remote working directory: /amzn-s3-demo-bucket1
sftp> cd ..
sftp> ls
Couldn't read directory: Permission denied

Update Lambda if using Amazon EFS

If you selected Amazon EFS as the storage option for your Transfer Family server, you need to edit the lambda function for your stack.

To add a Posix profile to your Lambda function

  1. Open the Lambda console at https://console.amazonaws.cn/lambda/.

  2. Select the Lambda function that you created earlier. The Lambda function has the format of stack-name-GetUserConfigLambda-lambda-identifier, where stack-name is the CloudFormation stack name and lambda-identifier is the identifier for the function.

  3. In the Code tab, select index.js to display the code for the function.

  4. In the response, add the following line between Policy and HomeDirectory:

    PosixProfile: {"Uid": uid-value, "Gid": gid-value},

    Where the uid-value and gid-value are integers, 0 or greater, that represent the User ID and Group ID respectively.

    For example, after you add the Posix profile, the response field might look like the following:

     response = {
      Role: 'arn:aws-cn:iam::123456789012:role/api-gateway-transfer-efs-role', // The user will be authenticated if and only if the Role field is not blank
      Policy: '', // Optional JSON blob to further restrict this user's permissions
      PosixProfile: {"Gid": 65534, "Uid": 65534},
      HomeDirectory: '/fs-fab2c234' // Not required, defaults to '/'
    };