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 ```