Secure HTTP proxy for authenticating users via OAuth2
|Latest on Hackage:||1.94.1|
This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow stackage.org to host generated Haddocks.
HTTP proxy for authenticating users via OAuth2.
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.
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
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).
Do note that Sproxy2 fetches only
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:
groupis identified by a name. Every group has - members (identified by email address, through
group_member) and - associated privileges (through
privilegeis identified by a name and a domain. It has associated rules (through
privilege_rule) that define what the privilege gives access to.
ruleis a combination of sql patterns for a
pathand 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
pathpattern 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:
group | privilege | domain
---------------- | --------- | -----------------
privilege | domain | path | method
----------- | ------------------ | -------------- | ------
With this setup, everybody (that is
will have access to e.g.
/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
readers have no access to e.g.
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 (
%) 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
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 |
---------------- | -------------- | ---------
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
User-agent: * Disallow: /
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
For differences with the original Sproxy scroll down.
Fixed a typo introduced in version 1.94.0 in SQL query:
... WHERE domain = domain ...->
... WHERE domain = :domain ...
BREAKING: Disregard possible port in the Host HTTP header. Previously, Sproxy took possible port number into account when looking for backend and privileges. Now it ignores port and considers domain name only. This also gets Sproxy in line with browsers and SSL certificates: certificates do not include port numbers, browsers ignore ports when sending cookies.
BREAKING: no SQL wildcards (
_) in domain names when looking up for privileges. This feature was ambiguous (in the same way as paths are) and never used anyway.
!includein config file. This changes semantics of options
oauth2.<provider>.client_secret. They are no longer files, but strings. To read content from files, use !include. The point of being files or read from files is to segregate secrets from non-sensitive easily discoverable settings. With
!includeit is much more simple and flexible.
Allow running in plain HTTP mode (no SSL). Useful when Sproxy is behind some other proxy or load-balancer. Added two more options:
ssl(defaults to true) and
https_port(defaults to like
ssl_certare required only if
ssl == true. SSL-terminations is still required at upstream proxies, because the cookie is set for HTTPS only.
Added "user" table into
sproxy.sql. No action is required, but PostgreSQL database built after this file will be incompatible with Sproxy Web ( <= 0.4.1 at least).
In addition to good old PostgreSQL data source, made it possible to import permission data from a YAML file. This means that Sproxy2 can work without any PostgreSQL database, just using file-only configuration. Useful for development or trivial deployments. Added new
datafileoption in configuration file.
Make sure all Sproxy-specific HTTP headers are UTF8-encoded.
/.sproxy/logoutjust redirects if no cookie. Previously it was returning HTTP 404 to unauthenticated users, and redirecting authenticated users with removal of the cookie. The point is not to reveal cookie name.
Made Warp stop printing exceptions, mostly "client closed connection", which happens outside of our traps.
Fixed headers processing. Wrong headers were making Chromium drop connection in HTTP/2. Firefox sometimes couldn't handle gzipped and chunked responses in HTTP/1.1.
After authenticating, redirect to original path with query parameters if method was GET. Otherwise redirect to "/". Previously, when unauthenticated users click on "https://example.net/foo?bar", they are redirected to "https://example.net/foo" regardless of the method.
1.90.0 (Preview Release)
Sproxy2 can work with remote PostgreSQL database. Quick access to the database is essential as sproxy does it on every HTTP request. Sproxy2 pulls data into local SQLite3 database.
At this release Sproxy2 is compatible with Sproxy database with one exception: SQL wildcards are not supported for HTTP methods. I. e. you have to change '%' in the database to specific methods like GET, POST, etc.
OAuth2 callback URLs changed: Sproxy2 uses
/.sproxy/oauth2/:provider, e. g.
/.sproxy/oauth2/google. Sproxy used
/sproxy/oauth2callbackfor Google and
Sproxy2 does not allow login with email addresses not known to it.
Sproxy2: OAuth2 callback state is serialized, signed and passed base64-encoded. Of course it's used to verify the request is legit.
Sproxy2: session cookie is serialized, signed and sent base64-encoded.
/.sproxybelongs to Sproxy2 completely. Anything under this path is never passed to backends.
Sproxy2 supports multiple backends. Routing is based on the Host HTTP header.
Sproxy2 uses HTTP Client to talk to backends. As a result Sproxy2 reuses backend connections instead of closing them after each request to the backend.
Sproxy2 optionally supports persistent key again (removed in Sproxy 0.9.2). This can be used in load-balancing multiple Sproxy2 instances.
Configuration file has changed. It's still YAML, but some options are renamed, removed or added. Have a look at well-documented sproxy.yml.example