Need help with nginx-google-oauth?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

416 Stars 101 Forks MIT License 51 Commits 15 Opened issues


Lua module to add Google OAuth to nginx

Services available


Need anything else?

Contributors list


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.


This project is no longer being maintained or supported by Cloudflare. Please refer to Cloudflare Access as an alternative to nginx-google-oauth.


You can copy

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:

  • $ngocallbackhost The host for the callback, defaults to first entry in the
    list (e.g
  • $ngocallbackscheme The scheme for the callback URL, defaults to that of the request (e.g.
  • $ngocallbackuri The URI for the callback, defaults to
  • $ngosignouturi The URI for sign-out endpoint.
  • $ngoclientid This is the client id key.
  • $ngoclientsecret This is the client secret.
  • $ngotokensecret The key used to encrypt the session token stored in the user cookie. Should be long & unguessable.
  • $ngosecurecookies If defined, will ensure that cookies can only be transferred over a secure connection.
  • $ngohttponly_cookies If defined, will ensure that cookies cannot be accessed via javascript.
  • $ngoextravalidity 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).
  • $ngoemailas_user If set and
    is defined, username returned will be full email address.

Available endpoints


Default sign-out URI, can be changed with

variable. It clears cookies and does redirect to the
location of your domain.


Endpoint that reports your OAuth token in a JSON object:

  "email": "[email protected]",
  "token": "",
  "expires": 1445455680


Endpoint that reports your OAuth token in text format:

email: [email protected]
expires: 1445455680


Endpoint that reports your OAuth token as

arguments for header auth:
-H "OauthEmail: [email protected]" -H "OauthAccessToken:" -H "OauthExpires: 1445455680"

You can add it to your

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

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

seconds. An good example would be some site you use at work. Setting
(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


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


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

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:

. 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

, 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:

    is the value of
    is the value of
    is the value of
    is the value of
    is the value of
    , required.
    is the value of
    , required.
    is the value of
    , required.
    is the value of
    is the value of
    is the value of
    is the value of
    is the value of
    is the value of
    is the value of
    is the value of
  • PORT
    is the port for nginx to listen on, defaults to
    : if set, prints the generated nginx configuation on container start
    can contain
    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-2020 Cloudflare
  • Copyright 2014-2015 Aaron Westendorf



We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.