View source for RCauth.eu and MasterPortal SSH Key Portal

== Introduction ==
The SSH Key Portal is a modified [http://grid.ncsa.illinois.edu/myproxy/oauth/ OAuth for MyProxy] (OA4MP) client. Instead of using the OIDC access_token to retrieve proxy certificates, it is used to authenticate to the [[Master Portal sshkey endpoint]], thereby providing a self-service portal for end-users for uploading their SSH public key to the Master Portal. Once the user has uploaded their public key they can use SSH key authentication to retrieve proxy certificates by ssh-ing to a special SSH server host, similar to SSH key authentication used by e.g. SVN, github, GlobusOnline etc.

The client is [https://github.com/rcauth-eu/aarc-ssh-portal/ implemented] as a tomcat servlet, running in the same tomcat container as the MasterPortal itself. For simplicity we also assume the vo-portal servlet is also enabled on the MasterPortal.

== SSH Key registration flow ==
<ol>
<li> The flow starts with the user going to the portal endpoint, <tt><nowiki>https://masterportal.example.org/sshkey-portal</nowiki></tt>. Note, the EGI instances use <tt><nowiki>https://masterportal.example.org/sshkeys</nowiki></tt> instead.
<li> The user now needs to login, which triggers a redirect to the RCauth.eu CA, where the user will log in via the WAYF.
<li> Once logged in the user is returned to the SSH Key Portal
<ul>
<li> When this is the first time the user logs in, (s)he can only add a new key
<li> When the user has previously added a key, it's also possible to remove or update an existing key
</ul>
<li> Adding a key:
<ul>
<li> one can either upload (click '''browse''') or paste the content of the file in the text field. Note: paste only a ''single'' key in the text field.
<li> a label can be given to the key, when not specified by the user, a default is given (''ssh-key-''<SEQUENCE NUMBER>).
<li> optionally, one can add a description for personal use.
</ul>
<li> Updating/removing a key:
<ul>
<li> one can only change the value of a existing public key or change the description.
<li> Changing the label requires removing the key and subsequently uploading it as a new key.
</ul>
</ol>

== SSH Key usage flow ==
Once the user has a SSH public key uploaded via the <tt><nowiki>https://masterportal.example.org/sshkey-portal</nowiki></tt> (or <tt><nowiki>https://masterportal.example.org/sshkeys</nowiki></tt> for EGI) portal, it's necessary to make sure there is a long-lived proxy certificate (typically 11 days) in the backend credential store of the MasterPortal. The easiest is to use the <tt><nowiki>https://masterportal.example.org/vo-portal</nowiki></tt> for that.

So the steps are as follows:
<ol>
<li>About once every week, the user goes to <tt><nowiki>https://masterportal.example.org/vo-portal</nowiki></tt> to ensure there is a valid long-lived proxy present on the MasterPortal.
<li>User adds their ssh private key to the ssh agent, using e.g. <pre>ssh-add -c</pre> or <pre>ssh-add -c ~/.ssh/id_rsa</pre>
<li>User can now ssh to the special ssh server using the special account to retrieve a proxy certificate. Something like <pre>ssh proxy@ssh.example.org > /tmp/x509up_u$(id -u)</pre>
<li>The user can verify that there is now a valid proxy by running <pre>voms-proxy-info -all</pre>.
</ol>

== Advanced options ==
By passing extra options on the ssh commandline, the user can adapt the returned proxy certificate or get extra information about the server or the availability of a proxy.
<br>
Valid options currently include:
{|
 |help
 |show help text with the available options, supported VOs etc.
 |-
 |info
 |return information on the long-lived credential currently in the MasterPortal for the user.
 |-
 |time=<HOURS>
 |specify preferred lifetime in hours of returned proxy, when longer than the available proxylifetime, the maximum available is used
 |-
 |voms=<VO<nowiki>|</nowiki>FQAN>
 |return a VOMS proxy instead of a plain proxy. Can repeated multiple times
|}

==== Examples ====
<ul>
<li>Get info for the user:
<pre>ssh proxy@ssh.example.org info</pre>
<li>Get a ''testvo'' proxy
<pre>ssh proxy@ssh.example.org voms=testvo > /tmp/x509up_u$(id -u)</pre>
<li>Get a ''testvo'' proxy with also an additional subgroup & Role. Also specify the preferred lifetime to be 24 hours
<pre>ssh proxy@ssh.example.org time=24 voms=testvo1 voms=testvo1:/testvo1/Role=member > /tmp/x509up_u$(id -u)</pre>
</ul>

== Source ==
The source of the portal can be found on [https://github.com/rcauth-eu/aarc-ssh-portal github]