From 2986026647868a57d00f7423f2b7d0a050774612 Mon Sep 17 00:00:00 2001
From: Fabian Kammel <fabian@kammel.dev>
Date: Wed, 16 Apr 2025 19:14:45 +0200
Subject: [PATCH 1/4] docs: document how to configure oauth2 for opkssh

Signed-off-by: Fabian Kammel <fabian@kammel.dev>
---
 book/src/integrations/oauth2/examples.md | 84 +++++++++++++++++++++++-
 1 file changed, 83 insertions(+), 1 deletion(-)

diff --git a/book/src/integrations/oauth2/examples.md b/book/src/integrations/oauth2/examples.md
index 3a8e54d0b..f688653a3 100644
--- a/book/src/integrations/oauth2/examples.md
+++ b/book/src/integrations/oauth2/examples.md
@@ -562,7 +562,7 @@ OAuth2 Proxy is a reverse proxy that provides authentication with OpenID Connect
 It is typically used to secure web applications without native OpenID Connect support.
 
 Prepare the environment.
-Due to a [lack of public client support](https://github.com/oauth2-proxy/oauth2-proxy/issues/1714) we have to set it up as a basic client. 
+Due to a [lack of public client support](https://github.com/oauth2-proxy/oauth2-proxy/issues/1714) we have to set it up as a basic client.
 
 ```bash
 kanidm system oauth2 create webapp 'webapp.example.com' 'https://webapp.example.com'
@@ -615,6 +615,88 @@ allowed_groups = ["webapp_admin"]
 client_secret = "<SECRET>"
 ```
 
+## OPKSSH
+
+[OPKSSH](https://github.com/openpubkey/opkssh) is a tool of the
+[OpenPubkey](https://github.com/openpubkey/openpubkey) project. It enables ssh
+to be used with OpenID Connect allowing SSH access to be managed via identities
+like alice@example.com instead of long-lived SSH keys. It does not replace SSH,
+but instead generates SSH keys on the fly, and augments the verification process
+on the server side.
+
+To set up OPKSSH to authenticate with Kanidm:
+
+1.  Add an email address to your regular Kanidm account, if it doesn't have one
+    already:
+
+    ```sh
+    kanidm person update alice -m alice@example.com
+    ```
+
+2. Create a new Kanidm group for your OPKSSH users (`opkssh_users`), and add your
+    regular account to it:
+
+    ```sh
+    kanidm group create opkssh_users
+    kanidm group add-members opkssh_users alice
+    ```
+
+3. Create a new OAuth2 application configuration in Kanidm (`opkssh`), configure
+    the redirect URL, and scope access to the `opkssh_users` group:
+
+    ```sh
+    # The last argument, the origin parameter, is required, but a dead link.
+    kanidm system oauth2 create-public opkssh opkssh http://localhost:3000
+
+    # Add the specific redirect URIs used by OPKSSH
+    kanidm system oauth2 add-redirect-url opkssh http://localhost:3000/login-callback
+    kanidm system oauth2 add-redirect-url opkssh http://localhost:10001/login-callback
+    kanidm system oauth2 add-redirect-url opkssh http://localhost:11110/login-callback
+
+    # Explicitly allow localhost redirects for this client
+    kanidm system oauth2 enable-localhost-redirects opkssh
+
+    # Map the group created earlier to the required OIDC scopes
+    kanidm system oauth2 update-scope-map opkssh opkssh_users email openid profile groups
+    ```
+
+4. OPKSSH currently only supports `RS256` based signatures, so we need to enable
+    support for this algorithm in the client:
+
+    ```sh
+    kanidm system oauth2 warning-enable-legacy-crypto opkssh
+    ```
+
+    ES256 support is tracked [here](https://github.com/openpubkey/opkssh/issues/131).
+
+5. On the SSH server side, as per [offical docs](https://github.com/openpubkey/opkssh?tab=readme-ov-file#server-configuration-1):
+
+    ```sh
+    wget -qO- "https://raw.githubusercontent.com/openpubkey/opkssh/main/scripts/install-linux.sh" | sudo bash
+    echo "https://idm.example.com/oauth2/openid/opkssh opkssh 24h" | sudo tee -a /etc/opk/providers
+    # where 'user' is the linux user
+    sudo opkssh add user alice@example.com https://idm.example.com/oauth2/openid/opkssh
+    ```
+
+6. On the SSH client side, as per [official docs](https://github.com/openpubkey/opkssh?tab=readme-ov-file#custom-openid-providers-authentik-authelia-keycloak-zitadel):
+
+    ```sh
+    # Install OPKSSH
+    curl -LO https://github.com/openpubkey/opkssh/releases/download/v0.4.0/opkssh-linux-amd64
+    sudo install opkssh-linux-amd64 /usr/local/bin/opkssh
+    rm opkssh-linux-amd64
+
+    # This will open a browser with consent screen
+    opkssh login --provider=https://idm.example.com/oauth2/openid/opkssh,opkssh
+    ```
+
+7. Use SSH as you would normally:
+
+    ```sh
+    ssh user@your-server-hostname
+    ```
+
+
 ## Outline
 
 > These instructions were tested with self-hosted Outline 0.80.2.

From 1e1ed6cabae7817b340b54a340932839a4e2fba7 Mon Sep 17 00:00:00 2001
From: Fabian Kammel <fabian@kammel.dev>
Date: Wed, 16 Apr 2025 21:45:55 +0200
Subject: [PATCH 2/4] docs: update to OPKSSH version 0.5.1 with support for
 ES256

Signed-off-by: Fabian Kammel <fabian@kammel.dev>
---
 book/src/integrations/oauth2/examples.md | 17 ++++-------------
 1 file changed, 4 insertions(+), 13 deletions(-)

diff --git a/book/src/integrations/oauth2/examples.md b/book/src/integrations/oauth2/examples.md
index f688653a3..2d5dae661 100644
--- a/book/src/integrations/oauth2/examples.md
+++ b/book/src/integrations/oauth2/examples.md
@@ -660,16 +660,7 @@ To set up OPKSSH to authenticate with Kanidm:
     kanidm system oauth2 update-scope-map opkssh opkssh_users email openid profile groups
     ```
 
-4. OPKSSH currently only supports `RS256` based signatures, so we need to enable
-    support for this algorithm in the client:
-
-    ```sh
-    kanidm system oauth2 warning-enable-legacy-crypto opkssh
-    ```
-
-    ES256 support is tracked [here](https://github.com/openpubkey/opkssh/issues/131).
-
-5. On the SSH server side, as per [offical docs](https://github.com/openpubkey/opkssh?tab=readme-ov-file#server-configuration-1):
+4. On the SSH server side, as per [offical docs](https://github.com/openpubkey/opkssh?tab=readme-ov-file#server-configuration-1):
 
     ```sh
     wget -qO- "https://raw.githubusercontent.com/openpubkey/opkssh/main/scripts/install-linux.sh" | sudo bash
@@ -678,11 +669,11 @@ To set up OPKSSH to authenticate with Kanidm:
     sudo opkssh add user alice@example.com https://idm.example.com/oauth2/openid/opkssh
     ```
 
-6. On the SSH client side, as per [official docs](https://github.com/openpubkey/opkssh?tab=readme-ov-file#custom-openid-providers-authentik-authelia-keycloak-zitadel):
+5. On the SSH client side, as per [official docs](https://github.com/openpubkey/opkssh?tab=readme-ov-file#custom-openid-providers-authentik-authelia-keycloak-zitadel):
 
     ```sh
     # Install OPKSSH
-    curl -LO https://github.com/openpubkey/opkssh/releases/download/v0.4.0/opkssh-linux-amd64
+    curl -LO https://github.com/openpubkey/opkssh/releases/download/v0.5.1/opkssh-linux-amd64
     sudo install opkssh-linux-amd64 /usr/local/bin/opkssh
     rm opkssh-linux-amd64
 
@@ -690,7 +681,7 @@ To set up OPKSSH to authenticate with Kanidm:
     opkssh login --provider=https://idm.example.com/oauth2/openid/opkssh,opkssh
     ```
 
-7. Use SSH as you would normally:
+6. Use SSH as you would normally:
 
     ```sh
     ssh user@your-server-hostname

From 95ff67ddb46ae0bd75d93e7f56837dce2b2d0d90 Mon Sep 17 00:00:00 2001
From: Fabian Kammel <datosh18@gmail.com>
Date: Fri, 18 Apr 2025 16:13:39 +0200
Subject: [PATCH 3/4] Apply suggestions from code review

Co-authored-by: James Hodgkinson <james@terminaloutcomes.com>
---
 book/src/integrations/oauth2/examples.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/book/src/integrations/oauth2/examples.md b/book/src/integrations/oauth2/examples.md
index 2d5dae661..f0b33062d 100644
--- a/book/src/integrations/oauth2/examples.md
+++ b/book/src/integrations/oauth2/examples.md
@@ -618,10 +618,10 @@ client_secret = "<SECRET>"
 ## OPKSSH
 
 [OPKSSH](https://github.com/openpubkey/opkssh) is a tool of the
-[OpenPubkey](https://github.com/openpubkey/openpubkey) project. It enables ssh
-to be used with OpenID Connect allowing SSH access to be managed via identities
-like alice@example.com instead of long-lived SSH keys. It does not replace SSH,
-but instead generates SSH keys on the fly, and augments the verification process
+[OpenPubkey](https://github.com/openpubkey/openpubkey) project. It enables SSH
+to be used with OpenID Connect allowing access to be managed via identities
+like `alice@example.com` instead of long-lived private keys. It does not replace SSH,
+but instead generates private keys on the fly, and augments the verification process
 on the server side.
 
 To set up OPKSSH to authenticate with Kanidm:
@@ -645,7 +645,7 @@ To set up OPKSSH to authenticate with Kanidm:
     the redirect URL, and scope access to the `opkssh_users` group:
 
     ```sh
-    # The last argument, the origin parameter, is required, but a dead link.
+    # The redirect origin is set to localhost for local callbacks
     kanidm system oauth2 create-public opkssh opkssh http://localhost:3000
 
     # Add the specific redirect URIs used by OPKSSH
@@ -677,7 +677,7 @@ To set up OPKSSH to authenticate with Kanidm:
     sudo install opkssh-linux-amd64 /usr/local/bin/opkssh
     rm opkssh-linux-amd64
 
-    # This will open a browser with consent screen
+    # This will open a browser to login via Kanidm
     opkssh login --provider=https://idm.example.com/oauth2/openid/opkssh,opkssh
     ```
 

From d0014e547aa015685c9840920da5bc26734d2863 Mon Sep 17 00:00:00 2001
From: Fabian Kammel <fabian@kammel.dev>
Date: Fri, 18 Apr 2025 16:22:21 +0200
Subject: [PATCH 4/4] Link to official installation docs instead

Signed-off-by: Fabian Kammel <fabian@kammel.dev>
---
 book/src/integrations/oauth2/examples.md | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/book/src/integrations/oauth2/examples.md b/book/src/integrations/oauth2/examples.md
index f0b33062d..abae681b7 100644
--- a/book/src/integrations/oauth2/examples.md
+++ b/book/src/integrations/oauth2/examples.md
@@ -660,24 +660,18 @@ To set up OPKSSH to authenticate with Kanidm:
     kanidm system oauth2 update-scope-map opkssh opkssh_users email openid profile groups
     ```
 
-4. On the SSH server side, as per [offical docs](https://github.com/openpubkey/opkssh?tab=readme-ov-file#server-configuration-1):
+4. On the SSH server side, [install opkssh](https://github.com/openpubkey/opkssh#installing-on-a-server)
+    and allow your user to connect via:
 
     ```sh
-    wget -qO- "https://raw.githubusercontent.com/openpubkey/opkssh/main/scripts/install-linux.sh" | sudo bash
-    echo "https://idm.example.com/oauth2/openid/opkssh opkssh 24h" | sudo tee -a /etc/opk/providers
     # where 'user' is the linux user
     sudo opkssh add user alice@example.com https://idm.example.com/oauth2/openid/opkssh
     ```
 
-5. On the SSH client side, as per [official docs](https://github.com/openpubkey/opkssh?tab=readme-ov-file#custom-openid-providers-authentik-authelia-keycloak-zitadel):
+5. On the SSH client side, [install opkssh](https://github.com/openpubkey/opkssh#getting-started)
+    and login via Kanidm:
 
     ```sh
-    # Install OPKSSH
-    curl -LO https://github.com/openpubkey/opkssh/releases/download/v0.5.1/opkssh-linux-amd64
-    sudo install opkssh-linux-amd64 /usr/local/bin/opkssh
-    rm opkssh-linux-amd64
-
-    # This will open a browser to login via Kanidm
     opkssh login --provider=https://idm.example.com/oauth2/openid/opkssh,opkssh
     ```