Skip to main content

Security

Introduction

The security of ProactivePack uses a system of users and groups to determine what permission users have in the product. 

Users are first authenticated using one of the following mecanisms :

  • HTTP server authentication (Active Directory, htaccess,…) – this is still supported but is deprecated
  • Local authentication – simple solution where users are stored in ProactivePack
  • TSPS – using the BMC TrueSight presentation server authentication
  • SAML
  • Custom

 After users are authenticated they are assigned to one group by ProactivePack. This assignment can be done using local associations, or by integrating with a directory service or a custom mapping mechanism based on a script or a PHP function.

Groups provide permissions on modules, actions within modules, and specific options within actions.

Specific, individual user permissions can be set to override group-level permissions everywhere. This is an advanced configuration that can only be performed from a text editor.

The overall process is defined on this figure:


 

i Modifications to the file Default.ootb are not supported.

 

Authentication

ProactivePack relies on the web server for user authentication. In the simplest configurations, user authentication can be achieved using the “htaccess” feature of apache or the “basic authentication” feature of IIS. Other authentication mechanisms can of course be implemented, depending on what your web server supports and what your requirements are.

Local authentication

This is the default mechanism (note : since version 24.01) – users and passwords are stored locally in the ProactivePack software.

TrueSight authentication

If you use BMC TrueSight (10.x or 11.x), you can use TrueSight to authenticate users in ProactivePack.

To enable BMC TrueSight authentication :

1.       The parameter ExternalAuth, ExternalAuthType and ExternalLoginURL must be set in the Global Configuration. See that section for details.

2.       All other authentication mechanisms (htaccess, AD, etc) on the http server must be disabled.

 

SAML authentication

To enable SAML authentication :

1.       The parameter ExternalAuth, ExternalAuthType and ExternalLoginURL must be set in the Global Configuration. See that section for details.

2.       The SAML metadata must be imported in ProactivePack. To do so, navigate to Administration -> ProactivePack -> Global -> Then click on the 3-dots menu and select “Load a SAML XML file” :


3.       All other authentication mechanisms (htaccess, AD, etc) on the http server must be disabled.

i The SAML authentication only provides for user authentication. Once authentication is done, group association is done in ProactivePack, see section below.

i For the generation of report emails and Self-ServiceMonitoring import tasks, an application user with the ability to log into TSPS must still be provided.

 

User Overwrite (Custom authentication)

It is possible to overwrite the user passed by the authentication using the “UserOverwrite” parameter of the global configuration.

The format of the UserOverwrite must be as follows :

o   UserOverwrite =custom:<php file name>:<php function name>

 

The php file must be placed under $PRODUCT_HOME/data/Global and it must contain the function <php function name>

The PHP function itself takes no argument, and must return a valid user name.

For example :

UserOverwrite =custom:GetUser.php:GetUser

 

GetUser.php :

function GetUser()
{
  $headers = apache_request_headers();
  if (isset($headers["uid"]) and ! empty($headers["uid"]))
  {
       $User = $headers["uid"];
  }
  else
  {
        $User = "guest";
  }
  return $User;
}

User Groups

You can create and use as many user groups as you need.

To create a new group, navigate to “ProactivePack Administration” => “Groups” then click on the plus sign beside the existing groups and provide a name to the new group.


 

By default, the “Admins” (i.e. full access), “Guest” (i.e. restricted, read-only access) and AccessDenied (i.e. no access) groups are referenced. 

Group association

Once authenticated, the user is associated to one (and only one) user group. There are several options to retrieve the group to which the authenticated user belongs, which are described below.

The option used is set by the parameter UserToGroupFile in $PRODUCT_HOME/config/Global.conf (or $PRODUCT_HOME/config/custom/Global.conf)

Regardless of the method, If no group is found for the user, the user is placed in the DefaultGroupName (defined in Global parameters, “Guest” by default) group and will therefore have the permissions set for that group. 

Default mechanism – file based

By default, user-group associations are stored in the file $PRODUCT_HOME/security/UserGroup.conf, under the format (one association per line):

user:group

 

To use this default mechanism, the value of the UserToGroupFile in Global.conf must be (default):

                UserToGroupFile=file:security/UserGroup.conf

Using TrueSight group mapping

In case TrueSight authentication is used, it is possible to use the TrueSight user groups and map them to ProactivePack groups.

In this mode, the value of UserToGroupFile in Global.conf is:

                UserToGroupFile= function:MapFromTSPS

This works as follows :

-          ProactivePack retrieves all the TrueSight user groups of the authenticated user

-          ProactivePack sequentially reads the mapping file found under $PRODUCT_HOME/security/TrueSight/GroupMapping.conf. This file is of the format :

<TrueSight User Group>=<ProactivePack Group>

-          The first matching group found in the file is used as the user group.

 

i The mapping file can be edited from the ProactivePack console. Navigate to Administration -> Modules -> Global -> Edit TrueSight Group Mapping

 

Using a command output

As an alternative to using the file-based mechanisms above, you may prefer to use the output of a command to determine to which group the user belongs. This can be used e.g. to query a directory service, etc. and associate the user to an externally defined group.

In this mode:

-          The user name is passed as argument to the script.

-          The script must return one or more lines of the format user:group to the standard output.

-          ProactivePack will then use the first encountered occurrence (case insensitively) of the user will be used to determine to which group she belongs.

In this mode, the value of UserToGroupFile in Global.conf is:

                UserToGroupFile=cmd:<relative path to script>

