PGX 21.2.2
Documentation

End to End Security Example

Let us assume that we want to configure a PGX system where: users can have one of three roles: admin, analyst or data_scientist allow the users to access only the parts of the system that they need to fulfill their roles.

Create and Authenticate Our Four Users

First a realm implementations needs to be ready, that fits the deployment and the used identity provider. (see the general authentication documentation for more details).

Suppose the name of the realm class is com.example.realm.ExampleRealm. PGX needs to be configured by editing the pgx.conf file in the following way:

{
  "pgx_realm": {
    "implementation": "com.example.realm.ExampleRealm"
  }
}

All users that PGX will need to know about need to be present in the identity provider with their corresponding roles configured, and the realm needs to be able to authenticate them.

Configure Static Permissions in PGX Configuration File

First we need to configure the static permissions for each role in the PGX config. Static permissions include general permissions (e.g. PGX_SESSION_CREATE) and permissions on static resources like APIs, file locations, and pre-loaded graphs. To do so we will map the actions a role needs to perform to the required permission in PGX.

Action Privilege Target Object Roles
create a PGX session PGX_SESSION_CREATE -- analyst, data_scientist
create a new graph by loading it into PGX PGX_SESSION_NEW_GRAPH -- data_scientist
get a graph from the global namespace PGX_SESSION_GET_PUBLISHED_GRAPH -- analyst
publish a graph to the global namespace PGX_SESSION_ADD_PUBLISHED_GRAPH -- data_scientist
compile a custom algorithm PGX_SESSION_COMPILE_ALGORITHM -- analyst
manage PGX server PGX_SERVER_MANAGE -- admin
read files from the sample graph directory READ PGX_HOME/examples directory data_scientist

To grant these permissions to the different roles we need to add the following authorization config to the PGX config file. This needs to be done by someone with access to the location of the PGX config file and the permission to edit it. Note: To be able to grant permissions on a directory, we first need to declare a file_location for it.

{
  "file_locations": [
    {
      "name": "sample-graph-directory",
      "location": "<PGX_HOME>/examples/"
    }
  ],
  "authorization": [
    {
      "pgx_role": "admin",
      "pgx_permissions": [
        {
          "grant": "pgx_session_create"
        },
        {
          "grant": "pgx_server_manage"
        }
      ]
    },
    {
      "pgx_role": "data_scientist",
      "pgx_permissions": [
        {
          "grant": "pgx_session_create"
        },
        {
          "grant": "pgx_session_new_graph"
        },
        {
          "grant": "pgx_shared_add_published_graph"
        },
        {
          "file_location": "sample-graph-directory",
          "grant": "read"
        }
      ]
    },
    {
      "pgx_role": "analyst",
      "pgx_permissions": [
        {
          "grant": "pgx_session_create"
        },
        {
          "grant": "pgx_session_compile_algorithm"
        },
        {
          "grant": "pgx_session_get_published_graph"
        }
      ]
    }
  ]
}

Dynamically Grant Permissions

Alice is a data_scientist in our system. She wants to load graph data into PGX and share this graph with Bob, an analyst in our system. This includes two steps:

1. Grant Permissions

After loading Alice has MANAGE permission on g, but no other user has any permissions on it. For Bob to be able to use it, Alice needs to grant him permission first.

pgx> var g = session.readGraphWithProperties("examples/sample.adj.json", "sample-graph")
==> PgxGraph[name=sample-graph,N=4,E=4,created=1590096541575]
pgx> g.grantPermission(new PgxUser("Bob"), PgxResourcePermission.READ)
PgxGraph g = session.readGraphWithProperties("examples/sample.adj.json", "sample-graph")
g.grantPermission(new PgxUser("Bob"), PgxResourcePermission.READ)

2. Publish the Graph

Now Alice needs to publish the graph to the public namespace so it can be retrieved by Bob.

pgx> g.publish()
g.publish()