Skip to content

OPKSSH Setup Guide

Overview

opkssh allows SSH authentication via OpenID Connect (OIDC), eliminating the need for manual SSH key management. Users log in once with their BFH Microsoft account and a short-lived SSH key is generated automatically.

This guide documents the setup for BFH GPU servers using Azure Entra ID as the OIDC provider.

Important notes: - opkssh coexists with standard SSH — existing users with authorized_keys or LDAP keys are not affected - A Client-ID from an Azure App Registration is required (request via normal BFH IT channels) - The BFH tenant issuer is: https://login.microsoftonline.com/d6a1cf8c-768e-4187-a738-b6e50c4deb4a/v2.0

Server Setup

1. Install opkssh

wget -qO- "https://raw.githubusercontent.com/openpubkey/opkssh/main/scripts/install-linux.sh" | sudo bash

Do not use the provided deb package; might not install correctly, and thus might not work (e.g., missing service user opksshuser, etc.).

2. Configure the OIDC provider

Edit /etc/opk/providers and add the BFH Azure line or the Switch edu-ID (prefer Switch):

https://login.microsoftonline.com/d6a1cf8c-768e-4187-a738-b6e50c4deb4a/v2.0 e9cb7d7e-39df-4e43-8cbf-ab796044132e 24h
#or
https://login.eduid.ch/ bfh_oidc_client_43155 24h

The file may already contain default providers (Google, GitLab, etc.) — keep those and just add the BFH line at the bottom.

Parameters: 1. Issuer URL 2. Client-ID from your Azure App Registration (or Switch) 3. Key expiration policy (12h, 24h, 48h, 1week, oidc, oidc-refreshed)

3. Configure allowed users

Consider this part as an introduction to opkssh and its config files, but this is done via the user_creation.sh script, check opkssh user creation.

Edit /etc/opk/auth_id and add a line per user:

<linux-username> <bfh-email@bfh.ch> https://login.microsoftonline.com/d6a1cf8c-768e-4187-a738-b6e50c4deb4a/v2.0

For Switch edu-ID: 

<linux-username> <private email linked to switch> https://login.eduid.ch/

Parameters: 1. Local Linux username (must already exist on the server) 2. BFH email address as it appears in the Azure ID token OR private email linked to switch 3. Issuer URL

Example: 

sysadmin luis.parejabernal@bfh.ch https://login.microsoftonline.com/d6a1cf8c-768e-4187-a738-b6e50c4deb4a/v2.0
#or in Switch
pnl1 fernando.pareja2428@gmail.com https://login.eduid.ch/

4. Verify sshd configuration

The installer creates /etc/ssh/sshd_config.d/60-opk-ssh.conf with:

AuthorizedKeysCommand /usr/local/bin/opkssh verify %u %k %t
AuthorizedKeysCommandUser opksshuser

Confirm it is included by sshd:

grep "Include" /etc/ssh/sshd_config
# Should show: Include /etc/ssh/sshd_config.d/*.conf

Also confirm UsePAM yes is set:

grep UsePAM /etc/ssh/sshd_config

5. Fix permissions

The installer may set wrong ownership on the opkssh binary. Verify that it is:

sudo chown root:opksshuser /usr/local/bin/opkssh

The installer may set wrong ownership on /etc/opk. Verify that it is:

sudo chgrp -R opksshuser /etc/opk
sudo chmod -R 750 /etc/opk

6. Ensure user home directories exist (now done automatically with script)

Ensure home directory creation on first login with PAM.

opkssh reads the user's home directory during verification. Make sure home directories are created properly and have correct permissions:

# If recreating a user whose home directory is missing:
sudo userdel -r <username>
sudo useradd -m -s /bin/bash <username>
sudo usermod -aG sudo <username>

# Verify permissions
sudo chmod 750 /home/<username>
sudo chown <username>:<username> /home/<username>

Client Setup

1. Install opkssh

Follow the installation instructions on the opkssh GitHub page for your OS. On Linux:

wget -qO- "https://raw.githubusercontent.com/openpubkey/opkssh/main/scripts/install-linux.sh" | sudo bash

On Windows, restart your shell after installation so the PATH is updated.

2. Create the config file

opkssh login --create-config

This creates: - Windows: C:\Users\<USER>\.opk\config.yml - Linux/macOS: ~/.opk/config.yml

3. Edit the config file

default_provider: eduid

providers:
  - alias: azure
    issuer: https://login.microsoftonline.com/d6a1cf8c-768e-4187-a738-b6e50c4deb4a/v2.0
    client_id: e9cb7d7e-39df-4e43-8cbf-ab796044132e
    scopes: openid profile email offline_access
    access_type: offline
    prompt: select_account
    redirect_uris:
      - http://localhost:3000/login-callback
      - http://localhost:10001/login-callback
      - http://localhost:11110/login-callback

  - alias: eduid
    issuer: https://login.eduid.ch/
    client_id: bfh_oidc_client_43155  
    scopes: openid profile email offline_access
    access_type: offline
    redirect_uris:
      - http://localhost:3000/login-callback
      - http://localhost:10001/login-callback
      - http://localhost:11110/login-callback

Note: Use prompt: select_account instead of prompt: none if you have multiple Microsoft accounts in your browser — otherwise Azure may return an AADSTS16000 error.

4. Log in and connect

opkssh login -i ~/.ssh/bfh_opkssh_access      # opens browser
ssh -o IdentitiesOnly=yes -i ~/.ssh/bfh_opkssh_access <shortname>@<server>

The generated keys are stored in ~/.ssh/ with the name bfh_opkssh_access and expire after the configured period (e.g. 24h). After expiry, just run opkssh login -i ~/.ssh/bfh_opkssh_access again.

Troubleshooting

Problem Cause Fix
AADSTS16000 error on login Multiple Microsoft accounts in browser Set prompt: select_account in config
Permission denied (publickey) Home directory missing or wrong permissions Recreate user with -m flag; chmod 750 /home/<user>
Too many authentication failures SSH tries too many keys Use -i and -o IdentitiesOnly=yes
opkssh verify works but SSH still fails sshd config not loaded sudo systemctl reload ssh

Adding New Users

On the server, use the user_creation.sh script to add new users. It automatically creates a home directory, adds them to the users group and adds the respective entries in the auth_id file:

sudo bash user_creation.sh <Kürzel>

Deleting users

On the works.

References