PGX 20.1.1
Documentation

Authentication

When PGX is deployed in client-server mode, it requires users to authenticate themselves by supplying an authentication token.

To integrate with many identity providers PGX offers an abstract API called 'realm'. A realm consists of interfaces that can be implemented to fit a specific identity provider. The realm implementation is chosen at PGX configuration time.

Authentication Flow

The general authentication flow can be seen in the following diagram:

Diagram: realm based authentication

The general flow for authentication is:

  1. The user acquires a token from the identity provider directly (e.g. through a log in)
  2. The user connects to the PGX instance by providing the token. Each REST request to the PGX instance needs to have an authentication token set
  3. The PGX instance validates the token with the identity provider
  4. The PGX instance acquires user information from the token with the identity provider

PGX Client

When connecting from a PGX client, you need to first acquire a token from a identity provider. The PGX client does not have any method to acquire a token for you.

Once you have acquired a token, you need to provide it to the client using the Pgx.getInstance() API:

import oracle.pgx.api.*;

String authToken; // acquired from identity provider
ServerInstance instance = Pgx.getInstance("https://myhost:7007", authToken);

PGX Shell

There are multiple ways to present an authentication token using the PGX shell:

  1. By manually entering it upon startup
  2. By using a java keystore

(1) Manual Token Entry

When starting the PGX shell with only the argument to connect to a PGX instance, it will automatically prompt for the authentication token on startup:

enter authentication token (press Enter for no token):

(2) Using a Java Keystore

You can store the authentication token in a java keystore and use this to connect to the server using the --keystore_auth_token flag. The alias of the token in the keystore needs to be AuthorizationToken.

To set up a keystore with the an authentication token you can use the keytool tool:

keytool -importpass -alias AuthorizationToken -keystore keystore.p12
# 1. Enter the password for the keystore
# 2. Enter the authentication token

Use the following parameters to pgx-jshell to provide the token to the PGX shell

./pgx-jshell -b https://myhost:7007 -k keystore.p12 --keystore_auth_token

PGX Server Configuration

When deploying PGX you need a PGX realm implementation that matches your identity provider. The realm implementation and all dependencies need to be bundled into the PGX war file before deployment.

To configure the realm implementation to use, it needs to be set in the PGX config in the pgx_realm section.

For example to set the realm implementation to com.example.realm.ExampleRealm the relevant section in the pgx.conf file looks like:

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

Optional, realm-dependent configuration options can be provided under the options key. The available keys and meaning of the values is determined by the used realm implementation.

{
  "pgx_realm": {
    "implementation": "com.example.realm.ExampleRealm",
    "options": {
      "config_key_1": "value 1",
      "config_key_2": "value 2"
    }
  }
}

Realm Implementation

By default PGX does not ship with a default realm implementation, thus a realm has to be implemented for a specific deployment scenario and identity provider.

A realm gets a token that was attached to the PGX request. It needs to be able to perform the following actions:

  1. check the validity of the token and reject invalid tokens
  2. get the unique username of the user identified by the token
  3. get the set of roles the user has