AWS Transfer for SFTP
User Guide

Working with Identity Providers

You can integrate your existing identity provider into AWS SFTP by providing an Amazon API Gateway method with a RESTful interface. AWS SFTP invokes this method to authenticate your SFTP users.

The RESTful interface must contain a single method that authenticates and authorizes the users for access to Amazon S3. After the API method is configured, you attach this method to your SFTP server when creating a new server using the console or an AWS SFTP API operation.

Using Custom Identity Providers

API Gateway provides a secure way for you to create and provide APIs. API Gateway provides an HTTPS endpoint so that all incoming API calls are securely transmitted. API Gateway offers an authentication method named AWS_IAM, which gives you the same IAM-based authentication that AWS uses internally. If AWS_IAM is enabled, only callers with explicit permissions to invoke the customer's API reach their API Gateway method. For you to use AWS SFTP, callers must enable AWS Identity and Access Management (IAM) and provide an IAM role with permissions for AWS SFTP to invoke their API methods. For more details on the API Gateway service, see the API Gateway Developer Guide.

To use API Gateway for custom authentication

  1. Download the AWS CloudFormation template from the AWS website.

    This AWS SFTP AWS CloudFormation template creates a fully functional implementation that is backed by a prototype AWS Lambda function. Deploying this template is the easiest way to integrate a custom identity provider.

  2. Configure your SFTP server's API Gateway authentication method.

    After you load the template and create the method, go to the API Gateway console to implement your method body.

    The following illustration shows the template for this method. In this example, the method is backed by a Lambda function, but many other integration types are also possible.

  3. Test your method to make sure it can successfully authenticate valid users (and not authenticate invalid users).

    The following screenshot shows a successful test of a custom authentication method in API Gateway.

  4. Create your server, and choose Custom as the Identity provider type, as shown following.

  5. Enter the URL for the API Gateway endpoint you just created, and the IAM role that was created to provide access to the service to invoke this API Gateway.

Your API Gateway must implement a single method, with a resource path of /servers/serverId/users/username/config. The serverId and username come from the RESTful resource path.

If AWS SFTP attempts password authentication on behalf of your user, the service supplies a Password: header field. In the absence of a Password: header, it should be assumed that AWS SFTP is attempting public key authentication on behalf of your user to authenticate them.

This method should always return HTTP status 200. Any other HTTP status code denotes an error accessing the API.

The response body should be a JSON document of the following form.

{ "Role": "IAM role with configured S3 permissions", "PublicKeys": [ "ssh-rsa public-key1", "ssh-rsa public-key2" ], "Policy": "STS Assume role scope down policy", "HomeDirectory": "User's home directory" }

The Role field indicates that successful authentication occurred. When doing password authentication (that is, when a Password: header is supplied), the SSH public keys can be omitted. Also, the Policy and HomeDirectory fields are optional. When no home directory is provided, AWS SFTP defaults to root access for the Amazon S3 bucket. The role that you specify must have access to the HomeDirectory path. If the user doesn't exist or is not authorized for access to this server, the HTTP response body should be empty.