From 2266d91bb083aadefefab89b82aade9b9bb18432 Mon Sep 17 00:00:00 2001 From: Hannes Sandberg Date: Wed, 19 Nov 2025 08:59:20 +0100 Subject: [PATCH 1/6] abac page --- .../attribute-based-access-control.adoc | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc diff --git a/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc b/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc new file mode 100644 index 000000000..9f4d05806 --- /dev/null +++ b/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc @@ -0,0 +1,128 @@ +:description: How to use Cypher to manage attribute-based access control on a graph. + +//// +[source, cypher, role=test-setup] +---- +CREATE ROLE salesTeam; +CREATE ROLE engineeringTeamUK; +CREATE ROLE countryAccessRole; +---- +//// + +:page-role: enterprise-edition aura-db-business-critical aura-db-dedicated + +[[attribute-based-access-control]] += Attribute-based access control + +Attribute-based access control, ABAC grants roles based on the evaluation of attributes (or claims) contained in a user's authentication token. + +== Setup + +Use the following steps to set up attribute-based access control: + +1. Enable attribute-based access control in the `neo4j.conf` file by setting the `internal.dbms.feature_flag.attribute_based_access_control` setting to `true`. +2. Specify which OIDC provider will be used for attribute-based access control by setting the `internal.dbms.security.abac_enabled_authorization_providers` setting to the appropriate providers. +3. Define the authorization rules that will be used to grant roles based on user attributes by using the Cypher command `CREATE AUTH RULE`, explained below. +4. Specify which roles will be assigned when the authorization rules are fulfilled using the `GRANT ROLE` command, explained below. + +== Create auth rules +To create an authorization rule, use the following syntax: + +[source, cypher25, role="noheader"] +---- +CREATE AUTH RULE ruleName [IF NOT EXISTS] + SET CONDITION conditionExpression + [ SET ENABLED {true | false} ] +---- + +The conditionExpression is a boolean cypher expression that evaluates user attributes (claims) contained in the authentication token. +To access an attribute, use the syntax `abac.oidc.user_attribute('')`. + +The SET ENABLED clause is optional and can be used to enable or disable the rule upon creation. By default, the rule is enabled. + +[NOTE] +==== +To be able to create auth rules, the user must have the `AUTH RULE MANAGEMENT` privilege. +==== + +=== Drop auth rules +To drop an existing authorization rule, use the following syntax: + +[source, cypher25, role="noheader"] +---- +DROP AUTH RULE ruleName [IF EXISTS]; +---- + +[NOTE] +==== +To be able to drop auth rules, the user must have the `AUTH RULE MANAGEMENT` privilege. +==== + +== Grant roles to auth rules +To specify which roles will be granted to the user when the authorization rule is fulfilled, use the `GRANT ROLE` command with the following syntax: + +[source, cypher25, role="noheader"] +---- +GRANT ROLE[S] role[, ...] TO AUTH RULE[S] ruleName[, ...]; +---- + +[NOTE] +==== +No roles with associated deny privileges can be assigned using attribute-based access control. +==== + +[NOTE] +==== +To be able to grant roles, `GRANT ROLE` privileges. +==== + +== Revoke roles from auth rules +To revoke roles from an authorization rule, use the `REVOKE ROLE` command with the following syntax: + +[source, cypher25, role="noheader"] +---- +REVOKE ROLE[S] role[, ...] FROM AUTH RULE[S] ruleName[, ...]; +---- + +[NOTE] +==== +To be able to grant roles, `REVOKE ROLE` privileges. +==== + +== Examples + +An auth rule specifying that users with the attribute `department` equal to `sales` should be granted the `salesTeam` role can be created as follows: + +[source, cypher25, role="noheader"] +---- +CREATE AUTH RULE salesRule + SET CONDITION abac.oidc.user_attribute('department') = 'sales'; +GRANT ROLE salesTeam TO AUTH RULE salesRule; +---- + +Granting the role `engineeringTeamUK` to users with the attribute `department` equal to `engineering` and `location` equal to `UK` can be done as follows: + +[source, cypher25, role="noheader"] +---- +CREATE AUTH RULE engineeringUKRule + SET CONDITION abac.oidc.user_attribute('department') = 'engineering' + AND abac.oidc.user_attribute('location') = 'UK'; +GRANT ROLE engineeringTeamUK TO AUTH RULE engineeringUKRule; +---- + +Granting a role based on the presence of the allowed countries in a list of citizenship countries in the claims can be done as follows: + +[source, cypher25, role="noheader"] +---- +CREATE AUTH RULE ruleset_countries SET CONDITION + any(country IN abac.oidc.user_attribute('citizenshipCountries') + WHERE country IN ['c1', 'c5']); +GRANT ROLE countryAccessRole TO AUTH RULE ruleset_countries; +--- + +== Caveats and limitations + +* When evaluating `abac.oidc.user_attribute('')`, if the claim does not exist in the authentication token, it will evaluate to `NULL`. +* Newly created auth rules are not applied to existing user sessions. Users must re-authenticate to have the new rules applied. +* Attribute-based access control is only supported for OIDC authentication providers. +* For troubleshooting ABAC evaluation, enable debug logging for the security log and turn on JWT claims logging at debug level in `neo4j.conf`: `dbms.security.logs.oidc.jwt_claims_at_debug_level_enabled=true` From 1347ac96e679082993c7794ba18e49d28bf2b40b Mon Sep 17 00:00:00 2001 From: Hannes Sandberg Date: Wed, 19 Nov 2025 09:08:29 +0100 Subject: [PATCH 2/6] fix code block --- .../attribute-based-access-control.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc b/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc index 9f4d05806..1c39da65b 100644 --- a/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc +++ b/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc @@ -118,7 +118,7 @@ CREATE AUTH RULE ruleset_countries SET CONDITION any(country IN abac.oidc.user_attribute('citizenshipCountries') WHERE country IN ['c1', 'c5']); GRANT ROLE countryAccessRole TO AUTH RULE ruleset_countries; ---- +---- == Caveats and limitations From 99799095b800c6d55eafb65c5f2159ab6d42c0d1 Mon Sep 17 00:00:00 2001 From: Hannes Sandberg Date: Wed, 19 Nov 2025 09:16:37 +0100 Subject: [PATCH 3/6] add link --- modules/ROOT/content-nav.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index c7a14d7b4..2e9956f53 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -215,6 +215,7 @@ *** xref:authentication-authorization/manage-privileges.adoc[] *** xref:authentication-authorization/privileges-reads.adoc[] *** xref:authentication-authorization/property-based-access-control.adoc[] +*** xref:authentication-authorization/attribute-based-access-control.adoc[] *** xref:authentication-authorization/privileges-writes.adoc[] *** xref:authentication-authorization/database-administration.adoc[] *** xref:authentication-authorization/dbms-administration.adoc[] From 7dfc242d2e1c6d2a6de05e22092a98f79f529dd4 Mon Sep 17 00:00:00 2001 From: Hannes Sandberg Date: Wed, 19 Nov 2025 09:31:40 +0100 Subject: [PATCH 4/6] added that SHOW commands and alter commands are not supported yet. --- .../attribute-based-access-control.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc b/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc index 1c39da65b..658fb3c77 100644 --- a/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc +++ b/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc @@ -126,3 +126,5 @@ GRANT ROLE countryAccessRole TO AUTH RULE ruleset_countries; * Newly created auth rules are not applied to existing user sessions. Users must re-authenticate to have the new rules applied. * Attribute-based access control is only supported for OIDC authentication providers. * For troubleshooting ABAC evaluation, enable debug logging for the security log and turn on JWT claims logging at debug level in `neo4j.conf`: `dbms.security.logs.oidc.jwt_claims_at_debug_level_enabled=true` +* Show commands for listing AUTH RULES are not supported yet. +* Altering existing auth rules is not supported yet. From 5001d5d4061d30474c12eb15dbc98a774e35fe5f Mon Sep 17 00:00:00 2001 From: Hannes Sandberg Date: Thu, 20 Nov 2025 09:33:40 +0100 Subject: [PATCH 5/6] updates to grant/revoke section in the ABAC page --- .../attribute-based-access-control.adoc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc b/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc index 658fb3c77..2d8dbe6be 100644 --- a/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc +++ b/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc @@ -66,6 +66,8 @@ To specify which roles will be granted to the user when the authorization rule i GRANT ROLE[S] role[, ...] TO AUTH RULE[S] ruleName[, ...]; ---- +For information about the `GRANT ROLE` command, see xref:authentication-authorization/manage-roles.adoc#access-control-assign-roles[Assigning roles to users]. + [NOTE] ==== No roles with associated deny privileges can be assigned using attribute-based access control. @@ -73,7 +75,7 @@ No roles with associated deny privileges can be assigned using attribute-based a [NOTE] ==== -To be able to grant roles, `GRANT ROLE` privileges. +To be able to grant roles, the user must have `GRANT ROLE` privilege. ==== == Revoke roles from auth rules @@ -84,9 +86,11 @@ To revoke roles from an authorization rule, use the `REVOKE ROLE` command with t REVOKE ROLE[S] role[, ...] FROM AUTH RULE[S] ruleName[, ...]; ---- +For information about the `REVOKE ROLE` command, see xref:authentication-authorization/manage-roles.adoc#access-control-revoke-roles[Revoking roles from users]. + [NOTE] ==== -To be able to grant roles, `REVOKE ROLE` privileges. +To be able to revoke roles, the user must have `REVOKE ROLE` privilege. ==== == Examples From d295e2ae63745a74cf70cd444851d2f06e1b07d8 Mon Sep 17 00:00:00 2001 From: Hannes Sandberg Date: Thu, 20 Nov 2025 09:38:23 +0100 Subject: [PATCH 6/6] fix heading --- .../attribute-based-access-control.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc b/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc index 2d8dbe6be..38393e6ef 100644 --- a/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc +++ b/modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc @@ -45,7 +45,7 @@ The SET ENABLED clause is optional and can be used to enable or disable the rule To be able to create auth rules, the user must have the `AUTH RULE MANAGEMENT` privilege. ==== -=== Drop auth rules +== Drop auth rules To drop an existing authorization rule, use the following syntax: [source, cypher25, role="noheader"]