Configuration

Standalone Execution

The OCS is run using the script n2ocs. To run the OCS manually, run:

cd /opt/nsquared/ocs/bin
./n2ocs ../etc/server.json

The only command line argument is to the configuration file.

As the OCS is a Java program, it is possible to provide arguments to the JVM via the JAVA_OPT environment variable. For example, to define the configuration file for logging:

export JAVA_OPTS="-Dlogback.configurationFile=/opt/nsquared/ocs/etc/logback.xml"

The OCS uses Logback for logging and the logging configuration can be configured in a logback.xml file.

JSLEE Integrated Execution

Refer to JSLEE configuration

Example Configuration File

The n2ocs.json file is a JSON based configuration file which allows C-style multi-line comments.

When installed using the OS packaging, the configuration file will be installed in to the /opt/nsquared/ocs/etc/ directory. The example configuration file will include basic configuration:

{
    "database.mongodb": {
        "host": "127.0.0.1",
        "port": 27017,
        "db_name": "n2ocs",
        "useObjectId": false
    }
    , "http.api.enabled": true
    , "http.api.interface": "0.0.0.0"
    , "http.api.port": 5490
    , "management.http.api.port": 5492
    , "vouchers.enabled": true
    , "voucher.generation.enabled": false
    , "auth.enabled": false
    , "auth.provider": "jwt"
    , "auth.jwt.publickey": "base64 encoded public key"
    , "auth.jwt.rolepath": "resource_access/n2ocs/roles"
    , "groveller": {
      "account": {
        "enabled": true
      }
   }
}

Configuration Options

The following configuration options are available:

Database Configuration

The configuration option database.mongodb is required. This sub-object of the overall configuration defines how to connect to the OCS database via the MongoDB driver. See https://vertx.io/docs/vertx-mongo-client/java/ for more information on how to configure the driver.

Note that the configuration option useObjectId must be set to false, as object IDs are not supported by the OCS.

A standard Mongo DB connection is:

{
    "database.mongodb": {
      "host": "10.42.2.103",
      "port": 27016,
      "db_name": "n2ocs",
      "useObjectId": false
    }
}

OCS Groveller Configuration

Configuration to determine whether the groveller runs or not on the node. An example configuration for the groveller includes:

{
    "groveller": {
        "account": {
            "enabled": true,
            "reprocess.period.hours": 12,
            "maximum.tps": 4
        }
    }
}

This configuration will enable wallet grovelling. To control groveller speed, the following configuration options may be used:

Security Configuration

The OCS API may be secured using OpenID Connect (OIDC), specifically via JWT tokens.

The OCS is tested against the following OIDC providers:

• Keycloak
• AzureAD

This authentication is optional, however it is strongly recommended for when the OCS API is being used by provisioning and frontend services. When using Keycloak, the public key (for the configuration option auth.jwt.publickey) can be retrieved by:

1. Logging in to the Keycloak administration screens.
2. Choosing the N2OCS realm.
3. Choosing the keys tab from the Realm Settings screen.
4. Press the Public key button to show the public key for the RS256 Algorithm.

To enable and use the OpenID connect authentication solution, configure the following options:

OCS Roles

The JWT role path must provide the authenticated user’s roles to which the OCS should apply authorization checks. The following high level roles are used by the OCS to manage engine: