1. Graph Developer's Guide for Property Graph
  2. Installing Oracle Graph Server (PGX) and Client
  3. Oracle Graph Server and Client Installation

13 Oracle Graph Server and Client Installation

This chapter describes the steps for installing the graph server and the graph clients.

  • Before You Begin
    Before you begin to work with Oracle Property Graphs, you must understand the workflow for installing Oracle Graph Server and Client.
  • Oracle Graph Server Installation
    You must install the Oracle Graph Server in order to run graph queries and analytics in the graph server (PGX).
  • Oracle Graph Client Installation
    You can interact with the various graph features using the client CLIs and the graph visualization web client.
  • Setting Up Transport Layer Security
    The graph server (PGX), by default, allows only encrypted connections using Transport Layer Security (TLS). TLS requires the server to present a server certificate to the client and the client must be configured to trust the issuer of that certificate.

Parent topic: Installing Oracle Graph Server (PGX) and Client

13.1 Before You Begin

Before you begin to work with Oracle Property Graphs, you must understand the workflow for installing Oracle Graph Server and Client.

Table 13-1 Workflow for Installing Oracle Graph Server and Client

Sequence Task Description More Information
1 Verify Oracle Database Requirements Ensure that your Oracle Database version is 12.2 and higher. Verifying Database Compatibility
2 Download Oracle Graph Server and Client Download Oracle Graph Server and Client from Oracle Software Delivery Cloud or from Oracle Technology Network. Downloading Oracle Graph Server and Client
3 Install the PL/SQL patch in your Oracle Database Upgrade the PL/SQL Graph packages in your Oracle Database. Installing PL/SQL Packages in Oracle Database
4 Install Oracle Graph Server Install Oracle Graph server, which is available as a separate downloadable package. Installing Oracle Graph Server
5 Install Oracle Graph Clients Install the graph clients (such as the graph shell CLIs and graph visualization application) to work with property graphs. Oracle Graph Client Installation
6 Set up transport layer security Configure the graph server and client to trust the self-signed certificate. Setting Up Transport Layer Security
7 Add permissions to publish the graph Grant permissions to publish graphs. Adding Permissions to Publish the Graph

Parent topic: Oracle Graph Server and Client Installation

13.1.1 Verifying Database Compatibility

Oracle Graph Server and Client works with Oracle Database 12.2 onwards on both on-premises and cloud environments. The cloud environment includes working with all versions of Oracle Autonomous Database Serverless and Oracle Autonomous Database Dedicated.

However, modifying a property graph using a PGQL INSERT, UPDATE, or DELETE query is not supported for Oracle Database 12.2.

Parent topic: Before You Begin

13.1.2 Downloading Oracle Graph Server and Client

You can download Oracle Graph Server and Client from Oracle Software Delivery Cloud or from Oracle Technology Network.

Table 13-2 summarizes all the files contained in the Oracle Graph Server and Client deployment.

<ver> denoted in the file name in the Table 13-2 reflects the downloaded Oracle Graph Server and Client version.

Table 13-2 Components in the Oracle Graph Server and Client Deployment

File Component Description
oracle-graph-<ver>.rpm Oracle Graph Server An rpm file to deploy Oracle Graph Server.
oracle-graph-client-<ver>.zip Oracle Graph Client A zip file containing Oracle Graph Client.
oracle-graph-hdfs-connector-<ver>.zip Oracle Graph HDFS Connector A zip file containing libraries to connect Oracle Graph Server with the Apache Hadoop Distributed Filesystem (HDFS).
oracle-graph-sqlcl-plugin-<ver>.zip Oracle Graph PGQL Plugin for SQLcl A plugin for SQLcl to run PGQL queries in SQLcl.
oracle-graph-webapps-<ver>.zip Oracle Graph Web Applications A zip file containing .war files for deploying graph servers in an application server.
oracle-graph-plsql-<ver>.zip Oracle Graph PL/SQL Patch A zip file containing PL/SQL packages. It is recommended to update the PL/SQL Graph packages in your database with these packages. Instructions are in the README file.
oracle-graph-visualization-library-<ver>.zip Oracle Graph Visualization Library A zip file containing a Java Script library for the Graph Visualization application.

Parent topic: Before You Begin

13.1.3 Installing PL/SQL Packages in Oracle Database

Oracle Graph Server and Client will work with Oracle Database 12.2 onward. However, you must install the updated PL/SQL packages that are part of the Oracle Graph Server and Client download.

Note:

You can skip this section if you are using Graph Server and Client with Oracle Autonomous Database. You only need to create roles and assign permissions by executing step-5 and step-6 in Basic Steps for Using an Oracle Database for Authentication. You can run these steps using Database Actions in Oracle Cloud Infrastructure Console.

  1. Download the Oracle Graph PL/SQL patch component, which is a part of the Oracle Graph Server and Client download from Oracle Software Delivery Cloud.
  2. Unzip the file oracle-graph-plsql-<ver>.zip into a directory of your choice.
    <ver> denotes the version downloaded for the Oracle Graph PL/SQL Patch for PL/SQL.
  3. Connect to the database as a user with DBA privileges and run the create_graph_roles.sql script.
    -- Connect as SYSDBA
SQL> ALTER SESSION SET CONTAINER=<YOUR_PDB_NAME>;
SQL> @create_graph_roles.sql

    Optionally, if you plan to work with property graph schema (PG Schema) graphs, then you must install the PL/SQL packages by performing the following steps:

    • Choose one of the following directories in the optional_pg_schema folder:
      • 18c_and_below: This applies only if you are working with Oracle Database 18c or below.
      • 19c_and_above: This applies only if you are working with Oracle Database 19c or above.
    • As a database user with DBA privileges, follow the instructions in the README.md file in the appropriate directory (that matches your database version). You must do this for every PDB where you will use the graph feature. For example:
      -- Connect as SYSDBA
SQL> ALTER SESSION SET CONTAINER=<YOUR_PDB_NAME>;
SQL> @opgremov.sql
SQL> @catopg.sql

    See Using the Property Graph Schema for more information on PG Schema graphs.

  4. Connect as a database user with DBA privileges, create a user <graphuser>, and grant the following privileges:
    SQL> GRANT CREATE SESSION, CREATE TABLE, CREATE VIEW TO <graphuser>

    Optionally, if you plan to work with property graph schema (PG Schema) graphs, then grant the following privileges:

    SQL> GRANT CREATE SESSION, ALTER SESSION, CREATE TABLE, CREATE PROCEDURE, CREATE TYPE, CREATE SEQUENCE, CREATE VIEW, CREATE TRIGGER TO <graphuser>
  5. Grant the appropriate roles (GRAPH_DEVELOPER or GRAPH_ADMINISTRATOR), to the database user created in step 4 for working with the graphs.

    Note:

    
SQL> GRANT GRAPH_DEVELOPER to <graphuser>
SQL> GRANT GRAPH_ADMINISTRATOR to <adminuser>

Parent topic: Before You Begin

13.2 Oracle Graph Server Installation

You must install the Oracle Graph Server in order to run graph queries and analytics in the graph server (PGX).

The following sections explain the steps to install the Oracle Graph Server in a standalone mode or deploy the server as a web application using Oracle WebLogic Server or Apache Tomcat.

Related Topics

Parent topic: Oracle Graph Server and Client Installation

13.2.1 Using the RPM Installation

You can run the downloaded RPM file to install the Oracle Graph Server.

Parent topic: Oracle Graph Server Installation

13.2.1.1 Prerequisites for Installing Oracle Graph Server

Your system must adhere to certain prerequisite requirements in order to install the Oracle Graph Server.

The prerequisites for installing the Oracle Graph Server are:
  • Verify that you meet the following system requirements:
    • Oracle Linux 7 or 8 x64 or a similar Linux distribution such as RedHat
    • Oracle JDK 8, JDK 11, or JDK 17

      Note:

      • Due to a bug in Open JDK, it is recommended to avoid the following Oracle JDK versions:
        • JDK 11.0.9
        • JDK 11.0.10
        • JDK 11.0.11
        • JDK 11.0.12

        See this note for more details.

      • Compiling custom graph algorithms using the PGX Algorithm API is not supported on Oracle JDK 17.
  • Verify if you already have an installed version of the graph server, by running the following command:
    sudo rpm -q oracle-graph
[sudo] password for oracle: 
oracle-graph-23.2.0-0.x86_64

    Graph server installation may throw an error if an installation already exists. In that case, see Upgrading Oracle Graph Server to upgrade to a newer version.

13.2.1.2 Installing Oracle Graph Server
The installation steps for installing Oracle Graph Server in standalone mode are as shown:
  1. As a root user or using sudo, install the RPM file using the rpm command line utility: 
    sudo rpm -i oracle-graph-<version>.rpm

    Where <version> reflects the version that you downloaded. (For example: oracle-graph-23.2.0.x86_64.rpm)

    The .rpm file is the graph server.

    The following post-installation steps are carried out at the time of the RPM file installation:
    • Creation of a working directory in /opt/oracle/graph/pgx/tmp_data
    • Creation of a log directory in /var/log/oracle/graph
    • Automatic generation of self-signed TLS certificates in /etc/oracle/graph

      Note:

  2. As root or using sudo, add operating system users allowed to use the server installation to the operating system group oraclegraph. For example:
    usermod -a -G oraclegraph <graphuser>
    This adds the specified graph user to the group oraclegraph.

    Note that <graphuser> must log out and log in again for this to take effect.

  3. As <graphuser>, configure the server by modifying the files under /etc/oracle/graph by following the steps under Prepare the Graph Server for Database Authentication.
  4. Ensure that authentication is enabled for database users that will connect to the graph server, as explained in User Authentication and Authorization.
  5. As a root user or using sudo, start the graph server (PGX) by executing the following command: 
    sudo systemctl start pgx
You can verify if the graph server has started by executing the following command:
systemctl status pgx
  • If the graph server has successfully started, the response may appear as:
    ● pgx.service - Oracle Graph In-Memory Server
   Loaded: loaded (/etc/systemd/system/pgx.service; disabled; vendor preset: disabled)
   Active: active (running) since Wed 2021-01-27 10:06:06 EST; 33s ago
 Main PID: 32127 (bash)
   CGroup: /system.slice/pgx.service
           ├─32127 /bin/bash start-server
           └─32176 java -Dlogback.configurationFile=/etc/oracle/graph/logback-server.xml -Doracle.jdbc.fanEnabled=false -cp /opt/oracle/graph/pgx/bin/../../pgx/server/lib/jackson-databind...

    The graph server is now ready to accept requests.

  • If the graph server has not started, then you must check the log files in /var/log/oracle/graph for errors. Additionally, you can also run the following command to view any systemd errors:
    sudo journalctl -u pgx.service

