Skip to content

OAuth 2.0 proxy for nginx written in Lua. | DEPRECATED in favour of https://github.com/jirutka/nginx-oidc-njs

License

Notifications You must be signed in to change notification settings

jirutka/ngx-oauth

Repository files navigation

ngx-oauth

Build Status Coverage Status LDoc

IMPORTANT: This project has been deprecated in favour of nginx-oidc-njs.

Requirements

Installation

You can install ngx-oauth and its Lua dependencies (called rocks) using LuaRocks (the Lua package manager):

luarocks install ngx-oauth

or to get the latest development version:

luarocks install --server=http://luarocks.org/dev ngx-oauth

Note: If you want to bootstrap development environment or just try ngx-oauth without any hassle, read section Setup development environment.

Alpine Linux

  1. Install nginx with the Lua module:

    apk add nginx nginx-mod-http-lua
  2. Install Lua dependencies:

    apk add lua5.1-cjson lua5.1-ossl lua5.1-resty-http
  3. Install LuaRocks and git (for installing development version of the ngx-oauth from LuaRocks):

    apk add git luarocks-5.1
  4. Install ngx-oauth from LuaRocks:

    luarocks-5.1 install --server=http://luarocks.org/dev ngx-oauth

Debian/Ubuntu

  1. Install nginx-extras (consider installing from some PPA to get not-so-old version…):

    apt-get install nginx-extras
  2. Install luarocks, libssl-dev, and git:

    apt-get install luarocks libssl-dev git
  3. Install ngx-oauth:

    luarocks install luaossl CRYPTO_LIBDIR=/usr/lib/x86_64-linux-gnu OPENSSL_LIBDIR=/usr/lib/x86_64-linux-gnu
    luarocks install --server=http://luarocks.org/dev ngx-oauth

Usage

Example of nginx.conf:
http {

    # DNS servers used to resolve names of upstream servers into addresses.
    resolver 208.67.222.222 208.67.220.220 [2620:0:ccc::2] [2620:0:ccd::2];

    # Path of the file with trusted CA certificates.
    lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;

    # The verification depth in the server certificates chain.
    lua_ssl_verify_depth 3;

    # The Lua module search path.
    lua_package_path '/path/to/ngx-oauth/?.lua;;';

    ...

    server {
        listen 443 ssl;
        server_name client.example.org;

        ...

        set $oauth_client_id '01234567-89ab-cdef-0123-456789abcdef';
        set $oauth_client_secret 'very-top-secret-password';
        set $oauth_redirect_uri '/_oauth/callback';
        set $oauth_oaas_uri 'https://oaas.example.org/oauth';

        location /_oauth/login {
            content_by_lua_file '/path/to/ngx-oauth-login.lua';
        }

        location /_oauth/callback {
            content_by_lua_file '/path/to/ngx-oauth-redirect-handler.lua';
        }

        location /_oauth/logout {
            content_by_lua_file '/path/to/ngx-oauth-logout.lua';
        }

        location /_proxy {
            access_by_lua_file '/path/to/ngx-oauth-proxy.lua';

            rewrite ^/_proxy/(.*)$ /$1 break;
            proxy_pass https://resource-provider;
        }

        location / {
            ...
        }
    }
}

Configuration variables

$oauth_aes_bits

Selects the AES key length (in bits) for encrypting a refresh token stored in a cookie. The supported values are: 128, 192, and 256. The default value is 128.

$oauth_authorization_url

URL of the authorization endpoint provided by the authorization server. This variable is required if $oauth_oaas_uri is not set; otherwise it defaults to ${oauth_oaas_uri}/authorize.

$oauth_client_id

The client identifier registered on the authorization server. This variable is required.

$oauth_client_secret

The client secret (password). First n-bytes of this value, where n equals $oauth_aes_bits / 8, is also used as a key for encrypting a refresh token stored in a cookie. This n also defines the lower limit of the secret length. However, even if you use the default key length 128 bits, the client secret should be much longer (e.g. 32 characters). This variable is required.

$oauth_cookie_path

Specifies the Path attribute for the cookies. The default value is /.

$oauth_cookie_prefix

