Chapter 13. Authentication and Authorization

Table of Contents

Secure Preferences
Required Plug-Ins, User Interface
Configuring Authentication, Authorization and Secure Preferences


Access to some components of CSS is restricted. Changes to the alarm system configuration for example are only permitted to authorized users. User interface elements like the context menu entries to configure or remove some part of the alarm configuration are only accessible after the user has logged in and that user is indeed authorized to manipulate the alarm configuration.

Figure 13.1. Authenticate to change alarm configuration

Authenticate to change alarm configuration
The Configure Item command, initially inaccessible, becomes available after authenticating as a user who is authorized to configure the alarm system.

Authentication is the act of confirming a user's identity, typically by prompting for a user name and password, and trusting that the user is who he claims to be if the password checks out OK. Authentication associates the user with either a real name like Fred or a user ID like fr9.

Authorization is the process of determining if an authenticated user is allowed to perform a certain operation, typically by consulting some type of database that lists the permissions of all the known users.

A certain understanding of these mechanisms is required even if you want to start out by providing all users with full access to all features, because missing Auth & Auth support can result in restricted access for all users.

The following sections will explain the available options for authentication, authorization, secure preferences. At the end of the chapter you will find an example configuration file for a CSS product that selects a desired way of authenticating, authorizing and how to handle secure preferences.


CSS uses JAAS, a standard Java technology, for authentication. Fundamentally, JAAS requires a JAAS configuration file. You may already have a JAAS configuration file for your site that is used by other Java-based tools, and CSS could use that same file. Alternatively, you can also provide the equivalent of a JAAS configuration file via a single Eclipse preference, which may be more convenient for bundling and deploying CSS. The following examples will use the original JAAS configuration file syntax, and how to point CSS to such a configuration file or how to convert it into an Eclipse preference will be explained at the end of this chapter.

Initial User Identity

JAAS supports several Login Modules, including two which trust that the operating system has already determined the current user. The NTLoginModule accepts the currently logged-in Windows user, while the UnixLoginModule takes the currently logged-in Linux or Mac OS X user. In other words, these two modules do not require an actual log in process. They will not prompt for a user name and password, but simply fetch information about whoever started CSS.

On startup, CSS will try to use these modules to determine the initial user name as long as your JAAS configuration file contains the following two entries:

