The sproxy2 package

[Tags:mit, program]

Sproxy is secure by default. No requests makes it to the backend server if they haven't been explicitly whitelisted. Sproxy is independent. Any web application written in any language can use it.

[Skip to Readme]


Versions 1.90.0, 1.90.1, 1.90.2, 1.91.0, 1.92.0, 1.93.0, 1.94.0, 1.94.1
Change log
Dependencies aeson, base (>=4.8 && <50), base64-bytestring, blaze-builder, bytestring, cereal, conduit, containers, cookie (>=0.4.2), docopt, entropy, Glob, http-client (>=0.5.3), http-conduit, http-types, interpolatedstring-perl6, network, postgresql-simple, resource-pool, SHA, sqlite-simple, text, time, unix, unordered-containers, wai, wai-conduit, warp, warp-tls (>=3.2), word8, yaml (>=0.8.4) [details]
License MIT
Copyright 2016, Zalora South East Asia Pte. Ltd
Author Igor Pashev <>
Maintainer Igor Pashev <>
Stability Unknown
Category Databases, Web
Source repository head: git clone
Uploaded Tue Feb 7 13:38:31 UTC 2017 by ip1981
Distributions NixOS:1.94.1
Downloads 188 total (38 in the last 30 days)
0 []
Status Docs not available [build log]
Last success reported on 2017-02-07 [all 3 reports]


Maintainer's Corner

For package maintainers and hackage trustees

Readme for sproxy2

Readme for sproxy2-1.94.1


HTTP proxy for authenticating users via OAuth2.


This is overhaul of original Sproxy. See for the differences.

Why use a proxy for doing OAuth2? Isn't that up to the application?

  • sproxy is secure by default. No requests make it to the web server if they haven't been explicitly whitelisted.
  • sproxy is independent. Any web application written in any language can use it.

Use cases

  • Existing web applications with concept of roles. For example, Mediawiki, Jenkins, Icinga Web 2. In this case you configure Sproxy to allow unrestricted access to the application for some groups defined by Sproxy. These groups are mapped to the application roles. There is a plugin for Jenkins which can be used for this. Mediawiki and Icinga Web 2 were also successfully deployed in this way, though it required changes to their source code.

  • New web applications designed to work specifically behind Sproxy. In this case you define Sproxy rules to control access to the application's API. It would likely be a single-page application. Examples are MyWatch and Juan de la Cosa.

  • Replace HTTP Basic authentication.

How it works

When an HTTP client makes a request, Sproxy checks for a session cookie. If it doesn't exist (or it's invalid, expired), it responses with HTTP status 511 with the page, where the user can choose an OAuth2 provider to authenticate with. Finally, we store the the email address in a session cookie: signed with a hash to prevent tampering, set for HTTP only (to prevent malicious JavaScript from reading it), and set it for secure (since we don't want it traveling over plaintext HTTP connections).

From that point on, when sproxy detects a valid session cookie it extracts the email, checks it against the access rules, and relays the request to the back-end server (if allowed).

Permissions system

Permissions are stored in internal SQLite3 database and imported from data sources, which can be a PostgreSQL database or a file. See sproxy.sql and datafile.example.yml for details.

Do note that Sproxy2 fetches only group_member, group_privilege and privilege_rule tables, because only these tables are used for authorization. The other tables in PostgreSQL schema serve for data integrity. Data integrity of the data file is not verfied, though import may fail due to primary key restrictions.

Only one data source can be used. The data in internal database, if any, is fully overwritten by the data from a data source. If no data source is specified, the data in internal database remains unchanged, even between restarts. Broken data source is not fatal. Sproxy will keep using existing internal database, or create a new empty one if missed. Broken data source means inability to connect to PostgreSQL database, missed datafile, etc.

The data from a PostgreSQL database are periodically fetched into the internal database, while the data file is read once at startup.

Here are the main concepts:

  • A group is identified by a name. Every group has
    • members (identified by email address, through group_member) and
    • associated privileges (through group_privilege).
  • A privilege is identified by a name and a domain. It has associated rules (through privilege_rule) that define what the privilege gives access to.
  • A rule is a combination of sql patterns for a domain, a path and an HTTP method. A rule matches an HTTP request, if all of these components match the respective attributes of the request. However of all the matching rules only the rule with the longest path pattern will be used to determine whether a user is allowed to perform a request. This is often a bit surprising, please see the following example:

Privileges example

Consider this group_privilege and privilege_rule relations:

group | privilege | domain ---------------- | --------- | ----------------- readers | basic | readers | read | editors | basic | editors | read | editors | edit | administrators | basic | administrators | read | administrators | edit | administrators | admin |

privilege | domain | path | method ----------- | ------------------ | -------------- | ------ basic | | /% | GET read | | /wiki/% | GET edit | | /wiki/edit/% | GET edit | | /wiki/edit/% | POST admin | | /admin/% | GET admin | | /admin/% | POST admin | | /admin/% | DELETE

With this setup, everybody (that is readers, editors and administratorss) will have access to e.g. /imgs/logo.png and /favicon.ico, but only administrators will have access to /admin/index.php, because the longest matching path pattern is /admin/% and only administrators have the admin privilege.

Likewise readers have no access to e.g. /wiki/edit/delete_everything.php.

Keep in mind that:

  • Domains are converted into lower case (coming from a data source or HTTP requests).
  • Emails are converted into lower case (coming from a data source or OAuth2 providers).
  • Groups are case-sensitive and treated as is.
  • HTTP methods are case-sensitive.
  • HTTP query parameters are ignored when matching a request against the rules.
  • Privileges are case-sensitive and treated as is.
  • SQL wildcards (_ and %) are supported for emails, paths (this will change in future versions).

HTTP headers passed to the back-end server

All Sproxy headers are UTF8-encoded.

header | value -------------------- | ----- From: | visitor's email address, lower case X-Groups: | all groups that granted access to this resource, separated by commas (see the note below) X-Given-Name: | the visitor's given (first) name X-Family-Name: | the visitor's family (last) name X-Forwarded-Proto: | the visitor's protocol of an HTTP request, always https X-Forwarded-For | the visitor's IP address (added to the end of the list if header is already present in client request)

X-Groups denotes an intersection of the groups the visitor belongs to and the groups that granted access:

Visitor's groups | Granted groups | X-Groups ---------------- | -------------- | --------- all | all, devops | all all, devops | all | all all, devops | all, devops | all,devops all, devops | devops | devops devops | all, devops | devops devops | all | Access denied


Hitting the endpoint /.sproxy/logout will invalidate the session cookie. The user will be redirected to / after logout.


Since all sproxied resources are private, it doesn't make sense for web crawlers to try to index them. In fact, crawlers will index only the login page. To prevent this, sproxy returns the following for /robots.txt:

User-agent: *
Disallow: /


Sproxy2 is written in Haskell with GHC. All required Haskell libraries are listed in sproxy2.cabal. Use cabal-install to fetch and build all pre-requisites automatically.


By default sproxy2 will read its configuration from sproxy.yml. There is example file with documentation sproxy.example.yml. You can specify a custom path with:

sproxy2 --config /path/to/sproxy.yml