Managing FGAC rules through the REST API

Note

This documentation relates to Fine-grained access control, which requires a GraphDB Enterprise license.

Fine-grained access control can also be managed through the FGAC management API. Each scope is represented in the API according to a corresponding JSON model:

Statement scope

{
    "policy": "allow|deny",
    "role": "role-string",
    "scope": "statement",
    "operation": "read|write|*",
    "subject": "rdf-value|*",
    "predicate": "rdf-value|*",
    "object": "rdf-value|*",
    "context": "rdf-value|named|default|*"
}

Clear graph scope

{
    "policy": "allow|deny",
    "role": "role-string",
    "scope": "clear_graph",
    "context": "rdf-value|named|default|all|*"
}

Plugin scope

{
    "policy": "allow|deny",
    "role": "role-string",
    "scope": "plugin",
    "operation": "read|write|*",
    "plugin": "plugin-name-string"
}

System scope

{
    "policy": "allow|deny",
    "role": "role-string",
    "scope": "system",
    "operation": "read|write|*"
}

Note

The API supports the following operations:

List FGAC rules for a repository

List the Access control list for all FGAC rules in the repository. You can use one or more optional request parameters to narrow down the search for specific rules that meet your criteria.

Returns a JSON array of FGAC rule objects.

GET /rest/repositories/<repositoryID>/acl

Optional request parameters for filtering:

  • scope — The scope of the FGAC rule (for example, statement)

  • policy — The policy for the FGAC rule (allow or deny)

  • role — The role associated with the FGAC rule (for example, CUSTOM_ROLE1 or !CUSTOM_ROLE1)

  • operation — The operation for the FGAC rule (read, write or *)

  • subject — The subject of the FGAC rule in Turtle-star format (for example, <http://example.com/Mary>)

  • predicate — The predicate of the FGAC rule in Turtle-star format (for example, <http://www.w3.org/2000/01/rdf-schema#label>)

  • object — The object of the FGAC rule in Turtle-star format (for example, "Mary"@en)

  • context — The context of the FGAC rule in Turtle-star format (for example, <http://example.org/graphs/graph1>)

  • plugin — The plugin name for the FGAC rule with plugin scope (for example, elasticsearch-connector)

All of these correspond to the individual fields of the FGAC rule object and they must use the same string representation. When a parameter is not provided, the result will not be filtered by that parameter.

Note

If you construct your request manually, pay attention to the required URL-encoding of the request parameters.

Possible response type:

  • HTTP Status 200 (OK) — The request was successful, and the response will contain a list of FGAC rules

  • HTTP Status 400 (Bad Request) — The request is invalid (i.e. invalid value in any of the filtering parameters)

Add FGAC rules to a repository

Adds new FGAC rules to the repository. Accepts a JSON array of FGAC rule objects.

You can also provide an optional URL request parameter position that specifies the position of the rules to be added. The position is zero-based (0 is the first position). If the position parameter is not provided, the rules are added at the end of the list.

POST /rest/repositories/<repositoryID>/acl

Possible response type:

  • HTTP Status 200 (OK) — The FGAC rules were successfully added

  • HTTP Status 400 (Bad Request) — The request is invalid or missing required information (e.g. wrong value or a rule already exists)

Delete FGAC rules from a repository

Deletes the provided FGAC rules from the repository. Accepts a JSON array of FGAC rule objects. The provided FGAC rules are removed from the list regardless of their position.

DELETE /rest/repositories/<repositoryID>/acl

Possible response type:

  • HTTP Status 204 (No Content): The FGAC rules were successfully removed if they existed or the rules did not exist and thus nothing was removed

  • HTTP Status 400 (Bad Request): The request is invalid or missing required information (e.g. wrong value)

Set FGAC rules of a repository

Replaces the existing FGAC rules of a repository with a new ACL. Accepts a JSON array of FGAC rule objects.

PUT /rest/repositories/<repositoryID>/acl

Possible response type:

  • HTTP Status 200 (OK) — The access control list of FGAC rules was successfully updated

  • HTTP Status 400 (Bad Request) — The request is invalid or missing required information

Using the API and the UI together

Note that the API will keep the exact same order as provided by the caller when creating rules, while when using Workbench to manage ACL, it will reorganize your ACL list by grouping the rules with the same scope together following the order of statement, clear_graph, plugin and system. However, this does not change the order of the rules within each scope.

This is important only if you create or edit your ACL list via the API and then edit via Workbench.