N2IVR GUI Configuration
Introduction
The N2IVR GUI is largely configured by the Jarvis configuration file for the GUI, however several configuration changes must be made to the database directly. See Database Configuaration for these.
The Jarvis configuration file, located at /etc/jarvis/n2srp-gui.xml
provides several configuration fields
which may be adjusted on installation as required for each deployment. For more information on Jarvis and
general configuration options, see the N-Squared Jarvis page on the
N-Squared documentation website.
Authentication Models
The N2IVR GUI supports OAuth 2.0 and local database-based authentication.
Database Authentication
The N2IVR supports local database authentication for user login. This is the default configuration for a new system installation.
A default administration user admin
is created, with the default password
admin
. Database authentication is enabled by having the following Jarvis-
based configuration (in n2srp-gui.xml
) uncommented:
<login module="N2::SIP::Login">
<parameter name="expiry_in_seconds" value="1800"/>
</login>
<hook module="N2::SIP::Login"/>
Additionally, the <habitat>
should not include an "auth"
section in the
JSON stored in the habitat, otherwise the frontend GUI will believe that
public auth should be used.
It is recommended the administrator password be changed immediately on installation. Use the user administration screens or command line tools to make this change.
OAuth 2.0
To enable OAuth 2.0, the following changes to the installed n2srp-gui.xml
file must be performed. Locate the following section of the configuration file
and add the auth
section into the <habitat>
:
This section:
<habitat>
<![CDATA[{
"sync-model": "database"
}]]>
</habitat>
<!-- Example Habitat configuration for an Azure Public OAuth authentication mechanism. -->
<!--
<habitat>
<![CDATA[{
"auth": {
"auth_type": "oauth"
, "oauth": {
"response_type" : "code"
, "access_type" : "public"
, "site" : "https://login.microsoftonline.com"
, "authorize_endpoint" : "/<tenant_id>/oauth2/v2.0/authorize"
, "client_id" : "<client_id>"
, "redirect_uri" : "http://<hostname>/n2srp/complete-oauth-login"
, "token_endpoint" : "/<tenant_id>/oauth2/v2.0/token"
, "send_challenge_code" : true
, "scope" : "api://<application_scope_id>/n2srp"
}
}
}]]>
</habitat>
-->
should become similar to:
<habitat>
<![CDATA[{
"sync-model": "database",
"auth": {
"auth_type": "oauth"
, "oauth": {
"response_type" : "code"
, "access_type" : "public"
, "site" : "https://login.microsoftonline.com"
, "authorize_endpoint" : "/<tenant_id>/oauth2/v2.0/authorize"
, "client_id" : "<client_id>"
, "redirect_uri" : "http://<hostname>/n2srp/complete-oauth-login"
, "token_endpoint" : "/<tenant_id>/oauth2/v2.0/token"
, "send_challenge_code" : true
, "scope" : "api://<application_scope_id>/n2srp"
}
}
}]]>
</habitat>
Note that the auth
configuration must be configured to use the OAuth provider selected for authentication. For more
information on the Jarvis OAuth configuration, see the Jarvis configuration guide.
In addition to updating the habitat section, the following login module must be uncommented and configured
with the same values used in the <habitat>
section:
<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="/<tenant_id>/discovery/v2.0/keys"/>
<parameter name="public_key_store" value="/tmp/auth_public_key"/>
<parameter name="public_key_lifetime_seconds" value="60"/>
<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="<group_oid>" to="administrator,restricted_user"/>
</group_mappings>
</login>
<hook module="N2::SIP::OAuthLogin"/>
Additional group mappings can be made to associate received OAuth groups with
N2IVR administrator
or restricted_user
groups.
Finally the following login configuration must be removed (or commented out), to disable local (DB) based authentication:
<!--
<login module="N2::SIP::Login">
<parameter name="expiry_in_seconds" value="1800"/>
</login>
<hook module="N2::SIP::Login"/>
-->
Additional User Configuration
To correctly work with restricted user access, the OAuth authentication
mechanism requires a default restricted_user
user to be added to the
database. To create the necessary restricted user setup, run the following
SQL against the n2srp
database schema:
INSERT INTO n2srp.announcement_id_groups (group_name, min_announcement_id, max_announcement_id) VALUES ('restricted_user', 1, 100000);
INSERT INTO n2srp.users(user_name, password, enabled, access_level) VALUES ('restricted_user', '13+lROnwRYzjWgtkTfr+a9007a43afc4d3cbde349c7a9efa287ea3e0a07c82400c', TRUE, 10);
INSERT INTO n2srp.user_announcement_id_groups (user_id, announcement_id_groups_id)
SELECT user_id, (SELECT announcement_id_groups_id FROM n2srp.announcement_id_groups WHERE group_name = 'restricted_user')
FROM n2srp.users WHERE user_name = 'restricted_user';
Note that the maximum announcement ID to be used on-platform can be set to a maximum of 2147483647. It can be decreased as low as is appropriate for the deployment.
A value of 100000 is selected as a default.
Note that the admin
and restricted_user
users stored in the database
are never used for login authentication, only for group (resource ID)
authorization.
Database or File Based Audio Replication
The N2IVR GUI supports both file-based and database-based replication of audio content and announcement configuration from the GUI (SMS) node to service nodes. By default database replication is enabled and expected to be used. However if file-based replication should be enabled, change the configuration in the habitat:
<habitat>
<![CDATA[{
"sync-model": "database"
}]]>
</habitat>
to rsync
:
<habitat>
<![CDATA[{
"sync-model": "rsync"
}]]>
</habitat>
When using file-base replication the live
directory on the service nodes must be configured, and optionally the
rsync
path. These are configured in the default_parameters
section:
<default_parameters>
<!-- this has moved to default parameters -->
<parameter name="remote_live_target_directory" value="/var/lib/n2srp/resources/live"/>
<!-- for file copy/syncing -->
<parameter name="rsync" value="/usr/bin/rsync"/>
<parameter name="remote_rsync" value="/usr/bin/rsync"/>
</default_parameters>
Audio Encodings
The N2IVR service node on which N2SVCD and its SIP and RTP services are running will support streaming audio in one or more
audio formats. Those audio formats are configured in the <config>
section of the Jarvis configuration file:
<config>
<!-- Audio identification module. -->
<audio_identifier binary="/usr/bin/soxi"/>
<!-- Source encoding play flags. Kept separate to avoid special logic in the audio encodings. -->
<source_encoding binary="/usr/bin/sox" play_flags="--magic -q '%s' '%s'"/>
<!-- Configuration for each of our supported file codecs. -->
<audio_encodings>
<audio_encoding key="al" label="A-Law" description="ITU-T REC G.711 u-law, 8000 Hz, 64 kbit/s, mono." type="al" extension=".al" binary="/usr/bin/sox" play_flags="--magic -r 8000 -c 1 -q '%s' '%s'" encode_flags="'%s' -t raw -q -r 8000 -c 1 -e a-law '%s'"/>
<audio_encoding key="ul" label="U-Law" description="ITU-T REC G.711 a-law, 8000 Hz, 64 kbit/s, mono." type="ul" extension=".ul" binary="/usr/bin/sox" play_flags="--magic -r 8000 -c 1 -q '%s' '%s'" encode_flags="'%s' -t raw -q -r 8000 -c 1 -e u-law '%s'"/>
<audio_encoding key="amr" label="AMR-NB" description="3GPP TS 26.073 adaptive multi-rate [narrowband] (AMR-NB), 8000 Hz, mono." type="amr-nb" extension=".amr" binary="/usr/bin/bash" play_flags="-i '%s' -c:a libvorbis -b:a 64k -y '%s'" encode_flags="input_file='%s'; output_file='%s'; audio_files=(); modes=(4750 5150 5900 6700 7400 7950 10200 12200); for mode in "${modes[@]}"; do /usr/bin/ffmpeg -i "$input_file" -f amr -c:a amr_nb -ar 8000 -y -ac 1 -b:a $mode "$output_file.$mode"; audio_files+=("$output_file.$mode"); done; /usr/bin/tar -cf "$output_file" "${audio_files[@]}"; /usr/bin/rm "${audio_files[@]}""/>
<audio_encoding key="awb" label="AMR-WB" description="ITU-T REC G.722.2 adaptive multi-rate wideband (AMR-WB), 16000 Hz, mono." type="amr-wb" extension=".awb" binary="/usr/bin/bash" play_flags="-i '%s' -c:a libvorbis -b:a 64k -y '%s'" encode_flags="input_file='%s'; output_file='%s'; audio_files=(); modes=(6600 8850 12650 14250 15850 18250 19850 23050 23850); for mode in "${modes[@]}"; do /usr/bin/ffmpeg -i "$input_file" -f amr -c:a amr_wb -ar 16000 -y -ac 1 -b:a $mode "$output_file.$mode"; audio_files+=("$output_file.$mode"); done; /usr/bin/tar -cf "$output_file" "${audio_files[@]}"; /usr/bin/rm "${audio_files[@]}""/>
</audio_encodings>
</config>
Supported encodings are currently A-law, U-law, AMR Narrowband, and AMR Wideband. These come preconfigured, but may be disabled by commenting out the
corresponding <audio_encoding>
element(s) as required.
Database Configuration
The N2IVR GUI requires several direct database updates to be made before the
GUI can be used. First, connect to the configuration database as n2srp_owner
and apply
the following configuration:
psql -h localhost -U n2srp_owner n2in -W
Disabling the “Working” Set
By default the N2IVR GUI will require users to make changes to an interim “working” set before changes to the announcement configuration can be synced and made available to the N2IVR AS nodes.
However, if you want to disable the working set, and make all changes immediately available to N2IVR AS nodes (delayed only by database replication and N2IVR AS RPT cache timers), change the configuration in the N2IVR database.
Connected to the N2IVR database, run the following update command:
UPDATE n2srp.config set enable_working_set = FALSE;
Reload any N2IVR GUI screens open. From the point of the change on, changes can (and must) be made to the active announcement set, not the working set.
Note that if file-based sync is enabled, then the sync is still required to be performed to transfer files from the SMS node to the N2IVR AS nodes.
IVR Language Configuration
To configure the languages available in the N2IVR GUI, add the language
names to the n2srp.langauge
table. Connect to the N2IVR database and
run the following insert command for each language required:
INSERT INTO n2srp.language (language_name, creation_user) VALUES ('<language>', 'initial creation');
Where <language>
is the language name.
Available language are:
- Arabic
- Cantonese
- Dhivehi
- English
- German
- Hindi
- Japanese
- Mandarin
Each language listed above also has an associated language codec. Other language names can be used if a specific language codec is not required.
Audio Codec Configuration
The N2IVR GUI must be configured to support each individual audio codec that may be uploaded or used during RTP playback.
Once connected to the configuration database as n2srp_owner
define each audio codec
that will be supported. Select from the following:
-- These are encodings used by the service during playback. -- This list corresponds with definitions in lib/N2/RTP/Encoding.pm.
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('μ-Law', 'ul', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('AMR-NB', 'amr', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('AMR-WB', 'awb', 'initial creation');
-- These are valid encodings for source files.
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('MP3', 'mp3', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('OGG', 'ogg', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('FLAC', 'flac', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('RAW', 'raw', 'initial creation');
INSERT INTO n2srp.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('WAV', 'wav', 'initial creation');