OMK Authentication Methods
- 1 Purpose
- 2 Authentication Methods
- 2.1 htpasswd
- 2.2 ldap, ldaps
- 2.3 novell-ldap
- 2.4 apache
- 2.5 connectwise
- 2.6 crowd
- 2.7 openaudit
- 2.8 openid_connect
- 2.9 radius
- 2.10 saml
- 2.11 tacacs
- 2.12 token
- 3 Multiple Authentication Methods
- 4 NMIS9 Notes
- 5 Troubleshooting
- 6 Related Topics
Purpose
State the different authentication methods available for OMK applications.
Authentication Methods
OMK authentication methods are configured in /usr/local/omk/conf/opCommon.nmis inside the authentication hash. This entire file is a PERL hash, so be mindful of the syntax. After editing this file, a 'perl -c opCommon.nmis' will verify if the syntax is correct. For authentication method changes to take effect, the omkd service will need to be restarted.
The supported authentication methods for OMK applications are:
htpasswd
NMIS will use the users defined in the NMIS Users file, by default /usr/local/nmis9/conf/users.dat
The file is in the format created by the Apache htpasswd program.
htpasswd is the default authentication method for NMIS.
Key | Description | Example | Comment |
|
|---|---|---|---|---|
auth_htpasswd_file | Location of the password file |
| Default is | Not in GUI |
auth_htpasswd_encrypt | Enable encrypted passwords | 0/1 | Default is 1. Plain text passwords are checked ONLY if value is 0 or 'plaintext' | Not in GUI |
ldap, ldaps
For versions of products before October 2024, see Legacy LDAP Authentication For current products they have been simplified.
The FirstWave products will use the configured LDAP server to perform authentication and optionally authorization.
You can choose to use ldap or ldaps (secure), you can not use both of these at the same time. The ldap or ldaps options can also be used for Microsoft Active Directory servers.
Following are the configuration items:
Key | Description | Example | Comment |
|---|---|---|---|
auth_ldap_server | LDAP Server Name | host[:port] | The LDAP Server Name. No defaults. Entry must be created. |
auth_ldap_acc | LDAP Account Name |
| The administrative LDAP account name to login to the LDAP Server. The entry must be created. |
auth_ldap_psw | LDAP Password |
| The password associated with the above administrative LDAP account to login to the LDAP Server. The entry must be created. |
auth_ldap_base | Base Context | ou=people,dc=example,dc=com | Base context to attempt to bind to. The entry must be created. |
auth_ldap_attr | Username LDAP Attributes | uid cn sAMAccountName | The LDAP attribute(s) to match to username. |
auth_ldaps_verify | Verify CA Certificates? | require | Only for ldaps, One of 'none', 'optional', or 'require' (default 'optional'). |
auth_ldaps_capath | SSL Certificate Path | /path/to/servercerts/ | Only for ldaps, The full path to a directory containing SSL certificates for Certificate Authority (CA). Ask your LDAP Administrator. |
auth_ldap_privs | Use LDAP Groups? | 0/1 | Use LDAP for Authorisation (Privileges and Groups). See User Authorisation with Active Directory and LDAP. By default, set to 0 (disabled), which means NMIS Authorisation is used. |
auth_ldap_group | Group LDAP Attribute | memberOf | Default is memberOf. The attribute to lookup the LDAP groups the user belongs to. |
novell-ldap
-- Deprecated --
apache
The FirstWave products will use Apache to perform authentication and provide an authenticated user to FirstWave products with all the authorisation policies applied.
connectwise
The FirstWave products will use the ConnectWise API configured for authentication. For this, you need to setup the ConnectWise API and then setup the system to use the same authentication method using 'auth_method_1' => 'connectwise'.
Following are the configuration items for setting up the ConnectWise API in opCommon.json (Cannot be configured in GUI):
Key | Description | Example | Comment |
|---|---|---|---|
auth_cw_server | IP address of the ConnectWise Server | 1.2.3.4 | No defaults. Entry must be created. |
auth_cw_company_id | The company name in ConnectWise | COMPANY |
|
auth_cw_public_key | The ConnectWise Public Key | xxxxxxXXXXXxxxxx |
|
auth_cw_private_key | The Private Key associated with the above Public Key | yyyyyYYYYYyyyyy |
|
crowd
The FirstWave products will use Atlassian Crowd authentication. Use Crowd to assign additional groups to a user and define each service that requires authentication as an application in Crowd.
Following are the configuration items:
Key | Description | Example | Comment |
|---|---|---|---|
auth_crowd_server | Crowd server |
|
|
auth_crowd_user | Crowd User name | username |
|
auth_crowd_password | Crowd Password | password |
|
openaudit
Other FirstWave products can use Open-AudIT to authenticate users. See reference. Open-AudIT can use Active Directory and/or OpenLDAP for user authentication and/or authorisation. Open-AudIT will query both types of LDAP servers to validate a user's username and password and retrieve the user details (roles and orgs the user has access to). The user will be automatically created when they are authenticated.
To configure the use of openaudit authentication the following items must be configured:
Key | Description | Example | Comment |
|---|---|---|---|
oae_server | IP address of the Open-AudIT server | 1.2.3.4 | The link to Open-AudIT for internal connections. Should always be the original value unless explicitly directed by FirstWave to be changed. |
oae_type |
|
| Unused in on-premise installations. |
oae_cloud_server | cloud server URL |
| Unused in on-premise installations. |
omk_ua_insecure | Validation for editing remote nodes | 0 or 1 | Allows insecure (self-signed) SSL certificates |
openid_connect
FirstWave products use OKTA's OpenID Connect for authentication. In the authentication > auth_method_1 entry of opCommon.json, use the openid_connect. For more information, see OKTA OpenID authentication.
Following are the configuration items:
Key | Description | Example | Comment |
|---|---|---|---|
type | Authentication type | okta | The authentication type shall be "okta". |
YOUR_SUBDOMAIN | URL for your subdomain | https://YOUR_SUBDOMAIN.okta.com/oauth2/default/v1/token | Replace only the text in red with your subdomain name. |
password | Password | password | The password shall remain "password", since the internal password field is mapped to the one returned by the OKTA service. |
username | User name | username | The user name shall remain "username", since the internal username field is mapped to the one returned by the OKTA service. |
YOUR_CLIENT_ID | The client ID |
| Enter the client ID. |
YOUR_CLIENT_SECRET | The client secret |
| Enter the client secret. |
grant_type |
| password | This grant type shall be "password". |
scope |
| openid | The scope shall be "openid". |
After making the required changes, restart the omkd service.
radius
The FirstWave products will use the configured radius server (for example, Cisco ACS or Steel Belted Radius).
Following are the configuration items:
Key | Description | Example | Comment |
|---|---|---|---|
auth_radius_server | Radius Server Name | host:port | The Radius Server Name. No defaults. Entry must be created. |
auth_radius_secret | Radius Secret | secret | Also known as the Key |
saml
The FirstWave products will use the configured SAML Identify Provider server (IdP) to authenticate (for example, Keycloak or Okta). The FirstWave products are the SAML Service Provider (SP).
Key | Description | Example | Comment |
|---|---|---|---|
| Single Sign-On (SSO) URL | https://cloak.opmantek.net/realms/my_realm/protocol/saml/clients/omk | Mandatory. The Single Sign-On (SSO) URL is used by the SP to initiate the authentication process. It typically points to the IdP's SAML endpoint where the SP sends an authentication request (AuthnRequest) XML document. |
| Metadata URL | https://cloak.opmantek.net/realms/my_realm/protocol/saml/descriptor | Mandatory. Metadata URL provides essential information about the IdP, including endpoints, certificates, and other settings required for SAML authentication. |
| User Attribute | Username | Optional. SAML IDP attribute to be mapped with NMIS Username. SAML response needs to have a custom attribute which contains the NMIS Username, If the Username is present in NameId then this can be left empty. |
| Login Label | Login with Keycloak SAML | Optional. Label to be used on the FirstWave SAML login screen. Default is Login with SAML |
| Auth SameSite Cookie | Lax | This has to be set to Lax for SAML. The SameSite attribute for cookies is used to control whether cookies are sent along with cross-site requests. |
tacacs
The FirstWave products will use the configured TACACS+ server (for example, Cisco ACS).
Key | Description | Example | Comment |
|---|---|---|---|
auth_tacacs_server | TACACS Server Name | host:port | The TACACS Server Name |
auth_tacacs_secret | TACACS Secret | secret | Also known as the Key |
token
The FirstWave products support an authentication method called token, which offers Delegated Authentication. This enables an external party to pre-authenticate a user, who can access the FirstWave products without having to log in with username and password.
Key | Description | Example | Comment |
|---|---|---|---|
| Token Keys | extusr-1Kf!yVXt8TrP9zi | One or more shared keys |
| Maximum Token Age | 60 | The maximum length of time a token will remain valid. Must be a positive number, and defines how long a token remains valid after creation (in seconds). If not present, the default of 300 seconds is used. |
For more information on how to generate and log in with a token, see Delegated Authentication.
Multiple Authentication Methods
You can use up to 3 authentication methods for fail back. If authentication with method 1 fails, then if they are defined, the remaining methods are tried in order. Authentication fails if they all fail. For example, if you set auth_method_1 to be LDAP and auth_method_2 to be htpasswd and login with the default NMIS credentials (and you have not changed the password), the authentication for LDAP will fail, and then htpasswd authentication with the users.dat will succeed and the NMIS user will be logged in.
Here is an example of the authentication hash inside opCommon.nmis. Remember that statements preceded by the '#' sign are 'commented out' and will not be evaluated. In this example, if ms-ldap fails, it will fail back to htpasswd.
/usr/local/omk/conf/opCommon.nmis
'authentication' => {
'auth_htpasswd_file' => '<omk_conf>/users.dat',
'auth_htpasswd_encrypt' => 'crypt',
'auth_method_1' => 'htpasswd',
'auth_method_2' => '',
'auth_method_3' => '',
'auth_login_motd' => 'Authentication required: default credentials are nmis/nm1888',
'auth_crowd_server' => '',
'auth_crowd_user' => '',
'auth_crowd_password' => '',
'auth_sso_domain' => '',
'auth_expire_seconds' => '3600',
'auth_lockout_after' => 0,
#'auth_ms_ldap_attr' => 'sAMAccountName',
#'auth_ms_ldap_base' => 'CN=Users,DC=your_domain,DC=com',
#'auth_ms_ldap_group' => 'CN=Users,DC=your_domain,DC=com',
#'auth_ms_ldap_debug' => 'false',
#'auth_ms_ldap_dn_acc' => 'CN=Administrator,CN=Users,DC=your_domain,DC=com',
#'auth_ms_ldap_dn_psw' => 'your_administrator_password',
#'auth_ms_ldap_server' => 'your.ip.address.here'
},
Configuration of the External Authentications
In the OMK configuration, you can configure multiple methods, which are used for auth failure. Therefore, for example, if ms-ldap fails, it will fail back to htpasswd. This means, if you set auth_method_1 to be ldap and auth_method_2 to be htpasswd, and login with the default NMIS credentials (and you have not changed the password), the authentication for LDAP will fail, and then authentication with the users.dat will succeed and the user will be logged in.
It is important to change your default passwords if you expect any level of security.
Authentication methods are evaluated in sequence. The first method that returns successful authentication, terminates the authentication process. If a method returns an unsuccessful authentication, the process does not terminate, the next authentication method will be evaluated. Consider the following scenario when provisioning authentication for OMK applications.
OMK First authentication method: LDAP
OMK Second authentication method: htpasswd
User Bob has an LDAP account and has a user in the htpasswd users file.
User Bob leaves the company
The IT department removes Bob's LDAP account assuming he will no longer be able to access corporate systems.
Bob will still be able to access OMK applications because there is a user Bob in the htpasswd user file.
NMIS9 Notes
From NMIS9, changes will instead need to be made to the opCommon.json configuration file (located in /usr/local/omk/conf/). As we are using .json format files instead of .nmis, the format of the attributes to use is slightly different. See the examples below:
LDAP:
/usr/local/omk/conf/opCommon.json
"authentication" : {
"auth_ldap_server" : "the_fqdn_of_your_ad_server:389", # you could also use an IP address here, but you need to ensure that the LDAP/LDAPS port is added in the value, eg. 192.168.1.22:389
"auth_ldap_acc" : "svc_omk_admin@contoso.local",
"auth_ldap_psw" : "password_of_the_auth_ldap_acc_above",
"auth_ldap_context" : "dc=contoso,dc=local",
},
LDAPS (Secure)
/usr/local/omk/conf/opCommon.json
"authentication" : {
"auth_ldaps_server" : "the_fqdn_of_your_ad_server:389", # you could also use an IP address here, but you need to ensure that the LDAP/LDAPS port is added in the value, eg. 192.168.1.22:389
"auth_ldap_acc" : "svc_omk_admin@contoso.local",
"auth_ldap_dn_psw" : "password_of_the_auth_ldap_acc_above",
"auth_ldap_context" : "dc=contoso,dc=local",
},
TACACS:
"auth_tacacs_server" : "host:port",
"auth_tacacs_secret" : "secret",
MS-LDAP
An example of integrating your ms-ldap setup with modules such as opConfig, opEvents, opCharts etc. is below. Ensure you have also included ms-ldap as in one of the auth_methods:
/usr/local/omk/conf/opCommon.json
"authentication" : {
...
"auth_ms_ldap_server" : "IP_ADDRESS_OF_YOUR_MS_LDAP_SERVER", #eg. 192.168.1.22
"auth_ms_ldap_dn_acc" : "svc_omk_admin", #you should only need to use the username of the user here, but if this is not successful, you can use username@domain as well.
"auth_ms_ldap_dn_psw" : "password_of_the_dn_acc_above",
"auth_ms_ldap_attr" : "sAMAccountName",
"auth_ms_ldap_base" : "OU=Network Admins,DC=contoso,DC=local",
...
},
MS-LDAPS (Secure)
/usr/local/omk/conf/opCommon.json
"authentication" : {
...
"auth_ms_ldaps_server" : "IP_ADDRESS_OF_YOUR_MS_LDAPS_SERVER", #eg. 192.168.1.23
"auth_ms_ldap_dn_acc" : "svc_omk_admin", #you should only need to use the username of the user here, but if this is not successful, you can use username@domain as well.
"auth_ms_ldap_dn_psw" : "password_of_the_dn_acc_above",
"auth_ms_ldap_attr" : "sAMAccountName",
"auth_ms_ldap_base" : "OU=Network Admins,DC=contoso,DC=local",
...
},
RADIUS
"auth_radius_server" : "host:port",
"auth_radius_secret" : "secret",Once you have saved the updated opCommon.json configuration, you will then need to restart the omkd daemon.
Troubleshooting
If you are experiencing issues with configuring your external authentication method, extra debug can be enabled to assist.
Depending on the authentication method you are using, the following two attributes can be added to your opCommon.json. This should cover most, if not all of our authentication methods to debug.
/usr/local/omk/conf/opCommon.json
"authentication" : {
...
"auth_debug" : 1,
"auth_ldap_debug" : "true"
...
},Save the file once you have added these two extra lines and restart omkd. Repeat the authentication process again, then review auth.log (located in the /usr/local/omk/log directory) and troubleshoot.
auth_debug | Use Debug? | true/false | If true, log additional debugging information to the auth.log file |
|
|
|
|
|---|