Hugot Blog

[docs] Notities Over OpenLDAP

Dit zijn mijn notities over OpenLDAP. Deze notities dienen een dubbele functie: ze zijn een referentie voor mezelf bij het leren over OpenLDAP, EN ik hoop anderen er ook wat aan hebben in hun eigen leerproces. Houd er rekening mee dat ik werk vanuit het perspectief van een Software Engineer, niet een certified LDAPer, of hoe zoiets ook mag heten in het vakgebied ;).

Ondanks het feit dat LDAP vaak gebruikt wordt voor authenticatie doeleinden, is het eigenijk gewoon een database die geoptimaliseerd is voor lezen. Bij het lezen van artikelen over LDAP voelt het vaak alsof je in een ongeloofelijk complexe wereld terecht bent gekomen waarin je met domeinspecifieke termen voor enterprise sysadmins om de oren wordt geslagen. Als je geen interesse hebt in active directory functionaliteiten binnen een traditioneel netwerk van linux systemen, dan hoef je je over een heleboel van deze termen niet zoveel zorgen te maken.

LDAP als database voor gebruikersaccounts

De rest van deze notities gaan over het gebruiken van LDAP als een database voor gebruikersaccounts, waar applicaties net als met een RDBMS verbinding mee kunnen maken voor de opslag en het ophalen van data. We behandelen onder andere het opzetten van OpenLDAP, het opzetten van replicatie tussen OpenLDAP instanties en het instellen van een applicatie, authelia, om van het cluster gebruik te maken.

LDAP Termen

Hieronder volgen een paar LDAP-specifieke termen.

DN: Distinguished Name
CN: Common Name
DC: Domain Component
DIT: Directory Information Tree

Een Domain Component is een component van een domein, meestal is dit een DNS domein van een organisatie of applicatie. De componenten van een DNS domein worden begrensd door een punt (.). Dus het domein example.com heeft de componenten “example” en “com”. Een Common Name verschilt van een Domain Component in de zin dat het een generale naam is die niet met domeinen te maken heeft. Een Distinguished Name is de unieke naam van een ldap record, bestaande uit de opstapeling van Common Names, Domain Components en andere attributen waarop een record geselecteerd kunnen worden. Stel we willen de gebruiker met de uid “jan” opzoeken in een LDAP database van de organisatie example.com, dan is de Distinguished Name dus uid=jan,dc=example,dc=com.

Opzetten OpenLDAP

Installeer openldap met het commando apt install slapd ldap-utils. Configureer vervolgens de basis met het commando dpkg-reconfigure slapd.

Configuratie basis tonen: ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn (alleen vanaf root gebruiker). Dit is een speciale ldap directory waarin de configuratie van de server zelf is vastgelegd en gewijzigd kan worden.

Directory Information Tree (DIT) tonen: ldapsearch -x -LLL -H ldapi:/// -b dc=example,dc=com dn (verander domein waar nodig). Dit is de hoofd directory van de ldap server.

Schema’s

Schema’s bepalen, net als mysql table definities, de types van de objecten die in een directory kunnen worden opgeslagen. Bij OpenLDAP worden standaard een aantal schema’s geleverd, maar deze zijn erg uitgebreid en complex, zeker voor gebruikersaccounts van een doorsnee website. Daarom gaan we ons eigen schema maken voor een gebruikerstype met alleen de attributen die we nodig hebben.

