52N Web Security Services User Guide
This user guide shows how to work with the 52N Web Security Service v2.1.
2 Basic Architecture
In the most simple case the architecture of the 52North Security System is quite simple:
You just have to deploy and configure the Web Security Service (WSS) that...
- receives all service requests instead of the protected service (eg. your WMS),
- authenticates the user by some kind of credentials passed on with the request,
- checks and enforces access permissions defined in a policy XML file,
- and forwards the request to the protected service.
3 System Requirements
- Apache Tomcat 5.0, 5.5, 6.0 (recommended: 5.5.x)
- Java Development Kit (JDK) 1.5, 1.6
- Download the latest 2.1.x version of the WSS application.
The WSS service is delivered as zipped a web archive file ('war') to be easily deployed in a Servlet container.
- Deploy the WSS web application into Apache Tomcat.
The easiest way to deploy a web application is to unzip the downloaded file and save wss.war to <TOMCAT_HOME>/webapps.
5 Quick Start
This section guides you through the steps to test the newly installed WSS with as few modifications needed as possible, making use of pre-defined services, users and policies.
5.1 Pre-defined service, users and policies
When you downloaded and installed the WSS it is pre-configured to protect the Demis WMS. The URL of the protected service is http://localhost:8080/wss/httpauth/demiswms (adjust host, port, and context name if necessary). It can be connected and loaded like any other WMS, but requires HTTP Basic Authentication.
The installation comes with three user accounts and defines the following access policies:
- User Alice (username/password: alice/alice) has full access to all layers and operations on the Demis WMS
- User Bob (bob/bob) and user Guest (guest/guest) have GetMap and GetCapabilities access to the layers Cities, Builtup areas, Hillshading, Borders, and Countries.
- User Bob can only query features (GetFeatureInfo) from the Countries layer.
- User Guest can query features (GetFeatureInfo) from the Countries layer whithin the area of the Americas.
5.2 Adjusting the policies
As the WSS base URL is a part of the policies, you most likely have to replace the default URL http://localhost:8080/wss with your actual WSS URL in the policies. If your actual WSS base URL matches the default URL you don't need to replace the URLs!
To do so, follow these steps:
- In a text editor open <WSS_DIR>/WEB-INF/classes/permissions.xml
- Replace all occurances of http://localhost:8080/wss with your actual WSS URL.
- Save the modifcations.
5.3 Hello Word!
To test the installation let us request the capabilities of the protected service using Bob's account. In a browser open http://localhost:8080/wss/httpauth/demiswms?SERVICE=WMS&REQUEST=GetCapabilities (adjust host, port, and path if necessary).
If you are requested for username/password, enter bob / bob.
You will receive a capabilities document that only contains the layers, Bob is allowed to see.
If you'd like to request the capabilites with a different user account (alice or guest) you have to restart the browser in order to invalidate Bob's cached credentials.
To load the protected service into uDig
- Start uDig
- Select File > New > New Map
- Rename map to protected
- Right-click on protected > Add... > Web Map Server > Enter http://localhost:8080/wss/httpauth/demiswms
- Log in as Bob (bob/bob)
- Select all available layers
You are now be able to navigate the map as with any other WMS. If you use the info button to identify the features, you can only get information for the Countries layers -- according to the permissions.
6.1 Protecting a Service
Remember that a single WSS installation is capable of protecting an arbitrary number of services. For each service you want to protect you have to create a so called "Enforcement Point" receiving all service requests for a protected service and authorizing access to it. To create, edit, and delete an Enforcement Point, you should use the WSS Management Application that is available through http://localhost:8080/wss (may differ depending on your actual server setup).
Click on Manage WSS configuration for the service 'WSS' to start the application. You have to log in with a tomcat user, that has the role "manager" (defined in <TOMCAT_INSTALL>\conf\tomcat-users.xml).
After you have successfully logged in, you get a list of all Enforcement Points of that WSS instance.
Add new Enforcement Point
- Click Add to start adding a new Enforcement Point.
- Enter the Name of the Enforcement Point (this will be part of the EP's URL, eg. mywms
- Enter the Type of the protected service, i.e. WMS, SOS, or WFS for example.
- Enter the URL of the protected service, eg. http://localhost/geoserver/wms
- Select the interceptors (= authorization modules) that are supposed to inspect the requests/responses, eg. all names WMS... if this Enforcement Point is for a WMS.
- Specifiy the exception format for all exceptions that are issued by the Enforcement Point itself (not the ones forwarded from the protected service).
6.2 Defining Permissions
Policies for the WSS can be defined in various ways. If the installation is conducted in the way as described in the Quick Start section, policies are stored in files using the 52n Simple Permissions XML format.
52N Simple Permissions define triples of information that specify who is allowed to access what resource with a certain operation. In other words, a permission consists of
- The resources governed by this permission.
- The operations ("actions"), a policy applies to.
- The roles ("subjects") to which the policy applies.
This is a permission in the Simple Permissions format:
... <Permission name="bobAndGuest_most_GetMap_GetCaps"> <Resource value="layers/Cities" /> <Action value="operations/GetMap" /> <Subject value="guest" /> </Permission> ...
This WMS permission allows users, who are assigned to the role guest, to access the layer Cities with the operation GetMap, thus to view that layer.
Using the Simple Permissions File
Let's see, how policies are defined using the Simple Permissions file format.
By default, the policies are defined in <WSS_DIR>/WEB-INF/classes/permissions.xml.
This is the permissions.xml file delivered by the standard WSS application.
<?xml version="1.0" encoding="UTF-8"?> <SimplePermissions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.52north.org/security/simple-permission/1.0"> <PermissionSet name="WMS1 Permission"> <ResourceDomain value="http://localhost:8080/wss/*/demiswms/" /> <!-- Prefix for all resources --> <ActionDomain value="http://localhost:8080/wss/*/demiswms/" /> <!-- Prefix for all actions --> <SubjectDomain value="urn:n52:security:subject:role" /> <!-- Qualifier for all subjects --> <Permission name="alice_all"> <Resource value="layers/*" /> <!-- Any layers --> <Action value="operations/*" /> <!-- Any operations --> <Subject value="alice" /> </Permission> <Permission name="bobAndGuest_most_GetMap_GetCaps"> <Resource value="layers/Cities" /> <Resource value="layers/Builtup%20areas" /> <Resource value="layers/Hillshading" /> <Resource value="layers/Borders" /> <Resource value="layers/Countries" /> <Action value="operations/GetCapabilities" /> <Action value="operations/GetMap" /> <Subject value="bob" /> <Subject value="guest" /> </Permission> <Permission name="bob_Countries_GetFeatureInfo"> <Resource value="layers/Countries" /> <Action value="operations/GetFeatureInfo" /> <Subject value="bob" /> </Permission> <Permission name="guest_countries_GetFeatureInfo_obliged"> <Resource value="layers/Countries" /> <Action value="operations/GetFeatureInfo" /> <Subject value="guest" /> <Obligation name="obligation:wms:extent:boundingbox"> <Attribute name="srs">EPSG:4326</Attribute> <Attribute name="box">-170,-56,-36,83</Attribute> </Obligation> </Permission> </PermissionSet> </SimplePermissions>
Every file using the Simple Permissions format contains a list of PermissionsSet elements, one for each protected service.
An instance of a resource or an action is generally defined in a REST-style URL built of EnforcementPointURL+[resource_type]+[resource_id]. Thus, e.g. a layer is identified by its fully qualified ID http://localhost:8080/wss/httpauth/mywms/layers/countries.
With <ResourceDomain> or <ActionDomain> we can define default domain identifiers that are prepended to all <Resource> or <Action> identifiers of that single <PermissionSet>.
These domain identifiers as well as the Resource and Action identifiers may contain the wild card character '*' as part of the URL path. This, for example, allows you to bundle the ResourceDomains http://localhost:8080/wss/WSS/mywms and http://localhost:8080/wss/httpauth/mywms in the single entry http://localhost:8080/wss/*/mywms.
6.3 Defining Users
7 Advanced Configuration
The 52North Security Services are far more flexible than we are able to lay out in this user guide. Please visit the advanced configuration site to get more information on available extensions.
Coming soon...: More about
- Authentication methods
- Accessing user data
- Policy data and formats
- Authorization modules / Interceptors