From 5c8b19ad1c661df65100ced83c5043bc48e54891 Mon Sep 17 00:00:00 2001 From: matea16 Date: Wed, 5 Nov 2025 16:07:20 +0100 Subject: [PATCH 1/2] resolve ldap docs --- .../auth-system-integrations.mdx | 74 ++++++++++++++++++- 1 file changed, 70 insertions(+), 4 deletions(-) diff --git a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx index 1213de444..fcf43dea6 100644 --- a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx +++ b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx @@ -67,6 +67,12 @@ The built-in SSO modules (used with the `saml-entra-id`, `saml-okta`, `oidc-entra-id`, and `oidc-okta` auth schemes) are further configured using **environment variables**. See their respective sections below for more details. +> **Note:** Unlike the SSO modules, which can be configured entirely via +**environment variables**, the LDAP module requires a configuration file +(`/etc/memgraph/auth/ldap.yaml`). This means that in simple deployments (e.g., +Docker) configuration is less flexible and cannot yet be passed purely via +environment variables. + ## Auth module architecture ### Communication protocol @@ -611,13 +617,13 @@ Python 3 libraries installed: The module configuration file is located at: ``` -/etc/memgraph/auth_module/ldap.yaml +/etc/memgraph/auth/ldap.yaml ``` An example configuration file with all settings documented is provided at: ``` -/etc/memgraph/auth_module/ldap.example.yaml +/etc/memgraph/auth/ldap.example.yaml ``` For quick setup, you can copy the example configuration file into the module @@ -628,12 +634,72 @@ configuration file. To enable LDAP authentication and authorization, start Memgraph with: ``` ---auth-module-mappings=basic +--auth-module-mappings=basic:/usr/lib/memgraph/auth_module/ldap.py ``` You can also combine this with other configuration flags listed in [Configuration flags](#configuration-flags) as needed. +#### Docker deployment note + +If you are deploying Memgraph with LDAP in Docker, you must ensure that roles +exist before enabling authentication. + +You can achieve this easily using the `--init-file` flag, which runs a Cypher +script before the database starts. + +A recommended workflow: + + +{

Create a local directory for your Docker setup

} + +``` +my_ldap_init/ +├── Dockerfile +└── roles.cypherl +``` + +{

Define roles in `roles.cypherl`

} + +```cypher +CREATE ROLE superuser; +GRANT ALL PRIVILEGES TO superuser; +CREATE ROLE moderator; +``` + +{

Create the Dockerfile

} + +```dockerfile +FROM memgraph/memgraph:latest + +USER root +COPY roles.cypherl /usr/lib/memgraph/roles.cypherl +USER memgraph +``` + +{

Build the Docker image

} + +``` +docker build -t memgraph-ldap . +``` + +{

Run Memgraph without authentication first (optional)

} + +This step is optional if you are embedding the init file in your image. +You can skip it and go straight to the next step. + +{

Run Memgraph with LDAP enabled and init file executed on startup

} + +``` +docker run -it -p 7687:7687 -p 7444:7444 \ + memgraph-ldap \ + --init-file=/usr/lib/memgraph/roles.cypherl \ + --auth-module-mappings=basic:/usr/lib/memgraph/auth_module/ldap.py +``` + + +This avoids the need to manually stop and restart multiple containers or +recreate volumes. #### Example LDAP directory @@ -758,7 +824,7 @@ To enable LDAP integration specify the following flag: ``` Also, add the following LDAP module configuration to -`/etc/memgraph/auth_module/ldap.yaml`: +`/etc/memgraph/auth/ldap.yaml`: ```yaml server: From 6b9da370492aa7cd90a3386688d86fff9574285a Mon Sep 17 00:00:00 2001 From: matea16 Date: Wed, 12 Nov 2025 12:01:11 +0100 Subject: [PATCH 2/2] update docker note --- .../auth-system-integrations.mdx | 129 ++++++++++-------- 1 file changed, 69 insertions(+), 60 deletions(-) diff --git a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx index fcf43dea6..d642b82d6 100644 --- a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx +++ b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx @@ -73,6 +73,75 @@ The built-in SSO modules (used with the `saml-entra-id`, `saml-okta`, Docker) configuration is less flexible and cannot yet be passed purely via environment variables. +### Docker deployment note + +When deploying Memgraph with **any external authentication module** (for +example, LDAP, SAML, OIDC, or a custom auth module), you must ensure that all +required **roles exist in the database before enabling authentication**. + +External modules return one or more roles for each authenticated user, and +Memgraph matches these roles to existing roles defined in the database. If a +role does not exist at startup, affected users will not be able to log in. + +In containerized environments such as **Docker**, this initialization step can +be automated using the `--init-file` flag, which runs a Cypher script before the +database starts. This approach avoids having to manually stop and restart +containers to create roles later. + +A recommended workflow: + + +{

