Skip to main content

Lab 6 - Bookstack and LDAP Authentication

In this lab, you will install and configure Bookstack, a self-hosted web wiki tool that allows you to write and share documentation. In fact, this website is an instance of Bookstack. You will also configure Bookstack to utilize LDAP authentication, a precursor to many of the more modern (OIDC/SAML/etc) authentication methods today. As we are approaching the end of the course, this lab will be less guided. Instead, it is expected that you will be able to use the internet to determine the best course of action to complete the requirements below.

Objectives

  • Bookstack is installed and running
  • Bookstack is able to use LDAP authentication
  • Bookstack is accessible beyond your local gateway (OPNSense server)

Stage 1 - Installing Bookstack

Navigate to the bookstack documentation website linked here. Based on your knowledge from previous labs, use this documentation site and resources on the internet to determine the best path forward to install and run bookstack on your Ubuntu server. For a hint, consider how the LDAP server was installed in the previous lab.

As an alternative, you can look into hosting Bookstack and it's dependencies utilizing Proxmox's "LXC Container" functionality. However, this path will likely be more complex than simply using docker within your Ubuntu machine.

Remember, Bookstack is not a standalone application, and will require other software be running in a place it can access (Either locally or remote) in order to function properly. See if you can determine what these pre-requisites might be before you get started.

The Bookstack docs prescribe several different methods for installing and configuring Bookstack. Remember that we will be configuring LDAP authentication in this lab as well.

Stage 2 - Making Bookstack publicly accessible

At this stage, it would be prudent to expose Bookstack beyond your OPNSense. This will make future configuration of the application far easier. Refer back to previous labs if you do not remember how to accomplish this.

A few things to take of note:

  • HTTP's default port is 80
  • HTTPS's default port is 443
  • At the moment, your OPNsense is hosting it's own internal WebGUI over these ports. It's up to you to decide whether you simply want to open new ports for Bookstack, or shift the WebGUI to use alternative ports and route ports 80/443 to your Ubuntu instead

Stage 3 - Setting up LDAP Authentication

LDAP stands for Lightweight Directory Access Protocol. It is essentially a standardized method for different software to query user information from a central database. In Lab 5, we setup an LDAP server on our Ubuntu machine. Now, we must connect Bookstack to it.

Use the Bookstack documentation website and any other accompanying documentation you can find to properly configure LDAP

 

volumes:
    lldap_data:
        driver: local

