Difference between revisions of "Master Portal sshkey endpoint"
From PDP/Grid Wiki
Jump to navigationJump to search| (20 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
== Introduction == | == Introduction == | ||
| − | The MasterPortal server has an extra OIDC-protected end-point, ''/sshkey'', which can be used to | + | The MasterPortal server has an extra OIDC-protected end-point, ''/sshkey'', which provides an API for storing SSH public keys on the MasterPortal. These SSH public keys can be used to obtain proxy certificates from the MasterPortal, provided a long-lived proxy certificate is present. This wiki page describes the available Master Portal API for managing the SSH keys. |
| − | Additionally | + | See also [[RCauth.eu_and_MasterPortal_VOPortal_integration_guide | Instructions for VO Portal developers]] for information on how to register a client. |
| + | '''Note:''' the endpoint can be [[#Configuration | configured]] to require a specific OAuth2 scope, which then will need to be enabled for the client. | ||
| + | |||
| + | Additionally the MasterPortal also has a (non OIDC-protected) end-point ''/sshkeylisting'' for retrieving a flat list of ''username'' / ''publickey'' pairs. This latter endpoint is typically only accessible from certain hosts and intended for use by the `SSH host` to build up its '''AuthorizedKeysCommand'''. | ||
| + | |||
| + | For a fully-functional client, see the [[RCauth.eu and MasterPortal SSH Key Portal]]. This client can be used by end-users as a self-service portal. | ||
== API Description == | == API Description == | ||
| Line 13: | Line 18: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
| − | + | ! | Parameter | |
| − | + | ! | Description | |
|- | |- | ||
| | access_token | | | access_token | ||
| Line 42: | Line 47: | ||
=== Action values === | === Action values === | ||
| − | Valid action are the following | + | Valid action values are one of the following |
{| class="wikitable" | {| class="wikitable" | ||
| Line 48: | Line 53: | ||
! | Parameter | ! | Parameter | ||
! | Description | ! | Description | ||
| − | ! | Parameters other than access_token | + | ! | Parameters other than ''access_token'' |
|- | |- | ||
| | add | | | add | ||
| | Add a new key | | | Add a new key | ||
| − | | | Mandatory: client_id, client_secret, pubkey <BR>Optional: label, description | + | | | Mandatory: ''client_id'', ''client_secret'', ''pubkey'' <BR>Optional: ''label'', ''description'' |
|- | |- | ||
| | update | | | update | ||
| | Update existing key | | | Update existing key | ||
| − | | | Mandatory: client_id, client_secret, label <BR>Optional: description, pubkey | + | | | Mandatory: ''client_id'', ''client_secret'', ''label'' <BR>Optional: ''description'', ''pubkey'' |
|- | |- | ||
| | remove | | | remove | ||
| | Remove existing key | | | Remove existing key | ||
| − | | | Mandatory: label | + | | | Mandatory: ''label'' |
|- | |- | ||
| | get | | | get | ||
| | Retrieve specific key | | | Retrieve specific key | ||
| − | | | Mandatory: label | + | | | Mandatory: ''label'' |
|- | |- | ||
| | list | | | list | ||
| Line 78: | Line 83: | ||
* A key is identified using the pair ''username'' / ''label'', where username is obtained using the provided access_token. When a key is added without specifying a ''label'', a unique one is created using the prefix ''ssh-key-'' followed by a unique sequence number. | * A key is identified using the pair ''username'' / ''label'', where username is obtained using the provided access_token. When a key is added without specifying a ''label'', a unique one is created using the prefix ''ssh-key-'' followed by a unique sequence number. | ||
| − | * A certain public key must be unique for all users, i.e. may only occur once in the ''ssh_keys ''table in the ''oa2server'' database. | + | * A certain public key must be unique for *all* users, i.e. it may only occur once in the ''ssh_keys'' table in the ''oa2server'' database. |
| − | + | ||
| + | == Configuration == | ||
| + | |||
| + | The API is configured via the MasterPortal's server configuration file, <tt>/var/www/server/conf/cfg.xml</tt>, via the <tt><sshkeys></tt> node.<br> | ||
| + | There are currently (v.0.2.0) two configurable parameters: | ||
| + | * The maximum number of public keys a user may register, via the <tt>max</tt> attribute, | ||
| + | * The name of the OAuth2 scope required for making use of the API, via the <tt>scope</tt> attribute. | ||
| + | E.g.: | ||
| + | <!-- Specify allowed number of SSH keys --> | ||
| + | <sshkeys max="5" | ||
| + | scope="eu.rcauth.sshkeys" | ||
| + | /> | ||
Latest revision as of 12:43, 15 June 2022
Introduction
The MasterPortal server has an extra OIDC-protected end-point, /sshkey, which provides an API for storing SSH public keys on the MasterPortal. These SSH public keys can be used to obtain proxy certificates from the MasterPortal, provided a long-lived proxy certificate is present. This wiki page describes the available Master Portal API for managing the SSH keys.
See also Instructions for VO Portal developers for information on how to register a client. Note: the endpoint can be configured to require a specific OAuth2 scope, which then will need to be enabled for the client.
Additionally the MasterPortal also has a (non OIDC-protected) end-point /sshkeylisting for retrieving a flat list of username / publickey pairs. This latter endpoint is typically only accessible from certain hosts and intended for use by the `SSH host` to build up its AuthorizedKeysCommand.
For a fully-functional client, see the RCauth.eu and MasterPortal SSH Key Portal. This client can be used by end-users as a self-service portal.
API Description
Request parameters
A valid request consists of the following parameters:
| Parameter | Description |
|---|---|
| access_token | OIDC access_token, used for obtaining the username, mandatory for any request. |
| client_id | Mandatory for actions add and update. When specified it needs to match that belonging to the access_token |
| client_secret | idem |
| action | Specifies what to do, valid values are given below, mandatory for any request |
| label | Indicates the label for the specific public key, used for identifying it. |
| description | A user can optionally add a description for the public key |
| pubkey | The actual SSH public key. |
Action values
Valid action values are one of the following
| Parameter | Description | Parameters other than access_token |
|---|---|---|
| add | Add a new key | Mandatory: client_id, client_secret, pubkey Optional: label, description |
| update | Update existing key | Mandatory: client_id, client_secret, label Optional: description, pubkey |
| remove | Remove existing key | Mandatory: label |
| get | Retrieve specific key | Mandatory: label |
| list | Retrieve list of all keys for user | - |
The actions get and list return a JSON formatted list of key(s) to the user. The other actions do not return user output.
Notes
- A key is identified using the pair username / label, where username is obtained using the provided access_token. When a key is added without specifying a label, a unique one is created using the prefix ssh-key- followed by a unique sequence number.
- A certain public key must be unique for *all* users, i.e. it may only occur once in the ssh_keys table in the oa2server database.
Configuration
The API is configured via the MasterPortal's server configuration file, /var/www/server/conf/cfg.xml, via the <sshkeys> node.
There are currently (v.0.2.0) two configurable parameters:
- The maximum number of public keys a user may register, via the max attribute,
- The name of the OAuth2 scope required for making use of the API, via the scope attribute.
E.g.:
<sshkeys max="5"
scope="eu.rcauth.sshkeys"
/>
