2.6 Security subsystem

Configuring the security subsystem

Starting with GeoServer 1.6.0 the GeoServer security subsystem has been improved by integrating Acegi, a library that allows for taking care or various security issues in web applications. The library itself is very powerful, though due to development time constraints we're using just a few of its functionalities.

Accessing secured services

The web console is accessed by means of a form based authentication, with optional remember-me cookie setting.
The OGC services are secured using HTTP BASIC authentication, which is to be provided on each call.
The form based authentication is in fact session oriented, and if the same browser is used to access OWS services as well, the authentication will be remembered.
As a rule of thumb, accessing a secured resource follows this process:

• if any authentication information is included along with the resource access, it will be used, and in the case of form based one, a session will be created to store it, whilst in the BASIC authentication case, session integration will be performed only if a session is already available (session creation is avoided for service call to avoid its overhead)
• if no authentication is provided, anonymous login will be assumed
• if the resource being accessed is secured and the current user is anonymous, authentication will be requested either using BASIC authentication (for OWS services) or by using form based login (for the web console)
• if the resource begin accessed is secured and the currently authenticated user has not enough rights to access it (access roles missing) an HTTP 404 error will be returned.

To allow for authorization quick tests, the "sample request" page now provides (optional) username and password fields that will be turned into a HTTP BASIC authentication header.

Configuring the security subsystem

The current version of the security subsystem uses a set of plain text property files located in the GeoServer data directory to configure users and access permissions.
At the time of writing there is no web UI to edit those file contents, so you'll have to alter them by hand using a text editor.

User Level Security

The users file, GEOSERVER_DATA_DIR/security/user.properties, defines users, their password, and their roles. An example follows:

admin=geoserver,ROLE_ADMINISTRATOR
wfst=wfst,ROLE_WFS_READ,ROLE_WFS_WRITE
wfs=wfs,ROLE_WFS_READ

Passwords are kept clear text because there is no utility to edit the file that could handle password encription transparently, yet Acegi allows for using different password encrypters easily (so stay tuned for a version of Geoserver with UI editing and password encryption).
Roles are just strings starting with ROLE_, they are mostly free form. In the current implementation, ROLE_ADMINISTRATOR is the role required to access the web administration console, and it the only "well known" role, the others you'll have to make up to control access to services..

The other files do configure specific aspect of security, in particular:

• layers.properties configures Layer level security
• services.properties configures OGC service level security

Layer Level Security (aka Per-Layer Security)

Layer level security (aka per layer security) works for GeoServer 1.7.0 and higher only!

Access permissions will be configurable by entries in a the GEOSERVER_DATA_DIR/security/layers.properties property file, following the syntax already available for service level security:

namespace.layer.permission=ROLE_1[,ROLE_2][, ...]]

where:

• namespace indicates the name of the namespace. The wildcard * is used to indicate all namespaces (i.e. global scope).
• layer is the name of a feature type or coverage. The wildcard * is used to indicate all layers in the namespace.
• permission indicates the type of access permission
  • 'r' - indicates read access permission
  • 'w' - indicates write access permission
• ROLE#_ are the names of roles (defined in the user.properties file). The wildcard * is used to indicate the permission is applied to all users, including anonymous users.

Rules:

• Each entry must have a unique combination of namespace, layer, and permission values.
• If a permission at the global level is not specified, global permissions are assumed to allow read/write access, i.e. ..r=* and/or ..w=*
• If a permission for a namespace is not specified, it inherits permissions from the global specification.
• If a permission for a layer is not specified, it inherits permissions from it's namespace specification.
• If a user belongs to multiple roles, the least restrictive permission they inherit will apply.

The same file may contain a further directive that specified the way in which GeoServer will advertise secured layers and behave when a secured layer is accessed without the necessary privileges. The line is:

mode=HIDE|CHALLENGE|MIXED

where:

• hide (default): does not show to the user the layers that he cannot access, behaves as if a layer was read only if the user does not have write permissins. The capabilities document do not contain the clayers the current user cannot access to. This is the highest security mode, it assumes a privileged user has logged in before showing him the secured layers. Because of this, it does not work very well with clients such as uDig or Google Earth, where the authentication dialog pops up only if the server returns a HTTP 401 after attempting to access a secured resource.
• challenge: allows free access to metadata, any attempt at accessing actual data is metby a HTTP 401 code that forces most clients to show an authentication dialog. The capabilities do contain the full list of layers, DescribeFeatureType and DescribeCoverage do work fine, the first attempt to access the actual data without the necessary privileges is met with a 401 error. This mode works fine with capabilities driven clients such as uDig, and with any client that needs a 401 in order to trigger an authentication dialog.
• mixed: hides the layers the user cannot read from the capabilities, but triggers authentication for any other attempt to access the data or the metadata. Useful if you don't want the world to see the very existence of some of your data, but you still want selected people whom you give direct data access links to get the data after authentication.

