Gateway Authentication Technical Reference

Introduction Copied

When using the template setup file, users are allowed full access to all Gateway features for ease of configuration. User access to various functions within the Gateway can be restricted by the use of user definitions and permissions, configured in authentication.

Due to this section of the Gateway setup controlling who is allowed to edit the setup itself, care must be taken not to make changes which accidentally lock you out from further use of the Gateway Setup Editor. To help you avoid this, the Gateway makes some special checks when you use the Validate command in Gateway Setup Editor and when you save (apply) the setup:

• If no users at all would have permission to edit setup, the Gateway reports a critical issue. This prevents the setup from being applied. You can force all future setup changes to be made manually (by editing the XML files themselves), but only by actually editing the setup manually.
• If you have setup edit permission and you validate a setup which you have changed so that you will lose that permission, the Gateway will warn you of this, but it will not prevent you from applying the setup.
• When you first enable user authentication, the Gateway does not know yet which user you will connect as. Gateway warns you to check that you still have setup edit permission, but the Gateway does not prevent you from applying the setup. Also, this warning appears if you are logged in as a generic user with administrator permissions.

None of these checks are made when the Gateway validates its setup as it starts up, if the -validate command line option is used or if the Gateway reloads its setup through the includes > reloading setting or the SIGUSR1 signal (see includes > reloading or SIGUSR1). The Gateway will also not warn you about locking yourself out if you do so by editing an include file when you do not have permission to edit the main setup file.

Login types Copied

Gateway currently supports three mechanisms for authenticating users. These are password-based logins, system logins and SSO logins.

• SSO (single sign-on) logins use the ITRS SSO Agent to provide authentication and authorisation. The Gateway authenticates and authorises the user via an SSO token obtained by the Active Console from the SSO Agent. The SSO Agent is provided as a separate binary to the Gateway and can be downloaded from the ITRS Resources Downloads page.

General Copied

The first level of authentication allows administrators to control which users can login to Gateway and receive data. To enable user login authentication, configure Authentication. As a minimum, authenticateUsers and combineMode must be specified. These are required so that they are available during setup file merging.

authentication Copied

The authentication top-level section allows configuration of user access control to Gateway features. If no authentication section is specified, all users can connect to Gateway and access any feature as an administrator user.

Mandatory: No

Default: No authentication

Configuration - Basic tab Copied

authentication > authenticateUsers Copied

Boolean controlling if users are required to log in on connection to the Gateway.

Mandatory: Yes

authentication > combineMode Copied

Specifies the combine mode for permissions specified on users and groups. This is a Gateway-wide setting. Possible values are highest or lowest.

Mandatory: Yes

Configuration - Advanced tab Copied

authentication > enableSectionPermissions Copied

Boolean controlling if section permissions should be used. This is a Gateway-wide setting.

Section permissions are ignored if not set or set to false.

See Sections permissions for more information.

Mandatory: No

Default: false

authentication > enableDataPermissions Copied

Boolean controlling if data permissions should be used. This is a Gateway-wide setting.

Data permissions are ignored if not set or set to false.

See Data permissions for more information.

Mandatory: No

Default: false

authentication > caseInsensitiveUsernames Copied

Boolean controlling if usernames are case sensitive.

As well as controlling logging on to the system, this affects the definition of users since the names of users in the setup are also used as usernames.

When set to true, you cannot define two users with the same name but with a different case, as this would result in two usernames with the same name but different case.

Note

References to users (such as from roles and alerting) still use the name of each user (rather than username), and as such remain case sensitive regardless of what this is set to.

This is a Gateway-wide setting.

Mandatory: No

Default: false

Configuration - Single Sign On tab Copied

authentication > singleSignOn Copied

Allows SSO authentication for this Gateway.

authentication > singleSignOn > ssoAgent Copied

URL location of the SSO provider. This configuration is used only when the SSO provider is either SSO Agent or Gateway Hub.

• By the REST service /rest/authorize. If this URL is not provided, it is not possible to run REST commands as an SSO user.
• To obtain the list of SSO users that have the role properties specified in authentication > userAssignment > roleProperties > roleProperty.

To obtain a list of SSO users from the SSO Agent, the Gateway must first authenticate itself with the SSO Agent, which can be done through any of the following options:

• For SSO Agent that supports Kerberos Authentication, Kerberos authentication requires -kerberos-principal and -kerberos-keytab to be set using the command line. See Gateway command line options and Authenticating with Kerberos in Gateway Setup Files.

