Source

mapproxy / doc / auth.rst

The branch 'util_grids' does not exist.

Authentication and Authorization

Warning

This page and the described feautures of MapProxy are a work in progess and might change anytime.

Authentication is the process of mapping a request to a user. There are different ways to do this, from simple HTTP Basic Authentication to cookies or token based systems.

Authorization is the process that defines what an authenticated user is allowed to do. A datastore is required to store this authorization information for everything but trivial systems. These datastores can range from really simple text files (all users in this text file are allowed to do everything) to complex schemas with relational databases (user A is allowed to do B but not C, etc.).

As you can see, the options to choose when implementing a system for authentication and authorization are diverse. Developers (of SDIs, not the software itself) often have specific constraints, like existing user data in a database or an existing login on a website for a Web-GIS. So it is hard to offer a one-size-fits-all solution.

Therefore, MapProxy does not come with any embedded authentication or authorization. But it comes with a flexible authorization interface that allows you (the SDI developer) to implement custom tailored systems.

Luckily, there are lots of existing toolkits that can be used to build systems that match your requirements. For authentication there is the repoze.who package with plugins for HTTP Basic Authentication, HTTP cookies, etc. For authorization there is the repoze.what package with plugins for SQL datastores, etc.

Note

Developing custom authentication and authorization system requires a bit Python programming and knowledge of WSGI and WSGI middleware.

Authentication/Authorization Middleware

Your auth system should be implemented as a WSGI middleware. The middleware sits between your web server and the MapProxy.

WSGI Filter Middleware

A simple middleware that authorizes random requests might look like:

class RandomAuthFilter(object):
    def __init__(self, app, global_conf):
        self.app = app

    def __call__(self, environ, start_reponse):
        if random.randint(0, 1) == 1:
          return self.app(environ, start_reponse)
        else:
          start_reponse('403 Forbidden',
            [('content-type', 'text/plain')])
          return ['no luck today']

One way to add that middleware in front of MapProxy is the filter-with option of PasteDeploy. The config.ini looks like:

[app:mapproxy]
use = egg:MapProxy#app
mapproxy_conf = %(here)s/mapproxy.yaml
filter-with = auth

[filter:auth]
paste.filter_app_factory = myauthmodule:RandomAuthFilter

[server:main]
...

You can implement simple authentication systems with that method, but you should look at repoze.who before reinventing the wheel.

Authorization Callback

Authorization is a bit more complex, because your middleware would need to interpret the request to get information required for the authorization (e.g. layer names for WMS GetMap requests). Limiting the GetCapabilities response to certain layers would even require the middleware to manipulate the XML document. So it's obvious that some parts of the authorization should be handled by MapProxy.

MapProxy can call the middleware back for authorization as soon as it knows what to ask for (e.g. the layer names of a WMS GetMap request). You have to pass that function into the environment so that MapProxy knows what to call.

Here is a more elaborate example that denies requests to all layers that start with a specific prefix. These layers are also hidden from capability documents.

class SimpleAuthFilter(object):
    """
    Simple MapProxy authorization middleware.

    It authorizes WMS requests for layers where the name does
    not start with `prefix`.
    """
    def __init__(self, app, global_conf, prefix='secure'):
        self.app = app
        self.prefix = prefix

    def __call__(self, environ, start_reponse):
        # put authorize callback function into environment
        environ['mapproxy.authorize'] = self.authorize
        return self.app(environ, start_reponse)

    def authorize(self, service, layers=[], environ=None, **kw):
        allowed = denied = False
        if service.startswith('wms.'):
            auth_layers = {}
            for layer in layers:
                if layer.startswith(self.prefix):
                    auth_layers[layer] = {}
                    denied = True
                else:
                    auth_layers[layer] = {
                        'map': True,
                        'featureinfo': True,
                        'legendgraphic': True,
                    }
                    allowed = True
        else: # other services are denied
          return {'authorized': 'none'}

        if allowed and not denied:
            return {'authorized': 'full'}
        if denied and not allowed:
            return {'authorized': 'none'}
        return {'authorized': 'partial', 'layers': auth_layers}

