datalad-bao-ssh 1.0.0

DataLad extension to set up SSH to use OpenBao signed certificates

DataLad extension for OpenBao managed SSH certificates

This repository contains an extension that allows the use of short lived SSH certificates issued by an OpenBao server with DataLad.

This extension will setup your SSH environment for authentication with short-lived SSH certificates, signed by an OpenBao server. These can be used with suitably configured GitLab/Hub and SSH based RIA hosts as provided by your DataLad dataset service. Ordinarily you only need to run this once, unless something in your environment changes (e.g. a server address needs to be updated) or if your ~/.ssh/config file is lost.

Prerequisites

Ideally this script can utilise the bao client program to handle your logins, but can fall back to basic system tools (cURL and jq) for some authentication backends - if it can't find these then the script will fail. If your system already has the bao client installed then make sure this is available before running this command. This might involve loading and environment module or ensuring the system bao is in your software search PATH. Examples of installation methods for bao include MacPorts, Homebrew, RPM, apt. If it does not then the setup command will attempt to install Bao in the folder .baobin in your home folder (see below for how to change this).

Service Configuration

The command will attempt to download some basic configuration provided by the server referenced in the DataLad setting 'datalad.bao-ssh-config-url'. DataLad service administrators should make available at this URL a JSON format file (see :ref:JSON Configuration) that provides the main configuration for the service. If this site is unavailable you will be prompted for this configuration information (see :ref:Configuration).

After initial configuration you will be prompted to enter your user name on the OpenBao server (which must match that on the RIA and Git endpoints).

With this information your SSH client configuration will be updated to run a script each time you connect to the RIA/Git hosts.

Usage

When you carry out a DataLad command that requires SSH access, the script generated by this extension will ensure that you have a valid short-term SSH certificate. Where you don't you will be prompted to log into the authentication server again to obtain a new one.

Some authentication backends will prompt for passwords (e.g. 'ldap') and others may launch a web browser or ask you to visit a website to continue with the login (e.g. OpenID/Entra etc).

Maintenance

When called with the option --update, this plugin will check for updates to itself, DataLad (both from the PyPi repository) and the OpenBao bao software (where it installed this into your home folder). If updates are installed, you will be advised if you need to run the update command again to complete the upgrade process.

It is recommended that you run this on a regular basis to ensure you are using the latest versions of the software.

Configuration

Git configuration options:

• datalad.bao-ssh-config-url: URL of JSON configuration file
• datalad.bao-ssh-bao-install-dir: Path to install 'bao' client in - defaults to '.baobin' in the user's home folder

User questions:

• "Would you like to quit so that you can connect to a VPN and try again?"
  • If the JSON configuration server is behind a restrictive firewall and your institution provides a VPN service, answer 'y' to quit. Connect to your VPN and try again.

Please ask your DataLad/OpenBao administrator for the answers to the following questions.

• "OpenBao role that allows signing of SSH certificates"
• "OpenBao 'principal' that identifies users of DataLad"
• "SSH certificate type to generate" (usually accepting the default it correct)
• "Hostname of the OpenBao authentication server"
• "Port that OpenBao is listening on"
• "Authentication backend URL component on OpenBao server"
• "Does your remote git server(s) use a per-user username?"

You then need to enter the RIA and Git service host names - again, your administrator can provide these details. Provide the servers, one per line and press 'Return' on an empty line when finished with that server type.

Example questions...

• "Enter DataLad RIA endpoint host name (hit return to end)"
• "Enter DataLad GitLab/Hub host name (hit return to end)"

JSON Configuration

The web-available JSON configuration needs the following keys, equivalent to the questions asked without it:

Key	Purpose
ROLE	OpenBao role for the signing process
PRINCIPAL	The generic principal to apply - used by Git services to filter users
CERTTYPE	SSH certificate type - see ssh-keygen for allowed values
BAOHOST	Hostname of the OpenBao server
BAOPORT	Port OpenBao is listening on
BAOAUTH	Authentication plugin to use
GIT_REQUIRES_USERNAME	If your Git server provides per-user accounts set this to true
GIT_SSH_HOSTS	List of hostnames for your Git server hosts
RIA_HOSTS	List of hostnames for your RIA hosts

API

High-level API commands

• bao_setup Arguments:
  • update_bao (optional, boolean) - check for and update 'bao' client

Command line reference

Run this command to setup your SSH environment to create and use short-lived SSH certificates for authentication to your DataLad remotes.

Option arguments:

• --update When provided, will check for and update the signing script and the version of the 'bao' tool. For system-wide 'bao' installations this will only update the signing script.