The string to be used as a prefix for access_token, refresh_token and username cookies. The default value is oauth_.

$oauth_max_age

Specifies the Max-Age attribute for the refresh_token cookie and the username cookie, in seconds. The Max-Age of the access_token cookie is determined as a minimum of this value and token’s expires_in attribute. The default value is 2592000 (30 days).

$oauth_oaas_uri

Base URI of the OAuth 2.0 authorization server. This variable is required, unless you set $oauth_authorization_url, $oauth_token_url and $oauth_userinfo_url.

$oauth_redirect_uri

URL of the client’s redirection endpoint previously registered on the authorization server. It may be full (absolute) URL, or just a path (starting with /) relative to $scheme://$server_name. The default value is /_oauth/callback.

$oauth_scope

A space delimited set of OAuth scopes that should be requested. The default value is empty, i.e. all scopes allowed for the client will be requested.

$oauth_success_uri

Absolute or relative URI to which a browser should be redirected after successful authorization. The default value is /.

$oauth_token_url

URL of the token endpoint provided by the authorization server. This variable is required if $oauth_oaas_uri is not set; otherwise it defaults to ${oauth_oaas_uri}/token.

$oauth_userinfo_url

URL of the userinfo endpoint. This may be any GET resource secured by OAuth 2.0 that returns JSON with username (in the attribute username) of the user that has authorized the access token. This variable is required if $oauth_oaas_uri is not set; otherwise it defaults to ${oauth_oaas_uri}/userinfo.

Usage scenarios

This section describes various usage scenarios.

List of participants:
user-agent

This is typically user’s web browser.

proxy/nginx

Nginx with ngx-oauth module that serves our client-side application. It has URI https://nginx in the diagrams.

Authorization Server (OAAS)

OAuth 2.0 authorization server. It may be standalone, or coupled with an resource provider. It has URI https://oaas in the diagrams.

Resource provider (RP)

An resource provider, i.e. our backend application with RESTful API. It has URI https://rp in the diagrams.

Error handling:
  • If there’s some problem in ngx-oauth configuration, then the proxy responds with HTTP 500.

  • If the user-agent use an incorrect HTTP method (i.e. GET instead of POST), then the proxy responds with HTTP 405.

  • If some error occur in communication with the OAAS, then the proxy responds with HTTP 503.

User log-in

Modules: ngx-oauth-login and ngx-oauth-redirect-handler

This scenario is intended for authorization grant client credentials.

