cloudflare/nginx-google-oauth
Lua module to add Google OAuth to nginx.
500K+
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 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 {
server_name supersecret.net;
listen 443 ssl;
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";
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:
server_name
list (e.g supersecret.net
).https
)./_oauth
.$ngo_user
is defined, username
returned will be full email address./_signout
Default sign-out URI, can be changed with $ngo_signout_uri
variable. It clears
cookies and does redirect to the /
location of your domain.
/_token.json
Endpoint that reports your OAuth token in a JSON object:
{
"email": "foo@example.com",
"token": "abc..xyz",
"expires": 1445455680
}
/_token.txt
Endpoint that reports your OAuth token in text format:
email: foo@example.com
token: abc..xyz
expires: 1445455680
/_token.curl
Endpoint that reports your OAuth token as curl
arguments for header auth:
-H "OauthEmail: foo@example.com" -H "OauthAccessToken: abc..xyz" -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 https://example.com/rates.json > ~/currency-rates.json
Now if you enabled OAuth on example.com
, this command would not work anymore,
resulting in 301 redirect to OAuth from Google. To make it work, you'll have
to go to https://example.com/_token.curl
, copy header arguments for curl
and paste them into your command:
curl -s $HEADER_ARGS https://example.com/rates.json > ~/currency-rates.json
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.
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, 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. https://example.com/_oauth
).
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.
$ngo_user
can be used in any place where you could use variable in nginx,
this includes:
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;
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 ngo.lol
here. Make sure to add
http://ngo.lol/_oauth
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 startLOCATIONS
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_CALLBACK_SCHEME=http \
-e NGO_CLIENT_ID="client id from google" \
-e NGO_CLIENT_SECRET="client secret from google" \
-e NGO_TOKEN_SECRET="random token secret" \
cloudflare/nginx-google-oauth:1.1.1
Then open your browser at http://ngo.lol and you should get Google OAuth screen.
MIT
docker pull cloudflare/nginx-google-oauth