SFTP (embedded) transport configuration

A community can use an embedded Secure FTP (SFTP) server to receive messages from partners or as an application transport.

When you elect to set up an embedded SFTP transport for a community, the wizard asks whether you want to:

• Use a previously defined embedded SFTP server (if available)
• Define a new embedded SFTP server

If you choose to use a previously defined embedded SFTP server, the wizard prompts for the user account name. You can choose an existing account or define a new one. If you choose an existing account, you must choose a subdirectory within that account’s home directory that is not assigned to any other exchange point.

If you choose to define a new embedded SFTP server, the wizard prompts for a server name and port number. The wizard then asks for a user name and password for the new server. If the default selections already are in use, you must use another user name and password.

When you create an embedded SFTP server, Activator also generates an RSA public-private key pair for the server. The key pair has no visibility in your user interface. But when you export your community profile as a partner profile, the server’s public key is exported with it. When your B2Bi, Interchange, or Activator partner imports the partner profile, the public key can be displayed. Your partners use the public key to authenticate the embedded server upon connecting.

Related topics:

• Types of embedded SFTP servers
• SFTP user accounts
• Firewalls and embedded SFTP
• Embedded SFTP fields
• Public-private key and password authentication
• Modify an SFTP (external) pickup

Types of embedded SFTP servers

There are two types of embedded SFTP servers:

• Trading servers are used for receiving messages from partners. In the simplest case, a partner’s SFTP client connects to your embedded server to PUT a message for your community to pick up. There also is a more complex configuration — hosted embedded SFTP — where your community lets partners connect to your embedded server to GET messages.
• Application servers are used for retrieving messages from, or delivering messages to, back-end systems.

The exchange wizard enforces the usage context for embedded SFTP servers. For example, the wizard does not let you define a new embedded SFTP trading server when the usage requires an application server.

To configure hosted partner accounts for embedded SFTP servers, you must have a specific license permission. Your license.xml file must enable the permission: hostedPartnerSftpAccounts. Without this permission you can configure a partner to send messages via an external SFTP server, but not via an embedded server. This permission does not affect back-end application accounts; there is no restriction on adding hosted accounts from which a back-end system can pick up messages.

Related topics:

• SFTP user accounts
• Firewalls and embedded SFTP
• Embedded SFTP fields

SFTP user accounts

When you add an exchange that uses an embedded SFTP server, you must specify an SFTP user account. You can choose an existing account or define a new one. Activator internally associates user accounts with home directories for sending (PUT) or retrieving (GET) messages. There are three types of accounts.

User names are shared by all trading servers. This enables a load balancer to send a request to any trading server. However, user names associated with application servers are not related to user names shared by trading servers. For example, the user name user1 on the trading side is completely different from user1 on the application side.

The following topics describe each account type.

Community SFTP accounts

Community SFTP accounts are associated only with community pickups for receiving messages from partners.

Partners can perform PUT operations to community accounts associated with trading pickups, but not GET operations. This is to prevent partners from accessing each others’ files.

Partners can drop packaged messages directly into the home directory of a community account. As a result, community SFTP accounts can be referred to as shared accounts.

When a community profile is exported as a partner profile file to be imported by partners, the community SFTP account is exported with the pickup exchange.

To avoid file name collisions you can use the Message attributes tab on the pickup exchange to specify subdirectories where partners can place files based on the sender routing ID. This also allows identifying the sender when binary files are dropped off. For example, the following subdirectory scheme could be used for two partners (p1 and p2) to drop off files for community c1:

If a partner-specific subdirectory scheme is used, the partner must manually specify the subdirectory after importing the community's profile. If there is only one community and it has only one routing ID, the second directory level is unnecessary.

Partner SFTP accounts

Partner SFTP accounts are used only for trading. The accounts typically are used for outbound trading via deliveries set up for partners. But the same accounts can be used for inbound trading via pickups set up in communities. In this case they can be used in lieu of, or in addition to, community accounts.

The user interface segregates the two purposes. When adding a partner embedded SFTP delivery, the wizard suggests the /mailbox subdirectory under the home directory. This is where Activator delivers messages for the partner to pick up. This can be thought of as a hosted partner delivery exchange, since the partner is picking up messages from your server. If the same partner account is added to an existing community pickup exchange, the system suggests the home directory (/). This ensures outbound and inbound messages are not confused.

For hosted partner delivery exchanges, you must inform the partner performing the GET operation of the SFTP host name or IP address, the port number, the path, and the server user name and password. If your partner uses Interchange or Activator, the partner must add a community pickup exchange for receiving messages via an external SFTP server (see SFTP (external) transport configuration for configuration information). The default value of the pickup directory must be changed to mailbox or whatever directory you specified. Also, clear the option for use temporary files.

Partner SFTP accounts cannot be used by back-end application exchanges.

Outbound trading example

In this example, an administrator adds an outbound hosted SFTP delivery exchange for partner1. The administrator associates the user account p1. The user interface suggests /mailbox as the subdirectory where the partner retrieves (GET) messages.

Optionally, for binary trading the Message attributes tab can specify subdirectories where Activator delivers files based on the routing ID of the sending community. For instance:

