Geneos Gateway Authentication Technical Reference. Functional Area: Geneos Gateway Authentication. Geneos Release: v4.9. Document Version: v1.0.

Transcription

1 Geneos Gateway Authentication Technical Reference Functional Area: Geneos Gateway Authentication Geneos Release: v4.9 Document Version: v1.0.0 Date Published: 25 October 2018

2 Copyright ITRS Group Ltd. All rights reserved. Information in this document is subject to change without notice. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of those agreements. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or any means electronic or mechanical, including photocopying and recording for any purpose other than the purchaser's personal use without the written permission of ITRS Group Ltd. ITRS Group Ltd 6th Floor, The Bonhill Building, 15 Bonhill Street, London, EC2A 4DN, UK t: +44 (0)

3 Table of Contents Gateway Authentication - Technical Reference 7 Introduction 7 Login Types 8 General 9 Authentication 9 Authentication > AuthenticateUsers 9 Authentication > CombineMode 10 Authentication > EnableSectionPermissions 10 Authentication > EnableDataPermissions 10 Authentication > Sso 10 Authentication > Sso > SsoAgent 10 Authentication > Sso > Jwt > PublicKey 10 Authentication > AllowPaoLogin 11 Authentication > CaseInsensitiveUsernames 11 Authentication > Users 11 Authentication > Groups 11 Users 12 Authentication > Users > User 12 Authentication > Users > User > FullName 12 Authentication > Users > User > Password 12 Authentication > Users > User > Password > EncodedPassword 12 Authentication > Users > User > Password > Plaintext 13 Authentication > Users > User > GenericUser 13 Authentication > Users > User > AllowLogin 13 Authentication > Users > User > AllowPasswordAuth 13 Authentication > Users > User > AllowSystemAuth 13 Authentication > Users > User > AllowSslAuth 13 Authentication > Users > User > SslIdentities 13 Authentication > Users > User > SslIdentities > Id 13 Authentication > Users > User > SslIdentities > Id > Fingerprint 14 Authentication > Users > User > SslIdentities > Id > Subject 14 Authentication > Users > User > Permissions 14 Authentication > Users > User > 14 Authentication > Users > User > RoleProperties 14

4 Authentication > Users > User > RoleProperties > RoleProperty 14 Authentication > Users > User > Information 14 Authentication > Users > User > Information > Info > Type 15 Authentication > Users > User > Information > Info > Value 15 User Groups 16 Authentication > User > UserGroup 16 Authentication > User > UserGroup > Name 16 Authentication > User > UserGroup > RoleProperties 16 Authentication > User > UserGroup > RoleProperties > RoleProperty 16 Generic Users 18 Roles 19 Assigning Roles To Users 19 Role Configuration 19 Authentication > Roles > Role 19 Authentication > Roles > Role > Description 19 Authentication > Roles > Role > Permissions 19 Authentication > Roles > Role > RoleProperties 20 Authentication > Roles > Role > RoleProperties > RoleProperty 20 Authentication > Roles > Role > Users 20 Authentication > Roles > Role > Users > User 20 Authentication > Roles > Role > Information 20 Authentication > Roles > Role > Information > Info > Type 20 Authentication > Roles > Role > Information > Info > Value 20 Group Configuration 20 Authentication > Groups > Group 20 Authentication > Groups > Group > Description 21 Authentication > Groups > Group > Users 21 Authentication > Groups > Group > Users > User 21 Authentication > Groups > Group > Permissions 21 Authentication > Groups > Group > Information 21 Authentication > Groups > Group > Information > Info > Type 21 Authentication > Groups > Group > Information > Info > Value 21