Additional installation operations are required for specific use cases, such as:

For instructions to deploy the graph server in Oracle WebLogic Server or Apache Tomcat, see:

You can also deploy the graph server behind a load balancer. See Deploying Oracle Graph Server Behind a Load Balancer for more information.

13.2.1.3 Uninstalling Oracle Graph Server
To uninstall the graph server, ensure that you first shut down the existing graph server version.
  1. Run the following command as a root user or with sudo:
    sudo rpm -e oracle-graph
13.2.1.4 Upgrading Oracle Graph Server
To upgrade the graph server, ensure that you first shut down the existing graph server version. You can then run the following command with the newer RPM file as an argument.
  1. Verify the version of your current graph server installation.
    sudo rpm -q oracle-graph
  2. Stop the graph server if it is already running.
    sudo systemctl stop pgx
  3. Optionally, if you are using your own signed server certificates, then it is recommended that you preserve your existing certificates.

    Caution:

    • The default keystore certificates in /etc/oracle/graph is not automatically preserved during the upgrade process.
    • If you are upgrading the graph server from version 22.3.0 or earlier to 23.2.0, then note that the RPM file installation in Graph Server and Client Release 23.2.0 will generate a self-signed server keystore file by default. If you are using a self-signed server certificate, then note that the server configuration fields, server_cert and server_private_key are deprecated and will be desupported in a future release. See Setting Up Transport Layer Security for more information.
  4. Upgrade the graph server by running the following command as a root user or with sudo.
    sudo rpm -U oracle-graph-23.2.0.x86_64.rpm
    Also, note the following:
    • The upgrade process automatically preserves the previous PGX (pgx.conf),server (server.conf), and the logging (logback-server.xml, logback.xml) configurations files by saving the respective files with .rpmsave suffix.
    • Any manual configuration changes in the systemd configuration file for the PGX service (/etc/systemd/system/pgx.service) is lost. However, if you are using a drop-in file, then all customizations in the drop-in file are maintained.
    • Existing log files in /var/log/oracle/graph are preserved.
  5. Optionally, restore your saved server certificates or any of the previous configurations that are saved in the .rpmsave files.

    Note:

    Prior to restoring any of the previous configurations files, it is recommended that you compare the two files to verify if there are any changes in the default parameter values or if a new parameter is added to the configuration file.

    For example:

    mv /etc/oracle/graph/pgx.conf /etc/oracle/graph/pgx.conf.orig
mv /etc/oracle/graph/pgx.conf.rpmsave /etc/oracle/graph/pgx.conf
  6. Restart the graph server.
    sudo systemctl daemon-reload
sudo systemctl start pgx

13.2.2 Deploying Oracle Graph Server to a Web Server

You can deploy Oracle Graph Server to Apache Tomcat or Oracle WebLogic Server.

The following explains the deployment instructions to a web server:

Parent topic: Oracle Graph Server Installation

13.2.2.1 Deploying to Apache Tomcat

The example in this topic shows how to deploy the graph server as a web application with Apache Tomcat.

The graph server will work with Apache Tomcat 9.0.x.

  1. Download the Oracle Graph Webapps zip file from Oracle Software Delivery Cloud. This file contains ready-to-deploy Java web application archives (.war files). The file name will be similar to this: oracle-graph-webapps-<version>.zip.
  2. Unzip the file into a directory of your choice.
  3. Locate the .war file that follows the naming pattern: graph-server-<version>-pgx<version>.war.
  4. Configure the graph server.
    1. Modify authentication and other server settings by modifying the WEB-INF/classes/pgx.conf file inside the web application archive. See User Authentication and Authorization section for more information.
    2. Optionally, change logging settings by modifying the WEB-INF/classes/logback.xml file inside the web application archive.
    3. Optionally, change other servlet specific deployment descriptors by modifying the WEB-INF/web.xml file inside the web application archive.
  5. Copy the .war file into the Tomcat webapps directory. For example:
    cp graph-server-<version>-pgx<version>.war $CATALINA_HOME/webapps/pgx.war

    Note:

    The name you give the war file in the Tomcat webapps directory determines the context path of the graph server application. It is recommended naming the war file as pgx.war.
  6. Configure Tomcat specific settings, like the correct use of TLS/encryption.
  7. Ensure that port 8080 is not already in use.
  8. Start Tomcat:
    cd $CATALINA_HOME 
./bin/startup.sh

    The graph server will now listen on localhost:8080/pgx.

    You can connect to the server from JShell by running the following command:

    
$ <client_install_dir>/bin/opg4j --base_url https://localhost:8080/pgx -u <graphuser>
13.2.2.2 Deploying to Oracle WebLogic Server

The example in this topic shows how to deploy the graph server as a web application with Oracle WebLogic Server.

This example shows how to deploy the graph server with Oracle WebLogic Server. Graph server supports WebLogic Server version 12.1.x and 12.2.x.

  1. Download the Oracle Graph Webapps zip file from Oracle Software Delivery Cloud. This file contains ready-to-deploy Java web application archives (.war files). The file name will be similar to this: oracle-graph-webapps-<version>.zip.
  2. Unzip the file into a directory of your choice.
  3. Locate the .war file that follows the naming pattern: graph-server-<version>-pgx<version>.war.
  4. Configure the graph server.
    1. Modify authentication and other server settings by modifying the WEB-INF/classes/pgx.conf file inside the web application archive.
    2. Optionally, change logging settings by modifying the WEB-INF/classes/logback.xml file inside the web application archive.
    3. Optionally, change other servlet specific deployment descriptors by modifying the WEB-INF/web.xml file inside the web application archive.
    4. Optionally, change WebLogic Server-specific deployment descriptors by modifying the WEB-INF/weblogic.xml file inside the web application archive.
  5. Configure WebLogic specific settings, like the correct use of TLS/encryption.
  6. Deploy the .war file to WebLogic Server. The following example shows how to do this from the command line:
    . $MW_HOME/user_projects/domains/mydomain/bin/setDomainEnv.sh
. $MW_HOME/wlserver/server/bin/setWLSEnv.sh
java weblogic.Deployer -adminurl http://localhost:7001 -username <username> -password <password> -deploy -source <path-to-war-file>
13.2.2.2.1 Installing Oracle WebLogic Server

To download and install the latest version of Oracle WebLogic Server, see

http://www.oracle.com/technetwork/middleware/weblogic/documentation/index.html

13.2.3 User Authentication and Authorization

The Oracle Graph server (PGX) uses an Oracle Database as identity manager. Both username and password based as well as Kerberos based authentication is supported.

The actions that you are allowed to do on the graph server are determined by the privileges enabled by roles that have been granted to you in the Oracle Database.

Parent topic: Oracle Graph Server Installation

13.2.3.1 Privileges and Roles in Oracle Database

All database users that work with graphs require the CREATE SESSION privilege in the database.

Roles that are created for working with graphs are in Table 13-3. These roles are created when you install the PL/SQL package of the Oracle Graph Server and Client distribution on the target database.

Table 13-3 Privileges and Roles in Oracle Database

Role Operations enabled by this role Used By
PGX_SESSION_CREATE Create a new PGX session using the ServerInstance.createSession API. Graph developers and graph users
PGX_SERVER_GET_INFO Get status information on the PGX instance using the Admin API. Users who administer PGX
PGX_SERVER_MANAGE (includes PGX_SERVER_GET_INFO) Manage the PGX instance using the Admin API to stop or restart PGX. Users who administer PGX
PGX_SESSION_NEW_GRAPH Create a new graph in PGX by loading from the database using a config file, using the CREATE PROPERTY GRAPH statement in PGQL, creating a sub-graph from another graph, or using the GraphBuilder. Graph developers and graph users
PGX_SESSION_GET_PUBLISHED_GRAPH Query and view graphs published by another user to the public namespace. Graph developers and graph users
PGX_SESSION_ADD_PUBLISHED_GRAPH (includes PGX_SESSION_GET_PUBLISHED_GRAPH) Publish a graph to the public namespace. Graph developers
PGX_SESSION_COMPILE_ALGORITHM Compile an algorithm using the PGX Algorithm API. Graph developers
PGX_SESSION_READ_MODEL Load and use an ML model using PgxML. Graph developers
PGX_SESSION_MODIFY_MODEL Create, train, and store an ML model using PgxML. Graph developers

Few additional roles are also created to group multiple roles together. They provide a convenient way to grant multiple roles to database users. See Mapping Graph Server Roles to Default Privileges for more information on these additional roles.

You can create additional groups that are useful for your application, as described in Adding and Removing Roles and Defining Permissions for Individual Users.

13.2.3.2 Basic Steps for Using an Oracle Database for Authentication

You can follow the steps explained in this section to authenticate users to the graph server (PGX).

  1. Use an Oracle Database version that is supported by Oracle Graph Server and Client: version 12.2 or later, including Autonomous Database.
  2. Be sure that you have ADMIN access (or SYSDBA access for non-autonomous databases) to grant and revoke users access to the graph server (PGX).
  3. Be sure that all existing users to which you plan to grant access to the graph server have at least the CREATE SESSION privilege granted.
  4. Be sure that the database is accessible via JDBC from the host where the Graph Server runs.
  5. As ADMIN (or SYSDBA on non-autonomous databases), run the following procedure to create the roles required by the graph server:

    Note:

    You can skip this step if you install the PL/SQL packages as part of the Oracle Graph Server and Client installation. All the roles shown in the following code are created as part of the PL/SQL installation automatically. You need to add them separately only if you are using Oracle Graph Server and Client with Autonomous Database. You can run this code using Database Actions in Oracle Cloud Infrastructure Console. 
    
DECLARE
  PRAGMA AUTONOMOUS_TRANSACTION;
  role_exists EXCEPTION;
  PRAGMA EXCEPTION_INIT(role_exists, -01921);
  TYPE graph_roles_table IS TABLE OF VARCHAR2(50);
  graph_roles graph_roles_table;
BEGIN
  graph_roles := graph_roles_table(
    'GRAPH_DEVELOPER',
    'GRAPH_ADMINISTRATOR',
    'GRAPH_USER',
    'PGX_SESSION_CREATE',
    'PGX_SERVER_GET_INFO',
    'PGX_SERVER_MANAGE',
    'PGX_SESSION_READ_MODEL',
    'PGX_SESSION_MODIFY_MODEL',
    'PGX_SESSION_NEW_GRAPH',
    'PGX_SESSION_GET_PUBLISHED_GRAPH',
    'PGX_SESSION_COMPILE_ALGORITHM',
    'PGX_SESSION_ADD_PUBLISHED_GRAPH');
  FOR elem IN 1 .. graph_roles.count LOOP
  BEGIN
    dbms_output.put_line('create_graph_roles: ' || elem || ': CREATE ROLE ' || graph_roles(elem));
    EXECUTE IMMEDIATE 'CREATE ROLE ' || graph_roles(elem);
  EXCEPTION
    WHEN role_exists THEN
      dbms_output.put_line('create_graph_roles: role already exists. continue');
    WHEN OTHERS THEN
      RAISE;
    END;
  END LOOP;
EXCEPTION
  when others then
    dbms_output.put_line('create_graph_roles: hit error ');
    raise;
END;
/
  6. Assign default permissions to the roles GRAPH_DEVELOPER, GRAPH_USER and GRAPH_ADMINISTRATOR to group multiple permissions together.

    Note:

    You can skip this step if you install the PL/SQL packages as part of the Oracle Graph Server and Client installation. All the grants shown in the following code are executed as part of the PL/SQL installation automatically. You need to execute these grants separately only if you are using Oracle Graph Server and Client with Autonomous Database. You can run this code using Database Actions in Oracle Cloud Infrastructure Console. 
    
GRANT PGX_SESSION_CREATE TO GRAPH_ADMINISTRATOR;
GRANT PGX_SERVER_GET_INFO TO GRAPH_ADMINISTRATOR;
GRANT PGX_SERVER_MANAGE TO GRAPH_ADMINISTRATOR;
GRANT PGX_SESSION_CREATE TO GRAPH_DEVELOPER;
GRANT PGX_SESSION_NEW_GRAPH TO GRAPH_DEVELOPER;
GRANT PGX_SESSION_GET_PUBLISHED_GRAPH TO GRAPH_DEVELOPER;
GRANT PGX_SESSION_MODIFY_MODEL TO GRAPH_DEVELOPER;
GRANT PGX_SESSION_READ_MODEL TO GRAPH_DEVELOPER;
GRANT PGX_SESSION_CREATE TO GRAPH_USER;
GRANT PGX_SESSION_GET_PUBLISHED_GRAPH TO GRAPH_USER;
  7. Assign roles to all the database developers who should have access to the graph server (PGX). For example:
    GRANT graph_developer TO <graphuser>

    where <graphuser> is a user in the database. You can also assign individual permissions (roles prefixed with PGX_) to users directly.

  8. Assign the administrator role to users who should have administrative access. For example: 
    GRANT graph_administrator to <administratoruser>

    where <administratoruser> is a user in the database.

13.2.3.3 Prepare the Graph Server for Database Authentication

Locate the pgx.conf file of your installation.

If you installed the graph server via RPM, the file is located at: /etc/oracle/graph/pgx.conf

If you use the webapps package to deploy into Tomcat or WebLogic Server, the pgx.conf file is located inside the web application archive file (WAR file) at: WEB-INF/classes/pgx.conf

Tip: On Linux, you can use vim to edit the file directly inside the WAR file without unzipping it first. For example: 
vim graph-server-<version>-pgx<version>.war

Inside the pgx.conf file, locate the jdbc_url line of the realm options: 

