NGINX OAuth Proxy Module

The OAuth Proxy is an extension to your API gateway that you need when your single page applications (SPAs) call OAuth-secured APIs using the Token Handler pattern. The SPA sends an encrypted proxy cookie that transports an access token. The OAuth Proxy plugin decrypts the cookie to extract the access token.

When the OAuth Proxy work completes, your NGINX API gateway routes the request to the target API, which uses the access token to implement its OAuth security.

Download the OAuth Proxy

You get the OAuth Proxy by downloading the latest ZIP file version from the Curity Developer Portal, with a filename of the following form. This zip file contains an NGINX module that you deploy to your gateway and a README file with detailed instructions.

curity-token-handler-proxy-nginx-<version>.zip

Deploy the OAuth Proxy

You must deploy the OAuth Proxy to a gateway that runs in your SPA's backend for frontend domain. If a deployment uses the following URLs, the OAuth Proxy executes in a gateway at https://bff.product.example:

• SPA Web Origin: https://www.product.example
• Backend for Frontend Base URL: https://bff.product.example
• Target API Base URL: https://api.example.com

To deploy the OAuth Proxy, locate the binary .so library for your particular Linux distribution and NGINX version, at a path of the following form, where NGINX_VERSION is a particular numeric version of NGINX:

nginx-NGINX_VERSION/ubuntu22/ngx_http_oauth_proxy_module.so

First, produce an NGINX Docker image by following the NGINX packaging instructions. Next, deploy the module to the /usr/lib/nginx/modules path within your NGINX Docker container. For example, if you use Docker Compose you might deploy the following files.

api-gateway-nginx:
    image: nginx-<NGINX_VERSION>-alpine
    ports:
      - 443:3000
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./default.conf.template:/etc/nginx/templates/default.conf.template
      - ./ngx_http_oauth_proxy_module.so:/usr/lib/nginx/modules/ngx_http_oauth_proxy_module.so

When you deploy the NGINX gateway you typically also provide API routes that reference the modules. In the above example deployment, these routes are supplied in a default.conf.template file.

Load Modules

In your main nginx.conf file you must load the modules that your API gateway uses. An example is shown here that uses the OAuth Proxy module together with the Phantom Token module. When you configure multiple modules for an API route they execute in the reverse load order. In this example, the OAuth Proxy module executes before the Phantom Token module.

load_module modules/ngx_curity_http_phantom_token_module.so;
load_module modules/ngx_http_oauth_proxy_module.so;

Prepare Decryption

You need an asymmetric keypair as part of your overall token handler deployment. To create one, follow the instructions in the Configure Cryptographic Keys section of the Create a Token Handler tutorial. This results in a PKCS#8 file with an encrypted private key, and also a private key password.

Configure API Routes

You must configure the OAuth Proxy for all API routes that the SPA calls. Also, add a route such as /oauthuserinfo if the SPA calls the authorization server's OpenID Connect userinfo endpoint.

To configure the OAuth Proxy you must provide the cookie decryption key for the OAuth Proxy, using the content of the PKCS#8 file and the PKCS#8 file's password.

server {
    server_name bff.product.example;
    listen      3000;

    location /api/ {

        oauth_proxy on;
        oauth_proxy_key '-----BEGIN ENCRYPTED PRIVATE KEY-----\n...' 'myS3cret';

        proxy_pass http://api-internal:3001/;
    }
}

You can supply the configuration values in various ways. For example, at deployment time you can use a tool such as envsubst to produce the final configuration file. Alternatively, some NGINX deployments enable you to deploy a template file with environment variable placeholders to the /etc/nginx/templates folder, as in the following example. NGINX then populates a corresponding file in the /etc/nginx/conf.d folder with expanded environment variables.

oauth_proxy on;
oauth_proxy_key "${TH_COOKIE_KEY}" "${TH_COOKIE_KEY_PASS}";

Additional configuration settings are also available. For example, if the OAuth Agent uses a different prefix for cookie names than the default value th-, you should configure an oauth_proxy_cookie_prefix in the OAuth Proxy that matches the value from the OAuth Agent. You can find full information on configuration settings in the README file within your downloaded ZIP file, including some advanced options for caching.

Configure CORS

When you use a cross origin deployment you must also configure Cross-Origin Resource Sharing (CORS) to instruct the browser to only allow the SPA's precise web origin to send cookies. You can configure a CORS solution of your choice. The following example configuration uses NGINX instructions to provide a basic CORS solution:

server {
    server_name bff.product.example;
    listen      3000;

    location /oauthagent/example {
        proxy_pass http://login-internal:8443/oauthagent/example;
    }

    location /api/ {

        set $cors_mode '';
        if ($http_origin = 'http://www.product.example') {
            set $cors_mode 'matched';
        }

        if ($request_method = 'OPTIONS') {
            set $cors_mode '${cors_mode}-preflight';
        }

        if ($cors_mode = 'matched') {
            add_header 'access-control-allow-origin' $http_origin always;
            add_header 'access-control-allow-credentials' true always;
            add_header 'vary' 'origin';
        }

        if ($cors_mode = 'matched-preflight') {
            add_header 'access-control-allow-origin' $http_origin;
            add_header 'access-control-allow-credentials' true;
            add_header 'access-control-allow-methods' 'GET,POST,PUT,PATCH,DELETE';
            add_header 'access-control-allow-headers' $http_access_control_request_headers;
            add_header 'access-control-max-age' 86400;
            add_header 'vary' 'origin, access-control-request-headers';
            return 200;
        }

        oauth_proxy on;
        oauth_proxy_key '-----BEGIN ENCRYPTED PRIVATE KEY-----\n...' 'myS3cret';

        proxy_pass http://api-internal:3001/;
    }
}

OAuth Proxy Output

At runtime, the OAuth Proxy processes cookies in incoming requests from SPAs. On success it rewrites the HTTP request, setting the access token in the HTTP authorization header. The target API then receives a JWT access token in the standard way and can use it for its authorization.

If the OAuth Proxy experiences an invalid cookie error, it returns an error response to the SPA with a 401 HTTP status code. For other types of error, the OAuth Proxy returns a 500 HTTP status code.

Example Deployment

You can follow the Token Handler Deployment Example to fully understand how the OAuth Proxy integrates into an SPA and API solution. The tutorial deploys an example Single Page Application that calls an example API through the OAuth Proxy. You can run the end-to-end example on a development computer with various configurations.

Conclusion

The OAuth Proxy is part of your API gateway. It enables your SPAs to use the correct browser security and also make direct calls to API URLs. The OAuth Proxy plugin deals with the cookie complexity so that you do not need to implement it in your API code.