• For standalone SSO Agent that supports Basic Authentication:

  1. Get the username and password that the Gateway will use to connect to the SSO Agent.

  2. Use the -store-app-key command line option to create an app key:

     ./gateway2.linux_64 -store-app-key app.key gwuser <password> ssoAgent
     

  3. You must add the created app.key file to the Gateway at startup using the -app-key app.key command.

• For SSO Agent in Gateway Hub, generate an app-key using a client_id and secret obtained from Gateway Hub. See Connect securely using SSO or API keys in.

authentication > singleSignOn > jwt > publicKey Copied

Public key of the single sign on service. This key is used to verify that all JWT tokens have been generated by the single sign on service and have not been manipulated by a third party.

The key must be in PEM format, with lines no longer than 76 characters. For example:

-----BEGIN PUBLIC KEY----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA9KTR6IFL44UTGCs5Hi2xfISO7eMBaqf7
5BQym/E8woQE2NOocyAvshGLAaE9oHP4vqRnc+hHyDs7DDF2u0VFcYp6r4uISe+HUka+wKjfSZZF
OB5lFYzZfb7hRGvc5kMZEvg7QYBej/c37uSB9r1/T4yao3SAdHGEwlthTKf0V+TtDGvlWPKGzVdC
YowmNC0Z1RxsT/X3jhNvnkHRQYXWhwGiEKU1+U7Bgtlpzd/3UFQnZsOIMFME9R53b+Wjron04B6O
BB0jqmWFTYaoXWh2oZBK5XZ1e165HaNXAYkeC4RcHdu8M0urk8JkkRby9M8UXxCATbVrtYGosoI9
JH+t1wIDAQAB
-----END PUBLIC KEY-----

Caution

Changing this value results in all SSO user connections being dropped.

The public key used to sign Obcerv JWTs can be obtained from the auth/realms/obcerv endpoint provided by Obcerv. This produces a JSON file that looks like:

