tliesche/powerdns-auth-proxy repository overview

⁠PowerDNS Authentication Proxy

⁠Maintained Tags and Dockerfile links

• latest , 1.3.1 , 1.3 , 1⁠
• edge , 1.3.1-rc1 , 1.3.1-rc , 1.3-rc , 1-rc⁠

⁠Introduction

This is a simple proxy that can be used to authenticate users against a PowerDNS server.

It allows to assign individual permissions to users on global or domain-based level.

⁠Change Log

Information about the latest changes can be found here: CHANGELOG⁠.

⁠Building the Application

⁠building a local binary

The proxy is written in Golang and can be compiled by using the following command:

make build

Once the command has finished, you will find an executable file called "gateway" within your project directory.

To make this command work, you will need to have a running version of Go 1.22 or higher available, as well as the make command.

⁠building a docker image

Although it is possible to run this application locally, it is highly recommended to run the service in Docker instead.

A Dockerfile based on Debian Bookworm and Go 1.22 is provided in the repository. To build the Docker image, just run the following command:

make build-docker

To make this command work, you will need to have a running version of docker available, as well as the make command.

⁠Running the Application

⁠run locally

To run the application locally, you first have to create a yaml-formatted configuration file that can be used to setup the application. The configuration file should be named config.yaml and could be placed anywhere on your local system.

Additionally you need to create ec signing key for your JWT based authentication which is mandatory for your admin endpoints to work.

⁠Create config.yaml

The following is an example of a configuration file that contains all available configuration keys. Read carefully and extract the parts that match your desired setup for running the application.

# true, false
debug: false

# path to directory where log files should be created
# e.g. /var/log/powerdns-auth-proxy
log_path: "<path to log file>"

# type of authentication to be used for PowerDNS proxy endpoints
# admin endpoints always use jwt auth
# valid values: api_key, basic_auth, jwt
auth_type: "<auth type>"


jwt:
  # audience string used for issued JWT tokens
  audience: "<audience>"
  # issuer string used for issued JWT tokens
  issuer: "<issuer>"
  # string value of the ec public key for JWT authentication
  # this MUST be combined with public_key
  secret_key: "<secret key>"
  # string value of the ec private key for JWT authentication
  # this MUST be combined with secret_key
  public_key: "<public key>"
  # path to public key file
  # this MUST be combined with public_key_path
  # e.g. /var/lib/powerdns-auth-proxy/data/jwt.privkey.pem
  secret_key_path: "<path to secret key file>"
  # path to public key file
  # this MUST be combined with secret_key_path
  # e.g. /var/lib/powerdns-auth-proxy/data/jwt.pubkey.pem
  public_key_path: "<path to public key file>"

# database type to be used
# valid values: mariadb, mysql, postgres, postgresql, sqlite
database: "<database type>"

# only necessary if database type is mariadb or mysql
mariadb:
  # hostname or ip of the mariadb server
  # e.g. 10.100.0.1, mariadb.example.com
  host: "<mariadb host>"
  # port of the mariadb server
  # e.g. 3306
  port: <mariadb port>
  # username for the mariadb database
  user: "<mariadb user>"
  # password for the mariadb database
  password: "<mariadb password>"
  # name of the mariadb database
  database: "<mariadb database>"

# only necessary if database type is postgres or postgresql
postgres:
  # hostname or ip of the postgres server
  # e.g. 10.100.0.1, postgres.example.com
  host: "<postgres host>"
  # port of the postgres server
  # e.g. 5432
  port: <postgres port>
  # username for the postgres database
  user: "<postgres user>"
  # password for the postgres database
  password: "<postgres password>"
  # name of the postgres database
  database: "<postgres database>"

# connection settings for powerdns authoritative server
powerdns:
  # hostname or ip of the powerdns server
  # e.g. 10.100.0.1, powerdns.example.com
  host: "<powerdns host>"
  # port of the powerdns server api
  # e.g. 8081
  port: <powerdns port>
  # setting if api is behind ssl
  ssl: <true/false>
  # api key for powerdns server
  # e.g. "changeme"
  api_key: "<powerdns api key>"

⁠Create signing keys for jwt authentication

First we need to create a private key for signing the JWT tokens. This key should be kept secret and should not be shared with anyone. The following command can be used to create a private key:

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out <path to private key file>

Afterwards we need to create a public key for verifying the JWT tokens. This key can be shared with anyone who wants to verify the JWT tokens. The following command can be used to create a public key:

openssl ec -in <path to private key file> -pubout -out <path to public key file>

⁠Run application

To run the application locally, you can use the following command:

