Navigation :

Frontend Configuration

Jarvis Configuration File

The N-Squared Voucher Server GUI is a web-based responsive SPA designed for use on all modern browsers. Configuration of the GUI and it’s API is managed through a Jarvis configuration file in the middleware layer.

The Jarvis configuration file for the N2VS GUI is /etc/jarvis/n2vs-admin.xml.

Application Security

The N2VS GUI uses the Jarvis auth framework for its security. These backend services should be configured with authorization and authentication layers using the Jarvis security subsystem.

The Jarvis security subsystem supports a variety of authentication mechanisms including OAuth 2 (including Active Directory) and HTTP Basic Authentication.

Note that N2VS supports both role-based authentication which restricts the features available to users. The Jarvis security subsystem also supports HTTP security measures such as CSRF and XSRF protection. These should be enabled for all deployments.

Authentication Configuration for API Security

The <login> configuration in each Jarvis configuration file defines the security to apply to the backend API. This configuration secures the API from unauthorized use.

A Jarvis login module must be configured for the N2VS application. The example configuration files installed provides templates for Keycloak OAuth and local authentication.

The configuration template for Keycloak is:

<login module="Jarvis::Login::OAuth2">
  <parameter name="grant_type"                  value="auth_code"/>
  <parameter name="access_type"                 value="public"/>
  <parameter name="site"                        value="https://test-sso.nsquared.co.nz"/>
  <parameter name="public_key_path"             value="/auth/realms/nsquared/protocol/openid-connect/certs"/>
  <parameter name="groups_key"                  value="groups"/>
  <parameter name="public_key_store"            value="/tmp/auth_public_key"/>
  <parameter name="public_key_lifetime_seconds" value="10"/>
  <parameter name="self_signed_cert"            value="/etc/jarvis/N2-CA.pem"/>
  <parameter name="groups_key"                  value="groups"/>
  <parameter name="username_key"                value="preferred_username"/>
  <parameter name="user_identifier_key"         value="sub"/>

  <group_mappings>
    <group_mapping from='n2vs_admin' to="service_channel_write,service_channel_read,distribution_channel_read,distribution_channel_write,voucher_generator_read,voucher_generator_write,voucher_type_read,voucher_type_write,voucher_batch_read,voucher_batch_write,voucher_batch_write-configure,voucher_batch_write-generate,voucher_batch_write-lock,voucher_batch_write-void,voucher_batch_write-mark-redeemable,voucher_batch_write-distribute,voucher_read,voucher_update,voucher_redeem_by_serial_number,audit_read"/>
  </group_mappings>
</login>

When configuring the OAuth provider, update each parameter for your deployment. Jarvis documentation covers the full OAuth configuration.

Security Groups

N2VS maps groups provided by the authentication mechanism to internal roles. This allows N2VS to map OAuth groups to the list of internal roles used by the Voucher Server.

The group_mappings section of the login module lists one or more groups, with each group being a list of N2VS roles to grant to users who have a group.

Note that if a user has more than one of the listed groups, the user will receive the set of all roles across both mappings.

A full list of the roles available is included below.

GUI Configuration for Security Integration

The N2VS GUI be configured to correctly integrate with the API security defined in the <login> configuration section. The GUI’s security configuration is defined as part of the <habitat> and is defined in JSON format.

<habitat><![CDATA[
{ json configuration is here }
]]>
</habitat>

The configuration template for Keycloak is:

"auth": {
  "auth_type": "oauth",
  "oauth": {
    "site"                 : "https://test-sso.nsquared.co.nz"
    , "authorize_endpoint" : "/auth/realms/nsquared/protocol/openid-connect/auth"
    , "client_id"          : "n2vs"
    , "redirect_uri"       : "https://n2vs.nsquared.co.nz/complete-oauth-login"
    , "response_type"      : "code"
    , "token_endpoint"     : "/auth/realms/nsquared/protocol/openid-connect/token"
    , "access_type"        : "public"
  }
}

Update all fields as required for the OAuth system being used.

CSRF and XSRF Protection