...
"pgx_realm": {
  "implementation": "oracle.pg.identity.DatabaseRealm",
  "options": {
    "jdbc_url": "<REPLACE-WITH-DATABASE-URL-TO-USE-FOR-AUTHENTICATION>",
    "token_expiration_seconds": 3600,
...

Replace the text with the JDBC URL pointing to your database that you configured in the previous step. For example:

...
"pgx_realm": {
  "implementation": "oracle.pg.identity.DatabaseRealm",
  "options": {
    "jdbc_url": "jdbc:oracle:thin:@myhost:1521/myservice",
    "token_expiration_seconds": 3600,
...

Then, start the graph server by running the following command as a root user or with sudo: 

sudo systemctl start pgx

Preparing the Graph Server (PGX) to Connect to Autonomous Database

You can configure your graph server(PGX) to connect to an Autonomous Database instance.

Irrespective of whether your graph server (PGX) instance is running on premises or on Oracle Cloud Infrastructure (OCI), you can perform the following steps to determine the service name to connect to your Autonomous Database instance and update the JDBC URL in /etc/oracle/graph/pgx.conf file.

  1. Download and save the wallet for your Autonomous Database instance from the Oracle Cloud Infrastructure (OCI) Console. See Download Client Credentials (Wallets) for more information.
  2. Unzip the wallet to a new subdirectory in /etc/oracle/graph/wallets/<dbname>, and change the group permission as shown:
    sudo unzip Wallet_<dbname>.zip -d /etc/oracle/graph/wallets/<dbname>
sudo chgrp -R oraclegraph /etc/oracle/graph/wallets/<dbname>
  3. Determine the connect identifier from the tnsnames.ora file in /etc/oracle/graph/wallets/<dbname> directory. For example, the entry must be similar to:
    graphdb_low = 
    description= (retry_count=20)(retry_delay=3)
        (address=
            (protocol=tcps)(port=1522)
            (host=adwc.example.oraclecloud.com)
        )
        (connect_data=(service_name=graphdb_low.adwc.oraclecloud.com))
        (security=(ssl_server_cert_dn="CN=adwc.example.oraclecloud.com, OU=Oracle BMCS US, O=Oracle Corporation, L=Redwood City, ST=California, C=US"))
)

    In the preceding example, graphdb_low is the connect identifier.

  4. Update the JDBC URL in /etc/oracle/graph/pgx.conf file with the connect identifier determined in the preceding step along with the directory path to the unzipped wallet file. For example:
    ...
"pgx_realm": {
  "implementation": "oracle.pg.identity.DatabaseRealm",
  "options": {
    "jdbc_url": "jdbc:oracle:thin:@graphdb_low?TNS_ADMIN=/etc/oracle/graph/wallets/<dbname>",
    "token_expiration_seconds": 3600,
...
  5. Finally, restart the graph server as shown:
    sudo systemctl restart pgx
13.2.3.4 Store the Database Password in a Keystore

PGX requires a database account to read data from the database into memory. The account should be a low-privilege account (see Security Best Practices with Graph Data).

As described in Reading Graphs from Oracle Database into the Graph Server (PGX), you can read data from the database into the graph server without specifying additional authentication as long as the token is valid for that database user. But if you want to access a graph from a different user, you can do so, as long as that user's password is stored in a Java Keystore file for protection.

You can use the keytool command that is bundled together with the JDK to generate such a keystore file on the command line. See the following script as an example: 

# Add a password for the 'database1' connection
keytool -importpass -alias database1 -keystore keystore.p12
# 1. Enter the password for the keystore
# 2. Enter the password for the database
 
# Add another password (for the 'database2' connection)
keytool -importpass -alias database2 -keystore keystore.p12
 
# List what's in the keystore using the keytool
keytool -list -keystore keystore.p12

If you are using Java version 8 or lower, you should pass the additional parameter -storetype pkcs12 to the keytool commands in the preceding example.

You can store more than one password into a single keystore file. Each password can be referenced using the alias name provided.

Write the PGX graph configuration file to load a graph directly from relational tables

The following example loads a subset of the HR sample data from relational tables directly into PGX as a graph. The configuration file specifies a mapping from relational to graph format by using the concept of vertex and edge providers.

Note:

Specifying the vertex_providers and edge_providers properties loads the data into an optimized representation of the graph. 

{
    "name":"hr",
    "jdbc_url":"jdbc:oracle:thin:@myhost:1521/orcl",
    "username":"hr",
    "keystore_alias":"database1",
    "vertex_id_strategy": "no_ids",
    "vertex_providers":[
        {
            "name":"Employees",
            "format":"rdbms",
            "database_table_name":"EMPLOYEES",
            "key_column":"EMPLOYEE_ID",
            "key_type": "string",
            "props":[
                {
                    "name":"FIRST_NAME",
                    "type":"string"
                },
                {
                    "name":"LAST_NAME",
                    "type":"string"
                },
                {
                    "name":"EMAIL",
                    "type":"string"
                },
                {
                    "name":"SALARY",
                    "type":"long"
                }
            ]
        },
        {
            "name":"Jobs",
            "format":"rdbms",
            "database_table_name":"JOBS",
            "key_column":"JOB_ID",
            "key_type": "string",
            "props":[
                {
                    "name":"JOB_TITLE",
                    "type":"string"
                }
            ]
        },
        {
            "name":"Departments",
            "format":"rdbms",
            "database_table_name":"DEPARTMENTS",
            "key_column":"DEPARTMENT_ID",
            "key_type": "string",
            "props":[
                {
                    "name":"DEPARTMENT_NAME",
                    "type":"string"
                }
            ]
        }
    ],
    "edge_providers":[
        {
            "name":"WorksFor",
            "format":"rdbms",
            "database_table_name":"EMPLOYEES",
            "key_column":"EMPLOYEE_ID",
            "source_column":"EMPLOYEE_ID",
            "destination_column":"EMPLOYEE_ID",
            "source_vertex_provider":"Employees",
            "destination_vertex_provider":"Employees"
        },
        {
            "name":"WorksAs",
            "format":"rdbms",
            "database_table_name":"EMPLOYEES",
            "key_column":"EMPLOYEE_ID",
            "source_column":"EMPLOYEE_ID",
            "destination_column":"JOB_ID",
            "source_vertex_provider":"Employees",
            "destination_vertex_provider":"Jobs"
        },
        {
            "name":"WorkedAt",
            "format":"rdbms",
            "database_table_name":"JOB_HISTORY",
            "key_column":"EMPLOYEE_ID",
            "source_column":"EMPLOYEE_ID",
            "destination_column":"DEPARTMENT_ID",
            "source_vertex_provider":"Employees",
            "destination_vertex_provider":"Departments",
            "props":[
                {
                    "name":"START_DATE",
                    "type":"local_date"
                },
                {
                    "name":"END_DATE",
                    "type":"local_date"
                }
            ]
        }
    ]
}

Read the data

Now you can instruct PGX to connect to the database and read the data by passing in both the keystore and the configuration file to PGX, using one of the following approaches:

  • Interactively in the graph shell

    If you are using the graph shell, start it with the --secret_store option. It will prompt you for the keystore password and then attach the keystore to your current session. For example: 

    cd /opt/oracle/graph
./bin/opg4j --secret_store /etc/my-secrets/keystore.p12
 
 enter password for keystore /etc/my-secrets/keystore.p12:

    Inside the shell, you can then use normal PGX APIs to read the graph into memory by passing the JSON file you just wrote into the readGraphWithProperties API: 

    opg4j> var graph = session.readGraphWithProperties("config.json")
graph ==> PgxGraph[name=hr,N=215,E=415,created=1576882388130]
  • As a PGX preloaded graph
    As a server administrator, you can instruct PGX to load graphs into memory upon server startup. To do so, modify the PGX configuration file at /etc/oracle/graph/pgx.conf and add the path the graph configuration file to the preload_graphs section. For example: 
    {
  ...
  "preload_graphs": [{
    "name": "hr", 
    "path": "/path/to/config.json"
  }],
  "authorization": [{
    "pgx_role": "GRAPH_DEVELOPER",
    "pgx_permissions": [{
      "preloaded_graph": "hr",
      "grant": "read"
    }]
  },	
	....
  ]
}
    As root user, edit the service file at /etc/systemd/system/pgx.service and change the ExecStart command to specify the location of the keystore containing the password:
    
ExecStart=/bin/bash start-server --secret-store /etc/keystore.p12

    Note:

    Please note that /etc/keystore.p12 must not be password protected for this to work. Instead protect the file via file system permission that is only readable by oraclegraph user.
    After the file is edited, reload the changes using:
    sudo systemctl daemon-reload
    Finally start the server: 
    sudo systemctl start pgx
  • In a Java application

    To register a keystore in a Java application, use the registerKeystore() API on the PgxSession object. For example: 

    import oracle.pgx.api.*;
 
class Main {
   
  public static void main(String[] args) throws Exception {
    String baseUrl = args[0];
    String keystorePath = "/etc/my-secrets/keystore.p12";
    char[] keystorePassword = args[1].toCharArray();
    String graphConfigPath = args[2];
    ServerInstance instance = Pgx.getInstance(baseUrl);
    try (PgxSession session = instance.createSession("my-session")) {
      session.registerKeystore(keystorePath, keystorePassword);
      PgxGraph graph = session.readGraphWithProperties(graphConfigPath);
      System.out.println("N = " + graph.getNumVertices() + " E = " + graph.getNumEdges());
    }
  }
}
    You can compile and run the preceding sample program using the Oracle Graph Client package. For example:
    cd $GRAPH_CLIENT
// create Main.java with above contents
javac -cp 'lib/*' Main.java
java -cp '.:conf:lib/*' Main http://myhost:7007 MyKeystorePassword path/to/config.json

Secure coding tips for graph client applications

When writing graph client applications, make sure to never store any passwords or other secrets in clear text in any files or in any of your code.

Do not accept passwords or other secrets through command line arguments either. Instead, use Console.html#readPassword() from the JDK.

13.2.3.5 Adding Permissions to Publish the Graph

There are two ways by which you can view any graph in your graph server (PGX) session in the graph visualization application.

When you log into the graph visualization tool in your browser, that will be a different session from your JShell session or application session. To visualize the graph you are working on in your JShell session or application session in your graph visualization session, you can perform one of the following two steps:

  1. Get the session id of your working session using the PgxSession API, and use that session id when you log into the graph visualization application. This is the recommended option.
    opg4j> session.getId();
$2 ==> "898bdbc3-af80-49b7-9a5e-10ace6c9071c"  //session id

    or

  2. Grant PGX_SESSION_ADD_PUBLISHED_GRAPH permission and then publish the graph as shown:
    1. Grant PGX_SESSION_ADD_PUBLISHED_GRAPH role in the database to the user visualizing the graph as shown in the following statement:
      GRANT PGX_SESSION_ADD_PUBLISHED_GRAPH TO <graphuser>
    2. Publish the graph when you are ready to visualize the graph using the publish API.

    Note:

13.2.3.6 Token Expiration

By default, tokens are valid for 1 hour.

Internally, the graph client automatically renews tokens which are about to expire in less than 30 minutes. This is also configurable by re-authenticating your credentials with the database. By default, tokens can only be automatically renewed for up to 24 times, then you need to login again.

If the maximum amount of auto-renewals is reached, you can log in again without losing any of your session data by using the GraphServer#reauthenticate (instance, "<user>", "<password>") API.

Note:

If a session time out occurs before you re-authenticate, then you may lose your session data.

For example:


opg4j> var graph = session.readGraphWithProperties(config) // fails because token cannot be renewed anymore
opg4j> GraphServer.reauthenticate(instance, "<user>", "<password>".toCharArray()) // log in again
opg4j> var graph = session.readGraphWithProperties(config) // works now
13.2.3.7 Advanced Access Configuration

You can customize the following fields inside the pgx_realm block in the pgx.conf file to customize login behavior.

Table 13-4 Advanced Access Configuration Options

Field Name Description Default
token_expiration_seconds After how many seconds the generated bearer token will expire. 3600 (1 hour)
refresh_time_before_token_expiry_seconds After how many seconds a token is automatically refreshed before it expires. Note that this value must always be less than the token_expiration_seconds value. 1800
connect_timeout_milliseconds After how many milliseconds an connection attempt to the specified JDBC URL will time out, resulting in the login attempt being rejected. 10000
max_pool_size Maximum number of JDBC connections allowed per user. If the number is reached, attempts to read from the database will fail for the current user. 64
max_num_users Maximum number of active, signed in users to allow. If this number is reached, the graph server will reject login attempts. 512
max_num_token_refresh Maximum amount of times a token can be automatically refreshed before requiring a login again. 24

Note:

The preceding options work only if the realm implementation is configured to be oracle.pg.identity.DatabaseRealm.
13.2.3.8 Customizing Roles and Permissions

You can fully customize the permissions to roles mapping by adding and removing roles and specifying permissions for a role. You can also authorize individual users instead of roles.

This topic includes examples of how to customize the permission mapping.

Parent topic: User Authentication and Authorization

13.2.3.8.1 Checking Graph Permissions Using API

You can view your roles and graph permissions using the following PGX API methods:

Table 13-5 API for Checking Graph Permissions

Class Method Description
ServerInstance getPgxUsername() Name of the current user
ServerInstance getPgxUserRoles() Role names of the current user
ServerInstance getPgxGenericPermissions() Non-graph (system) permissions of the current user:
  • Pgx system permissions
  • File-location permissions
PgxGraph getPermission() Permission on the graph instance for a current user

You can get all permission-related information using the API in JShell as shown: 

/bin/opg4j -b "https://<host>:<port>" -u "<graphuser>"
opg4j> instance
instance ==> ServerInstance[embedded=false,baseUrl=https://<host>:<port>,serverVersion=null]
opg4j>instance.getPgxUsername()
$2 ==> "ORACLE"
opg4j>instance.getPgxUserRoles()
$3 ==> [GRAPH_DEVELOPER]
opg4j>instance.getPgxGenericPermissions()
$4 ==> [PGX_SESSION_CREATE, PGX_SESSION_READ_MODEL, PGX_SESSION_ADD_PUBLISHED_GRAPH, PGX_SESSION_NEW_GRAPH, PGX_SESSION_GET_PUBLISHED_GRAPH, PGX_SESSION_MODIFY_MODEL]
opg4jvar g = session.readGraphWithProperties("bank_graph_analytics.json")
g ==> PgxGraph[name=bank_graph_analytics,N=1000,E=5001,created=1625697341555]
opg4j>g.getPermission() // To get graph permissions
$9 ==> MANAGE

import oracle.pg.rdbms.*;
import java.sql.Connection;
import java.sql.Statement;
import oracle.pg.rdbms.pgql.PgqlConnection;
import oracle.pg.rdbms.pgql.PgqlStatement;
import oracle.pgx.api.*;
import oracle.ucp.jdbc.PoolDataSourceFactory;
import oracle.ucp.jdbc.PoolDataSource;
import java.nio.file.Files;
import java.nio.file.Path;

/**
 * This example shows how to get all permissions.
 */
public class GetPermissions
{

  public static void main(String[] args) throws Exception
  {
    int idx=0;
    String host               = args[idx++]; 
    String port               = args[idx++]; 
    String sid                = args[idx++]; 
    String user               = args[idx++]; 
    String password           = args[idx++];
    String graph              = args[idx++];
        
    Connection conn = null;
    PgxPreparedStatement stmt = null;
  
    try {
      
      // Get a jdbc connection
      PoolDataSource  pds = PoolDataSourceFactory.getPoolDataSource();
      pds.setConnectionFactoryClassName("oracle.jdbc.pool.OracleDataSource");
      pds.setURL("jdbc:oracle:thin:@"+host+":"+port +"/"+sid);
      pds.setUser(user);
      pds.setPassword(password);     
      conn = pds.getConnection();
      conn.setAutoCommit(false);
      
      ServerInstance instance = GraphServer.getInstance("http://localhost:7007", user, password.toCharArray());
      PgxSession session = instance.createSession("my-session");

      var statement = Files.readString(Path.of("/media/sf_Linux/Java/create-pg.pgql"));
      stmt = session.preparePgql(statement);
      stmt.execute();

      PgxGraph g = session.getGraph(graph);
      System.out.println("Graph: "+ g);
      
      String userName = instance.getPgxUsername();
      var userRoles = instance.getPgxUserRoles();
      var genericPermissions = instance.getPgxGenericPermissions();
      String graphPermission = g.getPermission().toString();

      System.out.println("Username is " + userName);
      System.out.println("User Roles are " + userRoles);
      System.out.println("Generic permissions are " + genericPermissions);
      System.out.println("Graph permission is " + graphPermission);

    }

    finally {
      // close the sql statment
      if (stmt != null) {
        stmt.close();
      }
      // close the connection
      if (conn != null) {
        conn.close();
      }
    }
  }
}

On execution, the code gives the following output:

Graph: PgxGraph[name=BANK_GRAPH_PG,N=1000,E=5001,created=1625731370402]
Username is ORACLE
User Roles are [GRAPH_DEVELOPER]
Generic permissions are [PGX_SESSION_MODIFY_MODEL, PGX_SESSION_CREATE, PGX_SESSION_NEW_GRAPH, PGX_SESSION_READ_MODEL, PGX_SESSION_ADD_PUBLISHED_GRAPH, PGX_SESSION_GET_PUBLISHED_GRAPH]
Graph permission is MANAGE
13.2.3.8.2 Adding and Removing Roles

You can add new role permission mappings or remove existing mappings by modifying the authorization list.

For example:


CREATE ROLE MY_CUSTOM_ROLE_1
GRANT PGX_SESSION_CREATE TO MY_CUSTOM_ROLE1 
GRANT PGX_SERVER_GET_INFO TO MY_CUSTOM_ROLE1 
GRANT MY_CUSTOM_ROLE1 TO SCOTT
13.2.3.8.3 Defining Permissions for Individual Users

In addition to defining permissions for roles, you can define permissions for individual users.

For example:

GRANT PGX_SESSION_CREATE TO SCOTT 
GRANT PGX_SERVER_GET_INFO TO SCOTT
13.2.3.8.4 Defining Permissions to Use Custom Graph Algorithms

You can define permissions to allow developers to compile custom graph algorithms.

For example,
  1. Add the following static permission to the list of permissions: 
    GRANT PGX_SESSION_COMPILE_ALGORITHM TO GRAPH_DEVELOPER
13.2.3.9 Revoking Access to the Graph Server

To revoke a user's ability to access the graph server, either drop the user from the database or revoke the corresponding roles from the user, depending on how you defined the access rules in your pgx.conf file.

For example:

REVOKE graph_developer FROM scott

Revoking Graph Permissions

If you have the MANAGE permission on a graph, you can revoke graph access from users or roles using the PgxGraph#revokePermission API. For example: 

PgxGraph g = ...
g.revokePermission(new PgxRole("GRAPH_DEVELOPER")) // revokes previously granted role access
g.revokePermission(new PgxUser("SCOTT")) // revokes previously granted user access
13.2.3.10 Examples of Custom Authorization Rules

You can define custom authorization rules for developers.

Example 13-1 Allowing Developers to Publish Graphs

Sharing of graphs with other users should be done in Oracle Database where possible. Use GRANT statements on the database tables so that other users can create graphs from the tables.

In the graph server (PGX) you can use the following permissions to share a graph that is already in memory, with other users connected to the graph server.

Table 13-6 Allowed Permissions

Permission Actions Enabled by this Permission
READ
  • READ the graph via the PGX API or in PGQL queries in PGX, create a subgraph, or clone the graph
MANAGE
  • Publish the graph or snapshot
  • Includes READ and EXPORT
  • Grant or revoke READ and EXPORT permissions on the graph
EXPORT
  • Export the graph to a file.
  • Includes READ permission.

The creator of the graph automatically gets the MANAGE permission granted on the graph. If you have the MANAGE permission, you can grant other roles or users READ or EXPORT permission on the graph. You cannot grant MANAGE on a graph. The following example of a user named userA shows how: 

import oracle.pgx.api.*
import oracle.pgx.common.auth.*
 
 
PgxSession session = GraphServer.getInstance("<base-url>", "<userA>", "<password-of-userA").createSession("userA")
PgxGraph g = session.readGraphWithProperties("examples/sample-graph.json", "sample-graph")
g.grantPermission(new PgxRole("GRAPH_DEVELOPER"), PgxResourcePermission.READ)
g.publish()
Now other users with the GRAPH_DEVELOPER role can access this graph and have READ access on it, as shown in the following example of userB:
PgxSession session = GraphServer.getInstance("<base-url>", "<userB>", "<password-of-userB").createSession("userB")
PgxGraph g = session.getGraph("sample-graph")
g.queryPgql("select count(*) from match (v)").print().close()

Similarly, graphs can be shared with individual users instead of roles, as shown in the following example:

g.grantPermission(new PgxUser("OTHER_USER"), PgxResourcePermission.EXPORT)

where OTHER_USER is the user name of the user that will receive the EXPORT permission on graph g.

Example 13-2 Allowing Developers to Access Preloaded Graphs

To allow developers to access preloaded graphs (graphs loaded during graph server startup), grant the read permission on the preloaded graph in the pgx.conf file. For example:

"preload_graphs": [{
  "path": "/data/my-graph.json",
  "name": "global_graph"
}],
"authorization": [{
  "pgx_role": "GRAPH_DEVELOPER",
  "pgx_permissions": [{
    "preloaded_graph": "global_graph"
    "grant": "read"
  },
...

You can grant READ, EXPORT, or MANAGE permission.

Example 13-3 Allowing Developers Access to the Hadoop Distributed Filesystem (HDFS) or the Local File System

To allow developers to read files from HDFS, you must first declare the HDFS directory and then map it to a read or write permission. For example:


CREATE OR REPLACE DIRECTORY pgx_file_location AS 'hdfs:/data/graphs'
GRANT READ ON DIRECTORY pgx_file_location TO GRAPH_DEVELOPER

Similarly, you can add another permission with GRANT WRITE to allow write access. Such a write access is required in order to export graphs.

Access to the local file system (where the graph server runs) can be granted the same way. The only difference is that location would be an absolute file path without the hdfs: prefix. For example: 

CREATE OR REPLACE DIRECTORY pgx_file_location AS '/opt/oracle/graph/data'

Note that in addition to the preceding configuration, the operating system user that runs the graph server process must have the corresponding directory privileges to actually read or write into those directories.

Example 13-4 Allowing Access to Directories on Autonomous Database

To allow developers to read and write from files in Oracle Autonomous Database, you must perform the following steps:

  1. Connect to your Autonomous Database instance as an ADMIN user using any of the SQL based Oracle Database tools or using Database Actions, the built-in web-based interface.

    See Also:

  2. Create the directory by specifying the path to the directory using the graph: prefix as shown:
    CREATE OR REPLACE DIRECTORY pgx_file_location AS 'graph:/opt/oracle/graph/data'
  3. Grant read or write permissions to the directory for the desired role. For example:
    GRANT READ ON DIRECTORY pgx_file_location TO GRAPH_DEVELOPER
13.2.3.11 Kerberos Enabled Authentication for the Graph Server (PGX)

The graph server (PGX) can authenticate users using an Oracle Database with Kerberos enabled as identity provider.

You can log into the graph server using a Kerberos ticket and the actions which you are allowed to do on the graph server are determined by the roles that have been granted to you in the Oracle Database.

13.2.3.11.1 Prerequisite Requirements

In order to enable Kerberos authentication on the graph server (PGX), the following system requirements must be met:

  • The database needs to have Kerberos authentication enabled. See Configuring Kerberos Authentication for more information.
  • Both the database and the Kerberos Authentication Server need to be reachable from the host where the graph server runs.
  • The database is prepared for graph server authentication. That is, relevant graph roles have been granted to users who will log into the graph server.
13.2.3.11.2 Prepare the Graph Server for Kerberos Authentication
The following are the steps to enable Kerberos authentication on the graph server (PGX):
  1. Locate the pgx.conf file of your installation.

    Note:

    If you installed the graph server via RPM, the file is located at: /etc/oracle/graph/pgx.conf
  2. Locate the krb5_conf_file line of the realm options, inside the pgx.conf file:
    "pgx_realm": {
  "implementation": "oracle.pg.identity.DatabaseRealm",
  "options": {
    ...
    "krb5_conf_file": "<REPLACE-WITH-KRB5-CONF-FILE-PATH-TO-ENABLE-KERBEROS-AUTHENTICATION>",
    "krb5_ticket_cache_dir": "/dev/shm",
    "krb5_max_cache_size": 1024
  }
},
  3. Replace the text with the krb5.conf file that you are using for the database and user authentication. For example:
    "pgx_realm": {
  "implementation": "oracle.pg.identity.DatabaseRealm",
  "options": {
    ...
    "krb5_conf_file": "/etc/krb5.conf",
    "krb5_ticket_cache_dir": "/dev/shm",
    "krb5_max_cache_size": 1024
  }
},

    Note:

    The file provided for the krb5_conf_file option needs to be valid and readable by the graph server. In case you don't replace the krb5_conf_file value or the value is empty, then the graph server will not use Kerberos authentication.

    Also, you can set the cache directory that will be used for the graph server to temporarily store Kerberos tickets given by clients as well as the maximum cache size after which new login attempts will be rejected. The cache size represents the maximum amount of concurrent Kerberos sessions active on the graph server.

13.2.3.11.3 Login to the Graph Server Using Kerberos Ticket
The following are the steps to login to the graph server (PGX) using Kerberos ticket:
  1. Create a new Kerberos ticket using the okinit command:
    $ okinit <username>

    This will prompt for your password and then create a new Kerberos ticket.

  2. Connect to a remote graph server with only the base URL parameter using JShell:
    $ opg4j -b https://localhost:7007
    Or using Python client:
    $ opg4py -b https://localhost:7007
    On Linux, JShell and Python interactive client shells automatically detect the Kerberos ticket on your local file system and use that to authenticate with the graph server.
  3. In case the auto-detection is not working, you can also explicitly pass in the ticket to the shell. Run the oklist command, to find the location of the ticket on the local file system.
    $ oklist
 
Kerberos Utilities for Linux: Version 19.0.0.0.0 - Production on 31-MAR-2021 15:26:46
 
Copyright (c) 1996, 2019 Oracle.  All rights reserved.
 
Configuration file : /etc/krb5.conf.
Ticket cache: FILE:/tmp/krb5cc_54321
Default principal: oracle@realm
  4. Specify your Kerberos ticket path using the --kerberos_ticket parameter. For example, using JShell:
    $ opg4j -b https://localhost:7007 --kerberos_ticket /tmp/krb5cc_54321
    Or using Python Client:
    $ opg4py -b https://localhost:7007 --kerberos_ticket /tmp/krb5cc_54321

    If you are using a Java client program (or JShell on embedded mode), you can get a server instance using the following API:

    ...
ServerInstance instance = GraphServer.getInstance("https://localhost:7007", "/tmp/krb5cc_54321");
PgxSession session = instance.createSession("my-session");
...

    If you are using a Python Client program (or opg4py on embedded mode), you can get a server instance using the following API

    ...
instance = graph_server.get_instance("https://localhost:7007", "/tmp/krb5cc_54321")
session = instance.create_session("my-session")
...
    If you are connecting to a remote graph server, all you need is the Oracle Graph Client to be installed. For example:
    import sys
import pypgx as pgx
 
sys.path.append("/path/to/graph/client/oracle-graph-client-21.2.0/python/pypgx/pg/rdbms")
 
import graph_server
  
base_url = "https://localhost:7007"
kerberos_ticket = "/tmp/krb5cc_54321"
  
instance = graph_server.get_instance(base_url, kerberos_ticket)
print(instance)

13.3 Oracle Graph Client Installation

You can interact with the various graph features using the client CLIs and the graph visualization web client.

The following sections explain the steps to install the various clients:

  • Graph Clients
    The Oracle Graph client installation supports a Java and a Python client.
  • Graph Visualization Web Client
    You can run the Graph Visualization web application in a standalone mode or it can be deployed to a web container.

Related Topics

Parent topic: Oracle Graph Server and Client Installation

13.3.1 Graph Clients

The Oracle Graph client installation supports a Java and a Python client.

The following sections explain the steps to install the clients:

  • Oracle Graph Java Client
    You can install the Java client from the oracle-graph-client-23.2.0.zip file that is shipped with Oracle Graph Server and Client or you can use the Java client on Maven Central.
  • Oracle Graph Python Client
    You can install the Python client by downloading the oracle-graph-client-23.2.0.zip file that is shipped with Oracle Graph Server and Client or from PyPI.

Parent topic: Oracle Graph Client Installation

13.3.1.1 Oracle Graph Java Client

You can install the Java client from the oracle-graph-client-23.2.0.zip file that is shipped with Oracle Graph Server and Client or you can use the Java client on Maven Central.

Parent topic: Graph Clients

13.3.1.1.1 Installing the Java Client From the Graph Server and Client Downloads

You can download the zip file for Oracle Graph Client 23.2.0 and install the Java client.

The prerequisites for installing the Java client are:
  • A Unix-based operation system (such as Linux) or macOS or Microsoft Windows
  • Oracle JDK 11 or JDK 17

Note:

Due to a bug in Open JDK, which causes a deadlock when you attempt to copy and paste into a JShell session, it is recommended that you avoid the following Oracle JDK versions:
  • JDK 11.0.9
  • JDK 11.0.10
  • JDK 11.0.11
  • JDK 11.0.12
  1. Download the Oracle Graph Client from Oracle Software Cloud.
    For example, oracle-graph-client-23.2.0.zip.
  2. Unzip the file into a directory of your choice.
  3. Configure your client to trust the self-signed keystore. See Configuring a Client to Trust the Self-Signed Keystore for more information.
  4. Start the OPG4J shell to connect to the graph server (PGX) as shown:
    cd <CLIENT_INSTALL_DIR>
./bin/opg4j --base_url https://<host>:7007 --username <graphuser>

    In the preceding code:

    • <CLIENT_INSTALL_DIR>: Directory where the shell executables are located.

      The shell executables are generally found in /opt/oracle/graph/bin after server installation, and <CLIENT_INSTALL_DIR>/bin after the client installation.

    • <host>: Server host

      Note:

      The graph server (PGX), listens on port 7007 by default. If needed, you can configure the graph server to listen on a different port by changing the port value in the server configuration file (server.conf). See Configuring the Graph Server (PGX) for details.
    • <graphuser>: Database user

    You will be prompted for the database password.

    See Starting the OPG4J Shell for more information on the different ways you can start the OPG4J shell.

    The OPG4J shell starts and the following command line prompt appears as shown: 

    For an introduction type: /help intro
Oracle Graph Server Shell 23.2.0
Variables instance, session, and analyst ready to use.
opg4j>

    See Also:

    Java API Reference for more information on the Java APIs

Parent topic: Oracle Graph Java Client

13.3.1.1.2 Using Oracle Graph Java Client on Maven Central

You can obtain the property graph Java client from Maven Central.

The Maven artifact for the graph Java client is described as follows:
  • Group Name: com.oracle.database.graph
  • Artifact Name: opg-client
  • Version: 23.2.0

You can perform the following steps to use the graph Java client from Maven Central:

  1. Download and Install Apache Maven on your system.
    See Apache Maven Project for more information.
  2. Add the bin folder with the mvn command to the PATH variable.
  3. Build your Maven project and navigate to the project directory.
  4. Edit the pom.xml file on the following:
    1. Add the graph Java client dependency as shown:
      <dependencies>
    <dependency>
      <groupId>com.oracle.database.graph</groupId>
      <artifactId>opg-client</artifactId>
      <version>23.2.0</version>
    </dependency>
</dependencies>

      Note:

      If you use Gradle as a build tool, then the equivalent dependency declaration for the Java client is:

      implementation group: 'com.oracle.database.graph', name: 'opg-client', version: '23.2.0'

    2. Add the following repository as the Java client depends on the Spoofax Language Workbench Library to compile PGQL queries:
      <repositories>
    <repository>
      <id>spoofax</id>
      <url>https://artifacts.metaborg.org/content/repositories/releases</url>
    </repository>
</repositories>
  5. Optionally, you can skip step 4 and copy the following minimal POM configuration in <project_dir>/pom.xml file:
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>my-app</name>
  <repositories>
    <repository>
      <id>spoofax</id>
      <url>https://artifacts.metaborg.org/content/repositories/releases</url>
    </repository>       
  </repositories>
  <dependencies>
    <dependency>
      <groupId>com.oracle.database.graph</groupId>
      <artifactId>opg-client</artifactId>
      <version>23.2.0</version>
    </dependency>
  </dependencies>
</project>
  6. Build your Java code in <project_dir>/src/main/java/com/mycompany/app and compile with Maven.
    For example, the following code is stored in a file <project_dir>/src/main/java/com/mycompany/app/App1.java:
    package com.mycompany.app;
 
import java.sql.DriverManager;
import java.sql.Connection;
import java.sql.Statement;
import oracle.pg.rdbms.pgql.PgqlConnection;
import oracle.pg.rdbms.pgql.PgqlStatement;
import oracle.pg.rdbms.pgql.PgqlResultSet;
import oracle.pgx.api.*;
import oracle.pg.rdbms.GraphServer;
import oracle.pg.rdbms.pgql.jdbc.PgqlJdbcRdbmsDriver;

public class App1 {
 
  public static void main(String[] args) throws Exception {
    String dbConnectString = args[0];
    String username = args[1];
    String password = args[2];
 
    // Obtain a JDBC database connection
    DriverManager.registerDriver(new PgqlJdbcRdbmsDriver());
    String jdbcUrl = "jdbc:oracle:pgql:@" + dbConnectString;
    System.out.println("connecting to " + jdbcUrl);

    try (Connection conn = DriverManager.getConnection(jdbcUrl, username, password)) {
      conn.setAutoCommit(false);

      // Create PGQL connection
      PgqlConnection pgqlConn = PgqlConnection.getConnection(conn);

      // Create a PGQL statement to execute PGQL queries
      PgqlStatement pgqlStmt = pgqlConn.createStatement();

      // Create a property graph view using the CREATE PROPERTY GRAPH statement
      String pgViewName = "BANK_GRAPH_VIEW";
      String createPgViewQuery = 
          "CREATE PROPERTY GRAPH " + pgViewName + " " +
          "VERTEX TABLES ( BANK_ACCOUNTS AS ACCOUNTS " +
          "KEY (ID) " +
          "LABEL ACCOUNTS " +
          "PROPERTIES (ID, NAME)" +
          ") " +
          "EDGE TABLES ( BANK_TXNS AS TRANSFERS " +
          "KEY (FROM_ACCT_ID, TO_ACCT_ID, AMOUNT) " +
          "SOURCE KEY (FROM_ACCT_ID) REFERENCES ACCOUNTS (ID) " +
          "DESTINATION KEY (TO_ACCT_ID) REFERENCES ACCOUNTS (ID) " +
          "LABEL TRANSFERS " +
          "PROPERTIES (FROM_ACCT_ID, TO_ACCT_ID, AMOUNT, DESCRIPTION)" +
          ") OPTIONS(PG_VIEW)";

      pgqlStmt.execute(createPgViewQuery);

      // Execute a query to retrieve the first 10 elements of the graph
      String pgqlQuery = 
          "SELECT e.from_acct_id, e.to_acct_id, e.amount FROM " +
          "MATCH (n:ACCOUNTS) -[e:TRANSFERS]-> (m:ACCOUNTS) ON " +
          pgViewName + " LIMIT 10";

      PgqlResultSet rs = pgqlStmt.executeQuery(pgqlQuery);
      rs.print();

      // Drop the property graph view using the DROP PROPERTY GRAPH statement
      String dropPgViewQuery = "DROP PROPERTY GRAPH " + pgViewName;
      pgqlStmt.execute(dropPgViewQuery);
    }
    System.exit(0);
  }
}

    You can then compile and run the preceding code by navigating to your project directory and running the following command:

    mvn compile exec:java -Dexec.mainClass="com.mycompany.app.App1"-Dexec.arguments='<db-connect-string>,<username>,<password>'

    On successful processing, the code may produce an output similar to the following. Note, your output may be different depending on your <db-connect-string>. 

    [INFO] --- exec-maven-plugin:3.1.0:java (default-cli) @ my-app ---
connecting to jdbc:oracle:pgql:@myhost:1521/oradb
name = Baz

Parent topic: Oracle Graph Java Client

13.3.1.2 Oracle Graph Python Client

You can install the Python client by downloading the oracle-graph-client-23.2.0.zip file that is shipped with Oracle Graph Server and Client or from PyPI.

Alternatively, you can also install the python client in embedded mode.

Parent topic: Graph Clients

13.3.1.2.1 Prerequisites for Installing the Python Client
Before you install the Python client from the Graph Server and Client downloads:
  1. Ensure that your system meets the following requirements.
    • Operating system: Linux
    • Oracle JDK 8 or later
    • Python 3.8 or 3.9

      To verify that you are using the right version of the Python client, run the following command:

      python3 --version

      For more information on installing Python 3 on Oracle Linux, see Python for Oracle Linux.

    Note:

    If you are using any other operating system or Python version, then you can install the Python client from PyPI. See Installing the Python Client from PyPI for more information.
  2. Ensure that python3-devel is installed in your system.
    sudo yum install python3-devel
13.3.1.2.2 Installing the Python Client From the Graph Server and Client Downloads

You can download the zip file for oracle-graph-client-23.2.0 from the Graph Server and Client downloads and install the Python client.

Prior to installing the Python client, ensure that your system meets all the required prerequisites.

You can perform the following steps to install and connect using the Python client:

  1. Download the Oracle Graph Client from Oracle Software Cloud.
    For example, oracle-graph-client-23.2.0.zip.
  2. Install the client through pip.
    For example, 
    pip3 install --user oracle-graph-client-23.2.0.zip
  3. Configure your client to trust the self-signed keystore. See Configuring a Client to Trust the Self-Signed Keystore for more information.
  4. Start the OPG4Py shell to connect to the graph server(PGX) by running the following command:
    cd <CLIENT_INSTALL_DIR>
./bin/opg4py --base_url https://<host>:7007

    In the preceding code:

    • <CLIENT_INSTALL_DIR>: Directory where the shell executables are located.

      The shell executables are found in <CLIENT_INSTALL_DIR>/bin after the client installation.

    • <host>: Server host

      Note:

      The graph server (PGX), listens on port 7007 by default. If needed, you can configure the graph server to listen on a different port by changing the port value in the server configuration file (server.conf). See Configuring the Graph Server (PGX) for details.

    You are prompted to enter your username and password.

    See Starting the OPG4Py Shell for more information on the different ways you can start the OPG4Py shell.

    The OPG4Py shell starts and the following command line prompt appears as shown: 

    Oracle Graph Server Shell 23.2.0
>>>

    Note:

    You can also install the python client library in Jupyter Notebook. Using the Python API, you can then connect to the graph server (PGX) to run PGQL queries and graph algorithms in a Jupyter Notebook environment. See Using the Jupyter Notebook Interface for more details.

    See Also:

    Python API Reference for more information on the Python APIs
13.3.1.2.3 Installing the Python Client from PyPI

You can obtain the property graph Python client from PyPI.

You can install the oracle-graph-client-23.2.0.zip package from the PyPI repository using pip.
Before installing the Python client from PyPI, ensure that your system meets the following requirements:
  • Operating system: Linux, Windows, or macOS (M1 or M2 processor)
  • Oracle JDK 8 or later
  • Python 3.7, 3.8, or 3.9
  • Ensure that you set the JAVA_HOME environment variable.
  • If you are behind a proxy, then set the https_proxy environment variable to the proxy server.

You can install and verify the Python client installation as shown:

  1. Install the client through pip.
    For example, 
    pip install --user oracle-graph-client

    This installs the Python client along with all the required dependencies.

  2. Verify that your installation is successful.
    $ python3
Python 3.8.12 (default, Apr  5 2022, 08:07:47)
[GCC 8.5.0 20210514 (Red Hat 8.5.0-10.0.1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import opg4py
>>> import pypgx

    See Also:

    Python API Reference for more information on the Python APIs
13.3.1.2.4 Installing the Python Client in Embedded Mode

You can install and work with the Python client in embedded mode.

To install the embedded Python client:

  1. Run the following pip command:
    pip3 install --user /opt/oracle/graph/client/
  2. Start the OPG4Py shell in embedded mode as shown:
    cd /opt/oracle/graph
./bin/opg4py

    Note that the shell executables are found in /opt/oracle/graph/bin after the server installation.

    The OPG4Py shell starts and the following command line prompt appears as shown: 

    Oracle Graph Server Shell 23.2.0
>>> instance
ServerInstance(embedded: True, version: 23.2.1)
>>>
13.3.1.2.5 Uninstalling the Python Client

This section describes how to uninstall the Python client.

To uninstall the Python client, run the following command:

pip3 uninstall pypgx

13.3.2 Graph Visualization Web Client

You can run the Graph Visualization web application in a standalone mode or it can be deployed to a web container.

Parent topic: Oracle Graph Client Installation

13.3.2.1 Running the Graph Visualization Application in Standalone Mode

If you install the graph server rpm file, the Graph Visualization application starts up by default when you start the PGX server.

The Graph Visualization application requires Oracle Graph Server to be installed as a prerequisite component.

See Installing Oracle Graph Server for more information.

To start the Graph Visualization application in standalone mode:
  1. Start the graph server (PGX) as shown:
    sudo systemctl start pgx
    The Graph Visualization application starts up by default.
  2. Configure your Graph Visualization application to trust the self-signed keystore. See Configuring a Client to Trust the Self-Signed Keystore for more information.
  3. Connect to your browser for running the Graph Visualization application as shown
    https://localhost:7007/ui
    One of the following messages may appear: 
    • Your connection is not private
    • Your connection is not secure

    Click the Continue or Accept button to proceed.

    The Graph Visualization Login screen opens as shown:

    Figure 13-1 Graph Visualization Login

    Description of Figure 13-1 follows
    Description of "Figure 13-1 Graph Visualization Login"
  4. Enter your database Username and Password.
  5. Select and configure the required PGQL Driver.
  6. Click Submit.

    You are now signed into the Graph Visualization application.

    The title bar on the query visualization page displays the connection mode along with the relevant URL.

13.3.2.2 Deploying the Graph Visualization Application

You must download the oracle-graph-webapps-<version>.zip package and deploy the web application archive (WAR) file into your Oracle Weblogic 12.2 (or later) or Apache Tomcat (9.x or later) web containers.

Parent topic: Graph Visualization Web Client

13.3.2.2.1 Deploying the Graph Visualization Application to Apache Tomcat
The following are the steps to deploy the Graph Visualization application to Apache Tomcat.
  1. Download the Oracle Graph Webapps zip file from Oracle Software Delivery Cloud. This file contains ready-to-deploy Java web application archives (.war files). The file name will be similar to this: oracle-graph-webapps-<version>.zip.
  2. Configure Tomcat specific settings, like the correct use of TLS/encryption.
  3. Ensure that port 8080 is not already in use.
  4. Start Tomcat:
    cd $CATALINA_HOME 
./bin/startup.sh

    The Graph Visualization application is now listening on localhost:8080/ui

  5. Navigate to the Graph Visualization Application using the URL, localhost:8080/ui in your browser.
    The Graph Visualization login page appears as shown in Figure 13-1.
  6. Enter your database credentials and configure the required PGQL driver.
  7. Click Submit.
    You are now signed into the Graph Visualization application.

    The title bar on the query visualization page displays the connection mode along with the relevant URL.

13.3.2.2.2 Deploying the Graph Visualization Application in Oracle WebLogic Server

The following instructions are for deploying the Graph Visualization application in Oracle WebLogic Server 12.2.1.3. You might need to make slight modifications, as appropriate, for different versions of the Weblogic Server.

  1. Download the Oracle Graph Webapps zip file from Oracle Software Delivery Cloud. This file contains ready-to-deploy Java web application archives (.war files). The file name will be similar to this: oracle-graph-webapps-<version>.zip
  2. Start WebLogic Server.
    # Start Server
cd $MW_HOME/user_projects/domains/base_domain
./bin/startWebLogic.sh
  3. Enable tunneling.

    In order to be able to deploy the Graph Visualization application WAR file over HTTP, you must enable tunneling first. Go to the WebLogic admin console (by default on http://localhost:7001/console). Select Environment (left panel) > Servers (left panel). Click the server that will run Graph Visualization (main panel). Select (top tab bar), check Enable Tunneling, and click Save.

  4. Deploy the graphviz-<version>-pgviz<graphviz-version>-wls.war file.

    To deploy the WAR file to WebLogic Server, use the following command, replacing the <<...>> markers with values matching your installation: 

    cd $MW_HOME/user_projects/domains/base_domain
source bin/setDomainEnv.sh
java weblogic.Deployer -adminurl <<admin-console-url>> -username <<admin-user>> -password <<admin-password>> -deploy -upload <<path/to>>/graphviz-<<version>>-pgviz<<graphviz-version>>.war

    To undeploy, you can use the following command:

    java weblogic.Deployer -adminurl <<admin-console-url>> -username <<admin-user>> -password <<admin-password>> -name <<path/to>>/graphviz-<<version>>-pgviz<<graphviz-version>>.war -undeploy

    To test the deployment, navigate using your browser to: https://<<fqdn-ip>>:<<port>>/ui.

    The Graph Visualization Login screen appears as shown in Figure 13-1.

  5. Enter your database credentials and configure the required PGQL driver.

    See Configuring Advanced Options for PGQL Driver Selection for more information.

  6. Click Submit.

    You are now logged in and the Graph Visualization query user interface (UI) appears and the graphs from PGX are retrieved.

    The title bar on the query visualization page displays the connection mode along with the relevant URL.

13.3.2.3 Configuring Advanced Options for PGQL Driver Selection

The Graph Visualization application can be configured to communicate either with the graph server (PGX) or to the Oracle Database.

You can apply the required configuration at the time of login through the Advanced Options settings in the Graph Visualization login page.

You can dynamically change and configure the PGQL driver by following the instructions as appropriate for your preference:

13.3.2.3.1 Configuring the Graph Visualization Application for PGQL on Graph Server (PGX)
To configure Graph Visualization application to communicate with a PGX deployment (PGQL on Graph Server):
  1. Click Advanced Options in the Graph Visualization login page.
  2. Select Graph Server as shown:

    Figure 13-2 PGQL on Graph Server (PGX)

    Description of Figure 13-2 follows
    Description of "Figure 13-2 PGQL on Graph Server (PGX)"
  3. Optionally, modify your PGX Base URL.

    Note:

    • By default, the Graph Visualization application connects to the graph server (PGX) using the PGX base URL defined in the web.xml file for your installation.
    • If you wish to disable transport layer security (TLS) in graph server, see Disabling Transport Layer Security (TLS) in Graph Server for more details.
  4. Optionally, enter Session Id.

    When the Graph Visualization application is using PGQL on Graph Server (PGX), the application will use your Oracle Database as identity manager by default. This means that you log into the application using existing Oracle Database credentials (username and password), and the actions which you are allowed to do on the graph server are determined by the roles that have been granted to you in the Oracle Database.

    Note:

    If you wish to enable Kerberos Authentication for the Graph Visualization Application, see Kerberos Enabled Authentication for the Graph Visualization Application for more information.
13.3.2.3.2 Configuring the Graph Visualization Application for PGQL on Database
To configure the Graph Visualization application to communicate with Oracle Database (PGQL on Database):
  1. Click Advanced Options in the Graph Visualization login page.
  2. Select Database as shown:

    Figure 13-3 PGQL on Database

    Description of Figure 13-3 follows
    Description of "Figure 13-3 PGQL on Database"
  3. Optionally, modify the JDBC URL for your Oracle database.

    Note:

13.4 Setting Up Transport Layer Security

The graph server (PGX), by default, allows only encrypted connections using Transport Layer Security (TLS). TLS requires the server to present a server certificate to the client and the client must be configured to trust the issuer of that certificate.

In this release of Graph Server and Client, the RPM file installation, will generate a self-signed server keystore file by default. This server_keystore.jks file contains the server certificate and server private key and is generated into /etc/oracle/graph, for the server to enable TLS. Note that the default password for the generated keystore is changeit and this is configured using an environment variable PGX_SERVER_KEYSTORE_PASSWORD in /etc/systemd/system/pgx.service file as shown: 

[Service]
Environment="PGX_SERVER_KEYSTORE_PASSWORD=changeit"

If this default keystore configuration is sufficient for you to get started and if your connections are only to localhost, you can skip to Configuring a Client to Trust the Self-Signed Keystore.

If you prefer to use a self-signed server certificate, then refer to Using a Self-Signed Server Certificate for more information. However, it is important to note that the server configuration fields, server_cert and server_private_key are deprecated and will be desupported in a future release. After that, you will be required to use the server keystore to store the server certificate and the server private key.

  • Using a Self-Signed Server Keystore
    This section describes the steps to generate a self-signed keystore into /etc/oracle/graph and configure the graph server (PGX) and client to use the keystore.
  • Using a Self-Signed Server Certificate
    This section describes the steps to generate a self-signed certificate into /etc/oracle/graph and configure the graph server (PGX) to use this certificate.

Parent topic: Oracle Graph Server and Client Installation

13.4.1 Using a Self-Signed Server Keystore

This section describes the steps to generate a self-signed keystore into /etc/oracle/graph and configure the graph server (PGX) and client to use the keystore.

Parent topic: Setting Up Transport Layer Security

13.4.1.1 Generating a Self-Signed Server Keystore

You can create a server key store using the keytool command.

The following steps show how to create a server keystore with a self-signed certificate:
  1. Go to the following directory:
    cd /etc/oracle/graph
  2. Run the following command:
    keytool -genkey -alias pgx -keyalg RSA -keystore server_keystore.jks
  3. Provide the requested details. For example: 
    Enter keystore password:
Re-enter new password:
What is your first and last name?
  [Unknown]:  localhost
What is the name of your organizational unit?
  [Unknown]:  OU
What is the name of your organization?
  [Unknown]:  MyOrganization
What is the name of your City or Locality?
  [Unknown]:  MyTown
What is the name of your State or Province?
  [Unknown]:  MyState
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=localhost, OU=OU, O=MyOrganization, L=MyTown, ST=MyState, C=US correct?
  [no]:  yes
    The server_keystore.jks is created successfully in cd /etc/oracle/graph.
13.4.1.2 Configuring the Graph Server (PGX) When Using a Server Keystore

You must specify the path to the server keystore in the graph server (PGX) configuration file.

Note:

If you deploy the graph server into your web server using the web applications download package, then this section does not apply. Please refer to the manual of your web server for instructions on how to configure TLS.
  1. Edit the file at /etc/oracle/graph/server.conf to specify server keystore alias, server keystore provider, server keystore type and the path to the server keystore as shown:
    {
  "port": 7007,
  "enable_tls": true,
  "enable_client_authentication": false,
  "server_keystore": "/etc/oracle/graph/server_keystore.jks",
  "server_keystore_alias": "pgx",
  "server_keystore_type": "PKCS12",
  "server_keystore_provider": "SUN",
  "ca_certs": [],
  "working_dir": "/opt/oracle/graph/pgx/tmp_data"
}
  2. Set the keystore password using an OS environment variable called PGX_SERVER_KEYSTORE_PASSWORD or with a java property called pgx.SERVER_KEYSTORE_PASSWORD.

    For example, to set the keystore password in PGX_SERVER_KEYSTORE_PASSWORD, edit the file at /etc/systemd/system/pgx.service as shown: 

    [Service]
Environment="PGX_SERVER_KEYSTORE_PASSWORD=<keystore_password>"
  3. Reload the systemd configuration by running the following command:
    sudo systemctl daemon-reload
  4. Restart the graph server.

    Note:

    • You should use a certificate issued by a certificate authority (CA) which is trusted by your organization. If you do not have a CA certificate, you can temporarily create a self-signed certificate and get started.
    • Always use a valid certificate trusted by your organization. We do not recommend the usage of self-signed certificates for production environments.
13.4.1.3 Configuring a Client to Trust the Self-Signed Keystore

You must configure your client application to accept the self-signed keystore.

To configure a client to trust the self-signed keystore, the root certificate must be imported to your Java installation local trust store.
  • For a Java or a Python client, you must import the root certificate to all the Java installations used by all the clients.

    Note:

    The JShell client requires Java 11 or later.
  • For the Graph Visualization application, you must import the root certificate to the system Java installation of the environment running the graph server (PGX) or the web server serving the graph visualization application. That is, the JDK installation which is used by the OS user running the server that serves the Graph Visualization application.
  • For the Graph Zeppelin interpreter client, you must import the root certificate to the Java installation used by the Zeppelin server.

You can import the root certificate as shown in the following step:

  1. Run the following command as a root user or with sudo:
    1. For Java 8 (make sure JAVA_HOME is set):
      sudo keytool -importkeystore -srckeystore /etc/oracle/graph/server_keystore.jks -destkeystore $JAVA_HOME/jre/lib/security/cacerts -deststorepass changeit -srcstorepass changeit -noprompt
    2. For Java 11 or later (make sure JAVA_HOME is set):
      sudo keytool -importkeystore -srckeystore /etc/oracle/graph/server_keystore.jks -destkeystore $JAVA_HOME/lib/security/cacerts -deststorepass changeit -srcstorepass changeit -noprompt
    where changeit is the sample keystore password. You can change this password to a password of your choice. Be sure to remember this password as you will need it to modify the certificate.
    1. If you are upgrading the graph server from a previous release, you must first delete the certificate by running the following command appropriate to your Java version. You must run the command using sudo or as a root user:

      For Java 8:

      sudo keytool -delete -alias pgx -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit

      For Java 11 or later:

      sudo keytool -delete -alias pgx -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
    2. Import the new certificate as shown in the preceding step.

13.4.2 Using a Self-Signed Server Certificate

This section describes the steps to generate a self-signed certificate into /etc/oracle/graph and configure the graph server (PGX) to use this certificate.

Parent topic: Setting Up Transport Layer Security

13.4.2.1 Generating a Self-Signed Server Certificate

You can create a self-signed server certificate using the openssl command.

The following steps show how to generate a self-signed server certificate.
  1. Go to the following directory:
    cd /etc/oracle/graph
  2. Execute the following commands:
    openssl req -new -newkey rsa:2048 -days 365 -nodes -x509 -subj "/C=US/ST=MyState/L=MyTown/O=MyOrganization/CN=ROOT" -keyout ca_key.pem -out ca_certificate.pem
openssl genrsa -out server_key_traditional.pem 2048
openssl pkcs8 -topk8 -in server_key_traditional.pem -inform pem -out server_key.pem -outform pem -nocrypt
openssl req -new -subj "/C=US/ST=MyState/L=MyTown/O=MyOrganization/CN=localhost" -key server_key.pem -out server.csr
chmod 600 server_key.pem
openssl x509 -req -CA ca_certificate.pem -CAkey ca_key.pem -in server.csr -out server_certificate.pem -days 365 -CAcreateserial
chown oraclegraph:oraclegraph server_key.pem

    Note:

    • The certificate mentioned in the above example will only work for the host localhost. If you have a different domain, you must replace localhost with your domain name.
    • The above self-signed certificate is valid only for 365 days.
13.4.2.2 Configuring the Graph Server (PGX)

You must specify the path to the server certificate and the server's private key in PEM format in the graph server (PGX) configuration file.

Note:

If you deploy the graph server into your web server using the web applications download package, then this section does not apply. Please refer to the manual of your web server for instructions on how to configure TLS.
  1. Edit the file at /etc/oracle/graph/server.conf, and specify the paths to the server certificate and the server's private key in PEM format, as shown:
    {
  "port": 7007,
  "enable_tls": true,
  "server_private_key": "/etc/oracle/graph/server_key.pem",
  "server_cert": "/etc/oracle/graph/server_certificate.pem",
  "enable_client_authentication": false,
  "working_dir": "/opt/oracle/graph/pgx/tmp_data"
}
  2. Restart the graph server.

    Note:

    • You should use a certificate issued by a certificate authority (CA) which is trusted by your organization. If you do not have a CA certificate, you can temporarily create a self-signed certificate and get started.
    • Always use a valid certificate trusted by your organization. We do not recommend the usage of self-signed certificates for production environments.
13.4.2.3 Configuring a Client to Trust the Self-Signed Certificate

You must configure your client application to accept the self-signed graph server (PGX) certificate.

To configure a client to trust the self-signed certificate, the root certificate must be imported to your Java installation local trust store.
  • For a Java or a Python client, you must import the root certificate to all the Java installations used by all the clients.

    Note:

    The JShell client requires Java 11 or later.
  • For the Graph Visualization application, you must import the root certificate to the system Java installation of the environment running the graph server (PGX) or the web server serving the graph visualization application. That is, the JDK installation which is used by the OS user running the server that serves the Graph Visualization application.
  • For the Graph Zeppelin interpreter client, you must import the root certificate to the Java installation used by the Zeppelin server.

You can import the root certificate as shown in the following step:

  1. Run the following command as a root user or with sudo:
    1. For Java 8 (make sure JAVA_HOME is set):
      sudo keytool -import -trustcacerts -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -alias pgx -file /etc/oracle/graph/ca_certificate.pem -noprompt
    2. For Java 11 or later (make sure JAVA_HOME is set):
      sudo keytool -import -trustcacerts -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit -alias pgx -file /etc/oracle/graph/ca_certificate.pem -noprompt
    where changeit is the sample keystore password. You can change this password to a password of your choice. Be sure to remember this password as you will need it to modify the certificate.
    1. If you are upgrading the graph server from a previous release, you must first delete the certificate by running the following command appropriate to your Java version. You must run the command using sudo or as a root user:

      For Java 8:

      sudo keytool -delete -alias pgx -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit

      For Java 11 or later:

      sudo keytool -delete -alias pgx -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
    2. Import the new certificate as shown in the preceding step.