./powerdns-auth-proxy --config <path to config> run

It might be necessary to create (or upgrade) the database schema before actually running the application, this can be realized by the following command:

./powerdns-auth-proxy --config <path to config> db-migrate [--import-file <path to import file>]

⁠run with docker compose

To run the application in a Docker container, you need to create a docker-compose.yml file that can be used to setup the application. The configuration file should be named docker-compose.yml and could be placed anywhere on your local system.

⁠Creating a docker-compose.yml

To run the application in a Docker container, you can use the following docker-compose.yml file as a template. To learn more about the available configuration options, please refer to the section "environment variables".

services:
  api:
    image: tliesche/powerdns-auth-proxy:latest
    environment:
      - AUTH_TYPE=jwt
      - DB_TYPE=sqlite
      - ENABLE_DEBUG=true
      - JWT_AUDIENCE=powerdns-auth-proxy
      - JWT_ISSUER=powerdns-auth-proxy
      - PDNS_API_KEY=changeme
      - PDNS_HOST=pdns-auth.example.com
      - PDNS_PORT=8081
    volumes:
      - proxy-data:/var/lib/powerdns-auth-proxy/data
    ports:
      - "8080:8080"

volumes:
  proxy-data:
    driver: local

networks:
  default:
    external: true
    name: pdns-network

⁠environment variables

The following environment variables can be used to configure the application when running it in a Docker container. Read carefully and extract the parts that match your desired setup for running the application.

¹ Environment variables with prefix DB_MYSQL_ are only mandatory when DB_TYPE is set to mariadb|mysql

² Environment variables with prefix DB_POSTGRES_ are only mandatory when DB_TYPE is set to postgres|postgresql

³ JWT authentication setup:

• SECRET_KEY and PUBLIC_KEY are used when passing key values into the container directly
• SECRET_KEY_PATH and PUBLIC_KEY_PATH are used when passing pre-generated key files via mount into the container
• if none of these is defined, new keys will be generated on first container start and stored in /var/lib/powerdns-auth-proxy/data/

⁠Run application

To run the application in a Docker container, you can use the following command:

docker-compose -f <path to your docker-compose.yaml> -p "<name of your docker compose stack>" up -d

⁠Configuring the Application

To configure the application, you can use the following configuration options:

⁠Admin API Endpoints

The admin API endpoints can be used to manage users, permissions, and roles. To learn more about the available endpoints, please refer to the OpenAPI documentation⁠.

⁠Admin CLI Commands

With the admin CLI commands, you can manage users, permissions, and roles. To learn more about the available commands, please refer to the following section.

NOTE! The admin cli will only manage the authentication proxy layer and NOT change any resources within the PowerDNS server.

⁠Manage Domains

Domains are the main resource that can be managed by the PowerDNS server. To grant access to a domain, you need to add it to the local authorization management first.

⁠Add Domain

You can add a new domain to the PowerDNS authorization proxy by using the following command:

./powerdns-auth-proxy --config <path to config> cli domain add <domain fqdn>

Example response:

Domains successfully created: example.com

⁠List Domains

You can list all domains that are currently managed by the PowerDNS authorization proxy by using the following command:

./powerdns-auth-proxy --config <path to config> cli domain list

Example response:

+----+----------------+---------------------+
| ID |      FQDN      |     LAST UPDATE     |
+----+----------------+---------------------+
|  1 | example.com    | 2025-01-01 12:00:00 |
+----+----------------+---------------------+

⁠Delete Domain

You can delete a domain from the PowerDNS authorization proxy by using the following command:

./powerdns-auth-proxy --config <path to config> cli domain delete <domain fqdn>

Example response:

domain successfully deleted: example.com

⁠Manage Users

Users are the entities that will get granted access to certain resources within the PowerDNS server. To grant access to a user, you need to add it to the local authorization management first.

⁠Add User

You can add a new user to the PowerDNS authorization proxy by using the following command:

./powerdns-auth-proxy --config <path to config> cli user add <username> <password>

Example response:

User successfully created: example-user

⁠List Users

You can list all users that are currently managed by the PowerDNS authorization proxy by using the following command:

./powerdns-auth-proxy --config <path to config> cli user list

Example response:

----+---------------+--------------+-----------------------+---------------------+
| ID | USERNAME     | GLOBAL ROLES | DOMAIN SPECIFIC ROLES |     LAST UPDATE     |
+----+--------------+--------------+-----------------------+---------------------+
|  1 | example-user | none         | none                  | 2025-01-01 12:00:00 |
+----+--------------+--------------+-----------------------+---------------------+

⁠Delete User

You can delete a user from the PowerDNS authorization proxy by using the following command:

./powerdns-auth-proxy --config <path to config> cli user delete <username>

Example response:

User successfully deleted: example-user

⁠Manage Global User Roles

Global user roles are the roles that can be assigned to a user on a global level. These roles will be applied to all domains that are managed by the PowerDNS authorization proxy.

⁠Add Global User Role to User

You can add a new global user role to a user by using the following command:

./powerdns-auth-proxy --config <path to config> cli user role add <username> <role>

Example response:

role successfully added to user: example-user [role: admin]

⁠List Global User Roles

You can list all global user roles that are currently managed by the PowerDNS authorization proxy by using the following command:

./powerdns-auth-proxy --config <path to config> cli user role list <username>

Example response:

+-------+
| ROLE  |
+-------+
| admin |
+-------+

⁠Delete Global User Role from User

You can delete a global user role from a user by using the following command:

./powerdns-auth-proxy --config <path to config> cli user role remove <username> <role>

Example response:

role successfully removed from user: example-user [role: admin]

⁠Manage Domain-Specific User Roles

Domain-specific user roles are the roles that can be assigned to a user on a domain level. These roles will only be applied to the specified domain.

⁠Add Domain-Specific User Role to User

You can add a new domain-specific user role to a user by using the following command:

./powerdns-auth-proxy --config <path to config> cli user role add <username> <domain fqdn> <role>

Example response:

domain role successfully added to user: example-user [domain: example.com, role: admin]

⁠List Domain-Specific User Roles

You can list all domain-specific user roles that are currently managed by the PowerDNS authorization proxy by using the following command:

./powerdns-auth-proxy --config <path to config> cli user role list <username> <domain fqdn>

Example response:

+--------------+-------+
| DOMAIN       | ROLE  |
+--------------+-------+
| example.com  | admin |
+--------------+-------+

⁠Delete Domain-Specific User Role from User

You can delete a domain-specific user role from a user by using the following command:

./powerdns-auth-proxy --config <path to config> cli user role remove <username> <domain fqdn> <role>

Example response:

domain role successfully removed from user: example-user [domain: example.com, role: admin]

⁠Manage API Keys

API keys are the keys that can be used to authenticate against the PowerDNS authorization proxy. To grant access to an API key, you need to add it to the local authorization management first.

⁠Add API Key to User

You can add a new API key to a user by using the following command:

./powerdns-auth-proxy --config <path to config> cli api-key add <username>

Example response:

API key successfully generated for user: $2a$10$GcLqwe.zzXIOiIKev.CwX.iK2aJA/cG4104bhCBZoRSj36zIJW/LK [user: example-user, identifier: JADDkW28MKeH]

⁠List API Keys

You can list all API keys that are currently managed by the PowerDNS authorization proxy by using the following command:

./powerdns-auth-proxy --config <path to config> cli api-key list <username>

Example response:

+----+--------------+--------------+---------------------+
| ID |  IDENTIFIER  |   USERNAME   |      LAST USED      |
+----+--------------+--------------+---------------------+
|  1 | JADDkW28MKeH | example-user | 2025-01-01 12:00:00 |
+----+--------------+--------------+---------------------+

⁠Delete API Key from User

You can delete an API key from a user by using the following command:

./powerdns-auth-proxy --config <path to config> cli api-key delete <identifier>

Example response:

API key successfully deleted: JADDkW28MKeH

⁠Import Configuration Files

Additionally to the CLI commands, you can import configuration files to manage users, permissions, and roles. To learn more about the available configuration options, please refer to the following example.

domains:
  - fqdn: example.com
    deleted: false

users:
  - username: example-user
    password: example-password
    deleted: false
    user_roles:
      - role: admin
        deleted: false
    domain_roles:
      - domain: example.com
        role: admin
        deleted: false

The deleted fields are optional and default to false. If set to true, the import will check if the resource exists and delete it if it does.

To run the import of this yaml file, you can use the db migration command:

./powerdns-auth-proxy --config <path to config> db-migrate [--import-file <path to import file>]

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠Disclaimer

This project is not affiliated with, endorsed by, or sponsored by PowerDNS. It is an independent tool designed to act as an authentication and authorization proxy for the PowerDNS HTTP API. All trademarks, service names, and product names mentioned are the property of their respective owners. The use of "PowerDNS" is solely for descriptive purposes and does not imply any association with or endorsement by PowerDNS. Users are responsible for ensuring compliance with PowerDNS licensing and security requirements when using this tool.