Public | Automated Build

Last pushed: 4 days ago
Short Description
Lua module to add Google OAuth to nginx.
Full Description


Lua module to add Google OAuth to nginx. It is based on great work
from Agora Games.

Fast forward to the docker image section to try it out.


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 following modules:


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 {

  listen 443 ssl;

  ssl_certificate     /etc/nginx/certs/;
  ssl_certificate_key /etc/nginx/certs/;

  set $ngo_client_id         "";
  set $ngo_client_secret     "abcdefg-123-xyz";
  set $ngo_token_secret      "a very long randomish string";
  set $ngo_secure_cookies    "true";
  set $ngo_http_only_cookies "true";

  access_by_lua_file "/etc/nginx/lua/nginx-google-oauth/access.lua";

The access controls can be configured using nginx variables. The supported
variables are:

  • $ngo_callback_host The host for the callback, defaults to first entry
    in the server_name list (e.g
  • $ngo_callback_scheme The scheme for the callback URL,
    defaults to that of the request (e.g. https).
  • $ngo_callback_uri The URI for the callback, defaults to /_oauth.
  • $ngo_signout_uri The URI for sign-out endpoint.
  • $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_secure_cookies If defined, will ensure that cookies can only
    be transferred over a secure connection.
  • $ngo_http_only_cookies If defined, will ensure that cookies cannot
    be accessed via javascript.
  • $ngo_extra_validity Time in seconds to add to token validity period.
  • $ngo_domain The space separated list of domains to use for validating
    users when not using white- or blacklists.
  • $ngo_whitelist Optional space separated list of authorized email addresses.
  • $ngo_blacklist Optional space separated list of unauthorized email addresses.
  • $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.

Available endpoints


Default sign-out URI, can be changed with $ngo_signout_uri variable. It clears
cookies and does redirect to the / location of your domain.


Endpoint that reports your OAuth token in a JSON object:

  "email": "",
  "token": "",
  "expires": 1445455680


Endpoint that reports your OAuth token in text format:

expires: 1445455680


Endpoint that reports your OAuth token as curl arguments for header auth:

-H "OauthEmail:" -H "OauthAccessToken:" -H "OauthExpires: 1445455680"

You can add it to your curl command to make it work with OAuth.


Any request to nginx can be authenticated in two ways: with headers and with
cookies. When you open your site in a web browser, it sends you to Google
to obtain OAuth token and these are set as cookies. Users don't have to do
anything special, it just works seamlessly.

If you are willing to protect a domain that is used by automatic CLI tools,
it is problematic to use cookies from your browser. Instead, you can can use
any of endpoints described in the previous section to obtain tokens and pass
them to your tools.

An example would be a curl command that you might use to refresh local
currency rates:

curl -s > ~/currency-rates.json

Now if you enabled OAuth on, this command would not work anymore,
resulting in 301 redirect to OAuth from Google. To make it work, you'll have
to go to, copy header arguments for curl
and paste them into your command:

curl -s $HEADER_ARGS > ~/currency-rates.json

Extended token validity

OAuth token from Google are short-lived, but this is not always convenient if
you want to put something frequently used behind OAuth. In this case, you can
extend token validity by $ngo_extra_validity seconds. An good example would
be some site you use at work. Setting $ngo_extra_validity to 43200 (12h)
means that you only have to authorize on it once a day with a standard 8 hour
or less work day.

Token validity can be shortened with negative values as well.

Configuring OAuth access

Visit 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.

From the dashboard, create a new project. After selecting that project, search
for "Credentials" in the search box. Make sure to fill "OAuth consent screen"
section first. Then create "OAuth client ID": select "Web application", fill
the name of your app, skip "Authorized JavaScript origins" and fill
"Authorized redirect URIs" (e.g.

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.

Since you can have unlimited OAuth client IDs in one app, but number of apps
is limited, it makes sense to reuse the same app.

Username variable

$ngo_user can be used in any place where you could use variable in nginx,
this includes:

  • Logging
  • Passing params to external FastCGI/UWSGI scripts
  • Headers for upstream servers
  • Lua scripts
  • etc.


For blacklist the site, not even reaching oauth, use this nginx example:

    access_by_lua_file "/etc/nginx/lua/nginx-google-oauth/access.lua";
    deny your_blacklist_ip;
    satisfy all

For whitelist (ie: disable oauth for this ip) use this:

    access_by_lua_file "/etc/nginx/lua/nginx-google-oauth/access.lua";
    allow your_whitelist_ip;
    satisfy any;

Notice the satisfy any. You can also add several allow entries.

For allowing only one ip, block all others, and still oauth it, use this:

    access_by_lua_file "/etc/nginx/lua/nginx-google-oauth/access.lua";
    allow your_whitelist_ip;
    deny all;
    satisfy all;

Docker image

You have to obtain tokens first.

There is a pre-built image: cloudflare/nginx-google-oauth. If you are
hacking on this project, you might want to rebuild the image yourself.

To make it work locally, add a record to DNS or to /etc/hosts, pointing
to the ip of your docker daemon, we use here. Make sure to add as an "Authorized redirect URIs" in Google console.

Docker image has the following env variables for configuration:

  • NGO_CALLBACK_HOST is the value of $ngo_callback_host.
  • NGO_CALLBACK_SCHEME is the value of $ngo_callback_scheme.
  • NGO_CALLBACK_URI is the value of $ngo_callback_uri.
  • NGO_SIGNOUT_URI is the value of $ngo_signout_uri.
  • NGO_CLIENT_ID is the value of $ngo_client_id, required.
  • NGO_CLIENT_SECRET is the value of $ngo_client_secret, required.
  • NGO_TOKEN_SECRET is the value of $ngo_token_secret, required.
  • NGO_SECURE_COOKIES is the value of $ngo_secure_cookies.
  • NGO_HTTP_ONLY_COOKIES is the value of $ngo_http_only_cookies.
  • NGO_EXTRA_VALIDITY is the value of $ngo_extra_validity.
  • NGO_DOMAIN is the value of $ngo_domain.
  • NGO_WHITELIST is the value of $ngo_whitelist.
  • NGO_BLACKLIST is the value of $ngo_blacklist.
  • NGO_USER is the value of $ngo_user.
  • NGO_EMAIL_AS_USER is the value of $ngo_email_as_user.
  • PORT is the port for nginx to listen on, defaults to 80.
  • DEBUG: if set, prints the generated nginx configuation on container start
  • LOCATIONS can contain location directives that will be injected into the
    nginx configuration on container start. If not set, a demo page is served
    under location / {...}.

Run the image:

docker run --rm -it --net host \
  -e DEBUG=1 \
  -e NGO_CLIENT_ID="client id from google" \
  -e NGO_CLIENT_SECRET="client secret from google" \
  -e NGO_TOKEN_SECRET="random token secret" \

Then open your browser at and you should get Google OAuth screen.


  • Copyright 2015-2016 CloudFlare
  • Copyright 2014-2015 Aaron Westendorf



Docker Pull Command
Source Repository