mannemsolutions/pgfga repository overview

⁠PGFGA - Postgres Fine Grained Access tool

⁠License

Copyright 2021 - Bol.com and Mannem Solution

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

⁠Introduction

PGFGA is a tool to configure and manage Postgres logical objects (Users, Roles, Databases, Extensions and Replication Slots). Users and roles can be synced from a ldap directory.

⁠The origin

Usually organizations manage their users in a directory (like AD, ldap, or a cloud IAM). Although Postgres can integrate with such tools for authentication, it does not for authorization. Furthermore, the users need to either be defined in postgres or be mapped to an existing user before authentication can finish successfully.

As such many enterprises have looked into syncing authorization into postgres and many tools exist. At bol.com⁠ an existing tool based on python 2 was used. For conformity, the tool was in-house rebuilt into python 3 and after that enhanced with unit tests, and extra capabilities.

For the bol.com use case, it made sense to manage more types of objects next to users and roles. As an example, managing ownership on a database means that the database should exist too. The tool was expanded to manage databases, extensions and replication slots too. And thus, pgcdfga was born, built, and maintained.

After a few years, Mannem Solutions has been offered the ability to adopt the solution. We have renamed it to pgfga (PostGres Fine Grained Access), rebuilt it in GoLang and are now maintaining (and using) the new tool in our own solutions.

⁠Requirements

⁠PGFGA config

PGFGA can be configured using a configuration yaml. In container environments (like Kubernetes), that could be a configmap mounted as a volume. For more details on the configuration format, please refer to our config description⁠.

⁠Postgres User account

The PGFGA tool requires a postgres user with access and SUPERUSER privileges to run. The user could be made available either with:

• Local access (when running inside of master container) and using ident authentication
• A staged username / password e.a. configured with setup.sql script (by setting PG_PRIMARY_USER, PG_PRIMARY_PASSWORD, etc.).
• A staged pgfga user with client certificate authentication.
• Setting up ldap authentication for the postgres user (see the docker-compose example⁠ for an example of this setup).

⁠Downloading

docker pull mannemsolutions/pgfga

Please refer to our download instructions⁠ for more details and more options.

⁠Using

⁠Native docker

The image has an example config.yaml, but you probably want to mount your own config file at /etc/pgfga/config.yaml:

docker run -v $PWD/config.yaml:/etc/pgfga/config.yaml mannemsolutions/pgfga

Note that the $PWD is added to mount the file with its full absolute path. Relative paths are not supported.

⁠docker-compose

You can use pgfga with docker compose. The docker-compose.yml file could have contents like this:

services:
  pgfga:
    image: mannemsolutions/pgfga
    volume:
      - ./testdata/config.yaml:/etc/pgfga/config.yaml
  postgres:
    image: postgres:13
    environment:
      POSTGRES_HOST_AUTH_METHOD: 'md5'
      POSTGRES_PASSWORD: pgfga
  ldap:
    image: osixia/openldap
    command:
      - "--copy-service"
      - "--loglevel"
      - debug
    environment:
      LDAP_ORGANISATION: pgfga
      LDAP_DOMAIN: pgfga.org
      LDAP_ADMIN_PASSWORD: pGfGa
    volumes:
      - ./testdata/ldif:/container/service/slapd/assets/config/bootstrap/ldif/custom

Note that the ldap needs content. Please see the github project for pgfga⁠ for a working example of docker-compose setting up a ldap, and postgres, and running pgfga against it, which consists of.

• The docker-compose.yml file⁠
• The bash script running docker compose⁠
• The ldif file we use⁠
• The pgfga config file we use⁠

⁠More info

• Please refer to our configuration documentation⁠ to learn about all capabilities and configuration features of pgfga.
• Please refer to our download instructions⁠ for more details and more options.