{"realm":"obcerv","public_key":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAs+MoswQTYc+J0MhLhzprJTb8U0MAd4f1X+txv9j653tsIGTsyV0ufJpsvTMk+kt/7XI1RNGuJ9IqrYenRnN1h65C6xb1ehJ0f8BCYLL+lv084RR5T7bcxAIKOEr6TUQmKSIE2uqi0EZg0MyGhAkEcDjrf7YqPPTiMCffOx+T9/yPo/wLcSluP2VdESkU0R91D9d2KGv0LmzWFLHRN9Ag70EWokM4Cw+/zi32ZqQEGlTA1G7YyEM+FlbrYPSYiBe1toCJ3fKJE1xvrp7+kj4imxWd5l0ljs/233DCcBVEM46UJ5cupTptZfTGnP/9NbrYySMpT6wga5eK2y28AdOFJQIDAQAB","token-service":"https://cconfig-playground.itrslab.com/auth/realms/obcerv/protocol/openid-connect","account-service":"https://cconfig-playground.itrslab.com/auth/realms/obcerv/account","tokens-not-before":0}

The key needs to be line-wrapped with the added PEM Public key header and footer using the following bash script:

#!/bin/bash
obcerv_url=$1
echo "-----BEGIN PUBLIC KEY-----"
curl -s -k ${obcerv_url}/auth/realms/obcerv | jq -r .public_key | fold -w 40 -
echo "-----END PUBLIC KEY-----"

Users Copied

Once authentication is enabled, the Gateway will require authentication details for users attempting to connect. Users will be required to send a username to login which is then matched against the configured user definitions. If no matching definition is found, or if the user credentials do not match an accepted credential as specified in the user configuration, then the login attempt will fail.

Users are configured within the users section, which is inside the top-level authentication section. Each user definition must be named - this name is used as the username. These names must be unique among other user definitions, so that it is clear which definition is used when processing a user login request.

If a user definition with the special name “Administrator” is made, this user will be given full privileges to all functions on the Gateway. This user will also be allowed to edit Centralised Configuration for the Gateway without being logged in using SSO. Login types in the definition are still applicable so it is possible to deny login for this user if required, either by explicitly denying logon for the selected type or by not configuring a user definition with this name.

User definitions can contain a number of additional settings, which are described below:

authentication > users Copied

Contains any number of uniquely named user definitions.

Mandatory: No

Default: No users defined

authentication > users > user Copied

A uniquely named user section represents a single user definition. The name is used as the username, and must be unique among all other user definitions. The user “Administrator” is a built in user and will by default receive full permissions.

Mandatory: Yes

authentication > users > user > fullName Copied

A field for specifying the full name of a user, rather than the (typically shortened) username.

Mandatory: No

Default: No description

authentication > users > user > password Copied

The password configuration allows users to specify the password with which they login.

Mandatory: No

Default: The user cannot logon using password authentication.

authentication > users > user > password > encodedPassword Copied

This option specifies the password for the user is stored encoded in a format produced using the UNIX crypt utility, which is a one-way hashing of the password.

Mandatory: No

authentication > users > user > password > plaintext Copied

This option specifies the password is stored un-encrypted in the setup file and should only be used for debugging purposes.

Mandatory: No

authentication > users > user > genericUser Copied

Optionally specifies that this user is a generic user definition (see Generic Users section). There can only be one generic user definition per gateway.

Mandatory: No

Default: false

authentication > users > user > allowLogin Copied

Specifies whether this user can logon. Defaults to true. This setting can be set to false to deny users access to the gateway, without removing their user configuration from the setup.

Mandatory: No

Default: true

authentication > users > user > allowPasswordAuth Copied

Specifies whether the user can logon using their password.

Mandatory: No

Default: true if password is specified, false otherwise

authentication > users > user > allowSystemAuth Copied

Specifies whether the user can log on using system authentication.

Mandatory: No

Default: false

authentication > users > user > allowSslAuth Copied

Specifies whether the user can log on using an SSL Certificate.

Mandatory: No

Default: false

authentication > users > user > sslIdentities Copied

Specifies the SSL identities that will be used to authenticate the user if SSL authentication is enabled.

Mandatory: No

authentication > users > user > sslIdentities > id Copied

Specifies the type of the SSL identity (e.g. Subject).

Mandatory: Yes

authentication > users > user > sslIdentities > id > fingerprint Copied

Specifies the value of the SSL Fingerprint in capital hexadecimal characters (e.g. 4918A6213FF22C69739F16C05B1EF59D23A47B1E).

Mandatory: Yes

authentication > users > user > sslIdentities > id > subject Copied

Specifies the value of the SSL Subject (e.g. /CN=importingGateway/C=UK/L=London/O=ITRS).

Mandatory: Yes

authentication > users > user > permissions Copied

Specifies the permissions applicable for this user. See the permission section for more details.

Mandatory: No

Default: No permissions

authentication > users > user > roleProperties Copied

This setting specifies a set of property tags to apply to the user definition. A role definition can then select users to become members of the role, based on which tags they have.

For example, users who monitor or maintain MQ servers can be given an “MQ” tag. A role can then be created which selects all MQ users (users tagged with MQ) to give them specific permissions for MQ servers and/or plug-ins configured in Geneos.

Mandatory: No

authentication > users > user > roleProperties > roleProperty Copied

Specifies the value of a single role property tag.

Mandatory: No

authentication > users > user > information Copied

Specifies generic information associated with the user. Typically this would include contact information such as the user’s e-mail address which can be used by the gateway to send automated messages if configured to do so.

Mandatory: No

authentication > users > user > information > info > type Copied

Specifies the type of information e.g. Email.

Mandatory: Yes

authentication > users > user > information > info > value Copied

Specifies the value of information.

Mandatory: Yes

An example configuration is shown below:

User groups Copied

Users can be grouped in the setup file for ease of management using userGroup sections, in a similar way to managedEntityGroups. User group definitions also allow role property tags to be specified, which are applied recursively to all contained users and userGroups (again, this is similar to managedEntity attributes). These tags can be used by roles to select sets of users for role membership - see the Roles section for more details.

authentication > user > userGroup Copied

User groups are used to group sets of users, to improve ease of setup management.

Mandatory: No

authentication > user > userGroup > name Copied

Specifies the name of the userGroup. Although the name is not used internally by gateway, it is recommended to give the group a descriptive name so that users editing the setup file can easily determine the purpose of the group.

Mandatory: Yes

authentication > user > userGroup > roleProperties Copied

This setting specifies a set of property tags to apply to all contained user and userGroup definitions.

Mandatory: No

authentication > user > userGroup > roleProperties > roleProperty Copied

Specifies the value of a single role property tag.

Mandatory: No

In this example image, several userGroups have been configured (London, MQ, JMX and New York). Any role properties defined on London will be applied to the user jrichardson, and also to the contained userGroups MQ and JMX (and to any users or userGroups inside of these).

These role properties will not be applied to New York, since the New York userGroup is not specified within London.

Generic Users Copied

For large installations with a number of non-privileged users, configuring and managing user definitions for these users can be time consuming. Gateway provides the “generic users” mechanism which allows unique logins for these users, but is configured using a single user definition called the generic user definition.

The generic user definition is the same as a normal user definition, but with the optional setting genericUser set to true. Only one definition per gateway can be specified as a generic user and it is a checked error to configure more than one.

When a generic user definition is present in the system, users connecting to gateway using password or system login without their own specific user definition will use the generic user definition. This definition controls access rights to gateway, and on successful login the user will inherit all the groups and permissions as defined for the generic user.

The gateway audit and system log files will record when users connect using the generic user mechanism. Information logged includes the original username supplied by the user as well as the connecting IP address.

This definition allows system-login for generic users, and so users will connect using their system login name (e.g. their Windows user account).

Roles Copied

Roles allow users to be split into manageable units, which simplifies the task of assigning permissions to users. Users can have zero or more roles, and for each role the user inherits all permissions associated with the role.

Roles are defined in the authentication top-level section of the setup file. Any number of roles can be specified, although each must have a unique name.

A role with the special name “Administrators” will automatically be given full permissions, in a similar way to the specially named “Administrator” user. Any users with the “Administrators” role will inherit these permissions, thus gaining full privileges to all gateway functions.

Assigning roles to users Copied

There are two different methods available for assigning roles to users, and both can be used either singly or in conjunction. The simplest is to reference each user (by name) from the role, although this can be hard to manage for large numbers of users.

The other method is to use role properties to assign roles. Each user can be configured with a set of role properties, which are just user-configured text strings (tags) that are applied to each user. These properties are also inherited from any parent userGroups that the user definition is contained within, and recommended practise is to set properties on the userGroups so that changing properties for several users at a time is made easier.

Once role properties have been applied to the users, the users can be assigned to roles using these. To do this, configure the role with a set of role properties. Any user which contains a matching role property will then be added to that role.

Role configuration Copied

Settings for configuring a role definition are described below.

authentication > roles > role Copied

The roles section represents a list of roles, and each role must be uniquely named. The “Administrators” role is built-in and any users with this role will by default receive full permissions.

Mandatory: Yes

authentication > roles > role > description Copied

A textual description of the role.

Mandatory: No

Default: No description

authentication > roles > role > permissions Copied

Specifies the permissions that apply for this role. These permissions will then be inherited by all users with this role. See the permissions section for more details.

Mandatory: No

Default: No description

authentication > roles > role > roleProperties Copied

A set of properties used for selecting users for this role. Users which contain any property in this set are added to the role. See assigning roles to users for more details.

Mandatory: No

Default: An empty set (no properties).

authentication > roles > role > roleProperties > roleProperty Copied

Specifies a single property value, as part of a set used to select users for the role.

Mandatory: No

authentication > roles > role > users Copied

A list of referenced users which are assigned this role, and so inherit permissions from the role.

Mandatory: No

authentication > roles > role > users > user Copied

A named reference to a user in the users section. Referenced users are assigned this role.

Mandatory: Yes

authentication > roles > role > information Copied

Specifies generic information associated with the role. Typically this would include contact information such as a group e-mail address which can be used by the gateway to send automated messages if configured to do so.

Mandatory: No

authentication > roles > role > information > info > type Copied

Specifies the type of information e.g. Email.

Mandatory: Yes

authentication > roles > role > information > info > value Copied

Specifies an information value. E.g. If the information type is Email, then the value could be an email address.

Mandatory: Yes

Group configuration Copied

Earlier versions of gateway used groups of users for permissions management. These settings still work, but have been deprecated since they can easily be confused with userGroups. It is recommended to switch to using roles instead.

Group definitions can contain the following settings described below:

authentication > groups > group Copied

Deprecated: Use authentication > roles > role instead.

Mandatory: Yes

authentication > groups > group > description Copied

Deprecated: Use authentication > roles > role > description instead.

Mandatory: No

Default: No description

authentication > groups > group > users Copied

Deprecated: Use authentication > roles > role > users instead.

Mandatory: No

Default: No description

authentication > groups > group > users > user Copied

Deprecated: Use authentication > roles > role > users > user instead.

Mandatory: Yes

authentication > groups > group > permissions Copied

Deprecated: Use authentication > roles > role > permissions instead.

Mandatory: No

Default: No description

authentication > groups > group > information Copied

Deprecated: Use authentication > roles > role > information instead.

Mandatory: No

authentication > groups > group > information > info > type Copied

Deprecated: Use authentication > roles > role > information > info > type instead.

Mandatory: Yes

authentication > groups > group > information > info > value Copied

Deprecated: Use authentication > roles > role > information > info > value instead.

Mandatory: Yes

Permissions Copied

Both user and role definitions can contain permission entries. These entries detail which gateway functions the user can access. By default user and role definitions have no permissions and so any users logged-in using these definitions will be unable to do anything aside from viewing the monitoring data.

Configuration Copied

Permissions are configured inside the permissions section of a user or role definition. Each permission definition is specified with three pieces of information; the item (what is being permissioned), the targets (which data-items the permission applies to) and the actual permission values (access rights).

The item and targets work hand-in-hand to define the permissions. Using both of these settings, it is possible to give permissions to users to snooze (for example) data from one managed entity, but not another.

Configuration settings for permissions are shown below:

authentication > roles > role > permissions > permission Copied

A permission section defines a single permission entry. This entry should be located inside the permissions section of a user or role definition.

Mandatory: No

Command permissions configuration Copied

authentication > roles > role > permissions > permission > command Copied

Specifies a single user command permission entry. This section is mutually exclusive with the data, sections and setup section below (i.e. a permission entry type can only be one of command, data, sections or setup only).

Mandatory: Yes (one of command, data, sections or setup type must be specified).

authentication > roles > role > permissions > permission > command > targets Copied

The targets section contains a list of data-items that this command permission entry applies to. There must be at least one target in a command permission entry. The paths can include wildcards and allow different users or roles to have permissions for commands on different sets of data-items.

Mandatory: Yes

authentication > roles > role > permissions > permission > command > targets > target Copied

A target data-item, specified as a path to the item. See the command targets section for more details.

A target specifies a section of the directory tree, from the specified item downwards. A value of / specifies all items from the root, and so is a good value to use if you are unsure which path to configure.

Mandatory: Yes

authentication > roles > role > permissions > permission > command > names Copied

A list of command names that this permission applies to.

Mandatory: Yes

authentication > roles > role > permissions > permission > command > names > name Copied

The name of a single command the permission applies to. Names can be specified with wildcard characters (* and ?) as required. See Specifying command names . A value of * will match all commands on gateway.

Mandatory: Yes (at least one name is required)

authentication > roles > role > permissions > permission > command > groups Copied

The groups section specifies a list of group names, which is then checked in addition to the command name comparison, to determine whether the permissions entry applies to the selected command. The gateway will check that the command name and the command group match before attempting to apply the permission. If all commands in a command group (or internal group) are required, the Names for the command should be set to *.

Mandatory: No

authentication > roles > role > permissions > permission > command > groups > group Copied

Specifies a single command group entry. This will be checked against the command group list, in addition to the command name, when determining whether the permission entry applies to the command.

Mandatory: No

authentication > roles > role > permissions > permission > command > groups > group > commandGroup Copied

The commandGroup entry specifies a command group as configured by the user, in the commands section of the setup file.

Mandatory: Yes (one of commandGroup or internalGroup must be specified in group).

authentication > roles > role > permissions > permission > command > groups > group > internalGroup Copied

The internalGroup entry specifies a command group for an internal gateway command.

Mandatory: Yes (one of commandGroup or internalGroup must be specified in group).

authentication > roles > role > permissions > permission > command > access Copied

Specifies the permission value for this command. Possible values are none, view or execute. The meaning of these values is described in section 7.7.2.3 below.

Mandatory: Yes

Data permissions configuration Copied

authentication > roles > role > permissions > permission > data Copied

Specifies configuration for Gateway data permission. This section is mutually exclusive with the command, sections or setup section (i.e. a permission entry type can only be one of command, data, sections or setup only).

For more information about the data permissions, see Data permissions.

Mandatory: Yes (one of command, data, sections or setup type must be specified).

authentication > roles > role > permissions > permission > data > access Copied

Specifies the permission value for accessing the Gateway data via login to Gateway. Possible values are none``,view`. The meaning of these values are described here: Data permissions.

Setup permissions configuration Copied

authentication > roles > role > permissions > permission > setup Copied

Specifies configuration for a setup permission. This section is mutually exclusive with the command, sections or data section above (i.e. a permission entry type can be one of command, data, sections or setup only).

Mandatory: Yes (one of command, data, sections or setup type must be specified).

authentication > roles > role > permissions > permission > setup > files Copied

The files section contains a list of files that this permission entry applies to.

Mandatory: Yes (at least one file is required)

authentication > roles > role > permissions > permission > setup > files > mainFile Copied

Boolean value specifying whether or not this permission should apply to the main setup file (gateway.setup.xml by default). This must be used if the exact name of the file is unknown or if the Gateway is centrally configured.

Mandatory: No

Default: false

authentication > roles > role > permissions > permission > setup > files > file Copied

The name of a setup file (either a main setup file or an included file) the permission applies to. Files can be specified with wildcard characters (* and ?) as required.

Mandatory: No

Default: gateway.setup.xml

authentication > roles > role > permissions > permission > setup > access Copied

Specifies the permission value for editing the file. Possible values are none, view, apply or forceApply. See Specifying setup permission values.

Mandatory: Yes

authentication > roles > role > permissions > permission > setup > locking Copied

Specifies the permission value for locking the file. Possible values are none, lock or forceLock. Specifying setup permission values

Mandatory: Yes

Section permissions configuration Copied

authentication > roles > role > permissions > permission > sections Copied

Specifies configuration for Gateway sections permission. This permission setting is mutually exclusive with the command, data, or setup section (i.e. a permission entry type can only be one of command, data, sections or setup only).

For more information about the data permissions, see Sections permissions.

Mandatory: Yes (one of command, data, sections or setup type must be specified).

authentication > roles > role > permissions > permission > sections > allow Copied

A dropdown to choose between “Selected”, “All excepted selected” to determine whether the sections chosen below are permitted/unpermitted.

Mandatory: Yes

Default: Selected

authentication > roles > role > permissions > permission > sections > sections Copied

A list of all sections which are to be permitted/non-permitted as per the allow dropdown.

Mandatory: No

Default: None

authentication > roles > role > permissions > permission > sections > sections > section Copied

A wrapper for the section names which are to be permitted/non-permitted as per the allow dropdown.

Mandatory: No

Default: None

authentication > roles > role > permissions > permission > sections > sections > section > path Copied

The section name which is to be included in the permitted/non-permitted sections list as per the allow dropdown.

Mandatory: No

Default: None

Command permissions Copied

Command permissions apply to gateway commands. This includes both internal and user-defined commands, but permissions checks are only performed when a user attempts to execute a command. Scheduled commands or commands executed by an action are unaffected, since they are run internally by gateway and not by a particular user.

Specifying command targets Copied

This allows the permissions to be restricted to a set of data-items defined by the system administrator. This enables different permissions to be configured for the same command, depending upon the item the user clicks on.

For example to restrict this permission to all the managedEntities with attribute City = London, the following target can be specified:

/geneos/gateway/directory/probe/managedEntity[(attr("City")="London")

Specifying command names Copied

The commands that a permission entry applies to are specified by a list of name-references, naming the commands that the entry affects. As all commands are uniquely named, it is possible to unambiguously identify every command in gateway using this method.

To allow users to easily specify multiple commands, a permission entry can contain a command name reference that contains wildcard characters (* and ?). Using these it is possible to specify a command name reference that matches many commands.

For example, we shall look at the snooze functionality supported by the gateway. These are specified as commands which can be performed by permissioned users. There are several snooze commands, each of which begins with the prefix /SNOOZE:. One such command is named /SNOOZE:manual.

To permission all commands, specify a wildcard name that matches everything:

*

To permission all snooze commands, specify a wildcard name that matches the names of all snooze commands:

/SNOOZE*

To permission a specific snooze command, specify the name exactly:

/SNOOZE:manual

The full list of commands that are available in the Gateway is available here.

Specifying command permission values Copied

There are three permission values for command permissions. These are as follows:

none

The user has no permissions for this command. It does not appear in the list of commands (for the specified target data-items) and it cannot be executed.

view

The user has view permissions for this command. It appears in the list of commands but it cannot be executed.

execute

The user has both view and execute permissions for this command. It appears in the list of commands, and can also be executed.

The greyed-out menu options denote commands for which the user only has view permissions. The user can execute all other commands in the menu. This menu typically contains commands that are not displayed because the user does not have view permissions for these commands.

Further Examples Copied

A user with permissions configured to replicate Administrator permissions (i.e. can perform any setup action and run any command).

A command permission entry configured to give execute permissions for user-commands configured in groups "Group2" and "Group3". Groups are applied to all commands contained within them, so this permissions entry applies to commands cmd2a, cmd2b and cmd4.

Data permissions Copied

Data permissions allow a Gateway to be configured to allow or deny login to the Gateway to users or roles. Permission checks are performed during connection to Gateway as a particular user.

If data permissions are enabled, by setting Authentication -> Advanced -> enableDataPermissions to true, users will only be able to connect a Gateway and view its Dataviews if they are granted data view permission. This permission can be configured for a user or for a role.

For information on combining data permissions, see Combining permissions.

Specifying data permission Copied

values

There is only one type of data permission, access permission:

none

The user or role has no permission to login to Gateway and view its data.

view

The user or role has permission to login to Gateway and view its data.

Setup permissions Copied

Setup permissions apply to operations on the gateway setup files, including both the main setup file and included setup files. Permissions checks are only performed when users request the files through gateway, typically by using the ActiveConsole 2 Setup Editor.

Gateway cannot prevent users from editing the setup files directly by specifying permissions - for this the appropriate file-system permissions should be set to prevent access to unauthorised users.

Specifying setup files Copied

Setup files can be permissioned by adding their paths to the list of files in a setup permissions entry. File paths for included files will be the paths as specified in the main setup file. The path to the main setup file will be as specified using the -setup command-line option, or the default of gateway.setup.xml.

File name matching is performed using wildcard comparison, and so files specified using wildcard characters ( and ?) can therefore refer to multiple files. The main setup file (the file that gateway loads initially before any include files) can either be referenced by filename, or using the special mainFile setting. This setting is included for situations where the name of the main file may change - for instance when defining permissions within a “users.xml” included setup file shared between multiple gateways.

When specifying include file permissions, the filename can be specified either as a relative or an absolute path. However the method used here must be the same as the method used in the “File merging” section to specify the path of the include file in question. I.e. if an include files is specified as a relative path in the “includes” section, then permissions for that file must be specified as a relative path as well.

Specifies only the main file:

Specifies all setup files:

Specifying setup permission values Copied

Setup permissions are split into two types - access permissions and locking permissions. Access permissions control access to the setup files, and have the following meanings:

none

The user has no permissions for this file. They cannot request the contents of this file.

view

The user has view permissions for this file. They can request the contents of the file but not apply any changes they make to gateway.

apply

The user has view and apply permissions for this file. They can request the contents of the file, change it as desired and then apply this setup to gateway, subject to checksum validation (which prevents users applying a setup file when they do not have the latest version as they would overwrite another user’s changes).

forceApply

The user has view, apply and force apply permissions for this file. They can view and apply the file as above, and additionally have the option of force applying a file. This latter option applies the new changed setup to the gateway, ignoring the checksum validation stage.

Locking permissions control access to the setup file locking functionality. This allows users to lock a setup file and prevent changes to this file by other users while they are editing it. As stated previously, this control only applies to files accessed via gateway - users can still edit the files directly if they have file-system access to these files. Locking permission values have the following meanings:

none

The user has no lock permissions. They will be unable to lock any setup files, although they can still access lock information to see who has locked a setup file.

lock

The user has lock permissions. They can lock a setup file which is not already locked, and unlock files that they have locked themselves. They can also view lock information.

forceLock

The user has lock and force lock permissions. In addition to the above, users can also lock and unlock files that other users currently have locked.

Sections permissions Copied

Sections permissions specify the sections that a user (or role) is allowed to edit in all setup files. They are enabled using “Enable section permissions” setting in the “Authentication” section. Any section that the user cannot edit is displayed in the Gateway Setup Editor in a read-only mode.

Section permissions can be specified in two ways:

1. Allow selected. The user will be able to edit all selected sections.
2. Allow all except selected. The user will be able to edit all sections that were not selected.

When the user belongs to multiple roles all allowed sections from those roles will be allowed.

Inherited permissions Copied

When specifying permissions on hierarchical structures, permissions on parent nodes will be inherited by their children unless explicitly overridden. For example, consider the following configuration:

Permission A is configured on a parent node (Directory) which is then overridden by permission B on one of the child nodes (Sampler1). This is shown as the hierarchy below left.

The hierarchy above right shows the inherited permissions in blue. These are inherited from their parent nodes, except for Sampler1 which overrides the permissions. The children of Sampler1 then inherit these new permissions as before.

The cumulative effect is that a user with the permissions described above will be able to run the command /SNOOZE:manual on every component in the hierarchy except Sampler1, View1 and View2.

Combining permissions Copied

As users can belong to multiple groups, it is possible that different groups may define different permissions for the same item. If this happens, the permissions are merged to give either the highest or lowest available permissions.

Thus the highest level of permissions for a user is the union of all permissions specified for that user and in groups they are a member of. The lowest level of permissions is taken from those permissions which have been specified (rather than the default “none”) and so corresponds to the intersection of available permissions.

The method used to combine permissions is a gateway-wide setting, specified using the combineMode setting inside the authentication section. Thissetting can have the values highest or lowest. Some examples are shown below.

Below table shows the permission combination examples for data type permissions. Here, “not configured” means data type permission is not configured for user/group, “none” means data access none permission, “view” means data access view permission, “Allow” means allowed Gateway login, “Deny” means denied Gateway login. It is worth noting that the data permissions are ignored when enableDataPermissions is not set or set to false and the user is always allowed to login to Gateway and view Gateway data. When enableDataPermissions is set to true, the data permission type & combinemode setting determines whether or not access to Gateway data should be allowed/denied. Where neither enableDataPermission nor data permissions is configured, the user will be allowed to login to Gateway).

Note

If a User is not granted or denied data permissions (either by permissions defined for the user or permissions + defined for the user’s group) then the user will be given access to the data *UNLESS* the user is + an Single Sign On user. A Single Sign On user will only be given data access if they have been explicitly granted + view data permission.

Inheritance and combining Copied

When a user belongs to several groups and the permissions are set on using inheritance, the actual permissions are resolved in the manner below:

1. The permissions for the item are resolved separately for the user, and each group the user belongs to.
2. These resulting permissions are then taken and combined.
3. The results of the combination are the effective permissions used.

The below diagram shows two groups and a user definition each of which have configured permissions using inheritance. Managed entity “Fidessa” refers to all Fidessa managed entities, “Tradewatch” to all Tradewatch managed entities and “*” to all managed entities. User “Charles” is a member of groups “Fidessa” and “Tradewatch”.

For a target managed entity I which is both a Fidessa and Tradewatch managed entity, the following process is used to resolve permissions:

1. Permissions for I are checked in group Fidessa. Inheritance resolves permissions as B since permissions for Fidessa managed entities have been overridden to B in the configuration.
2. Permissions for I are checked in group Tradewatch. Inheritance resolves permissions as C since permissions are inherited from Directory which was specified as C in the configuration.
3. Permissions for I are checked in user definition for Charles. Inheritance resolves permissions as D since permissions are inherited from Directory which was specified as D in the configuration.
4. Permissions B, C and D are then combined to form the final result.

User assignment Copied

The User Assignment feature of the Gateway allows the assignment of Geneos Users to Data-items (for instance, when a data-item severity goes critical, a user can be assigned to “fix” it). User assignment is managed through the following commands:

• User Assignment/Assign: Command to assign an item to a user. The command will have a drop down list of the Geneos Users configured on that gateway that the item can be assigned to, on gateways with generic users configured the list will be editable and any username can be chosen. The command also features a text box for an optional comment.
• User Assignment/Assign To Me: Assigns the selected data-item to the currently logged in user.
• User Assignment/Unassign: Clears the assignment of the selected item.
• User Assignment/Info: Returns information on the currently assigned user, including the comment, the user who assigned the item, and the time of the assignment.

The last two commands may not be available for unassigned data-items.

Permission to execute User Assignment commands can be granted in the same way as permission for any command.

authentication > userAssignment Copied

The user assignment section holds settings to control user assignment.

authentication > userAssignment > assign > action Copied

The action to fire on a user assignment. Actions are passed the path of the assigned item, the name and e-mail address of the assigned user, the name of the user who did the assigning, and the assignment comment.

See User assignment script actions for additional environment variables available to this action.

authentication > userAssignment > unassign > action Copied

The action to fire on a user un-assignment. Actions are passed the path of the previously assigned item, the name and e-mail address of the previously assigned user, the name of the user who did the un-assigning, and the un-assignment comment.

authentication > userAssignment > displayOrder Copied

Changes the display order of users in the Assign… commands such as Assign To User. The options are:

See User assignment script actions for additional environment variables available to this action.

Note

If a fullName is not provided by the user the user is sorted by user name. Further note that this is case sensitive.

Mandatory: No

Default: lastName

authentication > userAssignment > roleProperties > roleProperty Copied

Configurable list of role properties from authentication > roles > role > roleProperties. This is used to restrict the assignable users shown by the User Assignment commands.

If the list here is empty, the list of assignable users shown by User Assignment commands is populated with all configured Gateway users.

If the list here is populated with at least one item, the list of assignable users shown by User Assignment commands is restricted to those users that have one or more of the configured role properties.

If Single Sign On is configured, all SSO users that belong to one or more of the configured role properties (AD groups or equivalent) also appear in the list of assignable users.

Both the URL and public key must be configured. See authentication > singleSignOn.

authentication > userAssignment > maxAssignableSize Copied

Maximum number of users that can appear in the list of assignable users.

If the number of users exceeds the configured limit, no user list is displayed and the assigned user needs to be manually entered via a text box.