Navigation :

Application Security

The N2ACD GUIs use the Jarvis RESTful web service framework as a basis for its backend web services. 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, HTTP Basic auth, Active Directory and JWT pass-through.

Note that N2ACD supports both role-based authentication which restricts the features available to users, and ACD customer authentication which restricts which customers each user can access. Customer access is controlled by ACD data and this can be managed both through the administration GUI and the internal user management command line application.

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 each N2ACD application (i.e. both the administration GUI and the flow editor GUI). The example configuration files installed provide templates for Keycloak and Microsoft Azure AD - both which use OAuth 2.0 for authentication and authorization (group/role configuration).

The N2ACD Flow Editor also supports a JWT pass-through mechanism which may be used by external authentication providers that don’t directly support authentication mechanisms such as OAuth2 or Active Directory.

The configuration template for Keycloak is:

<login module="Jarvis::Login::OAuth2">
    <parameter name="client_secret"      value="REPLACE_WITH_CLIENT_SECRET"/>
    <parameter name="client_id"          value="n2acd"/>
    <parameter name="site"               value="https://test-sso.nsquared.co.nz"/>
    <parameter name="token_path"         value="/auth/realms/nsquared/protocol/openid-connect/token"/>
    <parameter name="logout_path"        value="/auth/realms/nsquared/protocol/openid-connect/logout"/>
    <parameter name="redirect_uri"       value="http://localhost/n2acd-admin/complete-oauth-login"/>
    <parameter name="self_signed_cert"   value="/etc/jarvis/nsquared-root-ca.cert.pem"/>

    <group_mappings>
        <group_mapping from="n2acd_admin" to="admin_read,admin_write"/>
    </group_mappings>
</login>

When configuring Keycloak, update each parameter for your deployment. Note that token_path and logout_path will require changing to replace nsquared with the correct Keycloak realm name for your deployment.

The configuration template for Azure AD is:

<login module="Jarvis::Login::OAuth2">
    <parameter name="grant_type"                  value="auth_code"/>
    <parameter name="access_type"                 value="public"/>
    <parameter name="site"                        value="https://login.microsoftonline.com"/>
    <parameter name="public_key_path"             value="/REPLACE_WITH_TENANT_OID/discovery/v2.0/keys"/>
    <parameter name="public_key_store"            value="/tmp/auth_public.key"/>
    <parameter name="public_key_lifetime_seconds" value="86400"/>
    <parameter name="groups_key"                  value="groups"/>
    <parameter name="username_key"                value="unique_name"/>
    <parameter name="user_identifier_key"         value="oid"/>

    <group_mappings>
        <group_mapping from='REPLACE_WITH_N2ACD_ADMIN_GROUP_OID' to='admin_read,admin_write'/>
    </group_mappings>
</login>

When configuring AzureAD, update public_key_path. Other values are unlikely to require adjustment.

The configuration template for JWT pass-through is:

    <login module="Jarvis::Login::JWT">
        <parameter name="token_type"            value="rfc7519"/>
        <parameter name="validate_token"        value="1"/>
        <parameter name="token_source"          value="uri"/>
        <parameter name="token_path"            value="token"/>
        <parameter name="validation_key"        value="/tmp/signing_public_key"/>
        <parameter name="validation_algorithms" value="HS256"/>
        <parameter name="username_key"          value="username"/>
        <parameter name="groups_key"            value="group"/>
        <parameter name="expiry_key"            value="timestamp"/>
        <group_mappings>
            <group_mapping from='n2acd_admin' to='admin_read,admin_write'/>
        </group_mappings>
   </login>

When configuring JWT pass-through, update /tmp/signing_public_key accordingly. Other values may require changes depending on the source JWT provider and the encoding structure used to identify key items such as:

Username
Group Configuration
Expiry Information

Security Groups

N2ACD maps groups provided by the authentication mechanism to internal roles. This allows N2ACD to map AzureAD groups (which are GUIDs) to the list of internal roles used by N2ACD.

The group_mappings section of the login module lists one or more groups, with each group being a list of N2ACD 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 in N2ACD is given on the roles page.

GUI Configuration for Security Integration

Each N2ACD GUI must 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"          : "n2acd-public"
        , "redirect_uri"       : "http://localhost:5005/complete-oauth-login"
        , "response_type"      : "code"
        , "token_endpoint"     : "/auth/realms/nsquared/protocol/openid-connect/token"
        , "access_type"        : "public"
    }
}

Other than access_type and response_type, the rest of the configuration parameters will require updating for the planned

The configuration template for Azure AD is:

"auth": {
    "auth_type" : "oauth"
    , "oauth": {
        "response_type"       : "code"
        , "access_type"         : "public"
        , "site"                : "https://login.microsoftonline.com"
        , "authorize_endpoint"  : "/REPLACE_WITH_TENANT_OID/oauth2/v2.0/authorize"
        , "client_id"           : "REPLACE_WITH_CLIENT_OID"
        , "redirect_uri"        : "http://localhost:5005/complete-oauth-login"
        , "token_endpoint"      : "/REPLACE_WITH_TENANT_OID/oauth2/v2.0/token"
        , "send_challenge_code" : true
        , "scope"               : "api://REPLACE_WITH_CLIENT_OID/n2acd"
    }
}

Update all fields as required for the Azure AD tenant and OID configuration.

The configuration template for JWT pass-through is:

"auth": {
    "auth_type" : "jwt-passthrough"
    , "logout_login_path": "REPLACE_WITH_EXTERNAL_PROVIDER_LOGIN_PATH"
    , "jwt": {
        "token_uri_param": "token"
    }
}

Updating the logout_login_path as required to redirect users to the authenticating applications re-login route after performing a logout within the N2ACD Flow Editor.

CSRF and XSRF Protection

CSRF protection in N2ACD is enabled by default. In the N2ACD 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.

N2ACD 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/n2acd-fe/"/>
    <parameter name="Domain" value="n2acd-fe.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 N2ACD is installed and is to be used.

Path is the HTTP path to the Jarvis web service. This will almost always be /jarvis-agent/n2acd-fe/ for the flow editor, and /jarvis-agent/n2acd-admin/ for the administration GUI.
Domain must be the HTTP domain under which N2ACD 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. However note that the SameSite flag is set only when the module libcgi-pm-perl version 4.29 or later is installed.

Limiting Data Uploads

N2ACD does not require file uploads or large scale POST requests. To limit clients from attempting to upload to much data, edit /etc/jarvis/cgi_params.pm and:

Uncomment the configuration line $CGI::DISABLE_UPLOADS to disable all file uploads.
Uncomment the configuration line $CGI::POST_MAX to limit uploads of data to less than 10Mb.

Application Security