From a845d8c7d26787d0888c358ad3e1c813a43fa646 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20Tam=C3=A1s?= <44925919+Simi23@users.noreply.github.com> Date: Thu, 18 Jul 2024 17:05:50 +0200 Subject: [PATCH] website/integrations: add Observium documentation (#10460) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * website/integrations: add Observium documentation * Reorganize docs and fix wording * Update website/integrations/services/observium/index.md Co-authored-by: 4d62 Signed-off-by: Simon Tamás <44925919+Simi23@users.noreply.github.com> * Change Observium install guide link Signed-off-by: Simon Tamás <44925919+Simi23@users.noreply.github.com> --------- Signed-off-by: Simon Tamás <44925919+Simi23@users.noreply.github.com> Co-authored-by: 4d62 --- .../integrations/services/observium/index.md | 110 ++++++++++++++++++ website/sidebarsIntegrations.js | 1 + 2 files changed, 111 insertions(+) create mode 100644 website/integrations/services/observium/index.md diff --git a/website/integrations/services/observium/index.md b/website/integrations/services/observium/index.md new file mode 100644 index 0000000000..beed6340ef --- /dev/null +++ b/website/integrations/services/observium/index.md @@ -0,0 +1,110 @@ +--- +title: Observium +--- + +Support level: Community + +## What is Observium + +> Observium is a network monitoring and management platform that provides real-time insight into network health and performance. +> +> -- https://observium.org + +:::note +This is based on authentik 2024.6.0 and Observium CE 24.4.13528 +::: + +## Preparation + +The following placeholders will be used: + +- `observium.company` is the FQDN of the Observium install. +- `authentik.company` is the FQDN of the authentik install. + +This guide assumes you already have a working Observium instance. It is recommended to install it with the install script, following the [instructions](https://docs.observium.org/) on Observium's website. + +Apache2 comes bundled with Observium, but there is also a third party module, [mod_auth_openidc](https://github.com/OpenIDC/mod_auth_openidc), which is needed for this configuration to work. +Download the latest [release](https://github.com/OpenIDC/mod_auth_openidc/releases) of the project suitable for your machine. + +This guide uses `libapache2-mod-auth-openidc_2.4.15.7-1.bookworm_amd64.deb` as an example. + +Install the package: + +```bash +apt install ./libapache2-mod-auth-openidc_2.4.15.7-1.bookworm_amd64.deb +``` + +## authentik configuration + +1. In authentik, under **Providers**, create an **OAuth2/OpenID Provider** with these settings: + + - Name: Observium + - Client ID: Copy this for later + - Client Secret: Copy this for later + - Redirect URIs/Origins: `https://observium.company/secure/redirect_uri` (This can be any location on the domain that doesn't point to actual content) + - Signing Key: Select any available signing key + +2. In authentik, under **Applications**, create an Application with these settings: + + - Name: Observium + - Slug: observium + - Provider: Select `Observium` + +## Observium configuration + +1. Edit the file `/etc/apache2/sites-available/000-default.conf` and add the following lines: + + ```apacheconf + + ... + + OIDCProviderMetadataURL https://authentik.company/application/o/observium/.well-known/openid-configuration + OIDCClientID + OIDCClientSecret + OIDCRedirectURI https://observium.company/secure/redirect_uri + OIDCCryptoPassphrase + OIDCCookieDomain observium.company + OIDCXForwardedHeaders X-Forwarded-Host X-Forwarded-Proto + OIDCPathScope "openid email profile" + OIDCRemoteUserClaim preferred_username ^(.*)$ $1@authentik + + + AuthType openid-connect + Require valid-user + + + ... + + ``` + + Meaning of variables: + + - `OIDCRedirectURI` is the same URI that is set for the authentik Provider. + - The `OIDCCryptoPassphrase` directive should be set to a random string, for more information, see [the official documentation](https://github.com/OpenIDC/mod_auth_openidc/blob/9c0909af71eb52283f4d3797e55d1efef64966f2/auth_openidc.conf#L15). + - `OIDCXForwardedHeaders` is necessary if your instance is behind a reverse proxy. If omitted, the module does not accept information from these headers. + - `OIDCRemoteUserClaim` tells the module how to construct a username based on your claims. The first argument selects the claim, while the second and third are RegEx search and replace expressions. [More info](https://github.com/OpenIDC/mod_auth_openidc/blob/9c0909af71eb52283f4d3797e55d1efef64966f2/auth_openidc.conf#L794) + +2. Edit the Observium configuration. By default, it should be located at `/opt/observium/config.php`. + + Edit the following line: + + ```php + $config['auth_mechanism'] = "remote"; + ``` + + Add the following lines: + + ```php + $config['auth_remote_userlevel'] = 10; + $config['auth_remote_logout_url'] = "https://authentik.company/application/o/observium/end-session/"; + ``` + + With this method, you can only assign one permission level to all users. Since Observium permits only a single authentication mechanism to be selected, it is recommended to set `auth_remote_userlevel` to 10. You can read about all of the user levels [here](https://docs.observium.org/user_levels/). + +3. Restart the Apache2 service: + + ```bash + service apache2 restart + ``` + + Now you should be able to log in to your Observium instance using authentik. diff --git a/website/sidebarsIntegrations.js b/website/sidebarsIntegrations.js index 16322f0766..f416771437 100644 --- a/website/sidebarsIntegrations.js +++ b/website/sidebarsIntegrations.js @@ -137,6 +137,7 @@ module.exports = { "services/gatus/index", "services/glitchtip/index", "services/grafana/index", + "services/observium/index", "services/sentry/index", "services/ubuntu-landscape/index", "services/uptime-kuma/index",