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 |
- Verifying Database Compatibility
- Downloading Oracle Graph Server and Client
- 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.
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.
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.
- Using the RPM Installation
You can run the downloaded RPM file to install the Oracle Graph Server. - Deploying Oracle Graph Server to a Web Server
You can deploy Oracle Graph Server to Apache Tomcat or Oracle WebLogic Server. - 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.
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.
- Prerequisites for Installing Oracle Graph Server
- Installing Oracle Graph Server
- Uninstalling Oracle Graph Server
- Upgrading 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.
- 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.
- Due to a bug in Open JDK, it is recommended to
avoid the following Oracle JDK versions:
- 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.
Parent topic: Using the RPM Installation
13.2.1.2 Installing Oracle Graph Server
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 anysystemd
errors:sudo journalctl -u pgx.service
Additional installation operations are required for specific use cases, such as:
- Analyze property graphs using Python (see Installing the Python Client From the Graph Server and Client Downloads).
- Deploy the graph server as a web application with Oracle WebLogic Server (see Deploying to Oracle WebLogic Server).
- Deploy GraphViz in Oracle WebLogic Server (see Deploying the Graph Visualization Application in Oracle WebLogic Server).
- Deploy the graph server as a web application with Apache Tomcat (see Deploying to Apache Tomcat).
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.
Parent topic: Using the RPM Installation
13.2.1.3 Uninstalling Oracle Graph Server
Parent topic: Using the RPM Installation
13.2.1.4 Upgrading Oracle Graph Server
Parent topic: Using the RPM Installation
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:
- Deploying to Apache Tomcat
The example in this topic shows how to deploy the graph server as a web application with Apache Tomcat. - 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.
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.
- 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
. - Unzip the file into a directory of your choice.
- Locate the
.war
file that follows the naming pattern:graph-server-<version>-pgx<version>.war
. - Configure the graph server.
- 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. - Optionally, change logging settings by modifying the
WEB-INF/classes/logback.xml
file inside the web application archive. - Optionally, change other servlet specific deployment descriptors by modifying the
WEB-INF/web.xml
file inside the web application archive.
- Modify authentication and other server settings by modifying the
- Copy the
.war
file into the Tomcatwebapps
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 Tomcatwebapps
directory determines the context path of the graph server application. It is recommended naming the war file aspgx.war
. - Configure Tomcat specific settings, like the correct use of TLS/encryption.
- Ensure that port 8080 is not already in use.
- 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>
Related Topics
Parent topic: Deploying Oracle Graph Server to a Web Server
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.
- 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
. - Unzip the file into a directory of your choice.
- Locate the
.war
file that follows the naming pattern:graph-server-<version>-pgx<version>.war
. - Configure the graph server.
- Modify authentication and other server settings by modifying the
WEB-INF/classes/pgx.conf
file inside the web application archive. - Optionally, change logging settings by modifying the
WEB-INF/classes/logback.xml
file inside the web application archive. - Optionally, change other servlet specific deployment descriptors by modifying the
WEB-INF/web.xml
file inside the web application archive. - Optionally, change WebLogic Server-specific deployment descriptors by modifying the
WEB-INF/weblogic.xml
file inside the web application archive.
- Modify authentication and other server settings by modifying the
- Configure WebLogic specific settings, like the correct use of TLS/encryption.
- 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
Parent topic: Deploying to Oracle WebLogic Server
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.
- Privileges and Roles in Oracle Database
All database users that work with graphs require theCREATE SESSION
privilege in the database. - 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). - Prepare the Graph Server for Database Authentication
Locate thepgx.conf
file of your installation. - Store the Database Password in a Keystore
- 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. - Token Expiration
By default, tokens are valid for 1 hour. - Advanced Access Configuration
You can customize the following fields inside thepgx_realm
block in thepgx.conf
file to customize login behavior. - 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. - 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. - Examples of Custom Authorization Rules
You can define custom authorization rules for developers. - 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.
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.
Parent topic: User Authentication and Authorization
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).
Parent topic: User Authentication and Authorization
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
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.
- 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.
- 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>
- 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. - 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, ...
- Finally, restart the graph server as
shown:
sudo systemctl restart pgx
Parent topic: User Authentication and Authorization
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
- Read the data
- Secure coding tips for graph client applications
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 graphAs 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 thepreload_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 theExecStart
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 byoraclegraph
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 thePgxSession
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.
Parent topic: User Authentication and Authorization
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:
Parent topic: User Authentication and Authorization
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.
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
Parent topic: User Authentication and Authorization
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
.
Parent topic: User Authentication and Authorization
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.
- Checking Graph Permissions Using API
- Adding and Removing Roles
You can add new role permission mappings or remove existing mappings by modifying the authorization list. - Defining Permissions for Individual Users
In addition to defining permissions for roles, you can define permissions for individual users. - Defining Permissions to Use Custom Graph Algorithms
You can define permissions to allow developers to compile custom graph algorithms.
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:
|
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
Parent topic: Customizing Roles and Permissions
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
Parent topic: Customizing Roles and Permissions
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
Parent topic: Customizing Roles and Permissions
13.2.3.8.4 Defining Permissions to Use Custom Graph Algorithms
You can define permissions to allow developers to compile custom graph algorithms.
Parent topic: Customizing Roles and Permissions
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
Parent topic: User Authentication and Authorization
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 |
|
MANAGE |
|
EXPORT |
|
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()
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:
- 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.
- 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'
- Grant read or write permissions to the directory for the desired role. For
example:
GRANT READ ON DIRECTORY pgx_file_location TO GRAPH_DEVELOPER
Parent topic: User Authentication and Authorization
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.
- Prerequisite Requirements
- Prepare the Graph Server for Kerberos Authentication
- Login to the Graph Server Using Kerberos Ticket
Parent topic: User Authentication and Authorization
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
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 theoracle-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 theoracle-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.
- 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. - Using Oracle Graph Java Client on Maven Central
You can obtain the property graph Java client from 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.
- A Unix-based operation system (such as Linux) or macOS or Microsoft Windows
- Oracle JDK 11 or JDK 17
Note:
- JDK 11.0.9
- JDK 11.0.10
- JDK 11.0.11
- JDK 11.0.12
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.
- 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:
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.
- Prerequisites for Installing the Python Client
- Installing the Python Client From the Graph Server and Client Downloads
You can download the zip file fororacle-graph-client-23.2.0
from the Graph Server and Client downloads and install the Python client. - Installing the Python Client from PyPI
You can obtain the property graph Python client from PyPI. - Installing the Python Client in Embedded Mode
You can install and work with the Python client in embedded mode. - Uninstalling the Python Client
This section describes how to uninstall the Python client.
Parent topic: Graph Clients
13.3.1.2.1 Prerequisites for Installing the Python Client
Parent topic: Oracle Graph Python Client
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:
Parent topic: Oracle Graph Python Client
13.3.1.2.3 Installing the Python Client from PyPI
You can obtain the property graph Python client from PyPI.
- 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:
Parent topic: Oracle Graph Python Client
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:
Parent topic: Oracle Graph Python Client
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
Parent topic: Oracle Graph Python Client
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.
- Running the Graph Visualization Application in Standalone Mode
If you install the graph serverrpm
file, the Graph Visualization application starts up by default when you start the PGX server. - Deploying the Graph Visualization Application
You must download theoracle-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. - 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.
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.
See Installing Oracle Graph Server for more information.
Parent topic: Graph Visualization Web Client
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.
- Deploying the Graph Visualization Application to Apache Tomcat
- 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.
Parent topic: Graph Visualization Web Client
13.3.2.2.1 Deploying the Graph Visualization Application to Apache Tomcat
Parent topic: Deploying the Graph Visualization Application
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.
- 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
- Start WebLogic
Server.
# Start Server cd $MW_HOME/user_projects/domains/base_domain ./bin/startWebLogic.sh
- 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. - 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.
- Enter your database credentials and configure the required PGQL driver.
See Configuring Advanced Options for PGQL Driver Selection for more information.
- 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.
Parent topic: Deploying the Graph Visualization Application
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:
- Configuring the Graph Visualization Application for PGQL on Graph Server (PGX)
- Configuring the Graph Visualization Application for PGQL on Database
Parent topic: Graph Visualization Web Client
13.3.2.3.1 Configuring the Graph Visualization Application for PGQL on Graph Server (PGX)
Parent topic: Configuring Advanced Options for PGQL Driver Selection
13.3.2.3.2 Configuring the Graph Visualization Application for PGQL on Database
Parent topic: Configuring Advanced Options for PGQL Driver Selection
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.
- Generating a Self-Signed Server Keystore
You can create a server key store using thekeytool
command. - 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. - Configuring a Client to Trust the Self-Signed Keystore
You must configure your client application to accept the self-signed 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.
Parent topic: Using a Self-Signed Server Keystore
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.Parent topic: Using a Self-Signed Server Keystore
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.
- 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:
Parent topic: Using a Self-Signed Server Keystore
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.
- Generating a Self-Signed Server Certificate
You can create a self-signed server certificate using theopenssl
command. - 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. - Configuring a Client to Trust the Self-Signed Certificate
You must configure your client application to accept the self-signed graph server (PGX) 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.
Parent topic: Using a Self-Signed Server Certificate
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.Parent topic: Using a Self-Signed Server Certificate
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.
- 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:
Parent topic: Using a Self-Signed Server Certificate