When you connect to Platform.sh to use the CLI or interact with a deployed environment, you need to guard your connection against unauthorized access. Platform.sh helps by using Secure Shell (SSH) to provide a secure channel.

So you can securely log in to your deployed server to troubleshoot and read logs. And create a tunnel to export data through. And push changes to your Git repository. All secured through SSH.

There are three basic ways to authenticate with Platform.sh:

  • Through the CLI
    • The fastest and easiest method.
    • Supports multifactor authentication.
    • Automatically generates new certificates to keep your connection safe.
    • Necessary when using the CLI and when your organization has multifactor authentication set up.
  • Using SSH keys
    • Requires more setup on your part.
    • Represents only a single authentication method.
    • Requires you to regularly change the keys to maintain security.
    • Useful for checking out code as part of an automated process.
  • Using API tokens
    • Good for letting automation tools use the CLI.
    • Requires you to regularly change the tokens to maintain security.

Authenticate with the Platform.sh CLI 

To authenticate with the CLI:

  1. Install the Platform.sh CLI.
  2. Run platform login.
  3. In the open browser window, log in with your Platform.sh account credentials. (This webpage is encrypted with HTTPS [HTTP over TLS], making it secure.)
  4. Authorize the CLI to use your account.

A certificate gets stored in your local SSH configuration. The certificate is automatically cycled every hour for a new certificate as long as your session is active.

If you are inactive for an extended period, your certificate expires and you are asked to login again the next time you use a command that requires authentication.

You are now ready to run CLI commands and to connect to an environment.

Authenticate with SSH keys 

This process requires two keys:

  • A private key you must keep secret
  • A public key stored in your Platform.sh account

A key pair is valid for as long as you have access to the private key on the system from which you are connecting. If you have a key pair available, you are not prompted to login.

To keep connection secure, you need to regularly update the keys you use. A well-encrypted key is no substitute for regular key rotation.

If you used GitHub to sign up for your Platform.sh account, your public keys from GitHub are automatically synced to your Platform.sh account. So you can use them already with the CLI or to connect to a server.

Otherwise, you might be able to find existing keys or else you need to generate new keys.

Find your keys 

You may have already generated SSH keys before. Tech Republic has a guide to finding keys on different systems.

If you haven’t used SSH keys before or it’s been a while since you created the key, skip right to generating new keys.

A public key file has a name ending in .pub. It contains seemingly random lines of characters, like this example of a public RSA key (note the email address at the end, which wouldn’t be present in a private key):

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC2nDRLgPANWParTiaGIgySG+thTtnqFGI1tMWyqDdfvH+5hL91w2tK9PzaP+NJ5hA/cOyh30YRFb52Y64toU16Ko5K1mLqNFJajjWEI5Y4VukG6betrWfqdQ7XBr/s7nBuDOFQ5+eKbvug4rRSCSo8CsEI1eI0VNQkC9HJWYK28k7KurMdTN7X/Z/4vknM4/Rm2bnMk2idoORQgomeZS1p3GkG8dQs/c0j/b4H7azxnqdcCaR4ahbytX3d49BN0WwE84C+ItsnkCt1g5tVADPrab+Ywsm/FTnGY3cJKKdOAHt7Ls5lfpyyug2hNAFeiZF0MoCekjDZ2GH2xdFc7AX/ your_email_address@example.com

To find your public key file:

  1. Open a terminal.

  2. Run the following commands:

    $ cd ~/.ssh
    $ ls -a
    

If you find a file ending in .pub, copy the location and add it to your Platform.sh account.

If you don’t find an existing key, generate new keys.

Add an SSH key to your Platform account 

Once you have the location of your public key, add it to your Platform.sh account.

If you’re logged in using the Platform.sh CLI, in a terminal run the following command (replacing PATH_TO_YOUR_KEY with the location of your public key):

platform ssh-key:add 'PATH_TO_YOUR_KEY`

You can also add it in the management console, similar to this video.

Now you are ready to use the key to connect to an environment.

Generate new keys 

If you’re logged in using the Platform.sh CLI, generate a key and have it added to your Platform.sh account automatically.

  1. In a terminal, run platform ssh-key:add.

  2. If necessary, log in to a browser.

  3. Press Y and enter to create a new SSH key.

  4. Copy the location of the generated key.

  5. Run the following commands (replacing PATH_TO_YOUR_KEY with the location you copied):

    $ eval $(ssh-agent)
    $ ssh-add 'PATH_TO_YOUR_KEY'
    

To generate a key otherwise, GitHub has a good walk-through for creating SSH key pairs on various operating systems. Then you need to add it to your Platform.sh account.

Now you have a public and a private key and the public key is added to your account. You are ready to use the keys to connect to an environment.

Forwarding keys by default 

It may be helpful to set your SSH client to always forward keys to Platform.sh servers, which can simplify other SSH or rsync commands. To do so, include a block in your local ~/.ssh/config file like so:

Host *.us.platform.sh
       ForwardAgent yes
Host *.eu.platform.sh
       ForwardAgent yes

Include one Host entry for each Platform.sh region you want to connect to, such as us-2 or eu-4. (You can include other configuration as desired.)

Connect to your server with SSH 

To access an environment via the CLI:

  1. In a terminal, run platform ssh.
  2. (If not currently in a project directory) enter the number of the project you want to access.
  3. (If there are multiple environments) enter the ID of the environment you want to access.
  4. (If there are multiple apps) enter the number of the app you want to access.

To connect using SSH keys, find the details in the management console:

  1. Open the Platform.sh console.
  2. Select a project.
  3. In the Environment dropdown, select the environment you want to access.
  4. Click the SSH dropdown.
  5. Copy the ssh command for where you want access. (Example: ssh abcdefghi5k-master-7rqtwti--app@ssh.region.url)
  6. Enter the command into a terminal.

Note that if you have just added your SSH key, you need to redeploy your environment before you can access it using SSH keys.

Once you’ve used either method, you get a response like this:

   ___ _      _    __
  | _ \ |__ _| |_ / _|___ _ _ _ __
  |  _/ / _` |  _|  _/ _ \ '_| '  \
  |_| |_\__,_|\__|_| \___/_| |_|_|_|

 Welcome to Platform.

 This is environment master
 of project wk5fqz6qoo123.

web@wk5fqz6qoo123-master--php:~$

Now you can interact with the environment as you want.