Skip to content

Commit d556607

Browse files
authored
Resolve LDAP docs (#1459)
* resolve ldap docs * update docker note
1 parent 6af7625 commit d556607

File tree

1 file changed

+79
-4
lines changed

1 file changed

+79
-4
lines changed

pages/database-management/authentication-and-authorization/auth-system-integrations.mdx

Lines changed: 79 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -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:
611686
The module configuration file is located at:
612687

613688
```
614-
/etc/memgraph/auth_module/ldap.yaml
689+
/etc/memgraph/auth/ldap.yaml
615690
```
616691

617692
An 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

623698
For quick setup, you can copy the example configuration file into the module
@@ -628,7 +703,7 @@ configuration file.
628703
To 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

634709
You can also combine this with other configuration flags listed in
@@ -758,7 +833,7 @@ To enable LDAP integration specify the following flag:
758833
```
759834

760835
Also, add the following LDAP module configuration to
761-
`/etc/memgraph/auth_module/ldap.yaml`:
836+
`/etc/memgraph/auth/ldap.yaml`:
762837

763838
```yaml
764839
server:

0 commit comments

Comments
 (0)