Authentication

Steps for first time access

Access to the command shell of mini compute cluster is only available via SSH keys (see here for an explanation about SSH key based authentication). On the other hand, access to web services (JupyterHub, ...) is made via username/password authentication.

Firts-time access to mc2 involves execution of the following tasks (sequentially):

  1. Generate and install SSH keys on the computer from which you want to access mc2;

  2. Request SSH key registration by sending your public key to your supervisor via email, along with some basic info which will allow us to verify your identity:

    • Full name
    • Email address
    • Mobile number
    • Username (case sensitive, start with a letter, followed by letters, numbers, "-", "_", or ".")

    You will receive a confirmation that your key has been registered in the system;

  3. Make your first login to mc2 (for instance using the ssh command)

  4. Setup a strong password for web access.

Below you will find detailed instructions for each of the these steps.

1. Generating and installing SSH keys

Here is how it works. You generate a public key and a matching private key. They are stored in separate files. The private key file acts as a password and should be kept safe. With that I mean:

The private key belongs the client machine (your laptop or personal computer), it should not be duplicated/copied, and under no circumstance should leave from there. You may however own severak key pairs, one pair for each client machine.

However, the public key (which acts as a lock), should be copied to the target systems that you connect to regularly. The administrator of the target server will place your public key on a special place, so that when you try to log in, the keys are verified against each other, and if they match, access is granted.

mc2 accepts Ed25519 keys. They are an EdDSA implementation using the Twisted Edwards curve (elliptic curve cryptography) that offers higher security with faster performance compared to DSA or ECDSA.

To generate a SSH key pair, first make sure that you have a .ssh folder in your home space:

[user@client]$ stat ~/.ssh

If the result is something like stat: cannot statx '~/.ssh': No such file or directory, you have to create the .ssh folder:

[user@client]$ mkdir ~/.ssh

Then use the command below to create your keys. You may replace user@mylaptop and id_ed25519_mylaptop with more suitable alternatives (see below for further details):

[user@client]$ ssh-keygen -t ed25519 -f $HOME/.ssh/id_ed25519_mylaptop -C "user@mylaptop"
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase): [hit Enter key]
Enter same passphrase again: [hit Enter key again]
Your identification has been saved in id_ed25519_mylaptop
Your public key has been saved in id_ed25519_mylaptop.pub
The key fingerprint is:
SHA256:jg2xD3gCTrHtfuIEZncc29UmPwHHm88MOIsco/RTfQg user@mylaptop
The key's randomart image is:
+--[ED25519 256]--+
|  .       ...    |
|   +      E+.    |
|  + . o   o+++   |
| o o o.*o.++*..  |
|  = =.O+S= oo*   |
| o + +.B= .  .+  |
|    + o +.       |
|   o o           |
|    .            |
+----[SHA256]-----+

Importantly, we hitted the Enter-key (twice) when a passphrase was asked, effectively making our login passwordless.

The comment in the command line "user@mylaptop", is simply an identifying label which will help you and the person responsible for the server to find the owner (user) and computer (mylaptop) to which the key belongs.

According to the above, your private (id_ed25519_mylaptop) and public (id_ed25519_mylaptop.pub) keys are saved in the ~/.ssh folder. This is also the default location where your SSH client will look for a private key when trying to connect to a remote server like mc2. If the folder is not found, the keys will be saved on your home space. You can also change the name of the keys to best suit your linkings.

To finish, secure your SSH folder and keys:

[user@client]$ chmod 700 ~/.ssh
[user@client]$ chmod 600 ~/.ssh/id_ed25519_mylaptop
[user@client]$ chmod 644 ~/.ssh/id_ed25519_mylaptop.pub

1.1. Key generation for Windows Powershell users

An authentication key pair can also be generated on Windows machines. Windows added the OpenSSH client to Windows 10 several years ago. You can use PowerShell to ssh to mc2. Open a PowerShell Window. Then enter into the .ssh folder in your home space (create that directory if necessary),

C:\> cd $home\.ssh

Execute the following command as the user you plan to use for connecting to mc2. 

C:\> ssh-keygen -t ed25519 -f id_ed25519_mylaptop -C "user@mylaptop"

Like in a linux OS, hit the Enter key twice to avoid having to type a password during authentication.

Your public key is stored by default in C:\Users\<username>\.ssh\id_ed25519_mylaptop.pub. Provide this key when requesting access to mc2.

1.2. Key generation for Windows PuTTY users

Install PuTTY client (download the software from the official PuTTY web page).

Launch the application PuTTYgen and in the key Parameters area select the EdDSA, ensuring that the Curve to use for generating this key is Ed25519 (255 bits).

Select Ed25519 generation algorithm

Click on the Generate button to generate your SSH key pair and move your mouse in the empty area of the window to provide some randomness to the generation process.

Generate SSH key pair

Save the public and private keys in a secure location:

  • PuTTY private key - C:\Users\<username>\.ssh\id_ed25519_mylaptop.ppk
  • PuTTY public key - C:\Users\<username>\.ssh\id_ed25519_mylaptop.puttypub

Save SSH key pair

So far, we were able to create SSH keys in a native PuTTY format. The public key should be placed on the remote server, and since the SSH service of mc2 is based on OpenSSH, the key will have to be converted to OpenSSH format.

