GLAuth on AWS User Guide

Overview

This image runs GLAuth, the open source lightweight LDAP authentication server: a single Go binary that serves an LDAP directory defined entirely by a flat configuration file. It gives downstream services such as dashboards, git forges, wikis, media servers and monitoring tools one shared set of user accounts to authenticate against, and is an opinionated, simpler alternative to running a full OpenLDAP or Active Directory deployment for small environments.

The image installs GLAuth 2.5.0 from the official prebuilt release binary, run under systemd as an unprivileged glauth user with just the CAP_NET_BIND_SERVICE capability so it can bind the standard privileged ports. GLAuth answers plain LDAP on port 389 and LDAPS (LDAP over implicit TLS) on port 636. There is no web interface and no database: the directory lives in the single config file /etc/glauth/glauth.cfg.

Security by design — no default credentials, no demo users. GLAuth's upstream sample config ships several well known demonstration accounts (serviceuser, johndoe, hackers) with published password hashes. None of those ship in this image. On the very first boot of every instance a unique admin bind password is generated, its GLAuth passsha256 hash is written into a fresh glauth.cfg, a per instance self signed TLS certificate is generated for LDAPS, and the login is written to /root/glauth-credentials.txt (mode 0600, root only). No two instances share a credential.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 389 (LDAP) and 636 (LDAPS) from the application subnets that will authenticate against the directory
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Recommended instance type: m5.large (2 vCPU, 8 GB RAM) is ample for a small directory. GLAuth is extremely light; larger sizes are only needed for very high bind volumes.

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for GLAuth. Select the cloudimg listing and choose Select, then Continue on the subscription summary. Pick your instance type (m5.large recommended), your key pair, and a security group configured as described in Step 2, then launch.

Step 2: Launch from the AWS CLI

Substitute the AMI ID for the cloudimg GLAuth listing in your Region, your key pair name, subnet and security group.

AMI_ID="<ami-id>"          # the cloudimg GLAuth AMI in your Region
KEY_NAME="my-keypair"
SUBNET_ID="<subnet-id>"
SG_ID="<security-group-id>"

aws ec2 run-instances \
  --image-id "$AMI_ID" \
  --instance-type m5.large \
  --key-name "$KEY_NAME" \
  --subnet-id "$SUBNET_ID" \
  --security-group-ids "$SG_ID" \
  --metadata-options "HttpTokens=required" \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=glauth}]'

Configure the security group to allow TCP 389 (LDAP) and TCP 636 (LDAPS) from the application subnets that will bind to the directory, and TCP 22 for administration. Keep 389 and 636 restricted to your internal application subnets rather than the whole internet.

Step 3: Connecting to your instance

Connect over SSH as the default login user for the operating system variant you launched, using your EC2 key pair. Once connected, all administration is done with sudo.

Step 4: First boot

On first boot the image generates a unique admin bind password, renders /etc/glauth/glauth.cfg from the shipped template, generates a per instance self signed LDAPS certificate, starts glauth, and writes /root/glauth-credentials.txt. This completes within seconds. SSH in and read the details:

sudo cat /root/glauth-credentials.txt

The file records the admin username (cimgadmin), the generated password, the base DN (dc=glauth,dc=com), the admin bind DN, and the LDAP and LDAPS URIs for this instance.

Step 5: Confirm the service is running

glauth.service is active, glauth --version reports 2.5.0, and ss confirms it is listening on :389 (LDAP) and :636 (LDAPS) on all interfaces.

systemctl is-active glauth.service
/opt/glauth/glauth --version
ss -tlnp | grep -E ':389 |:636 '

Step 6: Search the directory over LDAP

Read the admin password from the credentials file into a shell variable and run an authenticated search against the loopback address. GLAuth returns the directory tree: the base DN, the ou=users and ou=groups containers, the svcaccts group, and the cimgadmin admin account.

PW=$(sudo grep '^GLAUTH_ADMIN_PASSWORD=' /root/glauth-credentials.txt | cut -d= -f2-)
ldapsearch -x -LLL -H ldap://127.0.0.1:389 \
  -D "cn=cimgadmin,ou=svcaccts,dc=glauth,dc=com" -w "$PW" \
  -b "dc=glauth,dc=com" "(objectClass=*)" dn cn uidNumber gidNumber

The admin binds with the short DN cn=cimgadmin,ou=svcaccts,dc=glauth,dc=com. Note that GLAuth reports the canonical entry under an ou=users level, as cn=cimgadmin,ou=svcaccts,ou=users,dc=glauth,dc=com — either form authenticates, and downstream services can use the short bind DN.

Step 7: Connect over LDAPS and confirm bad passwords are rejected

The same directory is served over LDAPS on port 636 with implicit TLS. Because the shipped certificate is per instance and self signed, pass LDAPTLS_REQCERT=never for this test (in production you install your own certificate and validate it). A bind with a wrong password is rejected with LDAP result 49 (Invalid credentials).

PW=$(sudo grep '^GLAUTH_ADMIN_PASSWORD=' /root/glauth-credentials.txt | cut -d= -f2-)
LDAPTLS_REQCERT=never ldapsearch -x -LLL -H ldaps://127.0.0.1:636 \
  -D "cn=cimgadmin,ou=svcaccts,dc=glauth,dc=com" -w "$PW" \
  -b "dc=glauth,dc=com" "(cn=cimgadmin)" dn cn

