Geneos ["Geneos"]
You are currently viewing an older version of the documentation. You can find the latest documentation here.
["Geneos > Gateway"]["Technical Reference"]

Gateway Authentication Technical Reference

Introduction

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

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

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

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

authentication > authenticateUsers

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

Mandatory: Yes

authentication > combineMode

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

authentication > enableSectionPermissions

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

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

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

authentication > singleSignOn

Enable this section to allow SSO authentication for this Gateway.

authentication > singleSignOn > ssoAgent

The URL location of the SSO Agent. This URL is used:

Note: Your Gateway must be set up to use Kerberos authentication to connect to the SSO Agent to obtain the list of SSO users. Kerberos authentication requires -kerberos-principal and -kerberos-keytab to be set using the command line. See Command line options in Gateway Installation Guide and Authenticating with Kerberos in Gateway Setup Files.

authentication > singleSignOn > jwt > publicKey

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 -----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA9KTR6IFL44UTGCs5Hi2x
fISO7eMBaqf75BQym/E8woQE2NOocyAvshGLAaE9oHP4vqRnc+hHyDs7DDF2u0VF
T4yao3SAdHGEwlthTKf0V+TtDGvlWPKGzVdCYowmNC0Z1RxsT/X3jhNvnkHRQYXW
cYp6r4uISe+HUka+wKjfSZZFOB5lFYzZfb7hRGvc5kMZEvg7QYBej/c37uSB9r1/
hwGiEKU1+U7Bgtlpzd/3UFQnZsOIMFME9R53b+Wjron04B6OBB0jqmWFTYaoXWh1
oZBK5XZ1e165HaNXAYkeC4RcHdu8M0urk8JkkRby9M8UXxCATbVrtYGosoI9JH+t
1wIDAQAB
-----END PUBLIC KEY-----

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

Users

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. 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

Contains any number of uniquely named user definitions.

Mandatory: No
Default: No users defined

authentication > users > user

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

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

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

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

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

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

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

Specifies whether the user can logon using their password.

Mandatory: No
Default: true if password is specified, false otherwise

authentication > users > user > allowSystemAuth

Specifies whether the user can log on using system authentication.

Mandatory: No
Default: false

authentication > users > user > allowSslAuth

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

Mandatory: No
Default: false

authentication > users > user > sslIdentities

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

Mandatory: No

authentication > users > user > sslIdentities > id

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

Mandatory: Yes

authentication > users > user > sslIdentities > id > fingerprint

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

Mandatory: Yes

authentication > users > user > sslIdentities > id > subject

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

Mandatory: Yes

authentication > users > user > permissions

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

Mandatory: No
Default: No permissions

authentication > users > user > roleProperties

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

Specifies the value of a single role property tag.

Mandatory: No

authentication > users > user > information

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

Specifies the type of information e.g. Email.

Mandatory: Yes

authentication > users > user > information > info > value

Specifies the value of information.

Mandatory: Yes

An example configuration is shown below:

User groups

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

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

Mandatory: No

authentication > user > userGroup > name

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

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

Mandatory: No

authentication > user > userGroup > roleProperties > roleProperty

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

For large installations with a number of non-privileged users, configuring and managing user definitions for these users can be time consuming. Gateway2 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

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

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

Settings for configuring a role definition are described below.

authentication > roles > role

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

A textual description of the role.

Mandatory: No
Default: No description
authentication > roles > role > permissions

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

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

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

Mandatory: No
authentication > roles > role > users

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

Mandatory: No
authentication > roles > role > users > user

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

Mandatory: Yes
authentication > roles > role > information

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

Specifies the type of information e.g. Email.

Mandatory: Yes
authentication > roles > role > information > info > value

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

Mandatory: Yes

Group configuration

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

Deprecated: Use authentication > roles > role instead.

Mandatory: Yes
authentication > groups > group > description

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

Mandatory: No
Default: No description
authentication > groups > group > users

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

Mandatory: No
Default: No description
authentication > groups > group > users > user

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

Mandatory: Yes
authentication > groups > group > permissions

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

Mandatory: No
Default: No description
authentication > groups > group > information

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

Mandatory: No
authentication > groups > group > information > info > type

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

Mandatory: Yes
authentication > groups > group > information > info > value

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

Mandatory: Yes

Permissions

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

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

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
authentication > roles > role > permissions > permission > command

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

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

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

A list of command names that this permission applies to.

Mandatory: Yes
authentication > roles > role > permissions > permission > command > names > name

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

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

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

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

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

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
authentication > roles > role > permissions > permission > data

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

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
authentication > roles > role > permissions > permission > setup

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

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

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

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

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

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

Mandatory: Yes
Section permissions configuration
authentication > roles > role > permissions > permission > sections

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

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

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

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

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

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

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

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

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

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

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 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

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

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

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

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

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

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. This setting can have the values highest or lowest. Some examples are shown below.

Permission Values Combine Mode  
  Highest Lowest
(no matching permission entry) none none
none, execute execute none
view, execute execute view
View view view

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).

EnableDataPermissions Data Permission Values Combine Mode  
    Highest Lowest
False not configured, not configured Allow Allow
False not configured, none Allow Allow
False not configured, view Allow Allow
False none, view Allow Allow
True not configured, not configured Special Special
True not configured, none Deny Deny
True not configured, view Allow Allow
True none, view Allow Deny

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

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

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

The user assignment section holds settings to control user assignment.

authentication > userAssignment > assign > action

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

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

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.

Option Setting Displayed As Result
lastName Last name

Sorts, users by the last name or more precisely last sequence of characters in the fullName setting of the user definition.

Users are then displayed as "Lastname, Rest of name".

firstName First name Sorts, users by the first name in the fullName setting of the user definition. Users are display as normal "Firstname Lastname" as entered in the fullname setting.
username User name Users are sorted by the username field of the user definition.

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

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

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.