SSHifu Server: OAuth Gateway and Certificate Authority

0.10.0 · active · verified Sun Apr 19

sshifu-server is an SSH authentication server that integrates an OAuth gateway with a certificate authority, issuing short-lived SSH certificates. It provides authentication against GitHub organizations and generic OIDC providers, including Authentik, Google Workspace, Okta, and Auth0. Currently at version 0.10.0, the project maintains an active release cadence, with several feature and bugfix releases in the past year. Key differentiators include its lightweight architecture, requiring minimal infrastructure with no external database, its seamless integration of OAuth for SSH, and its ability to act as a full certificate authority to enhance SSH security by reducing reliance on long-lived keys. The core server logic is implemented in Go, with the npm package serving as a wrapper for distribution and installation.

Common errors

```
Error: command not found: sshifu-server
```
cause The `sshifu-server` package was not installed globally, or the global `node_modules` bin directory is not in your system's PATH.

fix Run `npm install -g sshifu-server` to install the package globally, or use `npx sshifu-server` to run it without global installation.
```
npm ERR! Failed to extract sshifu-server binary from archive
```
cause This error often indicates issues with downloading the Go binary, corrupt archives, or insufficient permissions for extraction, especially on Windows or restricted environments.

fix Check your network connection and proxy settings. Ensure you have write permissions in your npm global installation directory. On Windows, ensure you are on `sshifu-server@0.7.7` or newer and that PowerShell's `Expand-Archive` command is available.
```
Error: Cannot find module 'sshifu-server'
```
cause Attempting to `require()` or `import` `sshifu-server` as a JavaScript/TypeScript library. This package is a CLI tool distributing a Go binary, not a JS module.

fix Remove `require('sshifu-server')` or `import ... from 'sshifu-server'` statements. Instead, interact with `sshifu-server` via its command-line interface: `npx sshifu-server` or `sshifu-server` if installed globally.

Warnings

gotcha The `sshifu-server` npm package primarily distributes a Go binary. It is not a JavaScript/TypeScript library and does not export any programmatic symbols for `import` or `require`.
Fix: Use `sshifu-server` as a command-line interface (CLI) tool. Do not attempt to import it programmatically in JS/TS code.
breaking Introduction of OIDC provider support and wizard changes in `v0.7.0` and `v0.10.0` may alter how configurations are created or updated, particularly for new deployments.
Fix: Review the setup wizard carefully during initial configuration or when updating from older versions to ensure OIDC settings are correctly applied. Back up existing configurations if migrating.
gotcha Prior to `v0.7.7`, `sshifu-server` npm package installation on Windows could fail due to incorrect archive formats and extraction logic, leading to missing binaries.
Fix: Ensure you are using `sshifu-server@0.7.7` or later for reliable installation on Windows. Update npm and Node.js to recent versions.
gotcha The `sshifu-server` requires a Go binary (downloaded automatically) and Node.js >=14.0.0. Network issues, restrictive firewalls, or incompatible Node.js versions can cause installation failures.
Fix: Verify network connectivity and proxy settings if the Go binary download fails. Ensure your Node.js version meets the `engines` requirement (>=14.0.0). Check npm logs for specific download or installation errors.

Install

npm install sshifu-server npm
yarn add sshifu-server yarn
pnpm add sshifu-server pnpm

Imports

sshifu-server command
wrong:
```
import { startServer } from 'sshifu-server'
```
correct:
```
npx sshifu-server
```
The `sshifu-server` package distributes a Go binary via npm. It is not intended for programmatic import as a JavaScript/TypeScript library; its primary interface is the command-line interface (CLI). Attempting to import symbols will result in module not found errors.
Global CLI
wrong:
```
require('sshifu-server').run()
```
correct:
```
npm install -g sshifu-server
```
To use `sshifu-server` directly from your terminal after installation, it must be installed globally. There are no exposed JavaScript functions to `require` or `import` from the package.
Configuration
wrong:
```
import { configure } from 'sshifu-server'
```
correct:
```
sshifu-server
```
Initial configuration for OAuth credentials and CA settings is performed interactively through the CLI when the server is first run, not via programmatic API calls.

Quickstart

Demonstrates how to quickly run sshifu-server using npx or install it globally and then run the CLI. It highlights the interactive configuration process.

#!/usr/bin/env bash

# Quick start using npx without global installation
echo "Starting sshifu-server via npx..."
npx sshifu-server

# --- OR ---

# Global installation for frequent use
echo "\nInstalling sshifu-server globally..."
npm install -g sshifu-server

# Run the globally installed server
echo "\nStarting globally installed sshifu-server..."
sshifu-server

echo "\nFollow the prompts to configure GitHub OAuth credentials, Certificate Authority (CA) settings, and server listen address."

view raw JSON →