diff --git a/docs/additional-resources/amc_ssh_auth.md b/docs/additional-resources/amc_ssh_auth.md index 04c975f3..35b628c7 100644 --- a/docs/additional-resources/amc_ssh_auth.md +++ b/docs/additional-resources/amc_ssh_auth.md @@ -46,17 +46,68 @@ You can move on to [Step 2](#step-2-generate-an-ssh-key), but please make sure 1 ``` ## *Step 2: Generate an ssh key* -You are strongly encouraged to set a passphrase for your key pair. You will be prompted to enter the passphrase each time you log in. - -SSH Key Generation for Windows Users: -- Using the command prompt, PowerShell, or Windows Terminal: -- Using PuTTY: +```{important} +You are strongly encouraged to set a passphrase for your key pair and generate a Ed25519 key. You will be prompted to enter the passphrase each time you log in. +``` -SSH Key Generation for Mac Users: - +(tabset-ref-get-account)= +``````{tab-set} +:sync-group: tabset-os-version +`````{tab-item} Windows +:sync: os-version-windows +When generating a key on Windows it is recommended you use Powershell, but the command prompt or a basic Windows terminal will also work. Once inside Powershell (or similar), execute the following command to generate an Ed25519 key: +``` +ssh-keygen -t ed25519 +``` +Once the above command is executed, you will be prompted for several items that will help you generate the key. It is recommended that you **_create a passphrase_** and note the file path of the generated key. During key generation, you may also name the key in the `Enter file in which to save the key` portion, instead of using the default `id_ed25519` name. This is often necessary if you have previously generated keys. In the example output provided below, we use the default name and see that the public key has been saved in the path `C:\Users\username\.ssh\id_ed25519.pub`. +``` +Z:\> ssh-keygen -t ed25519 +Generating public/private ed25519 key pair. +Enter file in which to save the key (C:\Users\username\.ssh\id_ed25519): +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in C:\Users\username\.ssh\id_ed25519. +Your public key has been saved in C:\Users\username\.ssh\id_ed25519.pub. +The key fingerprint is : +SHA256: +The key's randomart image is: ++-- [ED25519 256] --+ +| .++*=B=. | +... ++---- [SHA256] -----+ +``` -## *Step 3: Upload your ssh key to [registry.cilogon.org](https://registry.cilogon.org/registry/)* +````` +`````{tab-item} Mac +:sync: os-version-mac +SSH key generation for Mac and Linux users can be completed from a terminal window. In a terminal, execute the following command to generate an Ed25519 key: +``` +ssh-keygen -t ed25519 +``` +Once the above command is executed, you will be prompted for several items that will help you generate the key. It is recommended that you **_create a passphrase_** and note the file path of the generated key. During key generation, you may also name the key in the `Enter file in which to save the key` portion, instead of using the default `id_ed25519` name. This is often necessary if you have previously generated keys. In the example output provided below, we use the default name and see that the public key has been saved in the path `/Users/username/.ssh/id_ed25519.pub` +``` +username$ ssh-keygen -t ed25519 +Generating public/private ed25519 key pair. +Enter file in which to save the key (/Users/username/.ssh/id_ed25519): +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in /Users/username/.ssh/id_ed25519. +Your public key has been saved in /Users/username/.ssh/id_ed25519.pub. +The key fingerprint is : +SHA256: +The key's ranomart image is: ++-- [ED25519 256] --+ +| .++*=B=. | +... ++---- [SHA256] -----+ +``` +```{note} +There is a chance you need to create or alter your ssh config file `~/.ssh/config`. See more in the [Troubleshooting](#troubleshooting) section below. +``` +````` +`````` +## *Step 3: Upload your ssh key to registry.cilogon.org* After logging into [registry.cilogon.org](https://registry.cilogon.org/registry/) with your ACCESS credentials, click on the dropdown menu in the upper right-hand corner by your name. @@ -74,7 +125,7 @@ Click "Manage" in the SSHKeyAuthenticator row. Select "Add SSH Key". ![](./amc_ssh_images/add_sshkey.png) -Click "Choose File". If you store your SSH keys in a hidden directory (e.g. `~/.ssh`), it may be difficult to locate your public key using a Finder/File Explorer window. As a workaround, you can copy your public key to an easily discoverable location using the Terminal App/Windows Command Prompt:
`cp ~/.ssh/id_rsa.pub ~/Desktop` +Click "Choose File". If you store your SSH keys in a hidden directory (e.g. `~/.ssh`), it may be difficult to locate your public key using a Finder/File Explorer window. As a workaround, you can copy your public key to an easily discoverable location using the Terminal App/Windows Command Prompt:
`cp ~/.ssh/id_ed25519.pub ~/Desktop`
Locate your __public__ key (`.pub`) on your local drive, then click "UPLOAD". @@ -94,18 +145,19 @@ After a few minutes, you can proceed to [Step 4](#step-4-sign-in-from-a-terminal You must be on the University of Colorado Anschutz Medical Campus VPN or network. See [prerequisites](#prerequisites) above. ``` -SSH into the CURC CI login node by entering the following in your terminal or terminal emulator: +SSH into the CURC login node by entering the following in your terminal or terminal emulator: ``` ssh -i @xsede.org@login.rc.colorado.edu ``` The `-i` flag is used to point to the location of your __private__ key on your local system. The private key must correspond to the public key you uploaded to your RMACC CILogon profile. -For example, if I uploaded `id_rsa.pub` to my profile, I would log in as such: +For example, if I uploaded `id_ed25519.pub` to my profile, I would log in as such: ``` -ssh -i ~/.ssh/id_rsa lrf20@xsede.org@login.rc.colorado.edu +ssh -i ~/.ssh/id_ed25519 lrf20@xsede.org@login.rc.colorado.edu ``` +```{note} You will be prompted to enter your passphrase if you set one during key generation. - +``` Once you are logged in, you will see the CURC Message of the Day and your prompt will change to `@login-ciX` (where `X` will be a numeric value). The Message of the Day contains important information and reminders about CURC systems, so please take time to read this on a regular basis.
@@ -121,7 +173,14 @@ Log in at [registry.cilogon.org](https://registry.cilogon.org/registry/) and nav ## Troubleshooting * If you are able to get through [Step 3](#step-3-upload-your-ssh-key-to-registrycilogonorg) but unable to ssh in from your terminal, check that the ssh key in your command is the same key you uploaded to the registry. -* If you are prompted for a **__passphrase__** (not a password) when signing in from your terminal, this refers to the passphrase you set when you generated your ssh key. If you don't remember it then you will have to generate and upload a new ssh key to the registry. If you are prompted for a **__password__**, please submit a [support request form](https://colorado.service-now.com/req_portal?id=ucb_sc_rc_form), as this indicates an issue with your CILogon enrollment. Please include a screenshot of the error message and the date/time of your last login attempt. +* If you are prompted for a **__passphrase__** (not a password) when signing in from your terminal, this refers to the passphrase you set when you generated your ssh key. If you don't remember it then you will have to generate and upload a new ssh key to the registry. +* **For Mac users:** If you have set up the key and followed all the steps above but are prompted for a **__password__** instead of a **__passphrase__**, you may need to edit or create a config file (`~/.ssh/config`). If you don't have an ssh config file, you can create it from the terminal window with the command `touch ~/.ssh/config`. After, edit the file and add the following 3 lines before trying again: + ``` + Host login.rc.colorado.edu + HostKeyAlgorithms ssh-ed25519 + PubkeyAcceptedAlgorithms ssh-ed25519 + ``` +* If you are prompted for a **__password__** please submit a [support request form](https://colorado.service-now.com/req_portal?id=ucb_sc_rc_form), as this indicates an issue with your CILogon enrollment. Please include a screenshot of the error message and the date/time of your last login attempt. **Mac users should first attempt the solution provided in the bullet point above.** * If you receive an error message indicating that you are not in the COmanage registry (see screenshot below), please submit a [support request form](https://colorado.service-now.com/req_portal?id=ucb_sc_rc_form). ![](./amc_ssh_images/notregistered_error.png) diff --git a/docs/additional-resources/registrycilogon-instructions.md b/docs/additional-resources/registrycilogon-instructions.md index 343099dc..c2c0626c 100644 --- a/docs/additional-resources/registrycilogon-instructions.md +++ b/docs/additional-resources/registrycilogon-instructions.md @@ -27,14 +27,67 @@ You can move on to Step 2, but please make sure 10 minutes have elapsed between ## *Step 2: Generate an ssh key* -You are strongly encouraged to set a passphrase for your key pair. You will be prompted to enter the passphrase each time you log in. +```{important} +You are strongly encouraged to set a passphrase for your key pair and generate a Ed25519 key. You will be prompted to enter the passphrase each time you log in. +``` -SSH Key Generation instructions for Windows Users: -- Using command prompt, PowerShell, or Windows Terminal: visit [How to Generate SSH Keys in Windows 10 and Windows 11](https://www.howtogeek.com/762863/how-to-generate-ssh-keys-in-windows-10-and-windows-11/) -- Using PuTTY: visit [Use SSH Keys with PuTTY on Windows](https://devops.ionos.com/tutorials/use-ssh-keys-with-putty-on-windows/) +(tabset-ref-get-account)= +``````{tab-set} +:sync-group: tabset-os-version +`````{tab-item} Windows +:sync: os-version-windows +When generating a key on Windows it is recommended you use Powershell, but the command prompt or a basic Windows terminal will also work. Once inside Powershell (or similar), execute the following command to generate an Ed25519 key: +``` +ssh-keygen -t ed25519 +``` +Once the above command is executed, you will be prompted for several items that will help you generate the key. It is recommended that you **_create a passphrase_** and note the file path of the generated key. During key generation, you may also name the key in the `Enter file in which to save the key` portion, instead of using the default `id_ed25519` name. This is often necessary if you have previously generated keys. In the example output provided below, we use the default name and see that the public key has been saved in the path `C:\Users\username\.ssh\id_ed25519.pub`. -SSH Key Generation instructions for Mac Users: visit [Manually generating your SSH key in macOS](https://docs.tritondatacenter.com/public-cloud/getting-started/ssh-keys/generating-an-ssh-key-manually/manually-generating-your-ssh-key-in-mac-os-x) +``` +Z:\> ssh-keygen -t ed25519 +Generating public/private ed25519 key pair. +Enter file in which to save the key (C:\Users\username\.ssh\id_ed25519): +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in C:\Users\username\.ssh\id_ed25519. +Your public key has been saved in C:\Users\username\.ssh\id_ed25519.pub. +The key fingerprint is : +SHA256: +The key's randomart image is: ++-- [ED25519 256] --+ +| .++*=B=. | +... ++---- [SHA256] -----+ +``` +````` +`````{tab-item} Mac +:sync: os-version-mac +SSH key generation for Mac and Linux users can be completed from a terminal window. In a terminal, execute the following command to generate an Ed25519 key: +``` +ssh-keygen -t ed25519 +``` +Once the above command is executed, you will be prompted for several items that will help you generate the key. It is recommended that you **_create a passphrase_** and note the file path of the generated key. During key generation, you may also name the key in the `Enter file in which to save the key` portion, instead of using the default `id_ed25519` name. This is often necessary if you have previously generated keys. In the example output provided below, we use the default name and see that the public key has been saved in the path `/Users/username/.ssh/id_ed25519.pub` +``` +username$ ssh-keygen -t ed25519 +Generating public/private ed25519 key pair. +Enter file in which to save the key (/Users/username/.ssh/id_ed25519): +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in /Users/username/.ssh/id_ed25519. +Your public key has been saved in /Users/username/.ssh/id_ed25519.pub. +The key fingerprint is : +SHA256: +The key's ranomart image is: ++-- [ED25519 256] --+ +| .++*=B=. | +... ++---- [SHA256] -----+ +``` +```{note} +There is a chance you need to create or alter your ssh config file `~/.ssh/config`. See more in the [Troubleshooting](#troubleshooting) section below. +``` +````` +`````` ## *Step 3: Upload your ssh key to registry.cilogon.org* @@ -53,18 +106,15 @@ Click "Manage" in the SSHKeyAuthenticator row. Select "Add SSH Key". ![](./registry-images/add_sshkey.png) -Click "Choose File". If you store your SSH keys in a hidden directory (e.g. `~/.ssh`), it may be difficult to locate your public key using a Finder/File Explorer window. As a workaround, you can copy your public key to an easily discoverable location using the Terminal App/Windows Command Prompt: - -``` -cp ~/.ssh/id_rsa.pub ~/Desktop -``` +Click "Choose File". If you store your SSH keys in a hidden directory (e.g. `~/.ssh`), it may be difficult to locate your public key using a Finder/File Explorer window. As a workaround, you can copy your public key to an easily discoverable location using the Terminal App/Windows Command Prompt:
`cp ~/.ssh/id_ed25519.pub ~/Desktop` +
Locate your __public__ key (`.pub`) on your local drive, then click "UPLOAD". ![](./registry-images/upload_sshkey.png)
-A green message box will notify you that your SSH key was successfully added to your account. +A green message box will notify you that your SSH key has been successfully added to your account.
![](./registry-images/sshkeyadded.png) @@ -74,7 +124,16 @@ Log in at [registry.cilogon.org](https://registry.cilogon.org/registry/) and nav ## Troubleshooting -* If you receive an error message indicating that you are not in the COmanage registry (see screenshot below), please submit a [support request form](https://colorado.service-now.com/req_portal?id=ucb_sc_rc_form). +* If you are able to get through [Step 3](#step-3-upload-your-ssh-key-to-registrycilogonorg) but unable to access CURC resources from your terminal, check that the key in your command is the same key you uploaded to the registry. +* If you are prompted for a **__passphrase__** (not a password), this refers to the passphrase you set when you generated your key. If you don't remember it then you will have to generate and upload a new key to the registry. +* **For Mac users:** If you have set up the key and followed all the steps above but are prompted for a **__password__** instead of a **__passphrase__**, you may need to edit or create a config file (`~/.ssh/config`). If you don't have an ssh config file, you can create it from the terminal window with the command `touch ~/.ssh/config`. After, edit the file and add the following 3 lines before trying again: + ``` + Host login.rc.colorado.edu + HostKeyAlgorithms ssh-ed25519 + PubkeyAcceptedAlgorithms ssh-ed25519 + ``` +* If you are prompted for a **__password__** please submit a [support request form](https://colorado.service-now.com/req_portal?id=ucb_sc_rc_form), as this indicates an issue with your CILogon enrollment. Please include a screenshot of the error message and the date/time of your last login attempt. **Mac users should first attempt the solution provided in the bullet point above.** +* If you receive an error message indicating that you are not in the COmanage registry (see screenshot below), please submit a [support request form](https://colorado.service-now.com/req_portal?id=ucb_sc_rc_form). ![](./registry-images/notregistered_error.png)