< Editing

Internationalization >

## 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 three different locations where user and password are stored. There are three mechanisms built-in in CartoWeb:

1. .ini file
2. database
3. ldap

The parameter `securityContainer` controls which backend is used.

- securityContainer: can be `ini` for the file storage, `db` for the dabase storage, or `ldap` for the ldap storage.

Parameters for database and ldap storage are described below

#### 15.2.1.1. database 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.1.2. ldap storage

The following parameters are inspired from Pear::Auth_Container_LDAP

- host: hostname of the server that hosts the ldap server `localhost` (default), `ldap.netsols.de`.
- port: Port number on which the ldap server listens `389` (default).
- basedn: the base dn (Distinguished Name) of the ldap server For instance: `dc=ldap,dc=netsols,dc=de`
- userattr: the user attribute to search for. `uid` (default)
- groupdn: gets prepended to basedn when searching for group. For instance: `ou=Groups`
- groupattr: the group attribute to search for. `cn` (default)
- groupfilter: filter that will be added to the search filter when searching for a group: `(&(groupattr=group)(memberattr=username)(groupfilter))` `(objectClass=groupOfUniqueNames)` (default). For instance: `(objectClass=posixGroup)` or `(cn=cw*)(objectClass=posixGroup)` if you have groups starting with "cw" specifically set for Cartoweb.
- memberattr: the attribute of the group object where the user dn may be found `uniqueMember` (default)
- groupscope: Scope for group searching: `one`, `sub` (default), or `base`

### 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”.