Since partner SFTP accounts are partner-specific, message attribute mapping only is needed for identifying the community if there is more than one possible sending community or there is no other way to identify the community. This would be the case when you intend to trade binary files, which have no packaging or internal identifying information.

Message attribute mapping also can be used to sort messages into arbitrary subdirectories based on other metadata besides the sender or receiver. For example, an inline process could assign metadata items to outbound messages that would cause them to be sorted into subdirectories based on mappings specified on the Message attributes tab.

Inbound trading example

This example is for traders who do not want to upload files to a shared community SFTP account.

An administrator adds or selects a community-embedded SFTP trading pickup. The trading pickup can be one already associated with a community SFTP account like c1. The exchange provides an anchor for one or more partner SFTP accounts where files may be dropped off for the community.

The administrator selects the Directories tab on the community trading pickup. There the administrator can add a new partner account or select an existing one.

The user interface suggests / as the home directory for the SFTP account where partners can drop files for the community. In contrast, /mailbox is the suggested directory when a hosted delivery exchange is added for a partner to GET messages.

Application SFTP accounts

Application SFTP accounts are associated only with application pickups and deliveries for retrieving messages from, or delivering messages to, back-end systems. Application pickup exchanges are not tied to a particular community.

When you create an SFTP account you can choose to either use an existing account, a new account (with all fields empty), or to define one later.

The \out directory is suggested as the pickup subdirectory name and \in is suggested as the delivery subdirectory name. You can change the user names and subdirectories as long as the same combination of user name and subdirectory is not specified for two exchanges. This is true for all embedded SFTP exchanges.

Related topics:

• Types of embedded FTP servers
• Firewalls and embedded SFTP
• Embedded SFTP fields

Firewalls and embedded SFTP

If you have a corporate firewall and the computer running Activator also has a Windows firewall, turn off the Windows firewall. Ask the network administrator to open the control port for your embedded SFTP server (default is 4022) on the network firewall.

Related topics:

• Types of embedded SFTP servers
• SFTP user accounts
• Embedded SFTP fields

Embedded SFTP fields

When you add a new embedded SFTP server to a community, you complete the following fields in the exchange wizard.

Server fields

• Server name – Enter a name for the new embedded SFTP server. This can be any name pickup you want. You can select this server when setting up additional embedded SFTP delivery exchanges later.
• If this is the first server, the wizard suggests either the name Trading SFTP if the server is to be used for receiving messages from partners or Application SFTP if the server is to be used for exchanging messages with a back-end system.
• Port – The port number that listens for incoming SFTP connections. This is known as the control port. The wizard suggests a port not in use and displays a list of ports in use by Activator. You can use the suggested port or another.
• If this is the first server, the wizard suggests — if not already in use — 4022 for a trading server or 5022 for an application server. For security reasons, trading and integration servers must use different ports.

You must select one of the following authentication options:

• This server requires the SFTP client to authenticate using a password – Select to require your partner to submit a password to connect to your embedded SFTP server.
• This server requires the SFTP client to authenticate using a public/private key pair – Select to require your partner to use a private key to encrypt an authentication message and pass it to the server to decrypt with the matching public key. This process enables the server to verify the identity of the partner. Your partner must generate a private-public key pair and give you a file containing the public key.
• This server requires the SFTP client to authenticate using both a password and a public/private key pair –
  Select this option to require both a password and public/private key pair.
• This server allows the SFTP client to authenticate using either a password or a public/private key pair – Select this option to require either a password or a public/private key pair.

Click Next to continue the configuration.

User account fields

You have the following options for selecting a user account:

• Select an existing account from the drop-down list (if an account has been previously defined)
• Define a new account
• Define an account later

If you elect to define a new account, complete the fields for the authentication option you selected on the previous wizard page.

• User name – The user name to connect to the server. This field applies to both authentication options. Not only does your partner use this name to connect, but Activator creates a directory of the same name. This is the home directory for the SFTP account. It is where a partner sends messages to your community via SFTP. If you use the default location for the common directory, the directory is at <install directory>\common\data\ssh\users\trading. But if you are configuring a back-end application transport, the path is <install directory>\common\data\ssh\users\integration.

Password authentication

• Password – The password to connect to the server. Anonymous connections are not supported.
• Confirm password – Confirm the password.
• Transport user password policy – Select the password policy to assign to the user. See Manage password policies of transport users for more information.

Public key authentication

• Public key file – The path to the public key file. You must get this file from your partner, who generates a private-public key with some type of key-generation tool. The file can have an extension readable by simple text editors, such as .txt, .xml or .pub.
• Activator accepts a file containing a public key in the following format:
• Keytype EncodedKeyValue UserName
• where:
• Keytype must be one of the following values: ssh-rsa or ssh-dss
• EncodedKeyValue is a Base64 encoded string like this:
• AAAAB3NzaC1yc2EAAAABIwAAAIEAypVxTV0MRxv4LS3tVld0LX+YhQmbyBSjwGrKqpqyWYH
• Vrpv27Lri4oJ8KzeY2HSgiLGBqitVsQjnf65JYZxW0WSoXrCoh6Y1f7zJZszN8P+15wt3QH
• 0OcHerpdUp5LEfBgCaKRdaPTkgzhpDdMO87ZVFB8vam7fXEYuwUifUyfE=
• UserName is a value generated by the key tool (for example, pnuechte@ls0020). UserName is optional.

