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[] 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..38393e6ef --- /dev/null +++ b/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('')`. + +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('')`, 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.