5 Permissions 22 Configuration 22 Authentication > Roles > Role > Permissions > Permission 22 Command Permissions Configuration 22 Authentication > Roles > Role > Permissions > Permission > Command 22 Authentication > Roles > Role > Permissions > Permission > Command > Targets 22 Authentication > Roles > Role > Permissions > Permission > Command > Targets > Target 22 Authentication > Roles > Role > Permissions > Permission > Command > Names 23 Authentication > Roles > Role > Permissions > Permission > Command > Names > Name 23 Authentication > Roles > Role > Permissions > Permission > Command > Groups 23 Authentication > Roles > Role > Permissions > Permission > Command > Groups > Group 23 Authentication > Roles > Role > Permissions > Permission > Command > Groups > Group > CommandGroup23 Authentication > Roles > Role > Permissions > Permission > Command > Groups > Group > InternalGroup 23 Authentication > Roles > Role > Permissions > Permission > Command > Access 23 Data Permissions Configuration 23 Authentication > Roles > Role > Permissions > Permission > Data 24 Authentication > Roles > Role > Permissions > Permission > Data > Access 24 Setup Permissions Configuration 24 Authentication > Roles > Role > Permissions > Permission > Setup 24 Authentication > Roles > Role > Permissions > Permission > Setup > Files 24 Authentication > Roles > Role > Permissions > Permission > Setup > Files > MainFile 24 Authentication > Roles > Role > Permissions > Permission > Setup > Files > File 24 Authentication > Roles > Role > Permissions > Permission > Setup > Access 24 Authentication > Roles > Role > Permissions > Permission > Setup > Locking 24 Section Permissions Configuration 24 Authentication > Roles > Role > Permissions > Permission > Sections 25 Authentication > Roles > Role > Permissions > Permission > Sections > Allow 25 Authentication > Roles > Role > Permissions > Permission > Sections > Sections 25 Authentication > Roles > Role > Permissions > Permission > Sections > Sections > Section 25 Authentication > Roles > Role > Permissions > Permission > Sections > Sections > Section > Path 25 Command Permissions 25

6 Specifying Command Targets 25 Specifying Command Names 26 Specifying Command Permission Values 26 Further Examples 27 Data Permissions 29 Specifying Data Permission Values 29 Setup Permissions 29 Specifying Setup Files 29 Specifying Setup Permission Values 31 Sections Permissions 32 Inherited Permissions 33 Combining Permissions 33 Inheritance And Combining 35 UserAssignment 37 Authentication > UserAssignment 37 Authentication > UserAssignment > Assign > Action 37 Authentication > UserAssignment > Unassign > Action 37 Authentication > UserAssignment > DisplayOrder 37

7 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, which is configured in the authentication section of the Gateway setup file. Because this section of the Gateway setup controls 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 will report a critical issue. This will prevent 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 yet not know which user you will connect as. It will warn you to check that you will still have setup edit permission, but it will not prevent you from applying the setup. When you first enable user authentication, the Gateway does not yet know which user you will connect as. It will warn you to check that you will still have setup edit permission, but it will not prevent you from applying the setup. This warning will also appear 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. 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. Page 7 of 38

8 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 ITRS SSO Agent. The ITRS SSO Agent is provided as a separate binary to the Gateway and can be downloaded from the ITRS Resources Downloads page. Page 8 of 38

9 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 an authentication section. The section requires as a minimum the authenticateusers and combinemode settings to be specified. See 1 and 2 in the figure below. These are required so that they are available during setup file merging (see section 4.4 above). The available settings in this section are as follows: 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. Default: No authentication authentication > authenticateusers Required Boolean setting controlling whether users are required to login on connection to the gateway. Page 9 of 38

10 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. authentication > enablesectionpermissions Optional Boolean setting which controls whether section permissions should be used. This is a gateway-wide setting. If not set or set to false, the section permissions will be ignored. For more information about the section permissions, see Section permissions. Default: false authentication > enabledatapermissions Optional Boolean setting which controls whether data permissions should be used. This is a gatewaywide setting. If not set or set to false, the data permissions will be ignored. For more information about the data permissions, see Data permissions. Default: false authentication > sso Enable this section to allow users to log in to on to this gateway which are managed by a single sign on service. authentication > sso > ssoagent The URL location of the sso agent. This url is used by the REST service /rest/authorize. If this url is not provided then it is not possible to run REST commands as an SSO user. authentication > sso > 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/ Page 10 of 38

11 hwgieku1+u7bgtlpzd/3ufqnzsoimfme9r53b+wjron04b6obb0jqmwftyaoxwh1 ozbk5xz1e165hanxaykec4rchdu8m0urk8jkkrby9m8uxxcatbvrtygosoi9jh+t 1wIDAQAB -----END PUBLIC KEY----- Changing this value will result in all SSO user connections being dropped. authentication > allowpaologin This setting has been deprecated as PAO is no longer supported. authentication > caseinsensitiveusernames Optional Boolean setting which controls whether 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. With this 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. Default: false authentication > users The (optional) users section contains any number of uniquely named user definitions. Default: No users defined authentication > groups The (optional) groups section contains any number of uniquely named user-group definitions. Default: No groups defined Page 11 of 38

