How To: Setting up SSH Key Pairs

To set up a SFTP integration, you'll need to create a SSH key pair. This is to ensure that the SFTP connection via your client/HRIS is unique and secure.

A SSH key pair is a pair of unique keys that are generated by you and saved on your computer. There's a private key which should only be used by you (or very carefully within your own organization), and there's a public key which can safely be shared outside your organization. Groundswell's HRIS feed uses the combination of the two keys to verify the security of the connection.

Step 1: Check command line tools

First, check that you have the command line tools you need to generate openSSH keys:

If you're using a Mac OS:

• command + spacebar to search
• type 'terminal' which opens the native command line tool

If you're using a Windows OS:

• Select the Start button
• Type 'cmd' into search bar
• Select 'Command Prompt' from the list

What if I don't have a command line tool?

There are free, opensource key generator apps available to download. A commonly-used tool for generating SSH Key Pairs for Windows is PuTTYgen.

Step 2: Generate the key pair

Run the command `ssh-keygen -t rsa -b 2048` to generate a new key pair.

The -t switch specifies the type of key to generate - we require RSA. The -b switch specifies the key size - 2048 is the lowest acceptable.

When prompted, enter a file path and filename to save the new key pair to, for example `users/firstname.lastname/department-key-pair/[filename]`. We recommend you create a new folder to save your key pair to so that you don't overwrite any existing key pairs you may have saved.

You may be asked for a passphrase. It's a good idea to set (and keep a record of) a passphrase if you want to, but it's not required.

You can now navigate to the file in which your keys are saved, and:

• Copy the public key to Groundswell's HRIS SFTP feed setup page.
• Copy the private key to your HRIS or SFTP client setup side.

What if my computer is not set up to accept this command?

The `ssh-keygen` or `puttygen` apps can be downloaded for free with a search online.

NOTE: Be wary of sharing your private key. Don't send it anywhere via email, text or through any other insecure means. Multiple key pairs can be generated so you can choose to have a private key per person/SFTP connection.

Helpful Links

• Example of how to generate SSH key pairs in a Mac environment
• Example of how to generate SSH key pairs in a Windows environment

Uploading employee data files using the SFTP connection

Using the hostname and username provided on the Groundswell HRIS SFTP feed setup page along with your Private Key generated above, you’ll now be able to set the connection with your SFTP client, and upload employee data files.

Most SFTP clients will require the following information to set a connection:

• Protocol: SFTP
• Logon Type: Key File
• Host/Hostname: [Found on the Groundswell HRIS SFTP feed set up page after the SSH key has been entered]
• Username: [Found on the Groundswell HRIS SFTP feed set up page after the SSH key has been entered]

Make sure the hostname and username you use to set up your SFTP client are copied directly from the Groundswell HRIS SFTP feed setup page. Both are case-sensitive.

If required by your SFTP client, you may specify `/` as the upload directory

Tips for resolving issues with the SFTP connection:

"Connection refused" error

You may receive a "connection refused" error when setting up an SFTP client. A possibility is because your organization has an internal Firewall (either a local or network firewall) that's blocking the SFTP connection.

If this is the case, your firewall needs to be configured to allow outbound access via the hostname sftp.groundswell.io (NOT bound to a specific IP address: the IP will change) on TCP Port 22.

Make sure the hostname and username you use to set up your SFTP client are copied directly from the Groundswell HRIS SFTP feed setup page. Both are case-sensitive.