objectclass ( 1.3.6.1.4.1.54392.5.1632.1

    NAME 'com-example-Person'

    DESC 'A person affiliated with example.com.'

    STRUCTURAL

    MUST ( uid $ userPassword $ displayName $ mail )

**Private Enterprise Number / OID** Het lange nummer aan het begin van de definitie van de objectclass is een OID. Hiervoor heb je een OID namespace nodig, die een "Private Enterprise Number" wordt genoemd en welke je aan kunt vragen via de IANA. PEN aanvragen worden door mensen beoordeeld en toegekend, dus het kan even duren voordat je aan de beurt bent. Het is een beetje een overgecompliceerd en bureaucratisch systeem waarvan de voordelen mij niet helemaal duidelijk zijn, maar het is nou eenmaal onderdeel van de RFC. Als je geen zin hebt om te wachten op een toekenning van de IANA, dan is er deze website voor verkrijgen van OID zonder menselijke handeling: https://freeoid.pythonanywhere.com/ . Hier krijg je een sub-OID van een PEN die de IANA aan de maker van de website heeft toegekend.

Schema toevoegen

Om het nieuwe schema te gebruiken moeten we de configuratie van de LDAP server aanpassen. Bij oudere versies van OpenLDAP deed je dit door /etc/slapd.conf aan te passen, maar bij meer eigentijdse versies maak je hiervoor gebruik van de speciale configuratie directory binnen de LDAP server, cn=config genoemd.

Deze directory wijzig je net zoals je andere LDAP directories zou wijzigen, namelijk door middel van een ldif (LDAP Data Interchange Format) bestand. Dit is een bestand met omschrijvingen van records die aan een LDAP directory moeten worden toegevoegd. Een beetje zoals een .sql bestand met INSERT queries. Om een ldif bestand te maken van ons schema kunnen we de volgende commando’s uitvoeren:

tmpdir="$(mktemp -d)"

tee > schemas.conf <<EOF

include /etc/ldap/schema/core.schema

include /etc/ldap/schema/cosine.schema

include /etc/ldap/schema/inetorgperson.schema

include /etc/ldap/schema/openldap.schema

include /pad/naar/ons/schema.schema (WIJZIGEN)

EOF

slaptest -f ./schemas.conf -F "$tmpdir"

Dit commando maakt een representatie van een nieuwe cn=config directory in een mappenstructuur met ldif bestanden in een tijdelijke map. Bekijk de ldif bestanden van de geincludeerde schema’s zo:

cd "$tmpdir/cn=config/cn=schema"

ls

Open het ldif bestand dat bij jouw schema hoort. Het heeft dezelfde naam als je aan het schema hebt gegeven, met een cn={x} prefix. Het zou ongeveer de volgende inhoud moeten hebben:

# AUTO-GENERATED FILE - DO NOT EDIT!! Use ldapmodify.

# CRC32 eceebaf6

dn: cn={1}example-com

objectClass: olcSchemaConfig

cn: {1}example-com

olcObjectClasses: {0}( 1.3.6.1.4.1.54392.5.1632.1 NAME com-example-Person' DESC

 'A person affiliated with example.com.' STRUCTURAL MUST ( uid $ userPassword $ displayName $ mail ) )

structuralObjectClass: olcSchemaConfig

entryUUID: 112d022e-5cd9-103d-8da4-6b43adf243c1

creatorsName: cn=config

createTimestamp: 20230322084122Z

entryCSN: 20230322084122.015156Z#000000#000#000000

modifiersName: cn=config

modifyTimestamp: 20230322084122Z

Wijzig dit zodat het er als volgt uitziet:

dn: cn=example-com,cn=schema,cn=config

objectClass: olcSchemaConfig

cn: example-com

olcObjectClasses: {0}( 1.3.6.1.4.1.54392.5.1632.1 NAME com-example-Person' DESC

 'A person affiliated with example.com.' STRUCTURAL MUST ( uid $ userPassword $ displayName $ mail ) )

Dit schema kun je nu aan je configuratie toevoegen door middal van het ldapadd commando: ldapadd -Q -Y EXTERNAL -H ldapi:/// -f /pad/naar/schema.ldif.

Records (Gebruikers) Toevoegen

Voor het toevoegen van een gebruiker hebben we ook weer een ldif bestand nodig, dit keer voor het aanpassen van de feitelijke DIT van het root domein dat we hebben ingesteld bij de installatie van openldap.

dn: uid=hugo,dc=example,dc=com

objectClass: com-example-Person

displayName: Hugo

userPassword: {SSHA}REDACTED

mail: hugo@example.com

Het userPassword veld kun je genereren met het slappasswd commando:

slappasswd -h {SSHA} -s "$(read -rsp 'Password: ' password; echo "$password")"

ldif toepassen op database: ldapadd -D cn=admin,dc=example,dc=com -W -x -H ldapi:/// -f ./adduser.ldif

Records Wijzigen

dn: uid=hugo,dc=example,dc=com

replace: mail

mail: hugo-newmail@maildomain.example.com

ldif met wijziging toepassen: ldapmodify -D cn=admin,dc=example,dc=com -W -x -H ldapi:/// -f ./modifymail.ldif

Records Verwijderen

dn: uid=hugo,dc=example,dc=com

changetype: delete

Records (Gebruikers) Groeperen

Het groeperen van gebruikers kan met het groupOfNames datatype.

dn: cn=superusers,dc=example,dc=com

objectClass: groupOfNames

cn: superusers

description: Administrators and people who found an exploit in our code.

member: uid=hugo,dc=example,dc=com

Gebruiker Toevoegen

dn: cn=superusers,dc=example,dc=com

changetype: modify

add: member

member: uid=hugo,dc=example,dc=com

Gebruiker Verwijderen

dn: cn=superusers,dc=example,dc=com

changetype: modify

delete: member

member: uid=hugo,dc=example,dc=com

Replicatie

Voor replicatie zie deze pagina van de ubuntu documentatie. Er is verder ook documentatie op de openldap website.

SSL/TLS

Het instellen en gebruiken van TLS met openldap is dan misschien onnodig ingewikkeld, maar het is wel nodig voor de beveiligde verbinding van applicaties met de LDAP server.

In het kort: je hebt een root CA nodig, er is genoeg documentatie over hoe deze te produceren met openssl. Verder heb je een cert en een private key nodig. Om hier vervolgens gebruik van te maken moeten we een aantal waardes in onze cn=config directory aanpassen en een waarde aanpassen in het /etc/default/slapd configuratiebestand. Daarna is het nodig om slapd opnieuw op te starten.

Aanpassingen cn=config

dn: cn=config

changetype: modify

add: olcTLSCertificateKeyFile

olcTLSCertificateKeyFile: /etc/ldap/ssl/privkey.pem

add: olcTLSCACertificateFile

olcTLSCACertificateFile: /etc/ldap/ssl/my-root.ca

add: olcTLSCertificateFile

olcTLSCertificateFile: /etc/ldap/ssl/pubkey.crt

Aanpassing /etc/default/slapd

Pas het bestand /etc/default/slapd de waarde van SLAPD_SERVICES aan zodat deze ldaps:/// includeert:

SLAPD_SERVICES="ldap:/// ldapi:/// ldaps:///"

Clients Gebruiken met TLS

Met StartTLS:

LDAPTLS_REQCERT=allow ldapsearch -ZZ -x -LLL -H ldap://ldap.example.com -D cn=admin,dc=example,dc=com -W -b dc=example,dc=com

Of direct met TLS (via ldaps://):

LDAPTLS_REQCERT=allow ldapsearch -x -LLL -H ldaps://ldap.example.com -D cn=admin,dc=example,dc=com -W -b dc=example,dc=com

Authenticatie

De bind-DN cn=admin,dc=example,dc=com kan gebruikt worden voor alle mogelijke wijzigingen. Maar voor het gebruik van de ldap server met andere applicaties zoals authelia, is het toch wel fijn om apparte inlog gegevens aan te maken.

Een bind-DN is eigenlijk niets anders dan een object in de directory tree. Alles dat het attribuut userPassword heeft kan gebruikt worden als bind-DN. Je directory structuur kun je zo gek maken als je zelf wil.

Welke rechten een willekeurige bind-DN over de directory tree krijgt, kan ingesteld worden via access regels in de cn=config database. In de openldap documentatie en in man slapd.access wordt het opstellen van deze regels uitgelegd. Het is sowieso wel aan te raden om andere access regels in te stellen dan de standaard, want zonder aanpassingen geeft openldap alles en iedereen zonder authenticatie lees-rechten.

Voorbeeld: “o=access”

Omdat OpenLDAP veel vrijheid biedt in de structuur van onze directory, en in manieren om rechten van bind-DNs vast te leggen, is het makkelijk om dingen ingewikkelder te maken dan nodig. Een strategie die ik in zulke situaties graag hanteer is kijken hoe andere software projecten het probleem oplossen. Een stuk software waar ik relatief veel ervaring mee heb is MYSQL of, preciezer, mariaDB. MariaDB slaat database gebruikers en hun rechten op in een tabel van de speciale “mysql” database. Dit voorbeeld is daardoor geinspireerd: we gaan een speciale “o=access” directory maken waarin bind-DNs en hun rechten worden vastgelegd. De structuur van onze volledige DIT gaat er als volgt uitzien:

[ (root) dc=example,dc=com ]

  |_ [ (organization) o=access,dc=example,dc=com ]

  |     |

  |     |_ [ (groupOfNames) cn=authentication,o=access,dc=example,dc=com ]

  |     |     |

  |     |     |_ +member: uid=authlia,o=access,dc=example,dc=com

  |     |     |_ +member: uid=registration,o=access,dc=example,dc=com

  |     |

  |     |_ [ (groupOfNames) cn=something-else,o=access,dc=example,dc=com ]

  |     |     |

  |     |     |_ +member: uid=registration,o=access,dc=example,dc=com

  |     |

  |     |_ [ (com-example-Person) uid=authelia,o=access,dc=example,dc=com ]

  |     |_ [ (com-example-Person) uid=registration,o=access,dc=example,dc=com ]

  |_ [ (organization) o=authentication,dc=example,dc=com ]

  |_ [ (organization) o=something-else,dc=example,dc=com ]

Zoals te zien, zal de o=access directory twee soorten objecten bevatten: groupOfNames en com-example-Person. Het cn component van iedere groupOfNames heeft de naam van een andere organization die naast o=access in de DIT bestaat. Door gebruikers van het type com-example-Person als lid van een dergelijke groep toe te voegen, zullen deze gebruikers gebruikt kunnen worden als bind-DNs voor de congruerende organizations. Kort gezegd: als de gebruiker uid=authlia,o=access,dc=example,dc=com aan de groep cn=authentication,o=access,dc=example,dc=com wordt toegevoegd, dan kan de DN van deze gebruiker vanaf dat moment gebruikt worden om toegang te krijgen tot o=authentication,dc=example,dc=com.

Hiermee wordt het volgende bereikt:

Het is makkelijk om een bind-DN toegang te geven tot 1 of meerdere sub-organisaties in de DIT.
Omdat alleen op het root-niveau van de DIT rechten worden beheerd, wordt onnodige complexiteit met rechten in meerdere lagen van sub-directories voorkomen.
Net als een mariaDB database, is de ldap server met het gebruik van organization directories in de root van onze DIT in feite een multi-tennant database geworden. Een organization is in deze context als een schema in een mariaDB/MySQL database. En database gebruikers en hun rechten kunnen per organization worden bijgehouden.

olcAccess in cn=config

Om het bovenstaande mogelijk te maken is wel wat configuratie magie nodig. De regels die gevolgd moeten worden voor het toewijzen van rechten aan een bind-DN bij connectie staan vastgelegd in olcDatabase{1}mdb,cn=config.

dn: olcDatabase={1}mdb,cn=config

changetype: modify

replace: olcAccess

olcAccess: to attrs=userPassword by anonymous auth

olcAccess: to dn.regex="o=([^,]+),dc=example,dc=com$" by group/groupOfNames/member.expand="cn=$1,o=access,dc=example,dc=com" manage

Authelia Configuratie

How To Use Your Email Client For Physical Mail

Whether it's to re-read a conversation, find a plane ticket I ordered or check when a meeting was planned, I often find myself looking up old emails. It's usually easy to do so because email clients are designed for the task: Many of them support full-text search and some even complement that with neat tagging and categorization systems. To be honest I have become completely dependent on those features for my day to day life. Having full-text search and some sort of categorization for email can be a huge time saver. When it comes to physical mail however, I still have to browse through stacks of paper to (hopefully) find what I'm looking for. I figured that it'd be nice to use my fancy email client to deal with physical mail as well, so I found a way to do just that. Turns out it's pretty simple!

The main objective here is to transform our physical mail into an email that can be received, indexed and read by our email client of choice. Now, one way to do that would be to type the contents of our mail into an email by hand, but ain't nobody got time for that!. The (more appealing) alternative is to use a document scanner. I have a single purpose scanner unit from Canon that I hook up to my laptop for just this purpose.

It isn't as simple as just emailing a scanned document to ourselves though: email clients are smart, but they can't understand a word of text in our PDF or JPEG of a physical document. They need content to be in plain text form in order to provide us with some of their best features like full-text search. We'll have to somehow transform our scanned documents into plain text that we can include in our email. To do this, we can use tesseract. Tesseract is an optical character recognition (OCR) engine, meaning that it can recognize text in images and extract it for us. Installing it should be easy on Debian derivative distros like Ubuntu. My laptop is running Debian unstable so I just ran apt install tesseract and started using it. Using it is as easy as upening up a terminal and typing tesseract FILE.jpg OUTPUT. That command will save all the text that tesseract is able to recognize in the image FILE.jpg to a file called OUTPUT.txt.

All we have to do from there is copy-paste the contents of that file into an email and send it to ourselves! Depending on the formatting of the input document, the output may not always be pleasant to read. We can account for this by including the original document as an attachment to the email. That way we get the best of both worlds: we can use the search functionality of our email client to find the document, and then read it in its original form by opening the attachment.

This is all easy enough, but I'm lazy. I didn't feel like opening up my email client and doing manual copy-pasting, so I decided to automate the process a little further. I have postfix setup on my system to relay to my mail server, so I can simply use the mail command to send emails without a GUI mail client. I combined that with tesseract in a little bash script. The script iterates through all of its arguments and interprets them as filenames of scanned documents. It calls tesseract to extract text from them, concatenates the results, attaches the files to an email and sends it to my personal email address. Now all I have to do is run the script with filenames of some documents and my job is done. If anyone is interested in an actual program that does the same thing and doesn't require you to setup postfix, let me know! I might consider authoring one if it's useful to more people than just myself. The script I'm currently using can be found here (pretty) and here (raw), but I don't recommend using it if you don't fully understand its contents, it's not a polished user experience 🤓.

Creating a Simple Static Blog

I love personal websites. It's amazing that people can share content with the entire world just by writing some text and throwing it behind a web server. I wanted to know what that is like, so I set out to create a personal website of my own. As you can see I succeeded in doing so, but getting here wasn't as straight forward as I initially thought it would be. I thought that, being a programmer and knowing a thing or two about web servers, setting up my own website was going to be easy: How complicated can it be to throw some text behind a web server, right?! I was wrong. Throwing text behind a web server can be very complicated (and wasteful). But it doesn't have to be!

The search for a CMS

The first thought that popped into my head when I got started was: I need to find myself a CMS. I had a few requirements: my site should be self-hosted, be lightweight, have no JavaScript in it and it should look pretty. I also wanted to be able to write blog posts in markdown using my trusty text editor. The first CMSes that came to mind were WordPress, Ghost, Jekyll and Hugo. I don't want to get into too much detail, so I'll summarize my judgments here without any nuance: Wordpress is the devil, Ghost is great but too bulky and both Jekyll and Hugo required me to learn about theming and project structure which I deemed too much effort. I just wanted to write some text and throw it behind a web server, but all solutions I saw were sophisticated programs that were designed to "scale", support "modern workflows" or be "easy to use with integrated WYSIWYG editors". I didn't feel like exploring the idea further and gave up on having a website for a while.

Then, a few months back, I learned about writefreely. Writefreely is an open source web application from write.as that lets users create blogs that federate through the fediverse. I had just started to become acquainted with the fediverse and it seemed like a cool idea to me at the time, so me and a friend decided to set up our own instance. It wasn't too hard to set up and once it was running I only needed a couple of hours to add some custom style sheets. I finally had a fully functioning blog that satisfied all of my needs!

After that the holiday season came along and I turned my back on blogging for a while. When I checked on our instance three or four weeks later I was displeased to discover that spammers had created accounts on the instance and were posting spammy garbage. Sure, we could just close registrations. But this event reminded me that hosting any dynamic web application on the public internet is a big responsibility that involves keeping software up to date, monitoring and doing other configuration/maintenance work. Not to mention having to do regular database backups. I didn't feel like having to do any of that, I already have by hands full with self-hosting a bunch of other services. Once again I had found a complicated solution for a simple problem: I just wanted to throw some text behind a web server, remember? Why did I need to use a CMS again?

CMSes seem to offer solutions to a problem that I don't have: I don't mind writing plain html and I most certainly don't need a WISYWIG editor. I also don't need plugins, dynamic code for analytics, pretty yaml or toml configuration files, templates, extensive theming, admin panels, markdown, mailing lists, comment threads or any other common CMS features. I just want to throw some text behind a web server, so why not just write some HTML and do exactly that?

A CMS in ~200 lines

It was decided: I was going to blog in plain HTML. Having figured out what I actually wanted, I went to work. The first order of business was creating a style sheet to make things look good. I made it my goal to use as little CSS as possible and I managed to limit myself to just these 23 lines:

  html {
    font-family: Helvetica, Arial, sans-serif;
    color: #5b4636;
    background-color: #f4ecd8;
  }

  body {
    padding: 1em;
    margin: auto;
  }

  @media only all and (pointer: coarse), (pointer: none) {
    body {
      font-size: 5.5vmin;
    }
  }

  @media only all and (pointer: fine) {
    body {
      font-size: calc(16px + 0.6vmin);
      min-width: 500px;
      max-width: 50em;
    }
  }

This is all the CSS I need to have a responsive website that looks pretty (I stole the colors from firefox's reader mode btw). It's such a small amount that I don't mind copy-pasting it at the top of all new HTML pages that I add to my website. This might make it harder to change the styling later, but it has the added benefit that each page is a standalone document. So for example wget PAGE_URL will download a HTML page that looks exactly the same locally as it does on the web without having to download any extra assets.

The next challenge was creating and maintaining the article listing page and the RSS feed for the blog. I don't mind typing HTML pages, but typing out a page and an RSS feed containing excerpts/titles from other files gets old soon and I'd be bound to forget updating its content every once in a while. This seemed like a perfect occasion to write a little bash script, so I did. You can find the script here. What it basically does is read in a file called posts.txt that has html filenames in it, separated by newlines. Using those filenames and the contents of the files it then generates a HTML page (called blog.html) and an RSS feed (called feed.xml).

I keep all of this neatly stored under version control here, so deploying a new version is as easy as running git pull on my web server. I can honestly say that this is the simplest, most user-friendly CMS that I have ever used, and it only took me several months to figure out that this is exactly what I needed 🤓.

So, to conclude this story: websites are just HTML. You don't need fancy programs or WYSIWYG editors to create a website. Just a text editor, a web server and some spare time.

Introduction

Hello, welcome to my blog! My name is Hugo. I am a 22 year old Software Engineering student from the Netherlands. Software development is a huge part of my life, I write a lot of (weird) programs to scratch my own itch and most software I create is open source by default. I also run a one-man company that provides some IT services on the side.

Between working on projects and studying I like to watch movies & series, listen to music & podcasts, ride my road bike and take hikes.

What kind of blog is this?

Because I'm quite new to this and I want to keep myself interested, I won't be limiting myself to a single topic. You can expect me to post about a variety of topics that may interest/annoy/excite me at any given moment.

May my posts be interesting and my posting schedule be consistent 🤓🖖

I hope to see you around! - Hugo