OUT=$(ldapsearch -x -H ldap://127.0.0.1:389 \
  -D "cn=cimgadmin,ou=svcaccts,dc=glauth,dc=com" -w "wrong-password" \
  -b "dc=glauth,dc=com" "(cn=cimgadmin)" 2>&1 || true)
echo "$OUT" | grep -i "invalid credentials (49)"

Step 8: Review the secure by default configuration

No default or shared credentials ship in the image. The credentials file is 0600 root:root, the admin password is unique to this instance, the directory uses the config file backend, and none of the upstream demo users (serviceuser, johndoe, hackers) are present.

sudo stat -c '%n %a %U:%G' /root/glauth-credentials.txt
grep -E 'datastore|baseDN|name = ' /etc/glauth/glauth.cfg
echo -n 'demo users present: '; grep -cE 'serviceuser|johndoe|hackers|otpuser' /etc/glauth/glauth.cfg || true

Step 9: Add your own users and groups

You manage the directory by editing /etc/glauth/glauth.cfg. Each user is a [[users]] block and each group a [[groups]] block. GLAuth passwords use passsha256, which is the SHA 256 hex digest of the password. Generate a hash for a new user, add the block, and restart the service. This example uses <new-password> as a placeholder for a real password you choose.

# 1) generate the GLAuth passsha256 for the new user's password
printf '%s' '<new-password>' | sha256sum
# 2) add a [[users]] block for the user to /etc/glauth/glauth.cfg (see the snippet below),
#    pasting the hash above into passsha256, then apply the change:
sudo systemctl restart glauth

Add a block like the following to /etc/glauth/glauth.cfg (the primarygroup value is the gidnumber of an existing [[groups]] block):

[[users]]
  name = "alice"
  givenname = "Alice"
  mail = "alice@example.com"
  uidnumber = 5010
  primarygroup = 5501
  passsha256 = "PASTE_THE_SHA256_HEX_HERE"
    [[users.capabilities]]
    action = "search"
    object = "dc=glauth,dc=com"

[[groups]]
  name = "people"
  gidnumber = 5502

After restarting, alice binds as cn=alice,ou=svcaccts,dc=glauth,dc=com (or cn=alice,ou=people,dc=glauth,dc=com if her primary group is people).

Step 10: Point an application at GLAuth

Most self hosted apps authenticate against GLAuth with a bind DN and password. The values below map directly onto the credentials file. This example shows a Grafana [auth.ldap] server block; the same base DN, bind DN and search settings apply to Gitea, Nextcloud, Jenkins, and similar tools.

[[servers]]
host = "<your-glauth-host>"
port = 389
bind_dn = "cn=cimgadmin,ou=svcaccts,dc=glauth,dc=com"
bind_password = "the-admin-password-from-the-credentials-file"
search_filter = "(cn=%s)"
search_base_dns = ["dc=glauth,dc=com"]

For production, create a dedicated read only service account in glauth.cfg for each application rather than reusing the admin bind account, and connect over LDAPS (port 636) with a certificate your clients trust.

Step 11: Replace the LDAPS certificate for production

The image generates a per instance self signed certificate for LDAPS. For production, install a certificate issued for your server's hostname so clients can validate it. Generate or obtain the certificate, point glauth.cfg [ldaps] cert and key at it, and restart. This example uses <your-domain> as a placeholder for your hostname.

sudo openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -nodes \
  -keyout /etc/glauth/certs/glauth.key -out /etc/glauth/certs/glauth.crt \
  -subj "/CN=ldap.<your-domain>"
sudo chown root:glauth /etc/glauth/certs/glauth.key
sudo systemctl restart glauth

Step 12: Security recommendations

• Restrict the security group. Allow TCP 389 and 636 only from the application subnets that authenticate against GLAuth, and TCP 22 for administration only. Do not expose the LDAP ports to the public internet.

• Prefer LDAPS. Use port 636 (implicit TLS) for binds carrying credentials, and install a certificate your clients trust (Step 11).

• Use dedicated service accounts. Create a read only [[users]] account per application with a narrow search capability rather than reusing the admin bind account.

• Protect the config file. /etc/glauth/glauth.cfg holds the password hashes and is 0640 root:glauth. Keep it root owned and back it up; it is the single source of truth for your directory.

• Keep the OS patched. Unattended security upgrades remain enabled on the running instance.

Step 13: Support and Licensing

GLAuth is an open source project distributed under the MIT License. This cloudimg image bundles the unmodified official GLAuth release binary. cloudimg provides the packaging, the systemd hardening, the per instance credential and TLS automation, the paired deploy guide, and 24/7 support with a guaranteed 24 hour response SLA.

cloudimg is not affiliated with or endorsed by the GLAuth project. GLAuth is a mark of its respective owner and is used here only to identify the software.

Deploy on AWS

Find GLAuth on the AWS Marketplace, published by cloudimg. Launch from the console or the AWS CLI as shown above.

Need Help?

Email support@cloudimg.co.uk for deployment help, configuration questions, or licensing enquiries.