Simple oauth2 subrequest handler for reverse proxy configurations
The goal of
oauthsub is to enable simple and secure Single Sign On by
deferring authentication to an
oauth2 provider (like google, github,
oauthsub does not provide facilities for access control. The program is
very simple and if you wanted to implement authentication and access control,
feel free to use it as a starting point. It was created, however, to provide
authentication for existing services that already do their own access control.
oauthsub implements client authentication subrequest handling for reverse
proxies, and provides
oauth2 redirect endpoints for doing the whole
oauth2 dance. It can provide authentication services for:
- NGINX (via http_auth_request)
- Apache (via mod_perl and Authen::Simple::HTTP, backup link)
- HA-Proxy (via a lua extension, backup link)
The design is basically this:
- For each request, the reverse proxy makes a subrequest to
oauthsubwith the original requested URI
oauthsubuses a session cookie to keep track of authenticated users. If the user’s session has a valid authentication token, it returns HTTP status 200. Otherwise it returns HTTP status 401.
- If the user is not authenticated, the reverse proxy redirects them to the
oauthsublogin page, where they can start the dance with an
oauth2provider. You can choose to enable multiple providers if you’d like.
oauth2provider bounces the user back to the
oauthsubcallback page where the authentication dance is completed and the users credentials are stored.
oauthsubsets a session cookie and redirects the user back to the original URL they were trying to access.
- This time when they access the URL the subrequest handler will return status 200.
Oauthsub will also pass the authenticated username back to the reverse-proxy through a response header. This can be forwarded to the proxied service as a Remote User Token for access control.
oauthsub is a flask application with the following routes:
/auth/login: start of oauth dance
/auth/callback: oauth redirect handler
/auth/logout: clears user session
/auth/query_auth: subrequest handler
/auth/forbidden: optional redirect target for 401’s
/auth/ route prefix can be changed via configuration.
oauthsub uses the flask session interface. You can configure the session
backend however you like (see configuration options). If you share the session
oauthsub and another flask application behind the same nginx
instance then you can access the
oauthsub session variables directly
oauth token object).