diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index b2dc1e2b9..3b68afb4a 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -238,6 +238,7 @@ module.exports = { "argo", "cloud-run", "mtls", + "cockpit", "code-server", "admin-enroll-device", "enroll-device", diff --git a/docs/guides/cockpit.md b/docs/guides/cockpit.md new file mode 100644 index 000000000..72acc53f6 --- /dev/null +++ b/docs/guides/cockpit.md @@ -0,0 +1,80 @@ +--- +title: Cockpit +lang: en-US +meta: + - name: keywords + content: >- + pomerium, identity access proxy, cockpit, + authentication, remote, management, gui, linux +description: >- + Learn how to secure Cockpit, a web GUI for Linux servers, behind Pomerium +--- + +# Secure Cockpit + +[Cockpit](https://cockpit-project.org/) is "a web-based graphical interface for servers, intended for everyone". It provides a method of managing many administrative server tasks that would normally require command line access. + +## Before You Begin + +This guide assumes you already have Pomerium installed and connected to your [IdP](/docs/glossary.md#identity-provider). If not, follow the instructions in the following articles before continuing: + +- Install Pomerium + - [Binaries](/docs/install/binary.md) if installing Pomerium as a system-level service. + - [Pomerium using Docker](/docs/install/readme.md) if installing Pomerium as a Docker container + - [Install Pomerium using Helm](/docs/k8s/helm.md) for Kubernetes environments. +- Connect to an IdP - See [Identity Provider Configuration](/docs/identity-providers/readme.md) and find the article for your identity provider. + + +## Install & Configure Cockpit + +1. Cockpit provides detailed instructions on installation for many popular Linux distributions. See [Running Cockpit](https://cockpit-project.org/running.html) to find the steps to match your server. + +1. Once installed, create or edit `/etc/cockpit/cockpit.conf` to prepare it to accept proxied connections: + + ```conf + [WebService] + Origins = https://cockpit.localhost.pomerium.io wss://localhost.pomerium.io + ProtocolHeader = X-Forwarded-Proto + ``` + + - Adjust `cockpit.localhost.pomerium.io` to match the URL Cockpit will be accessible from. + +1. Restart the Cockpit service to apply the changes: + + ```bash + sudo systemctl restart cockpit.service + ``` + +## Pomerium Route + +1. A Pomerium route for Cockpit can follow the basic [route examples](/reference/readme.md#routes), but requires websockets to load the dashboard after initial login: + + ```yaml + - from: https://cockpit.localhost.pomerium.io + to: http://localhost:9090 + allow_websockets: true + policy: + - allow: + or: + - email: + is: alice@example.com + - email: + is: bob@example.com + ``` + + - This example assumes that Pomerium is running as a system service on the same server as Cockpit. Adust the `to` value to match the path to the Cockpit service if running on another server. + - Adjust `cockpit.localhost.pomerium.io` to match the URL Cockpit will be accessible from. + +1. If Pomerium is running as a system service the route will be updated automatically. Docker may not notify Pomerium of file changes, so the Pomerium container may need to be restarted. + +1. Navigate to the new route to confirm access: + + ![The Cockpit Login Screen](./img/cockpit-login-screen.png) + +## Authentication + +Cockpit uses PAM authentication by default. The project documentation includes a [Single Sign On](https://cockpit-project.org/guide/latest/sso.html) page that covers authentication to the software using Kerberos. As of this page's last update, there's no known way to provide user authentication from Pomerium using JWT or HTTP Headers. + +::: tip Prove Us Wrong! +Have you configured Cockpit to accept authentication from Pomerium? Let us know on [GitHub](https://github.com/pomerium/pomerium), or post in the [Community Showcase](https://discuss.pomerium.com/c/community-showcase/14) on our forums. +::: \ No newline at end of file diff --git a/docs/guides/img/cockpit-login-screen.png b/docs/guides/img/cockpit-login-screen.png new file mode 100644 index 000000000..5aedb9018 Binary files /dev/null and b/docs/guides/img/cockpit-login-screen.png differ diff --git a/docs/guides/readme.md b/docs/guides/readme.md index 69de6051a..582c66098 100644 --- a/docs/guides/readme.md +++ b/docs/guides/readme.md @@ -6,6 +6,7 @@ This section contains applications, and scenario specific guides for Pomerium. - The [argo](./argo.md) guide demonstrates how Pomerium can be used to add access control to [Argo](https://argoproj.github.io/projects/argo). - The [Client-Side mTLS](./mtls.md) guide demonstrates how Pomerium can be used to add mutual authentication to end-user connections using client certificates and a custom certificate authority. - The [Cloud Run](./cloud-run.md) recipe demonstrates deploying Pomerium to Google Cloud Run as well as using it to Authorize users to protected Cloud Run endpoints. +- Secure [Cockpit](./cockpit.md), a web GUI for Linux server administration, behind a Pomerium route. - The [code-server](./code-server.md) guide demonstrates how Pomerium can be used to add access control to third-party applications that don't ship with [fine-grained access control](https://github.com/cdr/code-server/issues/905). code-server is a tool to run Visual Studio code as a web application. - See [Device Admin-Enrollment](./admin-enroll-device.md) to create pre-approved device enrollment links in the Pomerium Enterprise Console. - See [Device User-Enrollment](./enroll-device.md) to learn how to register a security device (TPM, Yubikey, etc) to access routes requiring a device ID.