/* Use the currently logged-in user on Linux and Mac OS X */
{ required

/* Use the currently logged-in user on Windows */
{ required

The default JAAS configuration file that is built into CSS already contains these two entries, and in many cases that is all you need: As CSS is started, it knows who is currently logged in.

There are cases, where the initial user is not helpful for authentication purposes. For example, CSS used in the control room may run with a shared user account like operator. To configure the alarm system, however, you want users to log into CSS with their individual name like Fred. To accomplish this, use one of the following options.

Plain Text Password File

The JAAS FileLoginModule allows you to specify user names and their passwords in a plain text file. To use this option, add a configuration similar to the following to your JAAS configuration file:

/* Use plain-text password file. */
{ required

The password file simply lists user names and their passwords:

# Example passwords.conf

While the plain text password file offers an easy way to get started with authentication, it is most useful for testing. The passwords are not encrypted. Any user can view them, so this option is not practical for an operational setup.

JAAS LDAP Authentication

JAAS can connect to an LDAP server. This might be the same LDAP server that is also used for your Unix logins, or an LDAP server that mirrors a site-wide Active Directory. Fundamentally, no changes are required to such an existing LDAP server, you simply instruct JAAS to use it in one of two ways.

First, you can use the standard JAAS JndiLoginModule. This requires an LDAP server that provides the inetOrgPerson schema, which is commonly used for handling authentication on Linux.

/* LDAP authentication.
 * Example of using LDAP on 'localhost'
 * and some root DN.
 * Refer to javadoc of JndiLoginModule
 * for full details.
 * The user URL must point to entries
 * in the LDAP "inetOrgPerson" schema
 * with "uid" and "userPassword" attributes.
 * The provided user name must match a "uid",
 * and the password must match
 * the "{crypt}..." version of "userPassword".
{ required

The other LDAP based mechanism is more generic. JAAS will not attempt to read the password or anything else from LDAP, so there are no requirements on the encoding or accessibility of the password. JAAS will simply attempt to bind, i.e. connect to LDAP with a given user name and password.

/* Authentication via LDAP 'bind'.
 * Fundamentally, this uses
 * but that class would not be accessible by JAAS.
 * The Eclipse extension point 
 * registers it as "",
 * and JAAS will then use it via the Eclipse ExtensionLoginModule.
  /* Get LDAPBindLoginModule via Eclipse */
  /* Parameters for LDAPBindLoginModule */

Adding Custom Authentication Methods

JAAS is extensible. You can provide Java code for a JAAS LoginModule to handle authentication as you desire. For use in Eclipse/CSS, that login module needs to be placed in a plug-in and registered via the Eclipse extension point

Inside the JAAS configuration, you then use the Eclipse LoginModule to access your login module. This additional layer of indirection is required because Eclipse controls the Java class path. JAAS cannot directly reach your contributed JAAS LoginModule unless you register it via the extension point, and then access it via the Eclipse ExtensionLoginModule.

For details, refer to the JAAS LoginModule documentation and also the code in that relates to the LDAPBindLoginModule described in the previous section.


Once the user is authenticated, i.e. CSS has a valid user name or ID, it uses Authorization to determine if a user may perform a certain action. Each application determines which actions require what authorization. For example, the alarm system uses the following:

  • alarm_ack: Authorization that is required to acknowledge alarms. For example, everybody in the control room is typically allowed to acknowledge alarms.
  • alarm_config: Authorization that is required to configure the alarm alarm system. This permission may be limited to a smaller group of people.

File-Based Authorization

With file based authorization, a text file is used to list all authorizations and the users who are granted each authorization:

# Configure authorizations and users who have them
# based on user name patterns

# Format:
# authorization = pattern for users, pattern for users, ...
# Authorizations are defined by applications.
# For example, the alarm system GUI might require
# the "alarm_ack" authorization
# for acknowledging an alarm.
# In addition, the authorization "FULL" covers everything.
# User patterns are regular expressions.
# Multiple patterns are separated by ",".
# Each pattern itself must not contain a ",".

# Anybody can acknowledge alarms

# Specific users may configure alarms
alarm_config = Fred , jane

# Anybody called xyz-admin has full access
FULL = .*-admin,    ky9, 5hz

# The following would allow anybody to do anything
# FULL = .*

File-based authorization is relatively easy to configure and thus a good starting point. Anybody can read the autorization file. For an operational setup this file should consequently be read-only so that ordinary users cannot edit the file and thus grant themselves permissions that they are not meant to have.

LDAP-Group-Based Authorization

In this authorization mode LDAP is queried for the group membership of the authenticated user. Any group membership is then interpreted as authorization.

Usually, the same LDAP server that was also used for authentication can thus support authorization, making this approach very practical for a production setup.

The LDAP directory must support the posixGroup schema, which is the standard for Unix-type account information stored in LDAP.

Example LDAP entry:

dn: cn=archive_config,ou=Groups,dc=example,dc=com
objectClass: top
objectClass: posixGroup
cn: archive_config
description: Allow archive configuration
gidNumber: 1234
memberUid: Fred
memberUid: jane

The above entry defines a group archive_config with members Fred and jane. This will be treated as granting the archive_config authorization to users Fred and jane.

Note that members must specifically be listed via memberUid. In the above example, there may be a user with primary group ID 1234 that Linux would also consider to be a member of the archive_config Linux group, but for authorization purposes such a user must also be listed via memberUid. The numeric group ID is not used for authorization.

Script-Based Authorization

For script-based authorization, an external script is invoked with the name of the authenticated user. That script is then expected to return a list of authorizations for that user.

Example script:

# Script for ScriptAuthorizationProvider
# Invoked with user name, it lists all authentications.
# This implementation uses the group names of the user
# as authorization identifiers.
# Usable on Linux or Mac OS X

if [ $# -ne 1 ]
  echo "USAGE: id_auth user_name" 1>&2
  exit -1
  id -G -n "$@"

This specific example script is conceptually similar to the LDAP-group-based authorization, but instead of contacting an LDAP server, the script uses the id command to determine the user groups. By customizing the script for your needs, you can call any extenal program to obtain a lit of authorizations.

Adding Custom Authorization Methods

The Script-Based Authorization as just described allows adding new authentication methods that are external to CSS/Eclipse/Java. To include a new Java-based authorization method into CSS, add an OSGi/Eclipse Service that provides an AuthorizationProvider. Refer to the JavaDoc for for details.

Secure Preferences

CSS uses the Eclipse preferences to obtain URLs for accessing archived data etc. Some of these preference settings, for example passwords, are stored in an encrypted file separate from the normal Eclipse preferences.

You can configure where these encrypted settings are stored:

  • Default: Use the default location, which is typically the user's home directory.

    Advantage: It's the default.

    Disadvantage: You won't always know where the preferences are.

  • Instance: Use the Eclipse 'instance', i.e. the workspace.

    Advantage: You know where it is, and each workspace will have its own settings.

    Disadvantage: Each workspace has different settings.

  • Install: Use the Eclipse 'install' location, i.e. where the product is installed.

    Advantage: You know where it is, and every workspace for that product will have the same settings. Good for a "global" setup.

    Disadvantage: Ordinary users cannot (should not) have write permissions.

Setting Secure Preferences

Secure preferences can be provided via the hierachical preference system as usual, for example in a plugin_customization.ini:


When doing this, the password is obviously not encrypted. Direct editing of the secure preference file is not possible, because you would have to enter the encrypted value.

In the CSS user interface, secure preferences can be entered via the ordinary preference GUI (Menu Edit/Preferences). For headless CSS tools like the alarm server which do not offer a preference GUI, the command-line can be used:

AlarmServer -set_password org.csstudio.whatever/password=ThePassword

Required Plug-Ins, User Interface

The plugin defines the API for authentiation, authorization and secure preferences.

The plugin adds user interface elements. To the end user, this results in tool-bar buttons for logging in and out as shown in Figure 13.1, “Authenticate to change alarm configuration” as well as corresponding entries in the File menu.

By default, the user is automatically logged in when starting CSS based on information from the operating system. The unix respectively windows JAAS configurations described before determine this initial user identity. To prevent such automated log-in, use a JAAS configuration that does not include entries named unix respectively windows.

The Log-in toolbar button or menu entry allows users to log in as a different user by using for example LDAP or a File-based approach. Once logged in as a user different from the original, OS-authenticated user, the Log-out toolbar button allows reverting to the OS-authenticated user.

There is a Security View that can be opened from the menu Window/Show View/Other..., then selecting CSS/Security Info. This view displays information about the currently authenticated user and her authorizations. Some alarm-related example actions can be invoked for testing their accessibility.

Figure 13.2. Security Info View

Security Info View

Configuring Authentication, Authorization and Secure Preferences

The following example explains the available security-related settings.

For using them in a plugin_customization.ini file, note that each setting needs to be prefixed with For example, instead of


you need to use

In addition, some long lines have been reformatted with "\" to indicate that the following line should be joined.

# Security Settings

## Authentication

# Option 1:
# Use a JAAS config file as in normal use of JAAS

# Path to JAAS configuration file
# When located inside a plugin, use
#  "platform:/plugin/name.of.plugin/path/within/plugin.conf"

# Name of a JAAS login configuration to use.
# This must match the name of one of the entries
# in the jaas_config_file.

# Option 2:
# Do not use a JAAS config file.
# Instead, provide what would the desired entry in the config file
# as an Eclipse preference.
# If the preference "jaas_config" is defined, it will have
# precedence. "jaas_config_file" and "jaas_config_name" will
# be ignored!

# Format (all on one line!):
#   ModuleClass Flag option1=value1 option2=value2 ...; \
#   ModuleClass Flag ModuleOptions; ...
# ModuleClass, Flag and value options are in the same format
# as in auth.conf, but all on one line.
# Value strings must be quoted.
# Example (must be on one line!): required \
#            debug="true" passwordFile="/path/to/my_passwords.conf";

## Authorization

# Select authorization provider
# Standard implementations:
# FileBased, see
# LDAPGroup, see
# Script, see
# Additional providers can be added via extension point,
# see

# Path to FileBased authorization configuration file
authorization_file_name= \

# Path to command used by Script authorization

## Secure Preferences

# Where secure preferences are located.
# "Default":
# Use the default location, which is typically
# the user's home directory.
#  @see SecurePreferencesFactory#getDefault()
# Advantage: It's the default
# Disadvantage: You won't always know where the preferences are.
# "Instance":
# Use the Eclipse 'instance', i.e. the workspace.
# Advantage: You know where it is, and each workspace
# will have its own settings.
# Disadvantage: Each workspace has different settings.
# "Install":
# Use the Eclipse 'install' location,
# i.e. where the product is installed.
# Advantage: You know where it is, and every workspace for that
# product will have the same settings. Good for a "global" setup.
# Disadvantage: Ordinary users cannot
#               (should not) have write permissions.