AWS Transfer for SFTP

2019/03/27 - AWS Transfer for SFTP - 4 updated api methods

Changes  This release adds PrivateLink support to your AWS SFTP server endpoint, enabling the customer to access their SFTP server within a VPC, without having to traverse the internet. Customers can now can create a server and specify an option whether they want the endpoint to be hosted as public or in their VPC, and with the in VPC option, SFTP clients and users can access the server only from the customer's VPC or from their on-premises environments using DX or VPN. This release also relaxes the SFTP user name requirements to allow underscores and hyphens.

CreateServer (updated) Link ¶
Changes (request)
{'EndpointDetails': {'VpcEndpointId': 'string'},
 'EndpointType': 'PUBLIC | VPC_ENDPOINT'}

Instantiates an autoscaling virtual server based on Secure File Transfer Protocol (SFTP) in AWS. The call returns the ServerId property assigned by the service to the newly created server. Reference this ServerId property when you make updates to your server, or work with users.

The response returns the ServerId value for the newly created server.

See also: AWS API Documentation

Request Syntax

client.create_server(
    EndpointDetails={
        'VpcEndpointId': 'string'
    },
    EndpointType='PUBLIC'|'VPC_ENDPOINT',
    IdentityProviderDetails={
        'Url': 'string',
        'InvocationRole': 'string'
    },
    IdentityProviderType='SERVICE_MANAGED'|'API_GATEWAY',
    LoggingRole='string',
    Tags=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
)
type EndpointDetails

dict

param EndpointDetails
  • VpcEndpointId (string) --

type EndpointType

string

param EndpointType

type IdentityProviderDetails

dict

param IdentityProviderDetails

An array containing all of the information required to call a customer-supplied authentication API. This parameter is not required when the IdentityProviderType value of server that is created uses the SERVICE_MANAGED authentication method.

  • Url (string) --

    The IdentityProviderDetail parameter contains the location of the service endpoint used to authenticate users.

  • InvocationRole (string) --

    The Role parameter provides the type of InvocationRole used to authenticate the user account.

type IdentityProviderType

string

param IdentityProviderType

The mode of authentication enabled for this service. The default value is SERVICE_MANAGED , which allows you to store and access SFTP user credentials within the service. An IdentityProviderType value of API_GATEWAY indicates that user authentication requires a call to an API Gateway endpoint URL provided by you to integrate an identity provider of your choice.

type LoggingRole

string

param LoggingRole

A value that allows the service to write your SFTP users' activity to your Amazon CloudWatch logs for monitoring and auditing purposes.

type Tags

list

param Tags

Key-value pairs that can be used to group and search for servers.

  • (dict) --

    Creates a key-value pair for a specific resource. Tags are metadata that you can use to search for and group a resource for various purposes. You can apply tags to servers, users, and roles. A tag key can take more than one value. For example, to group servers for accounting purposes, you might create a tag called Group and assign the values Research and Accounting to that group.

    • Key (string) -- [REQUIRED]

      The name assigned to the tag that you create.

    • Value (string) -- [REQUIRED]

      This property contains one or more values that you assigned to the key name you create.

rtype

dict

returns

Response Syntax

{
    'ServerId': 'string'
}

Response Structure

  • (dict) --

    • ServerId (string) --

      The service-assigned ID of the SFTP server that is created.

DescribeServer (updated) Link ¶
Changes (response)
{'Server': {'EndpointDetails': {'VpcEndpointId': 'string'},
            'EndpointType': 'PUBLIC | VPC_ENDPOINT'}}

Describes the server that you specify by passing the ServerId parameter.

The response contains a description of the server's properties.

See also: AWS API Documentation

Request Syntax

client.describe_server(
    ServerId='string'
)
type ServerId

string

param ServerId

[REQUIRED]

A system-assigned unique identifier for an SFTP server.

rtype

dict

returns

Response Syntax

{
    'Server': {
        'Arn': 'string',
        'EndpointDetails': {
            'VpcEndpointId': 'string'
        },
        'EndpointType': 'PUBLIC'|'VPC_ENDPOINT',
        'IdentityProviderDetails': {
            'Url': 'string',
            'InvocationRole': 'string'
        },
        'IdentityProviderType': 'SERVICE_MANAGED'|'API_GATEWAY',
        'LoggingRole': 'string',
        'ServerId': 'string',
        'State': 'OFFLINE'|'ONLINE'|'STARTING'|'STOPPING'|'START_FAILED'|'STOP_FAILED',
        'Tags': [
            {
                'Key': 'string',
                'Value': 'string'
            },
        ],
        'UserCount': 123
    }
}

