Skip to content

Commit

Permalink
website/integrations: pgadmin: refactor (#12604)
Browse files Browse the repository at this point in the history 
* 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 <tanamarieberry@yahoo.com>
Signed-off-by: 4d62 <git@sdko.org>

* 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 <git@sdko.org>

* website/integrations: pgadmin: fix another stupidity I probably made

Glorious https://img.sdko.org/u/0k3f46.png

Signed-off-by: 4d62 <git@sdko.org>

---------

Signed-off-by: 4d62 <git@sdko.org>
Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
  • Loading branch information
@tanberry
4d62 and tanberry authored Jan 15, 2025
1 parent 99639a9 commit 8132733
Showing 1 changed file with 59 additions and 58 deletions.
117 changes: 59 additions & 58 deletions website/integrations/services/pgadmin/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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': '<Client ID from authentik>',
'OAUTH2_CLIENT_SECRET': '<Client secret from authentik>',
'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/<App Slug>/.well-known/openid-configuration',
'OAUTH2_SCOPE': 'openid email profile',
'OAUTH2_ICON': '<Fontawesome icon key (e.g., fa-key)>',
'OAUTH2_BUTTON_COLOR': '<Hexadecimal color code for the login button>'
}]
```

:::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' : '<display-name>',
'OAUTH2_CLIENT_ID' : '<client-id>',
'OAUTH2_CLIENT_SECRET' : '<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/<app-slug>/.well-known/openid-configuration',
'OAUTH2_SCOPE' : 'openid email profile',
'OAUTH2_ICON' : '<fontawesome-icon>',
'OAUTH2_BUTTON_COLOR' : '<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':'<Client ID from authentik>','OAUTH2_CLIENT_SECRET':'<Client secret from authentik>','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/<App Slug>/.well-known/openid-configuration','OAUTH2_SCOPE':'openid email profile','OAUTH2_ICON':'<Fontawesome icon key (e.g., fa-key)>','OAUTH2_BUTTON_COLOR':'<Hexadecimal color code for the login button>'}]"
```

In the code above the following placeholders have been used:
### General Notes

- `<display-name>`: The name that is displayed on the Login Button
- `<client-id>`: The Client ID from step 1
- `<client-secret>`: The Client Secret from step 1
- `<app-slug>`: The App Slug from step 2, it should be `pgadmin` if you did not change it
- `<fontawesome-icon>`: An icon name from [fontawesome](https://fontawesome.com). Only brand icons seem to be supported. This icon is displayed in front of the `<display-name>`. E.g.: _fa-github_.
- `<button-color>`: 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.

0 comments on commit 8132733

Please sign in to comment.