Example configuration protecting a single namespace and a single layer

The following entries demonstrate configuring GeoServer so that it is primarily a read-only server.

*.*.r=*
*.*.w=NO_ONE
private.*.r=TRUSTED_ROLE
private.*.w=TRUSTED_ROLE
topp.congress_district.w=STATE_LEGISLATORS

in this scenario here is the map of roles to permissions:

Example configuration for locking down GeoServer

The following entries demonstrate configuring GeoServer so that it is locked down.

*.*.r=TRUSTED_ROLE
*.*.w=TRUSTED_ROLE
topp.*.r=*
army.*.r=MILITAR_ROLE,TRUSTED_ROLE
army.*.w=MILITAR_ROLE,TRUSTED_ROLE

in this scenario here is the map of roles to permissions:

Example Configuration for something more complex

The following entries demonstrate configuring GeoServer with global-, namepace-, and layer-level permissions.

*.*.r=TRUSTED_ROLE
*.*.w=NO_ONE
topp.*.r=*
topp.states.r=USA_CITIZEN_ROLE,LAND_MANAGER_ROLE,TRUSTED_ROLE
topp.states.w=NO_ONE
topp.poly_landmarks.w=LAND_MANAGER_ROLE
topp.militar_bases.r=MILITAR_ROLE
topp.militar_bases.w=MILITAR_ROLE

in this scenario here is the map of roles to permissions:

Note: The topp.states.w=NO_ONE is not needed, because this permission would be inherited from the global level, i.e.

*.*.w=NO_ONE

Example of an Invalid Configuration File

The following set of entries would not be valid because the namespace, layer, permission combinations of the entries are not unique.

topp.state.rw=ROLE1
topp.state.rw=ROLE2,ROLE3

Service Level Security

A single configuration file, GEOSERVER_DATA_DIR/security/services.properties, states which services are secured, and which roles the user must have in order to access them. For example:

wfs.GetFeature=ROLE_WFS_READ
wfs.Transaction=ROLE_WFS_WRITE

Service security configuration requires a service.method or simply a service key, and a list of roles that can access that service or method. A user having at least one of those roles will be able to call that method. When invoking an service method, the dispatcher will check if there is any service.method role configuration, if none is found, a service configuration will be looked up, and if again none is found, the service will be assumed to be non secured so no password is required.

Please see the associated pages for more informations on how to use the respective files.

Relationship between the various security levels

Each request will be subject to both service and data authorization checks, according to the following workflow:

• the user gets authenticated using Acegi integration (at the moment, either form or HTTP basic authentication)
• the service level security gets checked by the dispatcher, if access is denied, the request ends
• the service will attempt to access the data catalog, each of those attempts will be subjected to data level security restrictions

So, to sum up, in order to successfully execute an OGC service call the user will have to be allowed to execute the requested service method and to access the data specified in the request.

Disabling the security subsystem

If you are already using an external security subsystem it might conflict with the GeoServer one. The only option at the moment is to disable completely the GeoServer one and rely only on the external one.
Beware, this means you'll have to make sure the external one locks down the administration area, if you follow these instructions no password will be required anymore to enter the admin section.

To disable GeoServer Acegi integration:

• unpack the GeoServer war
• open web.xml
• comment out the "Acegi Filter Chain Proxy" filter definition and filter params like this:

  <!--  If you want to use your security system instead of the GeoServer one, comment out
           this filter and the associated filter mapping below. Beware, when you do no
  
           user checking will be done for anything, not even for the admin console
     <filter>
       <filter-name>Acegi Filter Chain Proxy</filter-name>
       <filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class>
       <init-param>
         <param-name>targetClass</param-name>
         <param-value>org.acegisecurity.util.FilterChainProxy</param-value>
       </init-param>
     </filter>
      -->
  
    ...
  
    <!-- If you want to use your security system comment out this one too
    <filter-mapping>
      <filter-name>Acegi Filter Chain Proxy</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>
     -->
  

Then redeploy GeoServer, the security subsystem should be completely off, and access to the amin area should be free of password requests. Now your job is to setup whatever external security you have to protect the admin area (hint, the admin area pages are located at http://host:port/geoserver/config/*).