Metadata-Version: 2.4
Name: datalad-bao-ssh
Version: 1.0.0
Summary: DataLad extension to set up SSH to use OpenBao signed certificates
Author-email: Duncan Mortimer <duncan.mortimer@ndcn.ox.ac.uk>
License-Expression: MIT
Project-URL: Repository, https://git.fmrib.ox.ac.uk/open-science/datalad/datalad-bao-ssh
Project-URL: Documentation, https://git.fmrib.ox.ac.uk/open-science/datalad/datalad-bao-ssh
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: datalad>=1.2.1
Requires-Dist: sigstore>=4.2.0
Requires-Dist: certifi>=2026.4.22
Requires-Dist: truststore
Requires-Dist: packaging
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-httpserver; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: trustme; extra == "test"
Requires-Dist: coverage; extra == "test"
Requires-Dist: pexpect; extra == "test"
Requires-Dist: tomli; python_version < "3.12" and extra == "test"
Provides-Extra: style
Requires-Dist: pylint; extra == "style"
Requires-Dist: flake8; extra == "style"
Dynamic: license-file

# 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](http://datalad.org).

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.