And here is the part of the config.ini where we define the filter and pass custom options:

[filter:auth]
paste.filter_app_factory = myfiltermodule:SimpleAuthFilter
prefix = foo

MapProxy Authorization API

MapProxy looks in the request environment for a mapproxy.authorize entry. This entry should contain a callable (function or method). If it does not find any callable, then MapProxy assumes that authorization is not enabled and all requests are allowed.

The signature of the authorization function:

Note

The actual name of the callable is insignificant, only the environment key mapproxy.authorize is important.

The service parameter is a string and the content depends on the service that calls the authorize function. Generally, it is the lower-case name of the service (e.g. tms for TMS service), but it can be different to further control the service (e.g. wms.map).

The function should return a dictionary with the authorization information. The expected content of that dictionary can vary with each service. Only the authorized key is consistent with all services.

The authorized entry can have four values.

full
The request for the given service and layers is fully authorized. MapProxy handles the request as if is no authorization.
partial
Only parts of the request are allowed. The dictionary should contains more information on what parts of the request are allowed and what parts are denied. Depending on the service, MapProxy can then filter the request based on that information, e.g. return WMS Capabilities with permitted layers only.
none
The request is denied and MapProxy returns an HTTP 403 response.
unauthenticated
The request(er) was not authenticated and MapProxy returns an HTTP 401 response. Your middleware can capture this and ask the requester for authentication. repoze.who's PluggableAuthenticationMiddleware will do this for example.

WMS Service

The WMS service expects a layers entry in the authorization dictionary for partial results. layers itself should be a dictionary with all layers. All missing layers are interpreted as denied layers.

Each layer contains the information about the permitted features. A missing feature is interpreted as a denied feature.

Here is an example result of a call to the authorize function:

{
  'authorized': 'partial',
  'layers': {
    'layer1': {
      'map': True,
      'featureinfo': False,
    },
    'layer2': {
      'map': True,
      'featureinfo': True,
    }
  }
}

limited_to

You can restrict the geographical area for each request. This feature works for GetCapabilities, GetMap and GetFeatureInfo requests. MapProxy will modify the bounding box of each restricted layer for GetCapabilities requests. GetFeatureInfo requests will only return data if the info coordinate is inside the permitted area. For GetMap requests, MapProxy will clip each layer to the provided geometry – areas outside of the permitted area are transparent or in the background color of the WMS request.

MapProxy supports this clipping for the whole request or for each layer. You need to provide a dictionary with bbox and geometry. The following geometry values are supported:

BBOX:
Bounding box as a list of minx, miny, maxx, maxy.
WKT polygons:
String with one or more polygons and multipolygons as WKT. Multiple WKTs must be delimited by a new line character. Return this type if you are getting the geometries from a spatial database.
Shapely geometry:
Shapely geometry object. Return this type if you already processing the geometries in your Python code with Shapely.

You can provide the geometry for each layer or for the whole request.

Here is an example callback result with two limited layers and one unlimited layer:

{
  'authorized': 'partial',
  'layers': {
    'layer1': {
      'map': True,
      'limited_to': {
        'geometry': [-10, 0, 30, 50],
        'srs': 'EPSG:4326',
      },
    },
    'layer2': {
      'map': True,
      'limited_to': {
        'geometry': 'POLYGON((...))',
        'srs': 'EPSG:4326',
      },
    },
    'layer3': {
      'map': True,
    }
  }
}

Here is an example callback result where the complete request is limited:

{
  'authorized': 'partial',
  'limited_to': {
    'geometry': shapely.geometry.Polygon(
      [(-10, 0), (30, -5), (30, 50), (20, 50)]),
    'srs': 'EPSG:4326',
  },
  'layers': {
    'layer1': {
      'map': True,
    },
  }
}

Performance

The clipping is quite fast, but if you notice that the overhead is to large, you should reduce the complexity of the geometries returned by your authorization callback. You can improve the performance by returning the geometry in the projection from query_extent (ST_Transform), by limiting it to the query_extent (ST_Intersection) and by simplify it (ST_Simplify).

