From 8cf654a3d46e1a9cbb368e4dd6cd301d6b001ecc Mon Sep 17 00:00:00 2001 From: Rocco Jiang Date: Mon, 26 Oct 2026 15:26:00 +0000 Subject: [PATCH 1/2] update authz/auth plugins with tags usage --- .../extending-neo4j/security-plugins.adoc | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/modules/ROOT/pages/extending-neo4j/security-plugins.adoc b/modules/ROOT/pages/extending-neo4j/security-plugins.adoc index c22fe7c..5316791 100644 --- a/modules/ROOT/pages/extending-neo4j/security-plugins.adoc +++ b/modules/ROOT/pages/extending-neo4j/security-plugins.adoc @@ -60,6 +60,37 @@ public AuthorizationInfo authorize( Collection principals Note the usage of the helper class `PredefinedRole`. +[role=label--new-2026.11] +[[extending-neo4j-plugin-user-tags]] +=== Supplying user tags + +In addition to roles, an authorization plugin can supply a set of string tags for a user. +These tags can be evaluated by link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/attribute-based-access-control[attribute-based access control (ABAC)] auth rules using the link:{neo4j-docs-base-uri}/cypher-manual/current/functions/security/#functions-security-plugin-user-tags[`abac.plugin.user_tags()`] function. + +The example below extends the previous example to also assign the tags `engineering` and `internal` to the user named `neo4j`, using the `AuthorizationInfo.of()` factory method: + +[source, java] +---- +@Override +public AuthorizationInfo authorize( Collection principals ) +{ + if ( principals.stream().anyMatch( p -> "neo4j".equals( p.principal() ) ) ) + { + Set roles = Collections.singleton( PredefinedRoles.READER ); + return AuthorizationInfo.of( roles, List.of( "engineering", "internal" ) ); + } + return null; +} +---- + +The plugin is invoked with the principal(s) the user was authenticated with -- for example, the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/sso-integration[OIDC] `sub` claim when OIDC is used for authentication -- so tags are assigned by matching those principals. +Tags are fetched each time `authorize()` is invoked. +Authorization caching is enabled by default, so the tags are cached alongside the rest of the authorization result and are only fetched again when the cached entry expires (see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.security.auth_cache_ttl[`dbms.security.auth_cache_ttl`]). + +Tags supplied by a plugin are only evaluated by auth rules when the plugin is also listed in link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.security.abac.authorization_providers[`dbms.security.abac.authorization_providers`]. +For configuration details, see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/attribute-based-access-control[Operations Manual -> Attribute-based access control]. + + [[extending-neo4j-simplified-combined-plugin]] == Simplified combined plugin @@ -83,6 +114,18 @@ public AuthInfo authenticateAndAuthorize( AuthToken authToken ) } ---- +[role=label--new-2026.11] +=== Supplying user tags + +A combined plugin supplies user tags similarly to authorization plugins, through the `AuthInfo.of()` factory method: + +[source, java] +---- +return AuthInfo.of( username, roles, List.of( "engineering", "internal" ) ); +---- + +As authentication and authorization are performed together when the user logs in, the tags are captured at login and do not change for the rest of the session. + [[extending-neo4j-extendable-platform]] == Extendable platform From 3f406371d6c85e8f87024ae536bac5cb58a9202b Mon Sep 17 00:00:00 2001 From: Rocco Jiang Date: Wed, 28 Oct 2026 16:52:11 +0000 Subject: [PATCH 2/2] Apply batched suggestions from code review Co-authored-by: Reneta Popova --- .../pages/extending-neo4j/security-plugins.adoc | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/extending-neo4j/security-plugins.adoc b/modules/ROOT/pages/extending-neo4j/security-plugins.adoc index 5316791..07e6615 100644 --- a/modules/ROOT/pages/extending-neo4j/security-plugins.adoc +++ b/modules/ROOT/pages/extending-neo4j/security-plugins.adoc @@ -65,9 +65,10 @@ Note the usage of the helper class `PredefinedRole`. === Supplying user tags In addition to roles, an authorization plugin can supply a set of string tags for a user. -These tags can be evaluated by link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/attribute-based-access-control[attribute-based access control (ABAC)] auth rules using the link:{neo4j-docs-base-uri}/cypher-manual/current/functions/security/#functions-security-plugin-user-tags[`abac.plugin.user_tags()`] function. +These tags can be evaluated by attribute-based access control (ABAC) auth rules using the security function `abac.plugin.user_tags()`. +See link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/attribute-based-access-control[Operations Manual -> Attribute-based access control] and link:{neo4j-docs-base-uri}/cypher-manual/current/functions/security/#functions-security-plugin-user-tags[Cypher Manual -> `abac.plugin.user_tags()`] for details. -The example below extends the previous example to also assign the tags `engineering` and `internal` to the user named `neo4j`, using the `AuthorizationInfo.of()` factory method: +The following example extends the previous example to also assign the tags `engineering` and `internal` to the user named `neo4j`, using the `AuthorizationInfo.of()` factory method: [source, java] ---- @@ -83,11 +84,14 @@ public AuthorizationInfo authorize( Collection principals } ---- -The plugin is invoked with the principal(s) the user was authenticated with -- for example, the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/sso-integration[OIDC] `sub` claim when OIDC is used for authentication -- so tags are assigned by matching those principals. +The plugin is invoked with the principal(s) the user was authenticated with. +For example, the OIDC `sub` claim is used for authentication, so tags are assigned by matching those principals. +See link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/sso-integration[Operations Manual -> Configure Neo4j to use an OpenID Connect identity provider] for reference. Tags are fetched each time `authorize()` is invoked. -Authorization caching is enabled by default, so the tags are cached alongside the rest of the authorization result and are only fetched again when the cached entry expires (see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.security.auth_cache_ttl[`dbms.security.auth_cache_ttl`]). +Authorization caching is enabled by default, so tags are cached alongside the rest of the authorization result and are only fetched again when the cached entry expires. +See link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.security.auth_cache_ttl[Operations Manual -> `dbms.security.auth_cache_ttl`]. -Tags supplied by a plugin are only evaluated by auth rules when the plugin is also listed in link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.security.abac.authorization_providers[`dbms.security.abac.authorization_providers`]. +Tags supplied by a plugin are only evaluated by auth rules when the plugin is also listed in `dbms.security.abac.authorization_providers` in the _neo4j.conf_ file. For configuration details, see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/attribute-based-access-control[Operations Manual -> Attribute-based access control].