ABAC

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[]

modules/ROOT/pages/authentication-authorization/attribute-based-access-control.adoc

@@ -0,0 +1,134 @@
+: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('<claim_key>')`.
+
+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[, ...];
+----
+
+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.
+====
+
+[NOTE]
+====
+To be able to grant roles, the user must have `GRANT ROLE` privilege.
+====
+
+== 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[, ...];
+----
+
+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 revoke roles, the user must have `REVOKE ROLE` privilege.
+====
+
+== 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('<claim_key>')`, 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`
+* Show commands for listing AUTH RULES are not supported yet.
+* Altering existing auth rules is not supported yet.