15. Security Configuration

15.1. Introduction

Access to different parts of the CartoWeb can be allowed or denied according to who is currently using the application.

The following concepts are used in this chapter.

Security Mechanisms Concepts

User: Representation of a user accessing CartoWeb. If the user is not logged in, she is rerefenced as the anonymous user.
Role: A user can have zero or more roles associated to her. These roles are used to allow or deny a permission to a resource of feature.
Permissions: Permissions describe parts of the application which can be allowed or denied access. A permission can have roles for which access is allowed, and roles for which it is denied.

15.2. Auth Plugin

The security system in CartoWeb was developped to be modular and to allow different authentications systems to be easily plugged-in. This section describes one implementation of authentication, user password and roles management, which is the auth plugin shipped with CartoWeb.

The auth plugin is not a core plugin. That's why you need to enable it if you want to enable users to log-in. See Chapter 4, Configuration Files how to enable it in the list of plugins. If it is not activated the login dialog won't be available, so users will remain anonymous.

The next section describes the configuration file of the auth plugin. It is basically the management of usernames, passwords and roles.

15.2.1. auth.ini (Client-side)

The auth.ini configuration is located in the client. This file contains the list of usernames, their password and the roles they belong to:

authActive: boolean Whether to show the Authentication login/logout buttons. (note: this is not related to the fact the authentication system will be active or not)
users.USERNAME List of users and their passwords. USERNAME is the name of the user for whom the password is set. Passwords values are md5sums of the password. To get this value, you can type in a shell:
```
echo -n 'mypassword' | md5sum
```
Example:
```
users.alice = e3e4faee0cc7fc55ad402f517cdaf40
```
roles.USERNAME List of roles for each user. USERNAME is replaced by the user for whom the roles are set. Some roles have a special meaning, see Section 15.2.2, “Special Role Names”

It is possible to use two different location where user and password are stored. There are two mechanisms built-in in CartoWeb:

.ini file
database

The parameter securityContainer controls which backend is used, as described below (with parameters specific to the database backend):

securityContainer: can be file for the file storage of users/password, or db for the dabase storage.
dbSecurityDsn: The database connection string to be used. For instance pgsql://user:password@localhost/test.
dbSecurityQueryUser: The SQL query to perform to check a username/password pair is valid. It should return a row if the pair is correct. For instance: "SELECT * FROM users WHERE username='%s' AND password='%s'".
dbSecurityQueryRoles: The SQL query used to retrieve roles for a given user. It should return one column with all roles for the user each row. For instance: "SELECT roles FROM users WHERE username='%s'"

15.2.2. Special Role Names

The auth plugin configuration described in the previous section references the notion of users and roles. Basically a role can be any string, the application will only use them as a way to check if a feature is allowed or not. However, a set of role name have a special meaning. They are described below.

Special Roles

all: This role belongs to any user. It is useful in case a permission should not be restricted access.
loggedIn: This role is given to all users who have logged in the application. It means they are identified to the system with a username.
anonymous: This role is given to all users not known to the application. This role is attached to anyone who has not yet entered her username and password.

Example 15.1. Special Role Name Usage

general.allowedRoles = loggedIn

15.3. Global CartoWeb Permissions

The whole application can be denied access to anonymous users: only authenticated (or a set) of users can access the application. Anonymous users arriving on the main page will see a login dialog page if they have no rights to view the page (if the auth plugin is not loaded, they will simply see a denied page).

This feature can be parametrized on the CartoClient in the client.ini configuration file:

securityAllowedRoles = list : List of roles which are allowed to access the cartoweb. Set to 'all' if no if no restriction is given. (see Section 15.2.2, “Special Role Names” for typical predefined roles)

Example 15.2. Global Permissions Usage

securityAllowedRoles = loggedIn

15.4. Plugin Specific Permissions

The main part of permissions is set in the different plugins of CartoWeb. For instance, permissions related to which layer can be viewed are set in the layer plugin configuration files, and pdf printing permissions in the pdf plugin. These sections either describes the plugin permissions which can be used, or make references the the corresponding chapters.

15.4.1. Layers Related Permissions

It is possible to restrict which layer can be viewed by a set of users. For instance, only logged in admin users can be allowed to view security sensitive layers.

These layer permissions are inherited by children. It means that if a parent LayerGroup is not allowed to be viewed, then all the children won't be visible.

The permissions for layer must be activated in the layers.ini CartoClient configuration file, and are set in the metadata of the mapfile or the <layers>.ini configuration file. The concept of metadata in mapfiles and .ini file is described in Section 6.3, “Metadata in Mapfile and layers.ini”. The metadata key name which can be used is called security_view and contains a coma separated list of roles which are allowed to view this layer. If no such metadata key is associated to a layer or layerGroup, anyone can see the layer.

Heres the description of the layers.ini configuration file:

applySecurity: True if the security check of layer access is activated. It might have a minor impact on performances, if a large number of layer is used.

Here's an example of a security metadata key used in layer of the mapfile:

METADATA
    "exported_values" "security_view,some_specific_parameter"
    "security_view" "admin" 
    "some_specific_parameter" "value"
  
  "id_attribute_string" "FID|string"
  "mask_transparency" "50"
  "mask_color" "255, 255, 0"
  "area_fixed_value" "10"
END

In this example, the layer containing this metadata description will only be visible for users having the admin role.

Note

Notice the usage of the exported_values metadata key which lists the security related metadata key. It is explained in Section 6.3, “Metadata in Mapfile and layers.ini”

Now let's look the case where the metadata key is set on a layer group in the <layers>.ini configuration file:

layers.group_admin.className = LayerGroup
layers.group_admin.children = grid_defaulthilight 
layers.group_admin.metadata.security_view = admin

In this example, the admin role is set for the layerGroup called group_admin. You can notice the very similar syntax as used in the mapfile.

Warning

Don't forget to set applySecurity to True in the layers.ini CartoClient configuration file, otherwise security metadata keys won't be taken into account.

15.4.2. PDF Printing Permissions

The roles management in Pdf printing is explained in detail in Chapter 12, PDF Export. In particular, see Section 12.3.5, “Roles Management”.