Log-in for the first time
+-------------+                               +-------------+                                    +-------------+
| user-agent  |                               | proxy/nginx |                                    |    OAAS     |
+------+------+                               +------+------+                                    +------+------+
       |       POST https://nginx/_oauth/login       |                                                  |
      (1)------------------------------------------->|                                                  |
       |                                             |                                                  |
       |  302 | Location: https://oaas/authorize?... |                                                  |
       |<- - - - - - - - - - - - - - - - - - - - - (2a)                                                 |
       |                                             |                                                  |
       |                                         GET <Location>                                         |
     (2b)---------------------------------------------------------------------------------------------->|
       :                                             :                                                  :
       :                                             :                               /~~~~~~~~~~~~~~~~~~~~~~~~~~~+
       :                                             :                               | User logs in and approves |
       :                                             :                               |    authorization request. |
       :                                             :                               +~~~~~~~~~~~~~~~~~~~~~~~~~~~/
       :                     302 | Location: https://nginx/_oauth/callback?code=xyz                     :
       |<- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(3a)
       |                                             |                                                  |
       |               GET <Location>                |                                                  |
      (3b)------------------------------------------>|                                                  |
       |                                             | POST https://oaas/token | code= & redirect_uri=  |
       |                                             | Authorization: Basic <client_id>:<client_secret> |
       |                                            (4)------------------------------------------------>|
       |                                             |                                                  |
       |                                             |    200 | {access_token:, refresh_token:, ...}    |
       |                                             |<- - - - - - - - - - - - - - - - - - - - - - - - (5)
       |                                             |                                                  |
       |                                             |            GET https://oaas/userinfo             |
       |                                             |       Authorization: Bearer <access_token>       |
       |                                            (6)------------------------------------------------>|
       |                                             |                                                  |
       |                                             |              200 | {username, ...}               |
       |                                             |<- - - - - - - - - - - - - - - - - - - - - - - - (7)
       |      302 | Location: /, Set-Cookie: ...     |                                                  |
       |<- - - - - - - - - - - - - - - - - - - - - -(8)                                                 |
       |                                             |                                                  |
  1. The user-agent makes a POST request to the proxy’s login endpoint (i.e. user clicks on the login button).

  2. The proxy initiates the OAuth flow by directing the user-agent to the authorization endpoint (specified by $oauth_authorization_url). The URI includes the client identifier ($oauth_client_id), requested scope ($oauth_scope), and a redirection URI ($oauth_redirect_uri) to which the OAAS will send the user-agent back once access is granted (or denied).

  3. Assuming the user logs-in and grants access, the OAAS redirects the user-agent back to the proxy using the redirection URI with an authorization code.

  4. The proxy requests an access token from the OAAS’ token endpoint ($oauth_token_url) by including the authorization code and the redirection URI. When making the request, the proxy authenticates with the OAAS using the client identifier and the client secret ($oauth_client_secret).

  5. The OAAS validates the token request and if valid, it responds back with an access token and a refresh token.

  6. The proxy requests an userinfo from the OAAS’ userinfo endpoint ($oauth_userinfo_url) using the access token.

  7. The OAAS validates the access token and if valid, it responds back with an username and possibly other fields.

  8. Assuming that all previous steps were successful, the proxy redirects the user-agent to the $oauth_success_uri and sets access_token, refresh_token and username cookies. The refresh_token cookie is encrypted, so it’s not readable by the user-agent.

Log-in with an existing refresh token
+-------------+                               +-------------+                                    +-------------+
| user-agent  |                               | proxy/nginx |                                    |    OAAS     |
+------+------+                               +------+------+                                    +------+------+
       |       POST https://nginx/_oauth/login       |                                                  |
       |         Cookie: refresh_token, ...          |                                                  |
      (1)------------------------------------------->|                                                  |
       |                                             |     POST https://oaas/token | refresh_token=     |
       |                                             | Authorization: Basic <client_id>:<client_secret> |
       |                                            (2)------------------------------------------------>|
       |                                             |                                                  |
       |                                             |            200 | {access_token:, ...}            |
       |                                             |<- - - - - - - - - - - - - - - - - - - - - - - - (3)
       | 302 | Location: /, Set-Cookie: access_token |                                                  |
       |<- - - - - - - - - - - - - - - - - - - - - -(4)                                                 |
       |                                             |                                                  |
  1. The user-agent makes a POST request to the proxy’s login endpoint and includes a valid refresh_token cookie.

  2. The proxy requests an access token from the OAAS’ token endpoint ($oauth_token_url) using the refresh_token obtained from the cookie. When making the request, the proxy authenticates with the OAAS using the client identifier ($oauth_client_id) and the client secret ($oauth_client_secret).

  3. The OAAS validates the refresh token and if valid, it responds back with a new access token.

  4. Assuming that the previous step was successful, the proxy redirects the user-agent to the $oauth_success_uri and sets cookie with the new access token.

User log-out

Modules: ngx-oauth-logout

+-------------+                               +-------------+                                   +-------------+
| user-agent  |                               | proxy/nginx |                                   |    OAAS     |
+------+------+                               +------+------+                                   +------+------+
       |      POST https://nginx/_oauth/logout       |                                                 |
       |   Cookie: access_token, refresh_token, ...  |                                                 |
      (1)------------------------------------------->|                                                 |
       |                                             |                                                 |
       |                     204                     |                                                 |
       | Set-Cookie: oauth_*=deleted; Max-Age=0; ... |                                                 |
       |<- - - - - - - - - - - - - - - - - - - - - -(2)                                                |
       |                                             |                                                 |
  1. The user-agent makes a POST request to the proxy’s logout endpoint.

  2. The proxy responds back with HTTP status 204 and sets access_token, refresh_token and username cookies to expired (i.e. the user-agent will erase them).

