From fb8cb0ac979af98d99992c60c2e82523b4776498 Mon Sep 17 00:00:00 2001 From: matea16 Date: Wed, 5 Nov 2025 15:11:24 +0100 Subject: [PATCH] make ldap docs clearer --- next.config.mjs | 76 +++ .../authentication-and-authorization.mdx | 10 +- .../auth-system-integrations.mdx | 637 +++++++++++------- 3 files changed, 466 insertions(+), 257 deletions(-) diff --git a/next.config.mjs b/next.config.mjs index 5cd5a5779..aa99e3eae 100644 --- a/next.config.mjs +++ b/next.config.mjs @@ -3435,6 +3435,82 @@ export default withNextra({ destination: '/getting-started/build-memgraph-from-source#run-memgraph', permanent: true }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#flags', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#configuration-flags', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#communication', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#communication-protocol', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#single-role-response-backward-compatible', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#multiple-roles-support', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#multiple-roles-response-new-format', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#multiple-roles-support', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#single-role-in-array-format', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#multiple-roles-support', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#entra-id', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#configuration-1', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#okta', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#configuration-1', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#openid-connect-oidc', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#openid-connect', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#custom-auth', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#custom-oidc-provider', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#username', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#username-configuration', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#basic-username--password-auth', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#basic-authentication', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#ldap', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#ldap-authentication', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#example', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#example-ldap-directory', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#authentication', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#authentication-workflow', + permanent: true + }, + { + source: '/database-management/authentication-and-authorization/auth-system-integrations#authorization', + destination: '/database-management/authentication-and-authorization/auth-system-integrations#authorization-and-role-mapping', + permanent: true + }, + // END: NEW MEMGRAPH LAB REDIRECTS diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index 9017ce078..4bf66f19b 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -124,24 +124,24 @@ documentation. Learn how to manage users in Memgraph. -## [Role-based access control](/database-management/authentication-and-authorization/role-based-access-control) (Enterprise) +## [Role-based access control](/database-management/authentication-and-authorization/role-based-access-control) Enterprise Learn how to manage roles, set up their privileges and fine-grained access control. -## [Multi-role users and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles) (Enterprise) +## [Multi-role users and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles) Enterprise Learn how to assign multiple roles to users simultaneously and understand how permissions are combined from all roles. -## [Auth system integrations](/database-management/authentication-and-authorization/auth-system-integrations) (Enterprise) +## [Auth system integrations](/database-management/authentication-and-authorization/auth-system-integrations) Enterprise Learn how to integrate with third-party auth systems and manage user authentication and access control using Memgraph's auth module. -## [Impersonate user](/database-management/authentication-and-authorization/impersonate-user) (Enterprise) +## [Impersonate user](/database-management/authentication-and-authorization/impersonate-user) Enterprise Learn how the impersonate user feature enables authorized users to execute queries with the full permissions and context of another user. -## [User profiles](/database-management/authentication-and-authorization/user-profiles) (Enterprise) +## [User profiles](/database-management/authentication-and-authorization/user-profiles) Enterprise Learn how to manage user profiles and set resource limits for users to control resource consumption and prevent abuse. \ No newline at end of file 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 b5f22d743..1213de444 100644 --- a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx +++ b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx @@ -6,30 +6,35 @@ description: Learn how to integrate with third-party auth systems. Manage user a import { Steps } from 'nextra/components' import { Callout } from 'nextra/components' -# Auth system integrations (Enterprise) +# Auth system integrations Enterprise Memgraph supports authentication and authorization using external auth modules. It includes built-in support for basic (username and password) authentication via LDAP, as well as single sign-on over the SAML and OIDC protocols. -When a user is connecting, Memgraph will forward the user’s supplied -credentials (username and password, or scheme and auth response) to the -external auth module and retrieve its verdict. Based on this verdict, Memgraph -will either allow the user to connect or, in case of failure, close the -connection. +When a user connects, Memgraph forwards the supplied credentials (username and +password, or an auth scheme and response) to the external module. The module +returns an authentication verdict and based on that, Memgraph either allows or +denies access. -As this is an Enterprise feature, once the Memgraph Enterprise license expires, -newly created users will be granted all privileges. The existing users' -privileges will still apply but you won't be able to manage them. +> **Note:** As this is an Enterprise feature, once the Memgraph Enterprise +license expires, newly created users will be granted all privileges. The +existing users' privileges will still apply but you won't be able to manage them +further. ## Configuration ### Roles -User roles must be defined in Memgraph before using auth modules because these -modules return the role(s) associated with the user. As of v3.5 Memgraph supports multiple roles per user, allowing auth modules to return either a single role or multiple roles. +Before using any external authentication module, you must define the +corresponding **roles in Memgraph**. External modules return the role or roles +associated with a user and Memgraph matches these to existing roles. -### Flags +As of v3.5, Memgraph supports assigning **multiple roles per user**, meaning an +external auth module can return a single role or a list of roles. + + +### Configuration flags Use the following configuration flags to configure the external auth module authentication and authorization mechanisms used by Memgraph. @@ -39,15 +44,18 @@ authentication and authorization mechanisms used by Memgraph. `--auth-module-mappings` | Associates auth schemes to external modules. A mapping is structured as follows: `:` and individual entries are separated with `;`. If the mapping contains whitespace, enclose the flag value with quotation marks. `--auth-module-executable` | [DEPRECATED] Path to the executable that should be used for user authentication/authorization. Replaced by `--auth-module-mappings=basic` from Memgraph 2.18. `--auth-module-timeout-ms` | Specifies the maximum time that Memgraph will wait for a response from the external auth module. - `--auth-password-permit-null` | Can be set to false to disable null passwords. + `--auth-password-permit-null` | Can be set to `false` to disable null passwords. `--auth-password-strength-regex` | The regular expression that should be used to match the entire entered password to ensure its strength. Auth schemes that have built-in Memgraph support have default module paths. To enable them, you only need to list the auth schemes themselves, e.g. -`--auth-module-mappings=basic;saml-entra-id;oidc-okta`. -The schemes with built-in support are: -* `basic` (username + password authentication with external module) +``` +--auth-module-mappings=basic;saml-entra-id;oidc-okta +``` + +**Built-in authentication schemes** +* `basic` - username and password authentication via external module * `saml-entra-id` * `saml-okta` * `oidc-entra-id` @@ -55,46 +63,53 @@ The schemes with built-in support are: ### Environment variables -The built-in auth modules (used with the `saml-entra-id`, `saml-okta`, +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 the individual SSO module sections for more detail. +**environment variables**. See their respective sections below for more details. ## Auth module architecture -### Communication - -Memgraph uses inter-process pipes to communicate with the module. The module -will receive auth requests on file descriptor `1000` and has to return auth -responses to file descriptor `1001`. The standard streams (`stdin` and `stdout`) -aren't used because external libraries often tend to write something to `stdout` -which is difficult to disable. By using separate file descriptors, `stdout` is -left intact and can be used freely for debugging purposes (along with `stderr`). - -The protocol used between Memgraph and the module is as follows: - - Each auth request is sent as a JSON encoded object in a single line that is - terminated by a `\n`. - - Each auth response must be sent as a JSON encoded object in a single line - that is terminated by a `\n`. - - Auth requests are objects that contain the following fields: - - `basic` auth scheme: - - `username` - the user's username - - `password` - the user's password - - other auth schemes: - - `scheme` - the string representing the auth method, e.g. `oidc-entra-id` - - `response` - the authentication response (e.g. SAML response or JWT) - - Auth responses must be objects that contain the following fields: - - `authenticated` - a `bool` indicating whether the user is allowed to log - in to the database - - `role` - a `string` indicating which role the user should have (backward compatible) - - `roles` - an array of strings indicating which roles the user should have (new format) - - `username` - the user's username (optional) - - `errors` (optional) - if `authenticated` is false, Memgraph will put up a - warning with the error message returned by the module - -If the external auth module crashes during the processing of an auth request, -Memgraph won't allow the user to log in to the database and will automatically -restart the auth module for the next auth request. All crash logs will be seen -in Memgraph's output (typically in `systemd` logs using `journalctl`). +### Communication protocol + +Memgraph communicates with external auth modules through inter-process pipes: +- **Input (from Memgraph)**: file descriptor `1000` +- **Output (to Memgraph)**: file descriptor `1001` + +The standard streams (`stdin` and `stdout`) aren't used because external +libraries often tend to write something to `stdout` which is difficult to +disable. By using separate file descriptors, `stdout` is left intact and can be +used freely for debugging purposes (along with `stderr`). + +**Protocol format** + +Each request and response is a **single-line JSON object** terminated by `\n`. + +**Auth request structure** + +| Field | Description | +| ---------- | ------------------------------------------------------------- | +| `username` | User’s username (for `basic` scheme) | +| `password` | User’s password (for `basic` scheme) | +| `scheme` | Authentication method (for SSO schemes, e.g. `oidc-entra-id`) | +| `response` | Authentication response (e.g. SAML or JWT token) | + + +**Auth response structure** + +| Field | Type | Description | +| --------------- | ------------------- | ------------------------------------------ | +| `authenticated` | `bool` | Whether the user is allowed to connect | +| `role` | `string` | Single role (backward compatibility) | +| `roles` | `array[string]` | One or more roles (preferred format) | +| `username` | `string` (optional) | The authenticated username | +| `errors` | `string` (optional) | Error message in case authentication fails | + + +If the external module crashes during processing, Memgraph denies login and +automatically restarts the module for the next request. Crash logs are available +in Memgraph’s system logs (for example, via `journalctl` when running under +`systemd`). + ### Multiple roles support @@ -102,7 +117,7 @@ in Memgraph's output (typically in `systemd` logs using `journalctl`). responses. Auth modules can return either a single role (backward compatible) or multiple roles (new format). -#### Single role response (backward compatible) +{

Single role

} ```python def authenticate(username, password): @@ -112,7 +127,7 @@ def authenticate(username, password): } ``` -#### Multiple roles response (new format) +{