12 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 > 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. Default: No description authentication > users > user > password The password configuration allows users to specify the password with which they login. 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. Page 12 of 38

13 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. 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. Default: true authentication > users > user > allowpasswordauth Specifies whether the user can logon using their password. Default: true if password is specified, false otherwise authentication > users > user > allowsystemauth Specifies whether the user can log on using system authentication. Default: false authentication > users > user > allowsslauth Specifies whether the user can log on using an SSL Certificate. Default: false 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). Page 13 of 38

14 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. Default: No permissions authentication > users > user > Deprecated: Use authentication > users > user > information instead, which allows the inclusion of generic information. Use the value type " " 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 address which can be used by the gateway to send automated messages if configured to do so. Page 14 of 38

15 authentication > users > user > information > info > type Specifies the type of information e.g. . authentication > users > user > information > info > value Specifies the value of information. An example configuration is shown below: Page 15 of 38

16 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. An example configuration is shown below: Page 16 of 38

17 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. Page 17 of 38

18 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. An example generic user definition is shown below. This definition allows system-login for generic users, and so users will connect using their system login name (e.g. their Windows user account). Page 18 of 38

19 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. 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. Page 19 of 38

20 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. 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. See roleproperties. 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 address which can be used by the gateway to send automated messages if configured to do so. authentication > roles > role > information > info > type Specifies the type of information e.g. . authentication > roles > role > information > info > value Specifies an information value. E.g. If the information type is , then the value could be an address. 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. Page 20 of 38

21 authentication > groups > group > description Deprecated: Use authentication > roles > role > description instead. Default: No description authentication > groups > group > users Deprecated: Use authentication > roles > role > users instead. Default: No description authentication > groups > group > users > user Deprecated: Use authentication > roles > role > users > user instead. authentication > groups > group > permissions Deprecated: Use authentication > roles > role > permissions instead. Default: No description 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. Page 21 of 38

22 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). (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. 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. Page 22 of 38

23 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. Details of command naming are described in section A value of * will match all commands on gateway. (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 *. 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. (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. (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 below. Data permissions configuration Page 23 of 38

24 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. (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). (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. (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 can be used if the exact name of the file is not known. 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. 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. The meaning of these values are described in section below. authentication > roles > role > permissions > permission > setup > locking Specifies the permission value for locking the file. Possible values are none, lock or forcelock. The meaning of these values are described in section below. Section permissions configuration Page 24 of 38

25 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. (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. 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. 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. 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. 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: Page 25 of 38

26 /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 Page 26 of 38

27 The user has both view and execute permissions for this command. It appears in the list of commands, and can also be executed. An example of these in ActiveConsole 2 is shown below. 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 2 other commands, "Untilseveritychanges" and "Untilseveritychangesto " which 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 FIDESSA role configured to give view permissions on all commands, and execute permissions for all commands on managed entities with type "FIDESSA". Page 27 of 38

28 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. Page 28 of 38

29 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. Page 29 of 38

30 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 the main file and an include file by name: Page 30 of 38

31 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 Page 31 of 38

32 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. Page 32 of 38

33 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. Page 33 of 38

34 Permission Values Combine Mode Highest Lowest (no matching permission entry) none none none, execute execute none view, execute execute view View view view Table 1 Permission combining example, with values from command-type permissions 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 Allow Allow configured False not configured, none Allow Allow False not configured, view Allow Allow False none, view Allow Allow True not configured, not Special Special configured True not configured, none Deny Deny True not configured, view Allow Allow True none, view Allow Deny Table 2 Permission combining example, with values from data-type permissions 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. Page 34 of 38

35 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". Page 35 of 38

36 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. Page 36 of 38

37 UserAssignment 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: UserAssignment/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. UserAssignment/Assign To Me: Assigns the selected data-item to the currently logged in user. UserAssignment/Unassign: Clears the assignment of the selected item. UserAssignment/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. There are three items of configuration: 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 address of the assigned user, the name of the user who did the assigning, and the assignment comment. See section 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 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 "assigntouser". The options are: Page 37 of 38