CSRF protection in N2VS is enabled by default. In the Jarvis configuration file, the application configuration is set up by default as follows:

<app
    csrf_protection         = "yes"
    cross_origin_protection = "yes"
    xsrf_protection         = "yes"
>
<!-- other fields excluded for clarity -->

Cross-origin protection, which ensures that each request to the API is from an appropriate referrer origin, is also enabled by default.

You may disable any of this protection by setting the appropriate configuration attribute to no.

N2VS session cookies are protected using HTTP. The following example configuration defines a secure cookie configuration:

<sessiondb store="driver:file;serializer:default;id:md5" expiry="+1800s" cookie="id">
    <parameter name="Directory" value="/tmp/"/>
    <parameter name="Path" value="/jarvis-agent/n2vs-admin/"/>
    <parameter name="Domain" value="n2vs.nsquared.co.nz"/>
    <parameter name="Secure" value="yes"/>
</sessiondb>

Note that the Path and Domain must be updated for the deployment’s environment. Configuration options Path, Domain and Secure are disabled by default, however to increase cookie security, these should be set appropriately for the environment into which N2VS is installed and is to be used.

Path is the HTTP path to the Jarvis web service. This will almost always be /jarvis-agent/n2vs-admin/ for the administration GUI, and
Domain must be the HTTP domain under which N2VS will be accessed. If multiple domains are to be used, then this option will need to be left blank.
Secure should be set to yes if all access is to be via HTTPS.

Note that the HttpOnly and SameSite flags are set on session cookies by default.

Security Role List

N2VS uses a granular list of roles that are mapped to user groups based on the authentication configuration for each of the application GUIs. For more information on how to map user groups to these roles, see above.

Security Group	Admin?	Comment
`admin_read`	Y	Read access to the entire application.
`admin_write`	Y	Write access to the entire application.
`service_channel_read`	N	Read access to the “Service Channels” configuration stored in SMS Database.
`service_channel_write`	N	Write access to the “Service Channels” configuration stored in SMS Database.
`distribution_channel_read`	N	Read access to the “Distribution Channels” configuration stored in SMS Database.
`distribution_channel_write`	N	Write access to the “Distribution Channels” configuration stored in SMS Database.
`voucher_generator_read`	N	Read access to the “Voucher Generators” configuration stored in SMS Database.
`voucher_generator_write`	N	Write access to the “Voucher Generators” configuration stored in SMS Database.
`voucher_type_read`	N	Read access to the “Voucher Types” configuration stored in SMS Database.
`voucher_type_write`	N	Write access to the “Voucher Types” configuration stored in SMS Database.
`voucher_batch_read`	N	Read access to the “Voucher Batches” configuration stored in SMS Database.
`voucher_batch_write`	N	Write access to the “Voucher Batches” configuration stored in SMS Database. Users with this role can create new voucher batches, and update voucher batch configuration while the voucher batch is in the `Configuring` state only.
`voucher_batch_write-configure`	N	Can trigger a voucher batch state change from Configuring to Validated, or from Validated to Configuring.
`voucher_batch_write-generate`	N	Can trigger the generation of a voucher batch.
`voucher_batch_write-lock`	N	Can mark a voucher batch as `locked`.
`voucher_batch_write-void`	N	Can mark a voucher batch as `void`.
`voucher_batch_write-distribute`	N	Can mark a voucher batch as Redeemable.
`voucher_batch_write-mark-redeemable`	N	Can trigger the distribution of a voucher batch. Note that the actual distribution method will be predetermined by configuration.
`voucher_read`	N	Can query a single voucher’s details based on a voucher serial number. Can query summary data on vouchers.
`voucher_update`	N	Can update a single voucher’s state (e.g. to locked), and set a single voucher’s reseller/distributor information. Can update vouchers in bulk using the voucher range (by serial number) update workflow, which allows bulk update to voucher state and voucher reseller/distributor.
`voucher_redeem_by_serial_number`	N	Can redeem a single voucher.
`audit_read`	N	Can view auditing information stored in the audit database.