services:
    # The container for BookStack itself
    bookstack:
        image: lscr.io/linuxserver/bookstack:version-v25.02
        container_name: bookstack
        environment:
            - PUID=1000
            - PGID=1000
            - TZ=America/New_York
            - APP_URL=http://<OPNsense_IP>:6875
            # APP_KEY must be a unique key. Generate your own by running
            # docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey
            # You should keep the "base64:" part for the option value.
            - APP_KEY=base64:3qjlIoUX4Tw6fUQgZcxMbz6lb8+dAzqpvItqHvahW1c=

            # The below database details are purposefully aligned with those
            # configuted for the "mariadb" service below:

            - DB_HOST=mariadb
            - DB_PORT=3306
            - DB_DATABASE=bookstack
            - DB_USERNAME=bookstack
            - DB_PASSWORD=bookstack8432

            - AUTH_METHOD=ldap
            - LDAP_SERVER=lldap:3890
            # If using LDAP over SSL you should also define the protocol:
            # LDAP_SERVER=ldaps://example.com:636

            # The base DN from where users will be searched within
            - LDAP_BASE_DN="ou=people,dc=<your_name>,dc=lan"

            # The full DN and password of the user used to search the server
            # Can both be left as 'false' (without quotes) to bind anonymously
            - LDAP_DN="cn=admin,ou=people,dc=mirom,dc=lan"
            - LDAP_PASS="<ADMIN_PASSWORD>"
            # A filter to use when searching for users
            # The user-provided user-name used to replace any occurrences of '{user}'.
            # (Also supported via '${user}' for backwards compatibility.
            - LDAP_USER_FILTER=(&(uid={user}))
            # Set the LDAP version to use when connecting to the server
            # Should be set to 3 in most cases.
            - LDAP_VERSION=3

            # Set the property to use as a unique identifier for this user.
            # Stored and used to match LDAP users with existing BookStack users.
            # Prefixing the value with 'BIN;' will assume the LDAP service provides the attribute value as
            # binary data and BookStack will convert the value to a hexidecimal representation.
            # Defaults to 'uid'.
            - LDAP_ID_ATTRIBUTE=uid
            # Set the default 'email' attribute. Defaults to 'mail'
            - LDAP_EMAIL_ATTRIBUTE=mail
            # Set the property to use for a user's display name. Defaults to 'cn'.
            # Can have multiple attributes listed, separated with a '|' in which
            # case those values will be joined with a space.
            # Example: LDAP_DISPLAY_NAME_ATTRIBUTE=given_name|family_name
            - LDAP_DISPLAY_NAME_ATTRIBUTE=display_name

            # Set the attribute to use for the user's avatar image.
            # Must provide JPEG binary image data.
            # Will be used upon login or registration when the user doesn't
            # already have an avatar image set.
            # Remove this option or set to 'null' to disable LDAP avatar import.
            # Note: Using this option can increase the likelihood of errors during login
            # due to thumbnail generation which can exhaust available memory in some cases.
            - LDAP_THUMBNAIL_ATTRIBUTE=jpegphoto
        volumes:
            # You generally only ever need to map this one volume.
            # This maps it to a "bookstack_app_data" folder in the same
            # directory as this compose config file.
            - ./bookstack_app_data:/config
        ports:
            # This exposes port 6875 for general web access.
            # Commonly you'd have a reverse proxy in front of this,
            # redirecting incoming requests to this port.
            - 6875:80
        restart: unless-stopped
    lldap:
        image: lldap/lldap:stable
        ports:
            # For LDAP, not recommended to expose, see Usage section.
            # - "3890:3890"
            # For LDAPS (LDAP Over SSL), enable port if LLDAP_LDAPS_OPTIONS__ENABLED set true, look env below
            #- "6360:6360"
            # For the web front-end
            - "17170:17170"
        volumes:
            - "lldap_data:/data"
            # Alternatively, you can mount a local folder
            # - "./lldap_data:/data"
        environment:
            - UID=1000
            - GID=1000
            - TZ=America/New_York
            - LLDAP_JWT_SECRET=0mIhV&))_:j(%!2Tqqx<=Hr[3f#*kmz1
            - LLDAP_KEY_SEED=Mxg%{8Ut;v[FjZRLKbp]L_GPKkZTaKy;
            - LLDAP_LDAP_BASE_DN="dc=<your_name>,dc=lan"
            - LLDAP_LDAP_USER_PASS="<ADMIN_PASSADMIN_PASSWORD>"
            # If using LDAPS, set enabled true and configure cert and key path
            # - LLDAP_LDAPS_OPTIONS__ENABLED=true
            # - LLDAP_LDAPS_OPTIONS__CERT_FILE=/path/to/certfile.crt
            # - LLDAP_LDAPS_OPTIONS__KEY_FILE=/path/to/keyfile.key
            # You can also set a different database:
            # - LLDAP_DATABASE_URL=mysql://mysql-user:password@mysql-server/my-database
            # - LLDAP_DATABASE_URL=postgres://postgres-user:password@postgres-server/my-database
            # If using SMTP, set the following variables
            # - LLDAP_SMTP_OPTIONS__ENABLE_PASSWORD_RESET=true
            # - LLDAP_SMTP_OPTIONS__SERVER=smtp.example.com
            # - LLDAP_SMTP_OPTIONS__PORT=465 # Check your smtp providor's documentation for this setting
            # - LLDAP_SMTP_OPTIONS__SMTP_ENCRYPTION=TLS # How the connection is encrypted, either "NONE" (no encryption, port 25), "TLS" (sometimes called SSL, port 465) or "STARTTLS" (sometim>
            # - [email protected] # The SMTP user, usually your email address
            # - LLDAP_SMTP_OPTIONS__PASSWORD=PasswordGoesHere # The SMTP password
            # - LLDAP_SMTP_OPTIONS__FROM=no-reply <[email protected]> # The header field, optional: how the sender appears in the email. The first is a free-form name, followed by an email >
            # - LLDAP_SMTP_OPTIONS__TO=admin <[email protected]> # Same for reply-to, optional.
    # The container for the database which BookStack will use to store
    # most of its core data/content.
    mariadb:
        # You should update the version here to match the latest
        # main version of the linuxserver mariadb container version:
        # https://github.com/linuxserver/docker-mariadb/pkgs/container/mariadb/versions?filters%5Bversion_type%5D=tagged
        image: lscr.io/linuxserver/mariadb:11.4.4
        container_name: mariadb
        environment:
            - PUID=1000
            - PGID=1000
            - TZ=America/New_York

            # You may want to change the credentials used below,
            # but be aware the latter three options need to align
            # with the DB_* options for the BookStack container.
            - MYSQL_ROOT_PASSWORD=mysupersecretrootpassword
            - MYSQL_DATABASE=bookstack
            - MYSQL_USER=bookstack
            - MYSQL_PASSWORD=bookstack8432
        volumes:
            # You generally only ever need to map this one volume.
            # This maps it to a "bookstack_db_data" folder in the same
            # directory as this compose config file.
            - ./bookstack_db_data:/config

        # These ports are commented out as you don't really need this port
        # exposed for normal use, mainly only if connecting direct the the
        # database externally. Otherwise, this risks exposing access to the
        # database when not needed.
        # ports:
        #   - 3306:3306
        restart: unless-stopped

Deliverables

  1. Bookstack is installed and running on your Ubuntu machine (Or LXC Container)
  2. Bookstack is publicly accessible outside of your assigned VLAN "network"
  3. Bookstack is utilizing your LDAP authentication server for LDAP
Back to top