Multiple roles

} ```python def authenticate(username, password): @@ -122,7 +137,7 @@ def authenticate(username, password): } ``` -#### Single role in array format +{

Single role in array format

} ```python def authenticate(username, password): @@ -132,22 +147,21 @@ def authenticate(username, password): } ``` -The system will: -1. First check for a `roles` field in the response -2. If `roles` is an array, use all roles in the array -3. If `roles` is a string, use it as a single role -4. If no `roles` field is found, fall back to the `role` field for backward - compatibility -5. If no valid roles are found, authentication fails +Memgraph processes roles as follows: +1. Use `roles` if present. +2. If `roles` is a list, all listed roles are applied. +3. If `roles` is a string, use it as a single role. +4. If no `roles` are found, fall back to `role`. +5. If no valid roles exist, authentication fails. When a user has multiple roles, their permissions are combined using the following rules: - **Grants**: If any role grants a permission, the user has that permission - **Denies**: If any role denies a permission, the user is denied that permission -- **Database Access**: If any role grants and no role denies access to a +- **Database access**: If any role grants and no role denies access to a database, the user has access -- **Fine-grained Permissions**: Combined using the same grant/deny logic +- **Fine-grained permissions**: Combined using the same grant/deny logic ### Module example @@ -203,45 +217,78 @@ assert module.authenticate("moderator_user", "password") == {"authenticated": Tr Single sign-on (SSO) lets you use an external ID to log in to Memgraph from [Lab](/data-visualization/user-manual/single-sign-on). -The built-in SSO modules let you customize which data from the identity service -supplies the username and password. Username configuration is service- and -protocol-specific, whereas role configuration works universally via remapping. +Memgraph provides **built-in SSO modules** that let you customize which identity +service fields define the **username** and **roles** of authenticated users. +Username configuration is **provider- and protocol-specific**, while role +configuration works universally through **role mapping**. + +### Role mapping + +Use the `MEMGRAPH_SSO_{provider}_{protocol}_ROLE_MAPPING` environment variable +to define how identity service roles map to Memgraph roles. -The `MEMGRAPH_SSO_{provider}_{protocol}_ROLE_MAPPING` flags define how the -identity service roles correspond to Memgraph’s. +Mappings follow this format: -The role mapping is defined as a string where individual mappings are separated -by a semicolon `;`. Each mapping is structured as follows: -`{identity service role}:{Memgraph role}, {another Memgraph role}, ...`. +``` +{identity_service_role}:{Memgraph_role}, {another_Memgraph_role}; {next_mapping} +``` -One identity service role can be mapped to one or more Memgraph roles. -When a user logs in and is assigned an identity service role that is mapped to an array of Memgraph roles, the user is assigned all of the mapped Memgraph roles. -For more information regarding how multi-role users are handled by Memgraph, please visit [Multi-role users and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles). +Each mapping pair is separated with a semicolon `;`. +One identity service role can map to one or multiple Memgraph roles. -For example, the `entra.admin:memadmin; entra.user:memuser` mapping defines -that the identity service roles `entra.admin` and `entra.user` respectively map -to Memgraph’s `memadmin` and `memuser` roles. +{

