OAuth Proxy Plugin for NGINX LUA Systems

A LUA plugin that is used during API calls from SPA clients, to forward JWTs to APIs.
This is part of a Backend for Frontend solution for SPAs, in line with best practices for browser based apps.

The Token Handler Pattern

The Token Handler Pattern is a modern evolution of a Backend for Frontend approach.
The SPA uses only SameSite encrypted HTTP Only cookies in the browser, and sends them during API requests.
This plugin performs the role of an OAuth Proxy in this solution, to make API calls work seamlessly:

The plugin translates from encrypted cookies to tokens, so that APIs receive JWTs in the standard way.

Components

The plugin can be used standalone, or in conjunction with the Phantom Token Plugin:

See also the following resources:

• The Example SPA, which acts as a client to this plugin.
• The OAuth Agent API, which issues the secure cookies for the SPA.

Installation

Kong API Gateway

If you are using luarocks, execute the following command to install the plugin:

luarocks install kong-oauth-proxy 1.3.0

Or deploy the .lua files into Kong's plugin directory, eg /usr/local/share/lua/5.1/kong/plugins/oauth-proxy.

OpenResty

If you are using luarocks, execute the following command to install the plugin:

luarocks install lua-resty-oauth-proxy 1.3.0

Or deploy the access.lua file to resty/oauth-proxy.lua, where the resty folder is in the lua_package_path.
A typical install location for LUA files is at /usr/local/openresty/luajit/share/lua/5.1/resty.

Required Configuration Directives

All of the settings in this section are required:

cookie_name_prefix

Syntax: cookie_name_prefix string

Context: location

The prefix used in the SPA's cookie name, typically representing a company or product name.
The value supplied must not be empty, and example would lead to full cookie names such as example-at.

encryption_key

Syntax: encryption_key string

Context: location

This must be a 32 byte encryption key expressed as 64 hex characters.
It is used to decrypt AES256 encrypted secure cookies.
The key is initially generated with a tool such as openssl, as explained in Curity tutorials.

trusted_web_origins

Syntax: trusted_web_origins string[]

Context: location

A whitelist of at least one web origin from which the plugin will accept requests.
Multiple origins could be used in special cases where cookies are shared across subdomains.

cors_enabled

Syntax: cors_enabled boolean

Default: true

Context: location

When enabled, the OAuth proxy returns CORS response headers on behalf of the API.
When an origin header is received that is in the trusted_web_origins whitelist, response headers are written.
The access-control-allow-origin header is returned, so that the SPA can call the API.
The access-control-allow-credentials header is returned, so that the SPA can send secured cookies to the API.

Optional Configuration Directives

allow_tokens

Syntax: allow_tokens boolean

Default: false

Context: location

If set to true, then requests that already have a bearer token are passed straight through to APIs.
This can be useful when web and mobile clients share the same API routes.

remove_cookie_headers

Syntax: remove_cookie_headers boolean

Default: true

Context: location

If set to true, then cookie and CSRF headers are not forwarded to APIs.
This provides cleaner requests to APIs, which only receive a JWT in the HTTP Authorization header.

cors_allow_methods

Syntax: cors_allow_methods string[]

Default: ['OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']

Context: location

When CORS is enabled, these values are returned in the access-control-allow-methods response header.
The SPA is then allowed to call a particular API endpoint with those HTTP methods (eg GET, POST).
A '*' wildcard value should not be configured here, since it will not work with credentialed requests.

cors_allow_headers

Syntax: cors_allow_headers string[]

Default: ['x-example-csrf']

Context: location

When CORS is enabled, the plugin returns these values in the access-contol-allow-headers response header.
Include here any additional non-safelisted request headers that the SPA needs to send in API requests.
To implement data changing requests, include the CSRF request header name, eg x-example-csrf.
A '*' wildcard value should not be configured here, since it will not work with credentialed requests.

cors_expose_headers

Syntax: cors_expose_headers string[]

Default: []

Context: location

When CORS is enabled, the plugin returns these values in the access-contol-expose-headers response header.
Include here any additional non-safelisted response headers that the SPA needs to read from API responses.
A '*' wildcard value should not be configured here, since it will not work with credentialed requests.

cors_max_age

Syntax: cors_max_age number

Default: 86400

Context: location

When CORS is enabled, the plugin returns this value in the access-contol-max-age response header.
When a value is configured, this prevents excessive pre-flight OPTIONS requests to improve efficiency.

Example Configurations

Standard settings would be expressed similar to the following if expressed in an nginx configuration file:

local config = {
    cookie_name_prefix = 'example',
    encryption_key = '4e4636356d65563e4c73233847503e3b21436e6f7629724950526f4b5e2e4e50',
    trusted_web_origins = {
        'http://www.example.com'
    },
    cors_enabled = true
}

The equivalent Kong configuration is expressed via YAML when using declarative configuration:

plugins:
  - name: oauth-proxy
    config:
      cookie_name_prefix: example
      encryption_key: 4e4636356d65563e4c73233847503e3b21436e6f7629724950526f4b5e2e4e50
      trusted_web_origins:
      - http://www.example.com
      cors_enabled: true

All API endpoints will then return these CORS headers to browsers in response headers:

access-control-allow-origin: http://www.example.com
access-control-allow-credentials: true
access-control-allow-methods: OPTIONS,HEAD,GET,POST,PUT,PATCH,DELETE
access-control-allow-headers: x-example-csrf
access-control-max-age: 86400

If you prefer you can override default settings:

local config = {
    cookie_name_prefix = 'example',
    encryption_key = '4e4636356d65563e4c73233847503e3b21436e6f7629724950526f4b5e2e4e50',
    trusted_web_origins = {
        'http://www.example.com'
    },
    cors_enabled = true,
    allow_tokens = false,
    remove_cookie_headers = true,
    cors_allow_methods = {
        'OPTIONS', 'GET', 'POST'
    },
    cors_allow_headers = {
        'my-header',
        'x-example-csrf'
    },
    cors_expose_headers = {
    },
    cors_max_age = 600
}

Or in Kong this would be configured like this:

plugins:
  - name: oauth-proxy
    config:
      cookie_name_prefix: example
      encryption_key: 4e4636356d65563e4c73233847503e3b21436e6f7629724950526f4b5e2e4e50
      trusted_web_origins:
      - http://www.example.com
      cors_enabled: true
      allow_tokens: false
      remove_cookie_headers: true
      cors_allow_methods:
      - OPTIONS
      - GET
      - POST
      cors_allow_headers:
      - my-header
      - x-example-csrf
      cors_expose_headers: []
      cors_max_age: 600

If you prefer you can configure cors_enabled=false, in which case you'll need to handle CORS in your API.

Deployment

The example Docker Compose File provides OpenResty and Kong deployment examples.

Development and Testing

The following resource provides further details on how to make code changes to this repo:

• Wiki

More Information

Please visit curity.io for more information about the Curity Identity Server.