Copy the text in the upper box labelled "Public key for pasting into OpenSSH authorized_keys file", paste it into an empty text file, and save it as id_ed25519_mylaptop.pub next to the other two keys:

  • OpenSSH public key - C:\Users\<username>\.ssh\id_ed25519_mylaptop.pub

The id_ed25519_mylaptop.pub file is your public key in OpenSSH format. Provide this key when requesting access to mc2 (and never send the private key).

Mind that the above only describes how to setup a pair of keys. You should now move to step 2 to (request the registration of the keys).

After having the keys registered in mini compute cluster, you will have to setup a PuTTY connection to mc2.ua.pt using those keys (step 3).

2. Request SSH key registration

If you are setting up your account for the first time, you should request the registration of your SSH keys. Attach your public key (id_ed25519_mylaptop.pub file) to an email and send it off to your superviser along with:

  • Full name
  • Email address
  • Mobile number
  • Username

You will be contacted when your key is registered. This will be a human-contact, and will allow us to confirm your identity.

3. First login to mc2

Proceed as indicated below, only after receiving an indication that your keys have been registered.

If you are a Linux/macOS/Powershell user, you simply have to open a terminal window and type:

[user@localhost]$ ssh -i ~/.ssh/id_ed25519_mylaptop <username>@mc2.ua.pt

where the -i option points to your private key, and <username> is your chosen user name on mc2.

On the first connection, you will be asked whether you trust and want to continue connecting to mc2.ua.pt (which your SSH client does not recognise yet):

The authenticity of host 'mc2.ua.pt (192.128.234.111)' can't be established.
ED25519 key fingerprint is SHA256:P3luN/z+V0k4RaOCWZSNQLS80sgOtkHovRiWVThepbk.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Simply answer the question with the fingerprint SHA256:P3lu...epbk (NOTE: do not include the trailing dot .) and hit the Enter key. You can copy+paste the whole string. Essentially, the fingerprint is derived from the server's encryption key pair, assuring that you are really connecting to the right place (and not sending your key to somewhere that you should not).

You should finally land on your home space of mc2 and proceed immediately to setting up a strong password in Step 4.

3.1. Setup a connection to mc2 using PuTTY

If you are a Windows/PuTTY user follow the steps below to set up a connection to mc2:

Launch PuTTY and create a Session profile for mc2.ua.pt. Most notably, you should enter the Host Name (mc2.ua.pt), Port number (22), and give a name to the session in the Saved Sessions text box (mc2).

Creat Session for mc2

Go to Connection > Data, and enter the user name that you want to use in the Auto-login username text box.

Setup username

Go to Connection > SSH > Auth > Credentials, and hit the browse button next to Private key file for authentication. Find and load your private key (C:\Users\<username>\.ssh\id_ed25519_mylaptop.ppk).

Setup private key

Go back to Session, make sure that there is a session name in the Saved Sessions text box (for example mc2), and finally click the Save button.

You are now ready to open your first SSH session to mc2 - Simply double-click the mc2 session in the Saved Sessions list, or select the session and hit the Open button.

On the first connection, you will be asked whether you trust and want to continue connecting to mc2.ua.pt (which SSH does not recognise yet). Read the first paragraphs of Step 3 First login to mc2 and follow the instructions about how to answer this question.

Once you are in, proceed immediately to setting up a strong password in Step 4.

4. Setup a strong password

Passwords on mc2 have to comply with a few quality requirements:

  • No more that 6 characters of an old password are allowed on a new one (if you are renewing your credentials);
  • They should have at least 12 characters;
  • Should contain at least one upper-case letter, one lower-case, one number, one special character (.:,&%$#@...);
  • It cannot resemble your name or your username.

Once you login for the first time, you will be asked to setup your password. Enter your secret twice:

New password: ***************** [Enter]
Retype new password: ***************** [Enter]

You are all set and ready to access both compute and web services. Test your credentials by visiting the JupyterHub web server and login.

Setup a SSH configuration file (optional)

Linux/macOS and powershell users will make their life easier by setting up a SSH configuration file. In there they can assign a short and handy alias to remote servers. For instance, users can define mc2 as an alias to mc2.ua.pt, as well as instruct SSH for the location of the private key. That way, when they want to connect to the server, all they have to do is to type ssh mc2 [Enter].

Below we describe a simple procedure to setup a SSH config file that defines an alias (mc2) to mini compute cluster:

Edit (or create if needed) the ~./ssh/config file on your local computer. Add the text below to configure an aliased connection to mini compute cluster:

Host mc2                                     # Host alias
    HostName=mc2.ua.pt                       # Hostname or IP address
    User=<username>                          # Username
    IdentityFile=~/.ssh/id_ed25519_mylaptop  # Private key

where <username> should be replaced by your user name. Save your configuration and test the connection to mc2 by issuing the following command:

[user@localhost]$ ssh mc2
[user@hn]$ ls -la
drwx------.  2 user user   14 Mar  2 14:12 .
drwx------. 27 root root   37 Mar  2 14:12 ..
-rw-r--r--.  1 user user  400 Jan 30 08:40 WELCOME

You can also use the mc2 alias on scp commands, for example:

[user@localhost]$ scp filename.txt mc2:tmp/myfolder

which is equivalent to:

[user@localhost]$ scp -i ~/.ssh/id_ed25519_mylaptop filename.txt username@mc2.ua.pt:tmp/myfolder