Example mappings

} -`entra.admin:memadmin; entra.user:memuser, memdev` maps `entra.user` to `memuser` and `memdev`. +```bash +entra.admin:memadmin; entra.user:memuser +``` -Different services use different parameters for defining roles. -Use `MEMGRAPH_SSO_{provider}_{protocol}_ROLE_FILED` to specify the token parameter that specifies the assigned roles. +Maps: +- `entra.admin` → `memadmin` +- `entra.user` → `memuser` + +``` +entra.admin:memadmin; entra.user:memuser, memdev +``` + +Maps: +- `entra.user` → `memuser` and `memdev` + + +When a user logs in and is assigned an identity service role that is mapped to +an array of Memgraph roles, the user is assigned all of the mapped Memgraph +roles. + +For more information regarding how multi-role users are handled by +Memgraph, please visit [Multi-role users and multi-tenant +roles](/database-management/authentication-and-authorization/multiple-roles). + + +Different services use different parameters for defining roles. Use +`MEMGRAPH_SSO_{provider}_{protocol}_ROLE_FILED` to specify the token parameter +that specifies the assigned roles. For correct operation, the Memgraph roles defined in the mapping need to be -created in the Memgraph DB beforehand. Additionally, you have to grant [label-based permissions](/database-management/authentication-and-authorization/role-based-access-control#label-based-access-control) to the roles used in SSO. +created in the Memgraph DB beforehand. Additionally, you have to grant +[label-based +permissions](/database-management/authentication-and-authorization/role-based-access-control#label-based-access-control) +to the roles used in SSO. -SSO identity providers often return multiple roles for users. Memgraph now supports this natively - if your identity provider returns multiple roles, they will all be mapped to Memgraph roles and the user will have permissions from all assigned roles combined. +SSO identity providers often return multiple roles for users. Memgraph now +supports this natively - if your identity provider returns multiple roles, they +will all be mapped to Memgraph roles and the user will have permissions from all +assigned roles combined. ### SAML -Memgraph has built-in support for single sign-on (SSO) over the SAML protocol -with the Microsoft Entra ID and Okta identity providers. +Memgraph supports SAML-based SSO with the following identity providers: +- Microsoft Entra ID +- Okta #### Configuration @@ -249,74 +296,66 @@ To enable SAML SSO using the built-in auth modules, set the `--auth-module-mappings` with the `saml-entra-id` or `saml-okta` schemes, e.g. `--auth-module-mappings=saml-entra-id;saml-okta` (or just one of them). + +#### Environment variables + The following environment variables are used to configure the built-in SAML module: -##### Entra ID - -* `MEMGRAPH_SSO_ENTRA_ID_SAML_CALLBACK_URL`: the same as - `AUTH_SAML_ENTRA_ID_CALLBACK_URL` for - [Memgraph Lab](/data-visualization/user-manual/single-sign-on#set-up-lab-integration) -* `MEMGRAPH_SSO_ENTRA_ID_SAML_ASSERTION_AUDIENCE`: the - [application audience](https://learn.microsoft.com/en-us/entra/identity-platform/msal-client-application-configuration#application-audience); - for single-tenant apps, equal to `spn:{tenant id}` -* `MEMGRAPH_SSO_ENTRA_ID_SAML_IDP_CERT`: the path to the application’s - [SAML certificate](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#set-up-authentication) -* `MEMGRAPH_SSO_ENTRA_ID_SAML_IDP_ID`: equal to `https://sts.windows.net/{tenant id}/` -* `MEMGRAPH_SSO_ENTRA_ID_SAML_ASSERTIONS_ENCRYPTED`: set to true if Entra ID is - configured to encrypt assertions in the SAML response -* `MEMGRAPH_SSO_ENTRA_ID_SAML_SP_PRIVATE_KEY`: if using a private key to - decrypt assertions, set this flag’s value to the path to the key -* `MEMGRAPH_SSO_ENTRA_ID_SAML_WANT_ATTRIBUTE_STATEMENT`: set to true if the - Entra ID SAML response is required to contain attributes -* `MEMGRAPH_SSO_ENTRA_ID_SAML_USE_NAME_ID`: set to true in order to supply the - username from the SAML NameID attribute -* `MEMGRAPH_SSO_ENTRA_ID_NAME_ID_ENCRYPTED`: set to true if Entra ID is - configured to encrypt the NameID element -* `MEMGRAPH_SSO_ENTRA_ID_SAML_USERNAME_ATTRIBUTE`: if not using NameID, set the - name of the SAML response attribute that contains the username -* `MEMGRAPH_SSO_ENTRA_ID_SAML_ROLE_MAPPING`: the [role mapping](#single-sign-on) - -##### Okta - -* `MEMGRAPH_SSO_OKTA_SAML_CALLBACK_URL`: the same as - `AUTH_SAML_OKTA_CALLBACK_URL` for - [Memgraph Lab](/data-visualization/user-manual/single-sign-on#set-up-lab-integration-1) -* `MEMGRAPH_SSO_OKTA_SAML_ASSERTION_AUDIENCE`: the - [application audience](https://help.okta.com/oag/en-us/content/topics/access-gateway/add-app-saml-pass-thru-add-okta.htm) -* `MEMGRAPH_SSO_OKTA_ID_SAML_IDP_CERT`: the path to the application’s - [SAML certificate](https://help.okta.com/oie/en-us/content/topics/apps/manage-signing-certificates.htm) -* `MEMGRAPH_SSO_OKTA_SAML_IDP_ID`: the - [Okta issuer URL](https://support.okta.com/help/s/article/What-is-theIssuerlocated-under-the-OpenID-Connect-ID-Token-app-settings-used-for) -* `MEMGRAPH_SSO_OKTA_SAML_ASSERTIONS_ENCRYPTED`: set to true if Okta is - configured to encrypt assertions in the SAML response -* `MEMGRAPH_SSO_OKTA_SAML_SP_PRIVATE_KEY`: if using a private key to decrypt - assertions, set this flag’s value to the path to the key -* `MEMGRAPH_SSO_OKTA_SAML_WANT_ATTRIBUTE_STATEMENT`: set to true if the Okta - SAML response is required to contain attributes -* `MEMGRAPH_SSO_OKTA_SAML_USE_NAME_ID`: set to true in order to supply the - username from the SAML NameID attribute -* `MEMGRAPH_SSO_OKTA_NAME_ID_ENCRYPTED`: set to true if Okta is configured to - encrypt the NameID element -* `MEMGRAPH_SSO_OKTA_SAML_USERNAME_ATTRIBUTE`: if not using NameID, set the - name of the SAML response attribute that contains the username -* `MEMGRAPH_SSO_OKTA_SAML_ROLE_ATTRIBUTE`: set the name of the SAML response - attribute that contains the user role -* `MEMGRAPH_SSO_OKTA_SAML_ROLE_MAPPING`: the [role mapping](#single-sign-on) - -### OpenID Connect (OIDC) - -Memgraph also supports authentication and authorization using OIDC (OIDC + OAuth 2.0) protocol with a -built-in auth module that is packaged with Memgraph Enterprise. - -The module currently supports the following SSO providers: +{
Microsoft Entra ID
} + +| Variable | Description | +| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `MEMGRAPH_SSO_ENTRA_ID_SAML_CALLBACK_URL` | Matches `AUTH_SAML_ENTRA_ID_CALLBACK_URL` used by [Memgraph Lab](/data-visualization/user-manual/single-sign-on#set-up-lab-integration). | +| `MEMGRAPH_SSO_ENTRA_ID_SAML_ASSERTION_AUDIENCE` | The [application audience](https://learn.microsoft.com/en-us/entra/identity-platform/msal-client-application-configuration#application-audience); for single-tenant apps, use `spn:{tenant id}`. | +| `MEMGRAPH_SSO_ENTRA_ID_SAML_IDP_CERT` | Path to the app’s [SAML certificate](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#set-up-authentication). | +| `MEMGRAPH_SSO_ENTRA_ID_SAML_IDP_ID` | Set to `https://sts.windows.net/{tenant id}/`. | +| `MEMGRAPH_SSO_ENTRA_ID_SAML_ASSERTIONS_ENCRYPTED` | `true` if assertions are encrypted. | +| `MEMGRAPH_SSO_ENTRA_ID_SAML_SP_PRIVATE_KEY` | Path to the private key for decrypting assertions (if used). | +| `MEMGRAPH_SSO_ENTRA_ID_SAML_WANT_ATTRIBUTE_STATEMENT` | `true` if the SAML response must contain attributes. | +| `MEMGRAPH_SSO_ENTRA_ID_SAML_USE_NAME_ID` | `true` to use the `NameID` attribute as the username. | +| `MEMGRAPH_SSO_ENTRA_ID_NAME_ID_ENCRYPTED` | `true` if `NameID` is encrypted. | +| `MEMGRAPH_SSO_ENTRA_ID_SAML_USERNAME_ATTRIBUTE` | Name of the SAML response attribute containing the username (if not using `NameID`). | +| `MEMGRAPH_SSO_ENTRA_ID_SAML_ROLE_MAPPING` | The [role mapping](#role-mapping) string. | + + +{
Okta
} + +| Variable | Description | +| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `MEMGRAPH_SSO_OKTA_SAML_CALLBACK_URL` | Matches `AUTH_SAML_OKTA_CALLBACK_URL` used by [Memgraph Lab](/data-visualization/user-manual/single-sign-on#set-up-lab-integration-1). | +| `MEMGRAPH_SSO_OKTA_SAML_ASSERTION_AUDIENCE` | The [application audience](https://help.okta.com/oag/en-us/content/topics/access-gateway/add-app-saml-pass-thru-add-okta.htm). | +| `MEMGRAPH_SSO_OKTA_ID_SAML_IDP_CERT` | Path to the app’s [SAML certificate](https://help.okta.com/oie/en-us/content/topics/apps/manage-signing-certificates.htm). | +| `MEMGRAPH_SSO_OKTA_SAML_IDP_ID` | The [Okta issuer URL](https://support.okta.com/help/s/article/What-is-theIssuerlocated-under-the-OpenID-Connect-ID-Token-app-settings-used-for). | +| `MEMGRAPH_SSO_OKTA_SAML_ASSERTIONS_ENCRYPTED` | `true` if assertions are encrypted. | +| `MEMGRAPH_SSO_OKTA_SAML_SP_PRIVATE_KEY` | Path to the private key for decrypting assertions (if used). | +| `MEMGRAPH_SSO_OKTA_SAML_WANT_ATTRIBUTE_STATEMENT` | `true` if the SAML response must contain attributes. | +| `MEMGRAPH_SSO_OKTA_SAML_USE_NAME_ID` | `true` to use the `NameID` attribute as the username. | +| `MEMGRAPH_SSO_OKTA_NAME_ID_ENCRYPTED` | `true` if the `NameID` element is encrypted. | +| `MEMGRAPH_SSO_OKTA_SAML_USERNAME_ATTRIBUTE` | Name of the SAML response attribute containing the username (if not using `NameID`). | +| `MEMGRAPH_SSO_OKTA_SAML_ROLE_ATTRIBUTE` | Name of the SAML response attribute containing the user’s role(s). | +| `MEMGRAPH_SSO_OKTA_SAML_ROLE_MAPPING` | The [role mapping](#role-mapping) string. | + + + +### OpenID Connect + +Memgraph supports authentication and authorization using **OpenID Connect +(OIDC)** with OAuth 2.0 via built-in modules packaged with Memgraph Enterprise. + +**Supported identity providers** - Microsoft Entra ID -- Okta using a custom authorization server +- Okta (custom authorization server) + +**Enabling OIDC** + +Use the `--auth-module-mappings` flag to enable OIDC providers: -To use the built-in auth module run Memgraph with the `--auth-module-mappings` [flag](/database-management/configuration#auth-module) with the name of each provider and protocol you want to use separated with a semicolon (;). -For example, to use OIDC with both Entra ID and Okta run Memgraph with `--auth-module-mappings=oidc-okta;oidc-entra-id`. +``` +--auth-module-mappings=oidc-okta;oidc-entra-id +``` -For SSO provider setup see [this](/data-visualization/user-manual/single-sign-on). +For full SSO setup instructions, see [this guide](/data-visualization/user-manual/single-sign-on). #### Module requirements @@ -325,18 +364,33 @@ The module is written in Python 3 and requires the following libraries: - `requests` - used to retrieve public keys for validating tokens. - `cryptography` - used to parse tokens. -The required packages are already installed in the docker image. If you are using a native build you to install the packages manually on your machine. -The list of all required packages is located at `src/auth/reference_modules/requirements.txt`. You can install them by running `pip3 install -r /path/to/requirements.txt`. -If you are running a native build make sure that you don't have the Python `JWT` library installed (you can check that with `pip freeze`) as `PyJWT` and `JWT` have some conflicts. +These dependencies are preinstalled in the Memgraph Docker image. + +The required packages are already installed in the docker image. If you are +using a native build you to install the packages manually on your machine. The +list of all required packages is located at +`src/auth/reference_modules/requirements.txt`. + +To install, run: +``` +pip3 install -r /path/to/memgraph/src/auth/reference_modules/requirements.txt +``` + +> **Note**: Ensure the `JWT` Python package is not installed, as it conflicts +with `PyJWT`. Run `pip freeze` to verify. + #### Module configuration -The module is located at `/usr/lib/memgraph/auth_module/oidc.py`. -The module has no configuration file. You have to run Memgraph with some environmental variables. -To use multiple SSO providers you have to set the environmental variables associated with that provider. +The module is located at `/usr/lib/memgraph/auth_module/oidc.py`. + +This module has no configuration file and is fully configured via environment +variables. You can use multiple SSO providers by setting variables for each one. + +#### MS Entra ID -##### MS Entra ID -For using OIDC with Microsoft Entra ID you have to set the following environmental variables: +For using OIDC with Microsoft Entra ID you have to set the following +environmental variables: ```bash MEMGRAPH_SSO_ENTRA_ID_OIDC_TENANT_ID= @@ -345,17 +399,32 @@ MEMGRAPH_SSO_ENTRA_ID_OIDC_ROLE_MAPPING= MEMGRAPH_SSO_ENTRA_ID_OIDC_USERNAME= ``` -You can find the tenant and client ID in the app overview in Azure. For a more detailed explanation see [this](/data-visualization/user-manual/single-sign-on). +- Tenant ID and client ID are available in your Azure app overview. +- See the [SSO setup guide](/data-visualization/user-manual/single-sign-on) for + details. + +Role mapping uses the same syntax described in [Role mapping](#role-mapping). + +The `MEMGRAPH_SSO_ENTRA_ID_OIDC_USERNAME` variable defines which token claim to +use as the username: +``` +token-type:field +``` + +- `token-type`: either `id` or `access` +- `field`: the token claim (e.g., `sub`, `preferred_username`) + +By default, it is set to `id:sub` as per the OIDC protocol it is +recommended to use the `sub` field from the id token as it is non-mutable and +globally unique for each application. For MS Entra ID one commonly used field is +`access:preferred_username` which is usually the email of the user. -Role mapping is described [here](#single-sign-on). +For claim references, see: +- [Access token claims]((https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens)) +- [ID token claims]((https://learn.microsoft.com/en-us/entra/identity-platform/id-tokens)) -The username variable tells the OIDC module what to use as the username. It has the format `token-type:field`. -Token type can be `id` or `access` depending on whether you want to use a field from the access or the ID token for the username. See the following to learn more about [access](https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens) and [id](https://learn.microsoft.com/en-us/entra/identity-platform/id-tokens) tokens. -By default, it is set to `id:sub` as per the OIDC protocol it is recommended to use the `sub` field from the id token as it is non-mutable and globally unique for each application. -For MS Entra ID one commonly used field is `access:preferred_username` which is usually the email of the user. For a list of all default claims look at [this](https://learn.microsoft.com/en-us/entra/identity-platform/access-token-claims-reference) and [this](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference). -You can also configure custom claims. -##### Okta +#### Okta For using OIDC with Okta you have to set the following environmental variables: ```bash @@ -366,18 +435,22 @@ MEMGRAPH_SSO_OKTA_OIDC_ROLE_MAPPING= MEMGRAPH_SSO_OKTA_OIDC_USERNAME= ``` -Role mapping is described [here](#single-sign-on). +Role mapping uses the same syntax described in [Role mapping](#role-mapping). -Issuer is `https://{your-okta-domain}.okta.com/oauth2/default/`. You can find the client ID on the Admin panel -> Applications -> General. You can find the authorization server on the Admin panel -> Security -> API -> Authorization Servers -> Audience. By default, it is set to `api://default`. +Issuer is `https://{your-okta-domain}.okta.com/oauth2/default/`. You can find +the client ID on the Admin panel -> Applications -> General. You can find the +authorization server on the Admin panel -> Security -> API -> Authorization +Servers -> Audience. By default, it is set to `api://default`. -##### Custom auth +#### Custom OIDC provider This is currently only supported through the Neo4j drivers. -If you are using an OIDC provider which is not listed above you can use you the custom auth scheme. -The only requirement is that your OIDC provider supports verifying the tokens through RSA algorithm (public & private key). +If you are using an OIDC provider which is not listed above you can use you the +custom auth scheme. The only requirement is that your OIDC provider supports +verifying the tokens through RSA algorithm (public & private key). Setup the following environmental variables: @@ -390,23 +463,34 @@ MEMGRAPH_SSO_CUSTOM_OIDC_USERNAME= MEMGRAPH_SSO_CUSTOM_OIDC_ROLE_MAPPING= ``` -Usernames are described below and role mappings are described [here](#single-sign-on). -One way to deduce the audience of the access and id tokens is to decode them using a tool like `jwt.io`, check the `aud` field and deduce what it is. -Often time access and id token will the use the same audience. For example in MS Entra ID both tokens use the client ID as audience. +Usernames are described below and role mappings are described +in [Role mapping](#role-mapping). +You can determine token audiences by decoding tokens via tools like `jwt.io` and + inspecting the `aud` field. In many cases, both tokens use the same audience +(for example, Entra ID uses the client ID). -##### Connect via Neo4j drivers +#### Connect via Neo4j drivers -When connecting through a driver, you can choose to provide only the access token and skip the ID token. -In general, all connection methods follow the same approach: setting only the **scheme** and **credentials**. -- **Scheme**: Use the scheme that applies to your setup (`oidc-entra-id`, `oidc-okta` or `custom`) +When connecting through a Neo4j driver, you can provide: +- Both `access_token` and `id_token`, or +- Only the `access_token` (if username uses an access token claim) + +In general, all connection methods follow the same approach: setting only the +**scheme** and **credentials**. +- **Scheme**: Use the scheme that applies to your setup (`oidc-entra-id`, + `oidc-okta` or `custom`) - **Credentials**: Provide them as a string in this format: -```access_token=token-data;id_token=token-data``` -If you don't want to include the ID token, simply omit it: -```access_token=token-data``` +```access_token=token-data;id_token=token-data``` If you don't want to include +the ID token, simply omit it: ```access_token=token-data``` - -The OIDC module automatically determines whether to validate the ID token based on your username configuration. If your username is configured to use a field from the ID token (e.g., `id:sub`), the module will require and validate the ID token. If your username uses a field from the access token (e.g., `access:preferred_username`), the ID token validation is skipped. + + +The OIDC module automatically determines whether to +validate the ID token based on your username configuration. If your username is +configured to use a field from the ID token (e.g., `id:sub`), the module will +require and validate the ID token. If your username uses a field from the access +token (e.g., `access:preferred_username`), the ID token validation is skipped. Below is an example of connecting via the Neo4j Python driver. @@ -424,17 +508,44 @@ driver = GraphDatabase.driver(MEMGRAPH_URI, ) ``` -##### Username -The username variable tells the OIDC module what to use as the username. It has the format `token-type:field`. -Token type can be `id` or `access` depending on whether you want to use a field from the access or the ID token for the username. See the following to learn more about [access](https://www.okta.com/identity-101/access-token/) and [id](https://developer.okta.com/docs/guides/validate-id-tokens/main/#id-tokens-vs-access-tokens) tokens. +#### Username configuration + +The username variable tells the OIDC module what to use as the username in the +following format: + +``` + token-type:field +``` + +By default: id:sub +- `id` → Use a field from the ID token +- `access` → Use a field from the Access token + +Token type can be `id` or `access` depending on +whether you want to use a field from the access or the ID token for the +username. See the following to learn more about +[access](https://www.okta.com/identity-101/access-token/) and +[id](https://developer.okta.com/docs/guides/validate-id-tokens/main/#id-tokens-vs-access-tokens) +tokens. -By default, it is set to `id:sub` as per the OIDC protocol it is recommended to use the `sub` field from the id token as it is non-mutable and globally unique for each application. -For Okta one commonly used field is `access:sub` which is usually the email of the user. You can also configure [custom claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/main/). +By default, it is set to `id:sub` as per the OIDC protocol it is recommended to +use the `sub` field from the id token as it is non-mutable and globally unique +for each application. For Okta one commonly used field is `access:sub` which is +usually the email of the user. You can also configure [custom +claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/main/). #### Database configuration -OIDC is by default enabled using the Memgraph `oidc.py` module. To use a custom auth module use the `--auth-module-mappings` [flag](/database-management/configuration#auth-module) like the following: -`--auth-module-mappings=oidc-entra-id:/path/to/oidc-entra-module;oidc-okta:/path/to/oidc-okta-module` depending on the SSO provider you want to use. +OIDC is by default enabled using the Memgraph `oidc.py` module. + +To use a custom auth module use the `--auth-module-mappings` +[flag](/database-management/configuration#auth-module) like the following: + +``` +--auth-module-mappings=oidc-entra-id:/path/to/oidc-entra-module;oidc-okta:/path/to/oidc-okta-module +``` + +depending on the SSO provider you want to use. #### Using OIDC SSO with the Neo4j Python driver @@ -442,45 +553,50 @@ Connecting using SSO is supported with the Neo4j Python driver. For the instructions on how to connect, check the [Python driver docs](/client-libraries/python#connect-with-single-sign-on-sso). -## Basic (username + password) auth - -When Memgraph is set up to use the external auth module for basic authentication -(`--auth-module-mappings=basic`), its internal users are automatically disabled. -Users are authenticated only using the module and existing local users are -ignored. +## Basic authentication -### LDAP +When Memgraph is set up to use the **external auth module** for basic (username ++ password) authentication (`--auth-module-mappings=basic`), its **internal +users management is automatically disabled**. Users are authenticated only using +the module and existing local users are ignored. -Memgraph also supports authentication and authorization using LDAP with a -built-in auth module that is packaged with Memgraph Enterprise. +### LDAP authentication -The module supports the authentication and authorization (LDAP bind and search -requests) operation mode. +Memgraph Enterprise includes a **built-in LDAP authentication and authorization +module**. This module supports both **authentication** (LDAP bind) and +**authorization** (LDAP search). #### Mode of operation -When using LDAP authentication the module builds the DN used for authentication -using the user specified username and the following formula: +When using LDAP, the module constructs a **Distinguished Name (DN)** for +authentication based on the username and the following formula: ```plaintext DN = prefix + username + suffix ``` -In most common situations the `prefix` will be `cn=` and the `suffix` will be -`,dc=example,dc=com`. With an example username `alice` that would yield a DN -equal to `cn=alice,dc=example,dc=com` which will then be used for the LDAP bind -operation with the user specified password. +In most cases: +- `prefix` = `cn=` +- `suffix` = `,dc=example,dc=com` + +For example, if the username is `alice`, the DN becomes: + +``` +cn=alice,dc=example,dc=com +``` + +This DN is used to perform the **LDAP bind operation** with the provided +password. + +After authentication, the module searches the role mapping tree to determine the +user’s role. Each role mapping object associates users (via the `member` +attribute) with roles (via the `cn` attribute). These attribute names and the +root DN can be customized in the module’s configuration file to match your LDAP +schema. -After the user is authenticated, the module searches through the role mapping -root DN object that contains role mappings. A role mapping object that has the -current bound user as its `member` attribute is used as the user's role. -The role that is mapped to the user is the `CN` attribute of the role mapping -object. The attribute that contains the user DN in the mapping object, as well -as the attribute that contains the role name, can be changed in the module -configuration file to accommodate your LDAP schema. +> **Note**: In large directories with thousands of roles, the search process can +take time, leading to longer login durations. -When searching for a role in directories that have thousands of roles, -the search process could take some time, causing long login times. #### Module requirements @@ -492,21 +608,34 @@ Python 3 libraries installed: #### Module configuration -The module configuration file is located at -`/etc/memgraph/auth_module/ldap.yaml`. An initial example configuration file -that has all settings documented and explained is located at -`/etc/memgraph/auth_module/ldap.example.yaml`. For quick setup, you can copy the example -configuration file into the module configuration file. +The module configuration file is located at: + +``` +/etc/memgraph/auth_module/ldap.yaml +``` + +An example configuration file with all settings documented is provided at: + +``` +/etc/memgraph/auth_module/ldap.example.yaml +``` + +For quick setup, you can copy the example configuration file into the module +configuration file. #### Database configuration -In order to enable the use of the LDAP authentication and authorization module -you have to set the following flag: `--auth-module-mappings=basic`. +To enable LDAP authentication and authorization, start Memgraph with: + +``` +--auth-module-mappings=basic +``` + +You can also combine this with other configuration flags listed in +[Configuration flags](#configuration-flags) as needed. -Other [flags](#configuration-flags) that change the behavior of the database to -module integration can be specified according to your needs. -#### Example +#### Example LDAP directory Organizations typically use an LDAP server to hold and manage the permissions. Because LDAP servers are already set-up in most large organizations, it is @@ -594,20 +723,21 @@ To summarize, the dataset contains the following data: - `cn=moderator,ou=roles,dc=memgraph,dc=com` - role `moderator` that has `alice` as its member. - `cn=admin,ou=roles,dc=memgraph,dc=com` - role `admin` that has `carol` and `dave` as its members. -#### Authentication +#### Authentication workflow -{

Run Memgraph

} +{

Run Memgraph

} -Firs, prepare Memgraph for the integration with LDAP. [Run a Memgraph -instance](/getting-started) without any users in its local authentication -storage. For more details on how the native authentication storage works in -Memgraph check [user privileges](/database-management/authentication-and-authorization/role-based-access-control). +Start Memgraph without local users in its authentication storage. See [Getting +started](/getting-started) for running Memgraph, and refer to [User + privileges](/database-management/authentication-and-authorization/role-based-access-control) + to understand how native authentication works. -{

Create an administrator

} -When using the module, all users are handled by the auth module and no user +{

Create an administrator

} + +When using the external LDAP module, all users are handled by the auth module and no user information is stored locally in Memgraph. In order to allow user login, the corresponding roles need to be defined locally. @@ -619,7 +749,7 @@ GRANT ALL PRIVILEGES TO superuser; Once the role has been created and all privileges granted, it's safe to disconnect from the database and proceed with the LDAP integration. -{

