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:
-
Get the username and password that the Gateway will use to connect to the SSO Agent.
-
Use the
-store-app-key
command line option to create an app key:./gateway2.linux_64 -store-app-key app.key gwuser <password> ssoAgent
-
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 aclient_id
andsecret
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:
- 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 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.
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 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:
- 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 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.
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 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.