jirutka / Ngx Oauth

= ngx-oauth Jakub Jirutka https://github.com/jirutka[@jirutka] :source-language: sh :gh-name: jirutka/ngx-oauth :gh-branch: master :gh-url: https://github.com :ldoc-url: https://jirutka.github.io/ngx-oauth/ldoc/ :rocks-url: https://luarocks.org/modules :rfc6749: http://tools.ietf.org/html/rfc6749 :rfc6265: http://tools.ietf.org/html/rfc6265 :ngx-http-core-doc: http://nginx.org/en/docs/http/ngx_http_core_module.html

ifdef::env-github[] image:https://travis-ci.org/{gh-name}.svg?branch={gh-branch}["Build Status", link="https://travis-ci.org/{gh-name}"] image:https://coveralls.io/repos/{gh-name}/badge.svg?branch={gh-branch}&service=github["Coverage Status", link="https://coveralls.io/github/{gh-name}?branch={gh-branch}"] image:https://img.shields.io/badge/ldoc-docs-blue.svg["LDoc", link="{ldoc-url}"] endif::env-github[]

TBD

== Requirements

• http://nginx.org[nginx] with compiled https://github.com/openresty/lua-nginx-module[Lua module], or http://openresty.org/#Installation[OpenResty]
• http://luajit.org[LuaJIT] 2.0+, or http://www.lua.org[Lua] 5.1 (newer versions are not supported by lua-nginx yet)
• lua-resty-http [{gh-url}/pintsized/lua-resty-http[source]] [{rocks-url}/pintsized/lua-resty-http[LuaRocks]]
• lua-cjson [{gh-url}/mpx/lua-cjson[source]] [{rocks-url}/luarocks/lua-cjson[LuaRocks]], or luajson [{gh-url}/harningt/luajson[source]] [{rocks-url}/harningt/luajson[LuaRocks]]
• luaossl [{gh-url}/wahern/luaossl[source]] [{rocks-url}/daurnimator/luaossl[LuaRocks]]

== Installation

You can install ngx-oauth and its Lua dependencies (called rocks) using https://luarocks.org[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 <>.

=== Alpine Linux

. Install nginx with the Lua module:

apk add nginx nginx-mod-http-lua

. Install Lua dependencies:

apk add lua5.1-cjson lua5.1-ossl lua5.1-resty-http

. Install LuaRocks and git (for installing development version of the ngx-oauth from LuaRocks):

apk add git luarocks-5.1

. Install ngx-oauth from LuaRocks:

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

=== Debian/Ubuntu

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

apt-get install nginx-extras

. Install luarocks, libssl-dev, and git:

apt-get install luarocks libssl-dev git

. 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

[source, nginx] .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 {rfc6749}#section-3.1[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 {rfc6749}#section-2.2[client identifier] registered on the authorization server. This variable is required.

$oauth_client_secret:: The {rfc6749}#section-2.3.1[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 {rfc6265}#section-4.1.2.4[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 {rfc6749}#section-4.1.2.2[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 {rfc6749}#section-3.1.2[redirection endpoint] previously registered on the authorization server. It may be full (absolute) URL, or just a path (starting with /) relative to {ngx-http-core-doc}#var_scheme[$scheme]://{ngx-http-core-doc}#var_server_name[$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 {rfc6749}#section-3.2[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 {rfc6749}#section-1.3.1[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 | (2b)---------------------------------------------------------------------------------------------->| : : : : : /~~~~~~~~~~~~~~~~~~~~~~~~~~~+ : : | User logs in and approves | : : | authorization request. | : : +~~~~~~~~~~~~~~~~~~~~~~~~~~~/ : 302 | Location: https://nginx/_oauth/callback?code=xyz : |<- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(3a) | | | | GET | | (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

. Clone this repository:

git clone https://github.com/jirutka/ngx-oauth.git
cd ngx-oauth

. Source file .envrc into your shell (or manually add $(pwd)/.env/bin to your PATH):

source .envrc

. 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

. 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 http://opensource.org/licenses/MIT/[MIT License]. For the full text of the license, see the link:LICENSE[LICENSE] file.

This README file is licensed under http://creativecommons.org/licenses/by/4.0[Creative Commons Attribution 4.0 International License].