Click Next to continue the configuration.

Destination directory fields

• Enter a new path – This field enables you to associate the same embedded server and user account to multiple subdirectories. Each subdirectory can be used by a single partner to send messages to or receive messages from your community via SFTP. If you leave this field blank, the effective directory where a partner uploads or downloads messages is the top-level directory. For example:

  common\data\ssh\users\trading\<user account>

• If you add an amended path, the effective directory is the specified subdirectory. For example:

  common\data\ssh\users\trading\<user account>\<amended path>

• For the first trading server, the wizard suggests an amended path of mailbox for trading pickup. By default the home directory (/) is not used, but you can change this.
• For the first application server, the wizard suggests an amended path of in for application delivery or out for application pickup. By default the home directory (/) is not used, but you can change this.
• Activator keeps track of the embedded SFTP directory structure for you. Do not manually change any directories Activator creates for managing messages transported via embedded SFTP servers.

Click Next if you want to name the exchange. Otherwise, click Finish.

Related topics:

• Types of embedded SFTP servers
• SFTP user accounts
• Firewalls and embedded SFTP

Public-private key and password authentication

The following procedures together describe how to use public-private key authentication and password authentication for SFTP.

This procedure assumes:

• The local community and the remote partner both use Activator.
• Both parties use AS3 embedded SFTP. However, the steps for external SFTP are similar (see SFTP (external) transport configuration).
• The local community’s embedded SFTP server requires the SFTP client (the remote partner) to authenticate using a password.
• The remote partner’s embedded SFTP server requires the SFTP client (the local community) to authenticate using a public-private key pair.

The following procedures indicate the tasks performed by the local community and the remote trading partner.

Procedure 1: Local community exports a community profile for the remote trading partner

1. Use an external tool such as PuTTY-Gen to generate an OpenSSH public-private key pair. You cannot use Activator to generate the key. Export the public-private key pair in OpenSSH format.
2. In step 12 you give the public key in the key pair to your partner. Using your external tool, export the pubic key in SSH1 single-line format.
2. On the community summary page, click Certificates in the navigation graphic at the top.
3. Select the SSH keys tab on the Certificates page.
4. Click Add an SSH key to add to the community the public-private key pair generated in step 1.
5. Select the key as the default SSH key and click Save changes.
6. In the community, add an embedded SFTP pickup for receiving messages from a partner. Set up a user name and password for password authentication when adding the exchange.
7. Click the Embedded SFTP link of the exchange added in step 6 to open its maintenance page.
8. On the Advanced tab, select the option Process consumed messages using community delivery settings.
9. On the Directories tab, under Accounts owned by this community, be sure the user added in step 6 is the default user. This user and password are exported to the local community’s partner profile in step 12.
10. On the Embedded SFTP settings tab, click View settings for this embedded server.
11. On the server’s Settings tab, select the option This server requires the SFTP client to authenticate using a password. Click Save changes.
12. Export the community profile as a partner profile. Give the public key from step 1 and the profile file to the remote partner.

Procedure 2: Remote partner imports the community's profile and exports a profile for the community

1. Import the profile of the local community (exported in the previous procedure) as a partner profile in Activator of the remote partner. (The remote partner also uses Activator.)
2. Add an embedded SFTP trading pickup for receiving messages from a partner to the community of the remote partner.
   • Select public-private key pair authentication for the SFTP exchange.
   • Select Configure SFTP user account later.
3. Click the Embedded SFTP link of the exchange added in the previous step, to open its maintenance page.
4. On the Advanced tab, select the option Process consumed messages using community delivery settings.
5. On the Directories tab, click Add under Accounts owned by partners.
6. When prompted to pick a party, select the partner for the local community.
7. Click Create a new user.
   • Enter a user name. This user name will be used again in the next procedure.
   • Enter a password.
   • Select a transport user password policy (see Manage password policies of transport users).
   • Click Browse and locate the public key file provided by the local community in the imported profile.
   • Click Save.
8. Return to the maintenance page of the SFTP trading pickup for the community.
9. On the Embedded SFTP settings tab, click View settings for this embedded server.
10. On the server’s Settings tab, select the option This server requires the SFTP client to authenticate using a public/private key pair. Click Save changes.
11. Export the community profile of the remote partner as a partner profile. Give the profile file to the local community.

Procedure 3: Local community imports the trading partner's profile

1. Import the profile of the remote partner as a partner profile (exported in the previous procedure).
2. Open the partner that represents the remote trading partner. On the partner summary page click Application pickup on the navigation graphic at the top.
3. Click the link to open the maintenance page for the SFTP pickup.
4. On the SFTP settings tab:
   • Verify the Use public/private key pair authentication option is selected.
   • Add the user name from the previous procedure in the User name field. This is the user name the local community uses to connect to the remote partner's embedded SFTP server.
   • Click Save changes.

The partners now are configured to exchange messages.