If you are currently using version 5.x.x, we advise you to upgrade to the latest version before the EOL date. You can find the latest documentation here.
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.
Configuration - Basic tab
authentication > authenticateUsers
Boolean controlling if users are required to log in on connection to the Gateway.
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
.
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.
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.
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.
Configuration - Single Sign On tab
authentication > singleSignOn > ssoAgent
The URL location of the SSO Agent.
- 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.
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.
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.
authentication > users > user > fullName
A field for specifying the full name of a user, rather than the (typically shortened) username.
authentication > users > user > password
The password configuration allows users to specify the password with which they login.
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.
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.
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.
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.
authentication > users > user > allowPasswordAuth
Specifies whether the user can logon using their password.
authentication > users > user > allowSystemAuth
Specifies whether the user can log on using system authentication.
authentication > users > user > allowSslAuth
Specifies whether the user can log on using an SSL Certificate.
authentication > users > user > sslIdentities
Specifies the SSL identities that will be used to authenticate the user if SSL authentication is enabled.
authentication > users > user > sslIdentities > id
Specifies the type of the SSL identity (e.g. Subject).
authentication > users > user > sslIdentities > id > fingerprint
Specifies the value of the SSL Fingerprint in capital hexadecimal characters (e.g. 4918A6213FF22C69739F16C05B1EF59D23A47B1E).
authentication > users > user > sslIdentities > id > subject
Specifies the value of the SSL Subject (e.g. /CN=importingGateway/C=UK/L=London/O=ITRS).
authentication > users > user > permissions
Specifies the permissions applicable for this user. See the permission section for more details.
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.
authentication > users > user > roleProperties > roleProperty
Specifies the value of a single role property tag.
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.
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.
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.
authentication > user > userGroup > roleProperties
This setting specifies a set of property tags to apply to all contained user and userGroup definitions.
authentication > user > userGroup > roleProperties > roleProperty
Specifies the value of a single role property tag.
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.
authentication > roles > role > description
A textual description of the role.
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.
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.
authentication > roles > role > roleProperties > roleProperty
Specifies a single property value, as part of a set used to select users for the role.
authentication > roles > role > users
A list of referenced users which are assigned this role, and so inherit permissions from the role.
authentication > roles > role > users > user
A named reference to a user in the users section. Referenced users are assigned this role.
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.
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.
authentication > groups > group > description
Deprecated: Use authentication > roles > role > description instead.
authentication > groups > group > users
Deprecated: Use authentication > roles > role > users instead.
authentication > groups > group > users > user
Deprecated: Use authentication > roles > role > users > user instead.
authentication > groups > group > permissions
Deprecated: Use authentication > roles > role > permissions instead.
authentication > groups > group > information
Deprecated: Use authentication > roles > role > information instead.
authentication > groups > group > information > info > type
Deprecated: Use authentication > roles > role > information > info > type instead.
authentication > groups > group > information > info > value
Deprecated: Use authentication > roles > role > information > info > value instead.
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.
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).
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.
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.
authentication > roles > role > permissions > permission > command > names
A list of command names that this permission applies to.
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.
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 *.
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.
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.
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.
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.
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.
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).
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.
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
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.
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
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
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.
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.
authentication > roles > role > permissions > permission > sections > sections
A list of all sections which are to be permitted/non-permitted as per the allow dropdown.
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:
- Allow selected. The user will be able to edit all selected sections.
- 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:
- The permissions for the item are resolved separately for the user, and each group the user belongs to.
- These resulting permissions are then taken and combined.
- 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:
- Permissions for
I
are checked in group Fidessa. Inheritance resolves permissions asB
since permissions for Fidessa managed entities have been overridden toB
in the configuration. - Permissions for
I
are checked in group Tradewatch. Inheritance resolves permissions asC
since permissions are inherited from Directory which was specified asC
in the configuration. - Permissions for
I
are checked in user definition for Charles. Inheritance resolves permissions asD
since permissions are inherited from Directory which was specified asD
in the configuration. - Permissions
B
,C
andD
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.
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.