Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

NginxOmniauthAdapter - Use omniauth for nginx auth_request


Use omniauth for your nginx's authentication via ngx_http_auth_request_module.

NginxOmniauthAdapter provides small Rack app (built with Sinatra) for auth_request.


  • nginx with ngx_http_auth_request_module

Quick example

$ bundle install

$ cd example/
$ foreman start

(make sure to have nginx on your PATH)



  1. Start adapter app with proper configuration
  2. enable auth_request and add some endpoints on nginx
  • See example/nginx-site.conf for nginx configuration.

Running with Rubygems

# Gemfile
gem 'nginx_omniauth_adapter'

Then write then deploy it. (see ./ for example)

Using docker

  • Prebuilt:
    • Own your risk.
    • They're built at circleci
  • Build manually: checkout this repo and run docker build ..
    • Much safer.
    • But if you can't trust upstream image, write your own Dockerfile. This is just a simple Rack app.


environment variable is available only on included (or Docker image).

  • :providers: omniauth provider names.
  • :provider_http_header $NGX_OMNIAUTH_PROVIDER_HTTP_HEADER (string): Name of HTTP header to specify OmniAuth provider to be used (see below). Defaults to 'x-ngx-omniauth-provider`.
  • :secret $NGX_OMNIAUTH_SESSION_SECRET: Rack session secret. Should be set when not on dev mode
  • :host $NGX_OMNIAUTH_HOST: URL of adapter. This is used for redirection. Should include protocol (e.g.
    • If this is not specified, adapter will perform redirect using given Host header.
  • :allowed_app_callback_url $NGX_OMNIAUTH_ALLOWED_APP_CALLBACK_URL (regexp): If specified, URL only matches to this are allowed for app callback url.
  • :allowed_back_to_url $NGX_OMNIAUTH_ALLOWED_BACK_TO_URL (regexp): If specified, URL only matches to this are allowed for back_to url.
  • :app_refresh_interval NGX_OMNIAUTH_APP_REFRESH_INTERVAL (integer): Interval to require refresh session cookie on app domain (in second, default 1 day).
  • :adapter_refresh_interval NGX_OMNIAUTH_ADAPTER_REFRESH_INTERVAL (integer): Interval to require re-logging in on adapter domain (in second, default 3 days).

Working with multiple OmniAuth providers

When multiple providers are passed to :providers, nginx_omniauth_adapter defaults to the first one in list. Other providers in list will only be activated for requests with x-ngx-omniauth-provider header (key is configurable via :provider_http_header).

Included (or Docker)

You can set configuration via environment variables.

The following variables are only available on included

  • $NGX_OMNIAUTH_SESSION_COOKIE_NAME: session cookie name (default ngx_omniauth)
  • $NGX_OMNIAUTH_SESSION_COOKIE_TIMEOUT: session cookie expiry (default 3 days)
  • $NGX_OMNIAUTH_DEV=1 or $RACK_ENV=development
    • enable dev mode (omniauth developer provider)
  • github provider
    • $NGX_OMNIAUTH_GITHUB_KEY, $NGX_OMNIAUTH_GITHUB_SECRET: application key + secret.
    • $NGX_OMNIAUTH_GITHUB_HOST: (optional) Set if you'd like to use GitHub Enterprise instance (e.g. https://YOUR-GITHUB-ENTERPRISE)
    • $NGX_OMNIAUTH_GITHUB_TEAMS: (optional) Restrict to specified teams (e.g. awesomeorganization/owners)
  • google_oauth2 provider
    • $NGX_OMNIAUTH_GOOGLE_HD: (optional) Restrict to specified hosted domain (Google Apps Domain).

Manually (Rack)

If you're going to write from scratch, make sure:

  • OmniAuth is included in middleware stack
  • Rack session is enabled in middleware stack

Then run:

  providers: %i(developer),
  secret: secret_base64, # optional
  # ... (set more configuration, see above variable list)

How it works

  1. browser access to restricted area (where auth_request has enabled)
  2. nginx sends subrequest to /_auth/challenge. It will be proxied to adapter app (GET /test)
  3. adapter app /test returns 401 when request (browser) doesn't have valid cookie
  4. nginx handles 401 with error_page, so do internal redirection (/_auth/initiate)
  5. nginx handles /_auth/initiate. It will be proxied to adapter app GET /initiate.
  • Also nginx passes some information for callback to adapter app.
  • x-ngx-omniauth-initiate-back-to URL to back after logged in
  • x-ngx-omniauth-initiate-callback URL that proxies to adapter app /callback. This must be same domain to backend app for cookie.
  1. adapter app GET /initiate redirects to /auth/:provider.
  2. Browser do some authenticate in adapter app with Omniauth.
  3. adapter app's omniauth callback sets valid session, then redirects to /_auth/callback, where specified at x-ngx-omniauth-initiate-callback.
  • Adapter app gives GET parameter named session on redirect. It contains encrypted session.
  1. nginx handles /_auth/callback. It will be proxied to adapter app /callback.
  • This decrypts given encrypted session string and set to cookie.
  • Then redirect to x-ngx-omniauth-initiate-back-to.
  1. browser backs to URL where attempted to access first, at step 1.
  2. nginx sends auth subrequest to backend app /test.
  3. backend app /test returns 200, because request has valid session cookie.
  4. nginx returns response as usual.


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at


The gem is available as open source under the terms of the MIT License.