Proxy for resource provider

Module: ngx-oauth-proxy

+-------------+                       +-------------+                        +-------------+    +-------------+
| user-agent  |                       | proxy/nginx |                        |  RP (API)   |    |    OAAS     |
+------+------+                       +------+------+                        +------+------+    +------+------+
       |                                     |                                      |                  |
       |    GET https://nginx/_proxy/ping    |                                      |                  |
       | Cookie: access_token, refresh_token |                                      |                  |
      (1)----------------------------------->|         GET https://rp/ping          |                  |
       |                                     | Authorization: Bearer <access_token> |                  |
       |                                    (2)------------------------------------>|                  |
       |                                     |                                      |                  |
       |                                     |                 200                  |                  |
       |                 200                 |<- - - - - - - - - - - - - - - - - - (3)                 |
       |<- - - - - - - - - - - - - - - - - -(4)                                     |                  |
       :                                     :                                      :                  :
  /~~~~~~~~~~~~~~~~~~~~~~+                   :                                      :                  :
  | access_token expired |                   :                                      :                  :
  +~~~~~~~~~~~~~~~~~~~~~~/                   :                                      :                  :
       :                                     :                                      :                  :
       |    GET https://nginx/_proxy/ping    |                                      |                  |
       |        Cookie: refresh_token        |                                      |                  |
      (5)----------------------------------->|                                      |                  |
       |                                     |        POST https://oaas/token | refresh_token=         |
       |                                     |     Authorization: Basic <client_id>:<client_secret>    |
       |                                    (6)------------------------------------------------------->|
       |                                     |                                      |                  |
       |                                     |                200 | {access_token:, ...}               |
       |                                     |<- - - - - - - - - - - - - - - - - - - - - - - - - - - -(7)
       |                                     |                                      |                  |
       |                                     |         GET https://rp/ping          |                  |
       |                                     | Authorization: Bearer <access_token> |                  |
       |                                    (8)------------------------------------>|                  |
       |                                     |                                      |                  |
       |                                     |                 200                  |                  |
       |   200 | Set-Cookie: access_token    |<- - - - - - - - - - - - - - - - - - (9)                 |
       |<- - - - - - - - - - - - - - - - - (10)                                     |                  |
       |                                     |                                      |                  |
  1. The user-agent requests data on the resource provider (RP) through the proxy.

  2. The proxy adds an Authorization header with the access token obtained from the cookie (that has been set in the login flow) and passes it to the RP.

  3. The RP validates the access token on the OAAS and responds back to the user-agent through the proxy.

  4. The proxy just passes the RP’s response to the user-agent without any modification.

  5. Some time later, the access token expire and the user-agent requests another data through the proxy. The access token cookie has the same or shorter expiration time than the access token itself, i.e. when the token expire, the user-agent erases the cookie.

  6. The proxy requests an access token from the OAAS’ token endpoint ($oauth_token_url) using the refresh_token obtained from the cookie. When making the request, the proxy authenticates with the OAAS using the client identifier ($oauth_client_id) and the client secret ($oauth_client_secret).

  7. The OAAS validates the refresh token and if valid, it responds back with a new access token.

  8. The proxy adds the Authorization header with the new access token to the request (5) and passes it to the RP.

  9. The RP validates the access token on the OAAS and responds back to the proxy.

  10. The proxy passes the RP’s response to the user-agent and sets cookie with the new access token.

Setup development environment

  1. Clone this repository:

    git clone https://github.com/jirutka/ngx-oauth.git
    cd ngx-oauth
  2. Source file .envrc into your shell (or manually add $(pwd)/.env/bin to your PATH):

    source .envrc
  3. Install LuaJIT and modules for development into directory .env:

    ./script/bootstrap

    or to install nginx and Python modules for running integration tests as well, use:

    ./script/bootstrap-full
  4. Run tests with code coverage and linter:

    ./script/test

    and integration tests:

    ./script/test-integration

These scripts should work on every up-to-date Unix system (tested on OS X, Gentoo, Slackware, and Ubuntu).

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.

This README file is licensed under Creative Commons Attribution 4.0 International License.