Service types

The WMS service uses the following service strings:

wms.map

This is called for WMS GetMap requests. layers is a list with the actual layers to render, that means that group layers are resolved. The map feature needs to be set to True for each permitted layer. The whole request is rejected if any requested layer is not permitted. Resolved layers (i.e. sub layers of a requested group layer) are filtered out if they are not permitted.

Example

With a layer tree like:

- name: layer1
  layers:
    - name: layer1a
      sources: [l1a]
    - name: layer1b
      sources: [l1b]

An authorize result of:

{
  'authorized': 'partial',
  'layers': {
    'layer1':  {'map': True},
    'layer1a': {'map': True}
  }
}

Results in the following:

  • A request for layer1 renders layer1a, layer1b gets filtered out.
  • A request for layer1a renders layer1a.
  • A request for layer1b is rejected.
  • A request for layer1a and layer1b is rejected.

wms.featureinfo

This is called for WMS GetFeatureInfo requests and the behavior is similar to wms.map.

wms.capabilities

This is called for WMS GetCapabilities requests. layers is a list with all named layers of the WMS service. Only layers with the map feature set to True are included in the capabilities document. Missing layers are not included.

Sub layers are only included when the parent layer is included, since authorization interface is not able to reorder the layer tree. Note, that you are still able to request these sub layers (see wms.map above).

Layers that are queryable and only marked so in the capabilities if the featureinfo feature set to True.

With a layer tree like:

- name: layer1
  layers:
    - name: layer1a
      sources: [l1a]
    - name: layer1b
      sources: [l1b]
    - name: layer1c
      sources: [l1c]

An authorize result of:

{
  'authorized': 'partial',
  'layers': {
    'layer1':  {'map': True, 'feature': True},
    'layer1a': {'map': True, 'feature': True},
    'layer1b': {'map': True},
    'layer1c': {'map': True},
  }
}

Results in the following abbreviated capabilities:

<Layer queryable="1">
  <Name>layer1</Name>
  <Layer queryable="1"><Name>layer1a</Name></Layer>
  <Layer><Name>layer1b</Name></Layer>
</Layer>

TMS/Tile Service

The TMS service expects a layers entry in the authorization dictionary for partial results. layers itself should be a dictionary with all layers. All missing layers are interpreted as denied layers.

Each layer contains the information about the permitted features. The TMS service only supports the tile feature. A missing feature is interpreted as a denied feature.

Here is an example result of a call to the authorize function:

{
  'authorized': 'partial',
  'layers': {
    'layer1': {'tile': True},
    'layer2': {'tile': False},
  }
}

The TMS service uses tms as the service string for all authorization requests.

Only layers with the tile feature set to True are included in the TMS capabilities document (/tms/1.0.0). Missing layers are not included.

KML Service

The KML authorization is similar to the TMS authorization.

The KML service uses kml as the service string for all authorization requests.

Demo Service

The demo service only supports full or none authorization. layers is always an empty list. The demo service does not authorize the services and layers that are listed in the overview page. If you permit a user to access the demo service, then he can see all services and layers names. However, access to these services is still restricted to the according authorization.

The service string is demo.

MultiMapProxy

The :ref:`MultiMapProxy <multimapproxy>` application stores the instance name in the environment as mapproxy.instance_name. This information in not available when your middleware gets called, but you can use it in your authorization function.

Example that rejects MapProxy instances where the name starts with secure.

class MultiMapProxyAuthFilter(object):
    def __init__(self, app, global_conf):
        self.app = app

    def __call__(self, environ, start_reponse):
        environ['mapproxy.authorize'] = self.authorize
        return self.app(environ, start_reponse)

    def authorize(self, service, layers=[]):
        instance_name = environ.get('mapproxy.instance_name', '')
        if instance_name.startswith('secure'):
            return {'authorized': 'none'}
        else:
            return {'authorized': 'full'}
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.