From 813273338e1ab25454f8a8b218051e8ad006866f Mon Sep 17 00:00:00 2001 From: 4d62 Date: Wed, 15 Jan 2025 14:37:51 -0500 Subject: [PATCH] website/integrations: pgadmin: refactor (#12604) * website/integrations: pgadmin: refactor Refactors the pgAdmin integration documentation, makes it match existing style guide, and adds subsection for configuration for containerized deployments * website/integrations: pgadmin: lint Lints refactored documentation page * Update website/integrations/services/pgadmin/index.md Co-authored-by: Tana M Berry Signed-off-by: 4d62 * website/integrations: pgadmin: updates note Adds back "based on" note with updated versions * website/integrations: pgadmin: specify strict/regex rediect uri Not sure on wording tho * website/integrations: pgadmin: add configuration validation step Adds configuration validation step. Log out, log back in with authentik. Button on login page * website/integrations: pgadmin: fix redirect uri Fixes incorrect redirect uri introduced during refactor. Probably forgot to copy slug or something. Important thing is that it's fixed Signed-off-by: 4d62 * website/integrations: pgadmin: fix another stupidity I probably made Glorious https://img.sdko.org/u/0k3f46.png Signed-off-by: 4d62 --------- Signed-off-by: 4d62 Co-authored-by: Tana M Berry --- .../integrations/services/pgadmin/index.md | 117 +++++++++--------- 1 file changed, 59 insertions(+), 58 deletions(-) diff --git a/website/integrations/services/pgadmin/index.md b/website/integrations/services/pgadmin/index.md index b835c377beee..1a6153fcdedb 100644 --- a/website/integrations/services/pgadmin/index.md +++ b/website/integrations/services/pgadmin/index.md @@ -14,7 +14,7 @@ sidebar_label: pgAdmin > -- https://www.pgadmin.org/ :::note -This is based on authentik 2022.3.3 and pgAdmin4 6.19 +This is based on authentik 2024.12.2 and pgAdmin4 8.14 ::: ## Preparation @@ -24,78 +24,79 @@ The following placeholders are used in this guide: - `pgadmin.company` is the FQDN of pgAdmin. - `authentik.company` is the FQDN of authentik. -### Step 1: Create authentik Provider +# authentik configuration -In authentik, under _Providers_, create an _OAuth2/OpenID Provider_ with these settings: +1. From the Admin interface, navigate to **Applications** -> **Applications**. +2. Use the wizard to create a new application and provider. During this process: + - Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later. + - Set a `Strict` redirect URI to `https://pgadmin.company/oauth2/authorize`. + - Select any available signing key. -**Provider Settings** +## pgAdmin OAuth Configuration -- Name: pgAdmin -- Client ID: Copy and Save this for Later -- Client Secret: Copy and Save this for later -- Redirect URIs/Origins: `http://pgadmin.company/oauth2/authorize` -- Signing Key: Select any available key +To configure OAuth in pgAdmin, you can either use the `config_local.py` file or set environment variables if you are deploying pgAdmin in a containerized setup. -### Step 2: Create authentik Application +### Using `config_local.py` -In authentik, create an application which uses this provider. Optionally apply access restrictions to the application using policy bindings. +1. Locate or create the `config_local.py` file in the `/pgadmin4/` directory. -- Name: pgAdmin -- Slug: pgadmin -- Provider: pgAdmin -- Launch URL: https://pgadmin.company + - If the file does not exist, create it manually. -### Step 3: Configure pgAdmin +2. Add the following configuration settings to `config_local.py`: -All settings for OAuth in pgAdmin are configured in the `config_local.py` file. This file can usually be found in the path `/pgadmin4/config_local.py` + ```python + AUTHENTICATION_SOURCES = ['oauth2', 'internal'] + OAUTH2_AUTO_CREATE_USER = True + OAUTH2_CONFIG = [{ + 'OAUTH2_NAME': 'authentik', + 'OAUTH2_DISPLAY_NAME': 'authentik', + 'OAUTH2_CLIENT_ID': '', + 'OAUTH2_CLIENT_SECRET': '', + 'OAUTH2_TOKEN_URL': 'https://authentik.company/application/o/token/', + 'OAUTH2_AUTHORIZATION_URL': 'https://authentik.company/application/o/authorize/', + 'OAUTH2_API_BASE_URL': 'https://authentik.company/', + 'OAUTH2_USERINFO_ENDPOINT': 'https://authentik.company/application/o/userinfo/', + 'OAUTH2_SERVER_METADATA_URL': 'https://authentik.company/application/o//.well-known/openid-configuration', + 'OAUTH2_SCOPE': 'openid email profile', + 'OAUTH2_ICON': '', + 'OAUTH2_BUTTON_COLOR': '' + }] + ``` -:::note -More information on that file can be found in the official pgAdmin [documentation](https://www.pgadmin.org/docs/pgadmin4/development/config_py.html) -::: +3. Save the file and restart pgAdmin for the changes to take effect. -Copy the following code into the `config_local.py` file and replace all placeholders and FQDN placeholders -:::note -If the `config_local.py` file does not exist, it needs to be created in the `/pgadmin4/` directory. -::: + :::note + You must restart pgAdmin every time you make changes to `config_local.py`. + ::: + +### Using Environment Variables for Containerized Deployments + +For deployments using Docker or Kubernetes, you can configure OAuth using the following environment variables: + +1. Set these environment variables in your container: -```py -AUTHENTICATION_SOURCES = ['oauth2', 'internal'] -OAUTH2_AUTO_CREATE_USER = True -OAUTH2_CONFIG = [{ - 'OAUTH2_NAME' : 'authentik', - 'OAUTH2_DISPLAY_NAME' : '', - 'OAUTH2_CLIENT_ID' : '', - 'OAUTH2_CLIENT_SECRET' : '', - 'OAUTH2_TOKEN_URL' : 'https://authentik.company/application/o/token/', - 'OAUTH2_AUTHORIZATION_URL' : 'https://authentik.company/application/o/authorize/', - 'OAUTH2_API_BASE_URL' : 'https://authentik.company/', - 'OAUTH2_USERINFO_ENDPOINT' : 'https://authentik.company/application/o/userinfo/', - 'OAUTH2_SERVER_METADATA_URL' : 'https://authentik.company/application/o//.well-known/openid-configuration', - 'OAUTH2_SCOPE' : 'openid email profile', - 'OAUTH2_ICON' : '', - 'OAUTH2_BUTTON_COLOR' : '' -}] +```bash +PGADMIN_CONFIG_AUTHENTICATION_SOURCES="['oauth2', 'internal']" +PGADMIN_CONFIG_OAUTH2_AUTO_CREATE_USER=True +PGADMIN_CONFIG_OAUTH2_CONFIG="[{'OAUTH2_NAME':'authentik','OAUTH2_DISPLAY_NAME':'Login with authentik','OAUTH2_CLIENT_ID':'','OAUTH2_CLIENT_SECRET':'','OAUTH2_TOKEN_URL':'https://authentik.company/application/o/token/','OAUTH2_AUTHORIZATION_URL':'https://authentik.company/application/o/authorize/','OAUTH2_API_BASE_URL':'https://authentik.company/','OAUTH2_USERINFO_ENDPOINT':'https://authentik.company/application/o/userinfo/','OAUTH2_SERVER_METADATA_URL':'https://authentik.company/application/o//.well-known/openid-configuration','OAUTH2_SCOPE':'openid email profile','OAUTH2_ICON':'','OAUTH2_BUTTON_COLOR':''}]" ``` -In the code above the following placeholders have been used: +### General Notes -- ``: The name that is displayed on the Login Button -- ``: The Client ID from step 1 -- ``: The Client Secret from step 1 -- ``: The App Slug from step 2, it should be `pgadmin` if you did not change it -- ``: An icon name from [fontawesome](https://fontawesome.com). Only brand icons seem to be supported. This icon is displayed in front of the ``. E.g.: _fa-github_. -- ``: Sets the color of the Login Button. Should be in Hex format, E.g.: _#fd4b2d_ +- To **only allow OAuth2 login**, set: -:::note -To only allow authentication via authentik set `AUTHENTICATION_SOURCES` to _['oauth2']_. This should **only** be done once at least one user registered via authentik has been made an admin in pgAdmin. -::: + ```python + AUTHENTICATION_SOURCES = ['oauth2'] + ``` -:::note -To disable user creation on pgAdmin, set `OAUTH2_AUTO_CREATE_USER` to _False_ -::: + Ensure that you promote at least one user to an admin before disabling the internal authentication. -Finally, restart pgAdmin to apply the changes. +- To **disable automatic user creation**, set: + ```python + OAUTH2_AUTO_CREATE_USER = False + ``` + Setting this value to `False` disables automatic user creation. This ensures that only the first signed-in user is registered. -:::note -pgAdmin needs to be restarted **every** time changes to `config_local.py` are made -::: +## Configuration verification + +To confirm that authentik is properly configured with pgAdmin, log out and log back in via authentik. A new button should have appeared on the login page.