PGX 21.2.2
Documentation

Authorization

When running PGX in remote server mode it requires users to have permission when using the PGX API. The following sections will explain what kind of permissions and resources PGX has, how to configure them and how to grant or revoke permissions.

Permissions

In PGX permissions can be granted to roles as well as individual users. PGX has two types of permissions: resource permissions and static permissions.

Resource permission allows the user to perform a set of PGX operations on a specific resource (e.g. graphs or file-locations). For example to run a PGQL query on a graph, the user needs to have READ permission on that graph.

Static permissions are not related to a specific resource (e.g. graph) but allow to perform a set of PGX operations. For example PGX_SESSION_CREATE lets the user create a new PGX session via ServerInstance#createSession. PGX will throw an exception if a user tries to use such an API without having the proper permissions.

Some operations require a combination of different static and resource permissions. For example to create a subgraph from a given graph, the user needs to have both the static PGX_NEW_GRAPH permission as well as the READ permission on that graph resource. Similarly to export a graph a user would need the EXPORT permission on the graph and the WRITE permission on the file-location the graph should be written to.

Static Permissions

PGX has the following static permissions:

Permission Related Actions
PGX_SESSION_CREATE create a new PGX session
PGX_SESSION_NEW_GRAPH create a new graph e.g. via loading, GraphBuilder API or by creating a sub-graph from another graph
PGX_SESSION_GET_PUBLISHED_GRAPH get a published graph from the public namespace
PGX_SESSION_ADD_PUBLISHED_GRAPH publish a graph to the public namespace
PGX_SESSION_COMPILE_ALGORITHM compile a custom algorithm using the PGX Algorithm API
PGX_SESSION_READ_MODEL load and use an ML model using PgxML
PGX_SESSION_MODIFY_MODEL create, train, and store an ML model using PgxML
PGX_SERVER_GET_INFO get status information for the PGX instance using the Control API
PGX_SERVER_MANAGE manage the PGX server instance using the Control API e.g. kill sessions or restart the PGX server

Note: PGX_SESSION_ADD_PUBLISHED_GRAPH also includes PGX_SESSION_GET_PUBLISHED_GRAPH; PGX_SERVER_MANAGE includes PGX_SERVER_GET_INFO.

PGX_SESSION_COMPILE_ALGORITHM

During the compilation of custom algorithms the system may create temporary files in the tmp location defined in the PGX configuration.

Note: Some operations require multiple permissions; e.g. exporting a graph, creating a subgraph or publishing a graph. For a full list of PGX API calls and their required permissions please refer to this page.

Resource Permissions

PGX has two types of resources: file-locations and graphs. Each have a different set of permissions defined for them.

File Location Permissions

File locations represent a specific directory (including sub-directories) on a (HDFS) file-system. PGX allows to define two different permissions on file-locations:

Permission Related Actions
READ read a file at the file-location
WRITE write a file to the file-location

Note: WRITE also includes READ.

For a full list of PGX API calls and their required permissions please refer to this page.

Graph Permissions

There are three different permissions defined for graphs:

Permission Related Actions
READ read the graph data via the PGX API or in PGQL queries
run Analyst or custom algorithms on a graph
create a subgraph or clone the given graph
EXPORT export the graph
MANAGE publish the graph or snapshot
grant or revoke permissions on the graph
see

Note: EXPORT also includes READ; MANAGE includes EXPORT and READ.

Obtaining a Graph

In PGX there are different ways how a user can obtain a (new) graph. Depending on the method how users obtain a graph, they will receive different permissions on it. The following table shows the different methods and what permissions a user will be granted on the graph:

Method for obtaining a graph Permissions the user is being granted on the new graph
Load a graph MANAGE
Create a new graph via the GraphBuilder API MANAGE
Get a published graph permissions the user has been granted on the graph
Create a clone from an existing graph same permissions as the user has on the source graph
Create a subgraph from an existing graph same permissions as the user has on the source graph
Apply a changeset to an existing graph same permissions as the user has on the source graph

For more information about how to change (grant or revoke) permissions on a graph please refer to the changing permissions section.

Graph Operations

The following table describes some important operations on graphs and what permissions are required for them. Note that Some operations require a combination of different permissions:

