How do I generate a key pair for authentication using SSH?

Document created by Danny Haworth Employee on Aug 28, 2018Last modified by Adam Williams on Sep 18, 2018
Version 4Show Document
  • View in full screen mode
Bridge's Auto CSV feature automates user management between any HRIS, CRM or user management tool and Bridge. Through export tools or scripting, user data can be exported to a secure file transfer protocol (SFTP). The SFTP connection is accessed using key-based authentication. Once the file has been validated, users can set up a schedule to automatically sync learner data from the HRIS, CRM, or user management tool and Bridge.

 

Process

The following simple steps are required to set up public key authentication (for SSH):

  1. Key pair is created by the end user.
  2. Private key stays with the user (and only there), while the public key is sent to the server.
  3. Server stores the public key.
  4. Server will now allow access to anyone who can prove they have the corresponding private key.

 

About key-based authentication

Key-based authentication provides a more secure way of logging into a server with SSH than using a username and password. Each SSH key pair includes two keys:

 

  • A public key that is copied to the SSH server(s). Anyone with a copy of the public key can encrypt data which can then only be read by the person who holds the corresponding private key. Once an SSH server receives a public key from a user and considers the key trustworthy, the server marks the key as authorized.
  • A private key that remains (only) with the user. The possession of this key is proof of the user's identity. Only a user in possession of a private key that corresponds to the public key at the server will be able to authenticate successfully. The private keys need to be stored and handled carefully, and no copies of the private key should be distributed. The private keys are called identity keys.

 

You can place the public key on any server, and then unlock it by connecting to it with a client that already has the private key. When the two match up, the system unlocks without the need for a password. You can increase security even more by protecting the private key with a passphrase.

 

Step one: Generate a key pair

Ask the customer to generate a key pair using the Generate a key pair steps below (external documentation to be created soon), and to send you the public key. Public keys have a file extension of .pub or .ppk or .pem. It is extremely important that the privacy of the private key is guarded carefully.

The customer should never share the private key to us or anyone outside their organization. It should be kept secret.

The keys will be generated using the RSA (Rivest–Shamir–Adleman) Algorithm. A key size of at least 2048 bits is required for RSA; 4096 bits is better. The key size or "bit-length" determines how easily the key can be exploited with a brute force attack.

 

Using a Mac computer (or Linux)

  1. Launch Terminal and enter the following command, but use your email address:
    ssh-keygen -t rsa -b 4096 -C "yourname@instructure.com"

    Note: this creates a key with a bit length of 4096. We require a minimum of 2048.

  2. Once you have entered the ssh-keygen command, you will get a few more questions. First, you'll be asked where to save the key pair.
    Enter file in which to save the key(/Users/yourname/.ssh/id_rsa): 

    Press enter here to save the file in your home directory.

  3. Next, you'll be asked to enter a passphrase.
    Enter passphrase (empty for no passphrase):

    It's up to you whether you want to use a passphrase. Entering a passphrase does have its benefits: the security of a key, no matter how encrypted, still depends on the fact that it is not visible to anyone else. Should a passphrase-protected private key fall into an unauthorized users possession, they will be unable to log in to its associated accounts until they figure out the passphrase, buying the hacked user some extra time. The only downside, of course, to having a passphrase, is then having to type it in each time you use the key pair. If you type a passphrase, you'll be asked to re-enter it.

    Enter same passphrase again:

    Re-type your passphrase.

    Remember this passphrase. You will need it later.

     

  4. You'll see some output that looks like this:
    Your identification has been saved in /Users/yourname/.ssh/id_rsa.
    Your public key has been saved in /Users/yourname/.ssh/id_rsa.pub.
    The key fingerprint is:
    SHA256:iinGBiG9Bq/5GeyaOvE8zKfZXe6gx9glCP+3UZlxjYQ yourname@instructure.com
    The key's randomart image is:
    +---[RSA 4096]----+
    |           ..    |
    | .        E. o   |
    |+ .       . o .  |
    |.+..       =     |
    |. +o .  S +      |
    |.B  oo....       |
    |o*B o=ooo        |
    |.***oo=+..       |
    |=o*+o..o+.       |
    +----[SHA256]-----+

    The public key is now located in /Users/yourname/.ssh/id_rsa.pub. The private key (identification) is now located in /Users/yourname/.ssh/id_rsa.

  5. Once the key pair is generated, the public key will be sent to Operations (Ops) so they can place it on the SFTP server. Close the Terminal program and go to the Finder. From the Finder menu, either click Go > Go to Folder... or use the keyboard shortcut ⇧⌘G and enter ~/.ssh as the folder. This directory contains the key pair. You will attach the public key to the JIRA issue you create later.

 

Using a Windows Computer

The consensus is to use a free and open source Windows application called PuTTY to create a key pair. Then follow the instructions in this documentation (on an external site).

 

Step two: Send the public key to Bridge

Email the public key to your Bridge Customer Success Manager (CSM) or directly to your Bridge Implementations Consultant (IC).

Attachments

    Outcomes