Response Structure

  • (dict) --

    • Server (dict) --

      An array containing the properties of the server with the ServerID you specified.

      • Arn (string) --

        Specifies the unique Amazon Resource Name (ARN) for the server to be described.

      • EndpointDetails (dict) --

        • VpcEndpointId (string) --

      • EndpointType (string) --

      • IdentityProviderDetails (dict) --

        Specifies information to call a customer-supplied authentication API. This field is not populated when the IdentityProviderType of the server is SERVICE_MANAGED >.

        • Url (string) --

          The IdentityProviderDetail parameter contains the location of the service endpoint used to authenticate users.

        • InvocationRole (string) --

          The Role parameter provides the type of InvocationRole used to authenticate the user account.

      • IdentityProviderType (string) --

        This property defines the mode of authentication method enabled for this service. A value of SERVICE_MANAGED , means that you are using this Server to store and access SFTP user credentials within the service. A value of API_GATEWAY indicates that you have integrated an API Gateway endpoint that will be invoked for authenticating your user into the service.

      • LoggingRole (string) --

        This property is an AWS Identity and Access Management (IAM) entity that allows the server to turn on Amazon CloudWatch logging for Amazon S3 events. When set, user activity can be view in your CloudWatch logs.

      • ServerId (string) --

        This property is a unique system assigned identifier for the SFTP server that you instantiate.

      • State (string) --

        The condition of the SFTP server for the server that was described. A value of ONLINE indicates that the server can accept jobs and transfer files. A State value of OFFLINE means that the server cannot perform file transfer operations.

        The states of STARTING and STOPPING indicated that the server is in an intermediate state, either not fully able to respond, or not fully offline. The values of START_FAILED or STOP_FAILED can indicate an error condition.

      • Tags (list) --

        This property contains the key-value pairs that you can use to search for and group servers that were assigned to the server that was described.

        • (dict) --

          Creates a key-value pair for a specific resource. Tags are metadata that you can use to search for and group a resource for various purposes. You can apply tags to servers, users, and roles. A tag key can take more than one value. For example, to group servers for accounting purposes, you might create a tag called Group and assign the values Research and Accounting to that group.

          • Key (string) --

            The name assigned to the tag that you create.

          • Value (string) --

            This property contains one or more values that you assigned to the key name you create.

      • UserCount (integer) --

        The number of users that are assigned to the SFTP server you specified with the ServerId .

ListServers (updated) Link ¶
Changes (response)
{'Servers': {'EndpointType': 'PUBLIC | VPC_ENDPOINT'}}

Lists the Secure File Transfer Protocol (SFTP) servers that are associated with your AWS account.

See also: AWS API Documentation

Request Syntax

client.list_servers(
    MaxResults=123,
    NextToken='string'
)
type MaxResults

integer

param MaxResults

Specifies the number of servers to return as a response to the ListServers query.

type NextToken

string

param NextToken

When additional results are obtained from the ListServers command, a NextToken parameter is returned in the output. You can then pass the NextToken parameter in a subsequent command to continue listing additional servers.

rtype

dict

returns

Response Syntax

{
    'NextToken': 'string',
    'Servers': [
        {
            'Arn': 'string',
            'IdentityProviderType': 'SERVICE_MANAGED'|'API_GATEWAY',
            'EndpointType': 'PUBLIC'|'VPC_ENDPOINT',
            'LoggingRole': 'string',
            'ServerId': 'string',
            'State': 'OFFLINE'|'ONLINE'|'STARTING'|'STOPPING'|'START_FAILED'|'STOP_FAILED',
            'UserCount': 123
        },
    ]
}

Response Structure

  • (dict) --

    • NextToken (string) --

      When you can get additional results from the ListServers operation, a NextToken parameter is returned in the output. In a following command, you can pass in the NextToken parameter to continue listing additional servers.

    • Servers (list) --

      An array of servers that were listed.

      • (dict) --

        Returns properties of the server that was specified.

        • Arn (string) --

          The unique Amazon Resource Name (ARN) for the server to be listed.

        • IdentityProviderType (string) --

          The authentication method used to validate a user for the server that was specified. listed. This can include Secure Shell (SSH), user name and password combinations, or your own custom authentication method. Valid values include SERVICE_MANAGED or API_GATEWAY .

        • EndpointType (string) --

        • LoggingRole (string) --

          The AWS Identity and Access Management entity that allows the server to turn on Amazon CloudWatch logging.

        • ServerId (string) --

          This value is the unique system assigned identifier for the SFTP servers that were listed.

        • State (string) --

          This property describes the condition of the SFTP server for the server that was described. A value of ONLINE > indicates that the server can accept jobs and transfer files. A State value of OFFLINE means that the server cannot perform file transfer operations.

          The states of STARTING and STOPPING indicated that the server is in an intermediate state, either not fully able to respond, or not fully offline. The values of START_FAILED or STOP_FAILED can indicate an error condition.

        • UserCount (integer) --

          This property is a numeric value that indicates the number of users that are assigned to the SFTP server you specified with the ServerId .

UpdateServer (updated) Link ¶
Changes (request)
{'EndpointDetails': {'VpcEndpointId': 'string'},
 'EndpointType': 'PUBLIC | VPC_ENDPOINT'}

Updates the server properties after that server has been created.

The UpdateServer call returns the ServerId of the Secure File Transfer Protocol (SFTP) server you updated.

See also: AWS API Documentation

Request Syntax

client.update_server(
    EndpointDetails={
        'VpcEndpointId': 'string'
    },
    EndpointType='PUBLIC'|'VPC_ENDPOINT',
    IdentityProviderDetails={
        'Url': 'string',
        'InvocationRole': 'string'
    },
    LoggingRole='string',
    ServerId='string'
)
type EndpointDetails

dict

param EndpointDetails
  • VpcEndpointId (string) --

type EndpointType

string

param EndpointType

type IdentityProviderDetails

dict

param IdentityProviderDetails

This response parameter is an array containing all of the information required to call a customer's authentication API method.

  • Url (string) --

    The IdentityProviderDetail parameter contains the location of the service endpoint used to authenticate users.

  • InvocationRole (string) --

    The Role parameter provides the type of InvocationRole used to authenticate the user account.

type LoggingRole

string

param LoggingRole

Changes the AWS Identity and Access Management (IAM) role that allows Amazon S3 events to be logged in Amazon CloudWatch, turning logging on or off.

type ServerId

string

param ServerId

[REQUIRED]

A system-assigned unique identifier for an SFTP server instance that the user account is assigned to.

rtype

dict

returns

Response Syntax

{
    'ServerId': 'string'
}

Response Structure

  • (dict) --

    • ServerId (string) --

      A system-assigned unique identifier for an SFTP server that the user account is assigned to.