Lua module to add Google OAuth to nginx.
You can copy access.lua
to your nginx configurations, or clone the
repository. Your installation of nginx must already be built with Lua
support, and you will need the cjson
and luasec
modules as well.
You will need to install the following packages.
lua5.1
liblua5.1-0
liblua5.1-0-dev
liblua5.1-sec-dev
You will also need to download and build the following and link them with nginx
ngx_devel_kit
lua-nginx-module
lua-cjson-2.1.0
See /chef/source-lua.rb
for a Chef recipe to install nginx and Lua
with all of the requirements.
Add the access controls in your configuration. Because oauth tickets will be included in cookies (and you are presumably protecting something very important), it is strongly recommended that you use SSL.
server {
server_name supersecret.net;
listen 443;
ssl on;
ssl_certificate /etc/nginx/certs/supersecret.net.pem;
ssl_certificate_key /etc/nginx/certs/supersecret.net.key;
set $ngo_client_id "abc-def.apps.googleusercontent.com";
set $ngo_client_secret "abcdefg-123-xyz";
set $ngo_token_secret "a very long randomish string";
set $ngo_secure_cookies "true";
access_by_lua_file "/etc/nginx/nginx-google-oauth/access.lua";
}
The access controls can be configured using nginx variables. The supported variables are:
- $ngo_client_id This is the client id key
- $ngo_client_secret This is the client secret
- $ngo_token_secret The key used to encrypt the session token stored in the user cookie. Should be long & unguessable.
- $ngo_domain The domain to use for validating users when not using white- or blacklists
- $ngo_whitelist Optional list of authorized email addresses
- $ngo_blacklist Optional list of unauthorized email addresses
- $ngo_callback_scheme The scheme for the callback URL, defaults to that of the request (e.g.
https
) - $ngo_callback_host The host for the callback, defaults to first entry in the
server_name
list (e.gsupersecret.net
) - $ngo_callback_uri The URI for the callback, defaults to "/_oauth"
- $ngo_debug If defined, will enable debug logging through nginx error logger
- $ngo_secure_cookies If defined, will ensure that cookies can only be transfered over a secure connection
- $ngo_css An optional stylesheet to replace the default stylesheet when using the body_filter
- $ngo_user If set, will be populated with the OAuth username returned from Google (portion left of '@' in email)
- $ngo_email_as_user If set and $ngo_user is defined, username returned will be full email address
Visit https://console.developers.google.com. If you're signed in to multiple
Google accounts, be sure to switch to the one which you want to host the OAuth
credentials (usually your company's Apps domain). This should match
$ngo_domain
(e.g. "yourcompany.com").
From the dashboard, create a new project. After selecting that project, you should see an "APIs & Auth" section in the left-hand navigation. Within that section, select "Credentials". This will present a page in which you can generate a Client ID and configure access. Choose "Web application" for the application type, and enter all origins and redirect URIs you plan to use.
In the "Authorized Javascript Origins" field, enter all the protocols and
domains from which you plan to perform authorization
(e.g. https://supersecret.net
), separated by a newline.
In the "Authorized Redirect URI", enter all of the URLs which the Lua module
will send to Google to redirect after the OAuth workflow has been completed.
By default, this will be the protocol, server_name and /_oauth
(e.g.
https://supersecret.net/_oauth
. You can override these defaults using the
$ngo_callback_*
settings.
After completing the form you will be presented with the Client ID and
Client Secret which you can use to configure $ngo_client_id
and
$ngo_client_secret
respectively.
If you need to further limit access within your organization, you can use
$ngo_whitelist
and/or $ngo_blacklist
. Both should be formatted as
a space-separated list of allowed (whitelist) or rejected (blacklist) email
addresses. If either of these values are defined, the $ngo_domain
will
not be used for validating that the user is authorized to access the protected
resource.
If you want visual confirmation of successful authentication, you can use the
body_filter.lua
script to inject a header into your web application. Your
nginx configuration should look something like this:
server {
server_name supersecret.net;
listen 443;
set $ngo_client_id 'abc-def.apps.googleusercontent.com';
set $ngo_client_secret 'abcdefg-123-xyz';
set $ngo_token_secret 'a very long randomish string';
access_by_lua_file "/etc/nginx/nginx-google-oauth/access.lua";
location / {
header_filter_by_lua "ngx.header.content_length = nil";
body_filter_by_lua_file "/etc/nginx/nginx-google-oauth/body_filter.lua";
proxy_set_header Accept-Encoding "";
proxy_pass http://supersecret-backend;
}
}
The header_filter_by_lua
directive is required so that the
content_length
header returned by the backend is stripped and re-calculated
after the body filter has been applied.
The Accept-Encoding
directive is recommended in cases where the backend
may be returning a gzipped document, in which case nginx will not decompress
the document before sending it to the body filter.
The body_filter_by_lua_file
directive causes all responses from the backend
to be routed through a lua script that will inject a div just after the opening
<body>
element. The div will take the form of:
<div class="ngo_auth">
<img src="google-oauth-profile-pic" />
<span class="ngo_user">google-oauth-user-name</span>
<span class="ngo_email">google-oauth-email</span>
<a href="signout_uri">Signout</a>
</div>
If $ngo_css
is defined, the default stylesheet will be overridden,
otherwise the stylesheet will be:
<style>
div.ngo_auth { width: 100%; background-color: #6199DF; color: white; padding: 0.5em 0em 0. 5em 2em; vertical-align: middle; margin: 0; }
div.ngo_auth > img { width: auto; height: 2em; margin: 0 1em 0 0; padding: 0; }
div.ngo_auth > span.ngo_user { font-weight: bold; margin-right: 1em; }
div.ngo_auth > a { color: white; margin-left: 3em; }
</style>
The filter operates by performing a regular expression match on <body>
,
and so should act as a no-op for non-HTML content types. It may be necessary
to use the body filter only on a subset of routes depending on your application.
If you wish to pass the username returned from Google to an external FastCGI/UWSGI script, consider using the $ngo_user
variable:
server {
server_name supersecret.net;
listen 443;
ssl on;
ssl_certificate /etc/nginx/certs/supersecret.net.pem;
ssl_certificate_key /etc/nginx/certs/supersecret.net.key;
set $ngo_client_id "abc-def.apps.googleusercontent.com";
set $ngo_client_secret "abcdefg-123-xyz";
set $ngo_token_secret "a very long randomish string";
set $ngo_secure_cookies "true";
access_by_lua_file "/etc/nginx/nginx-google-oauth/access.lua";
set $ngo_user "[email protected]";
include uwsgi_params;
uwsgi_param REMOTE_USER $ngo_user;
uwsgi_param AUTH_TYPE Basic;
uwsgi_pass 127.0.0.1:3031;
}
If you wish the full email address returned from Google to be set as the username, set the $ngo_email_as_user
variable to any non-empty value.
Bug reports and pull requests are welcome.
It can be useful to turn off lua_code_cache while you're iterating.
- Add support for non-blocking sockets in obtaining an auth token
- Support auth token refresh and timeouts
- Continue support for Ubuntu but make imports work on other platforms as well
- Replace cjson requirement with "standard" Lua json
- 401 page that allows signing out and back in with a different account
- whitelist and blacklist is checked on every request
Copyright 2014 Aaron Westendorf
MIT
This project wouldn't have gone beyond the idea stage without the excellent example provided by SeatGeek.