Operation Required Permissions
Load a graph PGX_SESSION_NEW_GRAPH & READ on all file-locations (if any)
Create a new graph via the GraphBuilder API PGX_SESSION_NEW_GRAPH
Create a clone from an existing graph PGX_SESSION_NEW_GRAPH & READ on the source graph
Create a subgraph from an existing graph PGX_SESSION_NEW_GRAPH & READ on the source graph
Apply a changeset to an existing graph PGX_SESSION_NEW_GRAPH & READ on the source graph
Export a graph to a file-location EXPORT on the graph & WRITE on the file-location
Publish a graph PGX_SESSION_ADD_PUBLISHED_GRAPH & MANAGE on the graph
Get a published graph PGX_SESSION_GET_PUBLISHED_GRAPH & READ on the graph

For a full list of PGX API calls and their required permissions please refer to this page.

ML Model Operations

The following table describes some important operations on ML models and what permissions are required for them:

Operation Required Permissions
Build an ML model PGX_SESSION_MODIFY_MODEL
Fit an ML model PGX_SESSION_MODIFY_MODEL
Store an ML model PGX_SESSION_MODIFY_MODEL & WRITE on the location
Load an ML model PGX_SESSION_READ_MODEL & READ on the location
Infer using a pre-trained ML model PGX_SESSION_MODIFY_MODEL or PGX_SESSION_READ_MODEL
Frame Operations

The following table describes some important operations on frames and what permissions are required for them:

Operation Required Permissions
Create a frame PGX_SESSION_NEW_GRAPH
Store a frame PGX_SESSION_NEW_GRAPH & WRITE on the location
Load a frame PGX_SESSION_NEW_GRAPH & READ on the location

Configuration

PGX authorization can be configured in two ways: from the PGX configuration or by implementing the getPermissions method of the Realm interface.

Loading Authorization Rules from the PGX Config

In the authorization config we define a mapping from users and roles to the permissions that are being granted to them. Such a mapping consists of a list of defined users and roles each containing a list of permissions granted to them. The following example grants PGX_SESSION_CREATE and PGX_SESSION_GET_PUBLISHED_GRAPH to a role analyst. For a more in-depth example please refer to the end to end security example.

{
  "authorization": [
    {
      "pgx_role": "analyst",
      "pgx_permissions": [
        {
          "grant": "pgx_session_create"
        },
        {
          "grant": "pgx_session_get_published_graph"
        }
      ]
    }
  ]
}

For more information about the PGX configuration in general and the authorization config fields in particular please refer to this page.

Providing Authorization Rules from the Realm

The Realm interface can also be used to provide the static permissions and file location permissions, by implementing its getPermissions method. Graph permissions should not be returned by this method. If getPermissions is implemented and returns a non-empty optional result, then PGX will use the Realm as the source of static permissions and file location permissions, otherwise the PGX config will be used. Note that PGX will always load graph permissions from the PGX config. Also note that the method should either always return a non-empty optional result, or always an empty result, independently of the provided token.

The input of the getPermissions method is the same token passed to the authenticate method of the Realm. A possible implementation is to store the permissions in the token when generating it, and extract them in getPermissions.

Changing Permissions

Changing Graph Permissions

A user with MANAGE permission can use the grantPermission and revokePermission methods of PgxGraph to grant or revoke permissions on a graph to other users or roles.

Granting MANAGE

It is not possible to grant MANAGE using the API.

When publishing a graph, users need to also grant permissions (e.g. READ to the users and roles that they intend to have access to the graph. Just publishing the graph will not grant permissions by itself.

import oracle.pgx.common.auth.PgxResourcePermission;

PgxGraph g = session.readGraphWithProperties("examples/sample.adj.json", "sample-graph")
g.grantPermission(new PgxRole("analyst"), PgxResourcePermission.READ)

Changing Permissions on File-Locations, Preloaded-Graphs and Static Permissions

Static permissions, permissions on file-locations and permissions on pre-loaded graphs can be updated by calling Control#updatePgxConfig with an updated PGX config that contains the intended changes to the authorization configuratiom. This action requires the user to have the PGX_SERVER_MANAGE permission.