User auth providers
Authentication and authorization can be controlled on a user level using Cypher by setting auth providers on users.
To use auth providers, you need to set the dbms.security.require_local_user
configuration setting to true
.
This setting mandates that users with the relevant auth provider attached to them must exist in the database before they can authenticate and authorize with that auth provider.
User auth providers allow you to link externally-defined users (e.g., in a third-party ID provider like OIDC or LDAP) to the Neo4j internal user model.
The internal model can define roles (authorization), SUSPENDED
status, HOME DATABASE
, and metadata such as the unique displayed name of the user.
For consistency, you can also define native
(password-based) auth using the auth provider syntax, including native-only users (i.e., users who can only authenticate with a password).
Use cases
User auth providers can be used for a variety of use cases, including:
-
Provisioning different auth providers (including native username/password auth) for different users.
-
Setting an arbitrary easy username for a user while using an external unique identifier (like
sub
for OIDC auths, which itself is not a user-friendly value). -
Setting
HOME DATABASE
for externally authenticated users. -
Setting
SUSPENDED
status for an externally authenticated user. -
Using native authorization to manage roles for externally authenticated users.
-
Retaining full control of which users can authenticate from within the database.
How it works
When a user authenticates, their identifying attributes are checked against the relevant property of the auth providers in the database. If there is a match, then the user is linked to the Neo4j user and authorized according to the DBMS security configuration settings that match the name of the matching auth provider.
How the matching lookup is done depends on the type of provider. For example:
-
For an OIDC provider, the claim configured by
dbms.security.oidc.mysso.claims.username
(defaultsub
) is taken from the token and is used to look up an auth provider whoseID
andprovider
properties match thesub
and provider respectively of the OIDC provider. -
For an LDAP provider, the
dn
is used to look up an auth provider with aprovider
property ofldap
and anID
property that matches the supplieddn
. -
For the
native
(username/password) provider, the supplied username itself is used to look up the auth provider.
Enabling user auth providers mode
To enable user auth providers mode, set the configuration setting dbms.security.require_local_user
to true
.
This setting mandates that users with the relevant auth provider attached to them must exist in the database before they can authenticate and authorize with that auth provider.
When the user authenticates, Neo4j searches for a user with a matching authentication provider. If a match is found, the user can log in and be authorized successfully.
Migrating to auth providers mode
If you have existing users in the database and want to migrate to auth providers mode, you can use the ALTER USER … SET AUTH
command to attach an auth provider to each of them.
Until you change dbms.security.require_local_user
to true
, this will not impact the users' ability to authenticate and authorize as they always have done.
Once the process of adding auth providers to your users finishes, you can set dbms.security.require_local_user
to true
and restart the DBMS to complete the migration.
After this time, only users with a corresponding auth provider in the database will be able to authenticate and authorize.
Existing users created using the original To verify which auth providers are attached to a user, use the |