Enable LDAP integration

} +{

Enable LDAP integration

} To enable LDAP integration specify the following flag: @@ -657,12 +787,12 @@ settings. Once all the configuration options are set, restart the Memgraph database instance. -{

Check the integration

} +{

Verify the integration

} Verify that you can log into the database using the username `dba` and password `dba`. It will confirm that the LDAP authentication is successfully enabled. -{

Log in other users

} +{

Log in with other users

} User `alice` should be able to log in with password `alice`. The administrator `dba` should modify Alice's role's privileges to include the @@ -687,11 +817,11 @@ their LDAP password. -#### Authorization +#### Authorization and role mapping -{

Enable role mapping

} +{

Enable role mapping

} To enable role mapping for the described LDAP schema, modify the LDAP auth module configuration file, specifically the section `roles`, by adding the @@ -705,25 +835,28 @@ roles: role_attribute: "cn" ``` -This configuration tells the LDAP module that all role mapping entries are -children of the `ou=roles,dc=memgraph,dc=com` entry, that the children have -user DNs specified in their `member` attribute and that the `cn` attribute -should be used to determine the role name. +This configuration tells the LDAP module that: +- All role entries are located under `ou=roles,dc=memgraph,dc=com` +- Each entry uses `groupOfNames` as its object class +- User DNs are specified in the `member` attribute +- Role names are taken from the `cn` attribute When a user logs in to the database, the LDAP auth module will go through all role mapping entries and will try to find out which role mapping entry has the -user as its member. +user as its `member`. + +For example, when `alice` logs in, the module checks: +- `cn=admin,ou=roles,dc=memgraph,dc=com` +- `cn=moderator,ou=roles,dc=memgraph,dc=com` + +Since `alice` is listed as a member of the `moderator` entry, she receives the +`moderator` role in Memgraph. -So now when Alice logs in, the LDAP auth module will go through the following -entries: `cn=admin,ou=roles,dc=memgraph,dc=com` and -`cn=moderator,ou=roles,dc=memgraph,dc=com`. Because Alice is a member of the -`moderator` role mapping, the LDAP auth module will assign role moderator to -Alice. -{

Adjust permissions

} +{

Adjust permissions

} -Permissions for users and roles are still managed through Memgraph, they can't -be managed through the LDAP server. +Although authentication and role mapping are handled by LDAP, permissions are +still managed directly in Memgraph. The database administrator (user `dba`) now has to explicitly create the role the users have so they will be able to log into the database: @@ -732,8 +865,8 @@ the users have so they will be able to log into the database: CREATE ROLE moderator; ``` -In this scenario Alice and Bob will be able to log in. Alice will be -allowed to log in because her role (moderator) already exists. Carol and Dave -won't be allowed to log in because their role (administrator) doesn't exist. +In this setup: +- `alice` can log in because the `moderator` role exists. +- `carol` and `dave` cannot log in until the `admin` role is created.