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'. The realm consists of interfaces that can be implemented to fit a specific identity provider.

Which realm implementation to use needs to be set in the PGX configuration.

Authentication Flow

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

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 identity provider using the token.

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.

The realm implementation needs to be able to do the following actions given a token:

1. The realm needs to check the validity of a token and reject invalid and expired tokens.
2. Given a token it needs to be able to get the unique username and the set of roles which corresponds to the user identified by the token.