@@ -67,6 +67,81 @@ The built-in SSO modules (used with the `saml-entra-id`, `saml-okta`,
6767` oidc-entra-id ` , and ` oidc-okta ` auth schemes) are further configured using
6868** environment variables** . See their respective sections below for more details.
6969
70+ > ** Note:** Unlike the SSO modules, which can be configured entirely via
71+ ** environment variables** , the LDAP module requires a configuration file
72+ (` /etc/memgraph/auth/ldap.yaml ` ). This means that in simple deployments (e.g.,
73+ Docker) configuration is less flexible and cannot yet be passed purely via
74+ environment variables.
75+
76+ ### Docker deployment note
77+
78+ When deploying Memgraph with ** any external authentication module** (for
79+ example, LDAP, SAML, OIDC, or a custom auth module), you must ensure that all
80+ required ** roles exist in the database before enabling authentication** .
81+
82+ External modules return one or more roles for each authenticated user, and
83+ Memgraph matches these roles to existing roles defined in the database. If a
84+ role does not exist at startup, affected users will not be able to log in.
85+
86+ In containerized environments such as ** Docker** , this initialization step can
87+ be automated using the ` --init-file ` flag, which runs a Cypher script before the
88+ database starts. This approach avoids having to manually stop and restart
89+ containers to create roles later.
90+
91+ A recommended workflow:
92+
93+ <Steps >
94+ { <h4 className = " custom-header" >Create a local directory for your Docker setup</h4 >}
95+
96+ ```
97+ my_auth_init/
98+ ├── Dockerfile
99+ └── roles.cypherl
100+ ```
101+
102+ { <h4 className = " custom-header" >Define roles in `roles.cypherl`</h4 >}
103+
104+ ``` cypher
105+ CREATE ROLE superuser;
106+ GRANT ALL PRIVILEGES TO superuser;
107+ CREATE ROLE moderator;
108+ ```
109+
110+ { <h4 className = " custom-header" >Create the Dockerfile</h4 >}
111+
112+ ``` dockerfile
113+ FROM memgraph/memgraph:latest
114+
115+ USER root
116+ COPY roles.cypherl /usr/lib/memgraph/roles.cypherl
117+ USER memgraph
118+ ```
119+
120+ { <h4 className = " custom-header" >Build the Docker image</h4 >}
121+
122+ ```
123+ docker build -t memgraph-auth .
124+ ```
125+
126+ { <h4 className = " custom-header" >Run Memgraph with authentication enabled and the init file executed on startup</h4 >}
127+
128+ ```
129+ docker run -it -p 7687:7687 -p 7444:7444 \
130+ memgraph-auth \
131+ --init-file=/usr/lib/memgraph/roles.cypherl \
132+ --auth-module-mappings=basic:/usr/lib/memgraph/auth_module/ldap.py
133+ ```
134+
135+ > Replace the module mapping with your chosen authentication scheme, e.g.
136+ > oidc-okta, saml-entra-id, etc.
137+
138+ </Steps >
139+
140+
141+ This approach ensures that all roles are created before the external
142+ authentication module is activated, allowing users to log in seamlessly across
143+ all supported authentication methods.
144+
70145## Auth module architecture
71146
72147### Communication protocol
@@ -611,13 +686,13 @@ Python 3 libraries installed:
611686The module configuration file is located at:
612687
613688```
614- /etc/memgraph/auth_module /ldap.yaml
689+ /etc/memgraph/auth /ldap.yaml
615690```
616691
617692An example configuration file with all settings documented is provided at:
618693
619694```
620- /etc/memgraph/auth_module /ldap.example.yaml
695+ /etc/memgraph/auth /ldap.example.yaml
621696```
622697
623698For quick setup, you can copy the example configuration file into the module
@@ -628,7 +703,7 @@ configuration file.
628703To enable LDAP authentication and authorization, start Memgraph with:
629704
630705```
631- --auth-module-mappings=basic
706+ --auth-module-mappings=basic:/usr/lib/memgraph/auth_module/ldap.py
632707```
633708
634709You can also combine this with other configuration flags listed in
@@ -758,7 +833,7 @@ To enable LDAP integration specify the following flag:
758833```
759834
760835Also, add the following LDAP module configuration to
761- ` /etc/memgraph/auth_module /ldap.yaml ` :
836+ ` /etc/memgraph/auth /ldap.yaml ` :
762837
763838``` yaml
764839server :
0 commit comments