Create a local directory for your Docker setup

} + +``` +my_auth_init/ +├── Dockerfile +└── roles.cypherl +``` + +{

Define roles in `roles.cypherl`

} + +```cypher +CREATE ROLE superuser; +GRANT ALL PRIVILEGES TO superuser; +CREATE ROLE moderator; +``` + +{

Create the Dockerfile

} + +```dockerfile +FROM memgraph/memgraph:latest + +USER root +COPY roles.cypherl /usr/lib/memgraph/roles.cypherl +USER memgraph +``` + +{

Build the Docker image

} + +``` +docker build -t memgraph-auth . +``` + +{

Run Memgraph with authentication enabled and the init file executed on startup

} + +``` +docker run -it -p 7687:7687 -p 7444:7444 \ + memgraph-auth \ + --init-file=/usr/lib/memgraph/roles.cypherl \ + --auth-module-mappings=basic:/usr/lib/memgraph/auth_module/ldap.py +``` + +> Replace the module mapping with your chosen authentication scheme, e.g. +> oidc-okta, saml-entra-id, etc. + + + + +This approach ensures that all roles are created before the external +authentication module is activated, allowing users to log in seamlessly across +all supported authentication methods. + ## Auth module architecture ### Communication protocol @@ -640,66 +709,6 @@ To enable LDAP authentication and authorization, start Memgraph with: You can also combine this with other configuration flags listed in [Configuration flags](#configuration-flags) as needed. -#### Docker deployment note - -If you are deploying Memgraph with LDAP in Docker, you must ensure that roles -exist before enabling authentication. - -You can achieve this easily using the `--init-file` flag, which runs a Cypher -script before the database starts. - -A recommended workflow: - - -{

Create a local directory for your Docker setup

} - -``` -my_ldap_init/ -├── Dockerfile -└── roles.cypherl -``` - -{

Define roles in `roles.cypherl`

} - -```cypher -CREATE ROLE superuser; -GRANT ALL PRIVILEGES TO superuser; -CREATE ROLE moderator; -``` - -{

Create the Dockerfile

} - -```dockerfile -FROM memgraph/memgraph:latest - -USER root -COPY roles.cypherl /usr/lib/memgraph/roles.cypherl -USER memgraph -``` - -{

Build the Docker image

} - -``` -docker build -t memgraph-ldap . -``` - -{

Run Memgraph without authentication first (optional)

} - -This step is optional if you are embedding the init file in your image. -You can skip it and go straight to the next step. - -{

Run Memgraph with LDAP enabled and init file executed on startup

} - -``` -docker run -it -p 7687:7687 -p 7444:7444 \ - memgraph-ldap \ - --init-file=/usr/lib/memgraph/roles.cypherl \ - --auth-module-mappings=basic:/usr/lib/memgraph/auth_module/ldap.py -``` - - -This avoids the need to manually stop and restart multiple containers or -recreate volumes. #### Example LDAP directory