nginx-google-oauth

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #llm #go #rust #deep-learning #linux #java #windows #cli #awesome-list #security

nginx-google-oauth

(★ 141)

Lua module to add Google OAuth to nginx

File Explorer

Download Latest Version (.zip)

- source-lua.rb
- oauth.conf
- README.md
- setup.sh
access.lua
body_filter.lua
CHANGELOG
LICENSE
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

nginx-google-oauth
==================

Lua module to add Google OAuth to nginx.

## Installation

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 ``json`` and ``luasec`` modules as well.

### Ubuntu

You will need to install the following packages.

```
lua5.1
liblua5.1-0
liblua5.1-0-dev
liblua5.1-sec-dev
liblua5.1-json
```

You will also need to download and build the following and link them
with nginx

```
ngx_devel_kit
lua-nginx-module
```

See ``/chef/source-lua.rb`` for a Chef recipe to install nginx and Lua
with all of the requirements.

## Configuration

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.g ``supersecret.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

## Configuring OAuth Access

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.

## Body filter

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:

```html
<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:

```css
<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 { color: white; }
  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.

## Username variable

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_user "unknown@unknown.com";

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.

## Development

See `test/README.md`.

Bug reports and pull requests are [welcome](https://github.com/agoragames/nginx-google-oauth).

It can be useful to turn off [lua_code_cache](http://wiki.nginx.org/HttpLuaModule#lua_code_cache)
while you're iterating.

## Roadmap

- 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
- 401 page that allows signing out and back in with a different account
- whitelist and blacklist is checked on every request

## Copyright

## License

MIT

## Thanks

This project wouldn't have gone beyond the idea stage without the excellent
example provided by [SeatGeek](http://chairnerd.seatgeek.com/oauth-support-for-nginx-with-lua/).

Thank you to @eschwim for some much-needed usability and security [fixes](https://github.com/agoragames/nginx-google-oauth/pull/4).

nginx-google-oauth

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

nginx-google-oauth

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README