File must be executable by the http server user. Paths are relative to $PRODUCT_HOME.

For example (here on Windows):

Using ActiveDirectory

Introduction

The script GetADUserGroups.pl is provided to associate users to groups based on an active directory (AD) query .

By default, the AD groups must be created with the same name in ProactivePack, but a mapping mechanism is provided to translate AD group names into ProactivePack groupnames.

 

The script:

-          Takes as argument the name of the authenticated user.

-          Queries one or more directory servers to retrieve the groups of that user.

-          Verifies if the user belongs to a directory group that exists as a local ProactivePack group.

o   If yes, the script returns that group,

o   else the default guest group is returned. Mapping directives can be used to translate the AD group name into a ProactivePack group name

 

Configuration

The configuration file PPACKLDAPSearchGroup.conf located under $PRODUCT_HOME/Tools/etc must be edited.

 

Parameter

Description

Default/typical value

[Global] Section

AuthenticationSearchOrder

 

This is useful in case you want to combine locally defined user/group associations with directory defined user/group associations. Determines in what order the user/group association is done : if set to “Ldap,file”, the groups retrieved from the directory will prevail over  the groups retrieved from the UserGroup.conf file.

Ldap,file

DefaultLDAPGroups

Defaulf value returned if no ProactivePack usergroup was find running LDAP queries

Guests

LDAPMemberOfAttribute

Name of the directory attribute that identifies the ‘memberOf’ attribute. Can be overwrite on each LDAP definition.

memberOf

LDAPUserAttribute

Name of the directory attribute that identifies the user. Can be overwrite on each LDAP definition.

sAMAcoountName

PPACKDocumentRoot

Location of the ProactivePack installation directory ($PRODUCT_HOME)

/data/WWRoot/ProactivePack

StopOnFirstMatchingLDAP

Authentication will stop on first LDAP server where user is found or parse all LDAP servers

1

UserGroupPriority

In case a user belongs to multiple AD groups, this parameter can be used to determine which one should be preferred. Must contain a comma separated list of groups.

Admins,N3Team,N2Team

[LDAP specific] Section

LDAPBaseDN

Base DN in the directory

DN=DCexample,DC=com

LDAPBindHost

Hostname of the  directory server

 

LDAPBindUserName

Name of a user with browsing permissions on the directory

 

LDAPBindUserPassword

Password of that user. See details below to encrypt.

 

LDAPMemberOfAttribute

Name of the directory attribute that identifies the ‘memberOf’ attribute.

memberOf

LDAPSearchFilter

Filter string used in the query

(objectClass=group)

LDAPUserAttribute

Name of the directory attribute that identifies the user.

sAMAcoountName

[GroupMapping] Section

<name of the AD group  as retrieved by the LDAP query>

The [GroupMapping] section can be used to map the AD group name (this is case sensitive) into ProactivePack group names (also case sensitive). If no mapping entry is found for the AD group, the assumption is that there is a ProactivePack group with the same name.

<name of the corresponding ProactivePack group>

 

Password management

By default, the AD user password is stored in cleartext in the configuration file. To use an encrypted (3DES) password, use the utility EncryptPassword.pl under $PRODUCT_HOME/Tools/bin.

Example:


 

Copy and paste the encrypted password in to the file PPACKLDAPSearchGroup.conf as a value of the LDAPBindUserPassword parameter.

Using an encrypted password requires the perl Crypt::CBC module.

 

Enabling

To enable the script:

-          Set the value of the UserToGroupFile parameter of in the global configuration :

o   Windows :

§  UserToGroupFile=cmd:./Tools/bin/GetADUserGroups.cmd

o   Linux

§  UserToGroupFile=cmd:./Tools/bin/GetADUserGroups.pl

 

Using a custom PHP function

In some specific situations, for example if ProactivePack is installed behind an entry server, the user group may be available e.g. within a server variable.

In such situations it is possible to use a custom PHP function to retrieve the user group;

The format of the UserToGroupFile is in that case as follows :

o   UserToGroupFile=custom:<php file name>:<php function name>

 

The php file must be placed under $PRODUCT_HOME/data/Global and it must contain the function <php function name>

The PHP function itself takes the user name as unique argument, and must return a user group name.

Permissions

After a user is assigned to a group, permissions are computed based on the settings set within the group.          

For a given user, 4 files can be read, if they exist, in that order, each file content overriding preceding ones.

1.       Default.ootb : out of box permissions – do NOT edit.

2.       Default.conf (“Default” group) : default permissions, may be edited. Overrides out-of-box permissions

3.       <Group Name>.conf: group level permissions. They override default permissions.

4.       users/<User Name>.conf: user level permissions.

 

For example, for the Calendar module, we may have under $PRODUCT_HOME/security :

Default.ootb:

[Calendar]
Configure="0"
Add="0"
View="1"
Delete="0"

 

Default.conf:

[Calendar]
Configure="0"
Add="0"
View="0"
Delete="0"
Admins.conf:

[Calendar]
Configure="1"
Add="1"
View="1"
Delete="1"

 

users/Mike.conf:

[Calendar]
View="1"

Which translates as:

-          Out-of-box (default.ootb) all users can view the calendars.

-          This is overridden in the default group – no permissions are provided.

-          However members of the Admins group do have access to those options.

-          User Mike (whichever group he belongs to) also has read (view) access.

 

Check the documentation for each module for details.

 

Back to top