NGINX OpenID Connect

OpenID Connect and OAuth 2.0 module for NGINX written in njs (NGINX JavaScript).

Installation

Requirements

Runtime:

• nginx with:

  • ngx_http_js_module ≥ 0.7.0

  • ngx_http_keyval_module ≥ 0.1.0

  • ngx_http_auth_jwt_module ≥ 0.2.1

Build:

• Node.js 14.15+

• npm (distributed with Node.js)

• npm packages specified in package.json (will be installed using npm)

From release tarball

1. Download and verify the latest release tarball:

   curl -sSLO https://github.com/jirutka/nginx-oidc-njs/releases/download/v0.1.1/nginx-oidc-njs-0.1.1.tar.gz
   curl -sSL https://github.com/jirutka/nginx-oidc-njs/releases/download/v0.1.1/nginx-oidc-njs-0.1.1.tar.gz.sha256 | sha256sum -c

2. Install files somewhere, e.g. /usr/local/share/nginx-oidc-njs:

   mkdir -p /usr/local/share/nginx-oidc-njs
   cp -r nginx-oidc-njs-0.1.1/* /usr/local/share/nginx-oidc-njs/

From source

1. Install system dependencies specified in build requirements.

2. Clone this repository and jump in:

   git clone git@github.com:jirutka/nginx-oidc-njs.git
   cd nginx-oidc-njs

3. Build the project:

   make build

4. Install files (you may need to run this with sudo):

   make install

   You may use the DESTDIR and PREFIX variables to specify the destination.

Configuration

Example of nginx.conf:

http {
  # Configure name servers used to resolve domain names.
  resolver 193.17.47.1 185.43.135.1 [2001:148f:ffff::1] [2001:148f:fffe::1];

  js_import oidc from /path/to/nginx-oidc-njs/nginx-oidc.njs;
  include /path/to/nginx-oidc-njs/conf/http.conf;

  # Define cache zone for requested and inspected tokens.
  proxy_cache_path cache/oidc_tokens
    keys_zone=oidc_tokens:1m
    levels=2
    use_temp_path=off
    inactive=1h
    max_size=4m;

  keyval_zone_redis zone=oidc_id_tokens ttl=300;
  keyval_zone_redis zone=oidc_access_tokens ttl=300;
  keyval_zone_redis zone=oidc_refresh_tokens ttl=604800;
  keyval_zone_redis zone=oidc_auth_states ttl=60;

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

    ...

    include /path/to/nginx-oidc-njs/conf/server.conf;

    # This must be large enough to fit a JWT token.
    subrequest_output_buffer_size 32k;

    set $oidc_issuer "https://openid.example.org";
    set $oidc_authorization_endpoint "https://openid.example.org/authorize";
    set $oidc_token_endpoint "https://openid.example.org/token";
    set $oidc_end_session_endpoint "https://openid.example.org/logout";
    set $oidc_jwks_file "/path/to/jwks.json";

    set $oidc_client_id "oidc-njs";
    set $oidc_client_secret "top-secret";
    set $oidc_scope "openid profile";

    # This must match the keys_zone name defined above in the http context.
    set $oidc_cache_zone_tokens "oidc_tokens";

    location /api/ {
      include /path/to/nginx-oidc-njs/conf/auth-proxy.conf;

      proxy_pass "https://rp.example.org";
    }

    location / {
      set $oidc_access "flynnkev USER ADMIN";

      include /path/to/nginx-oidc-njs/conf/auth-access.conf;
    }
  }
}

Snippets

To simplify integration into your NGINX configuration, the conf/ directory contains a number of configuration snippets with predefined directives which are necessary for this module to work. These snippets should be included in the NGINX configuration using the https://nginx.org/en/docs/http/ngx_http_core_module.html#include directive. Alternatively, if you need to change them in any way, you can copy and paste their contents directly into your configuration.

http.conf

This snippet creates keyval variables and must be included in the http context.

server.conf

This snippet creates /-/oidc/ and /-/internal/ locations and it should be included in every server context (aka virtual host) where you want to use OIDC.

auth-access.conf

This snippet performs user access authorization using the OpenID Connect Authorization Code flow. It should be included either in location or server context. You can use the $oidc_allow and $oidc_deny variables for fine-grained access control.

auth-pages.conf

TBD

auth-proxy.conf

This snippet realises OAuth proxy for a resource provider. It should be included either in location or server context.

All auth-*.conf snippets uses the auth_request directive that performs a subrequest to one of the internal locations defined in server.conf.

Variables

This module is configured using nginx variables, which can be set with set, map or js_var directives. All variables should be set in the server context (or http context), unless specified otherwise.

OIDC Provider

The information for the following configuration variables can be retrieved from the OpenID Provider Discovery Metadata exposed by your Authorization Server or from its documentation.

$oidc_issuer

URL that the OIDC Provider asserts as its Issuer Identifier. It corresponds to property issuer in Provider Metadata.

This variable is required.

$oidc_jwks_file

Path to the JSON file in the JWKS format for validating JWT signature. This file can be downloaded from the location specified by the jwks_uri property in Provider Metadata.

This variable is required.

$oidc_authorization_endpoint

URL of the OAuth 2.0 Authorization Endpoint at the Authorization Server. It corresponds to property authorization_endpoint in Provider Metadata.

This variable is required.

$oidc_token_endpoint

URL of the OAuth 2.0 Token Endpoint at the Authorization Server. It corresponds to property token_endpoint in Provider Metadata.

This variable is required.

$oidc_introspection_endpoint

URL of the OAuth 2.0 Token Introspection Endpoint at the Authorization Server. It corresponds to property introspection_endpoint in Provider Metadata.

This variable is optional.

$oidc_end_session_endpoint

URL of the Logout Endpoint for the RP-Initiated Logout at the Authorization Server. It corresponds to property end_session_endpoint in Provider Metadata.

This variable is optional.

Client

$oidc_client_id

OAuth 2.0 Client Identifier registered at the Authorization Server.

This variable is required.

$oidc_client_secret

OAuth 2.0 Client Secret (password) associated with the $oidc_client_id.

This variable is required.

$oidc_scope

A space-separated set of OAuth 2.0 scopes that should be requested.

Default is openid.

$oidc_claim_username

The ID Token Claim that contains the user’s unique identifier (typically a username). This is used for access control (see $oidc_allow) and logging.

Default is preferred_username.

$oidc_claim_roles

The ID Token Claim that contains the roles of the user (as a flat array). This is used for access control (see $oidc_allow).

This variable is optional.

$oidc_redirect_uri

URL of the Client’s Redirection Endpoint previously registered at the Authorization Server. If only a path is provided (not an absolute URL), it will be prepended with $scheme://$server_name:$server_port.

Default is /-/oidc/callback, which corresponds to the location in conf/server.conf.

$oidc_post_logout_redirect_uri

URL to which the user will be redirected after logging out. If $oidc_end_session_endpoint is specified, then this URL will be passed to the Authorization Server’s Logout Endpoint via the post_logout_redirect_uri parameter and it must be previously registered at the Authorization Server.

This variable is optional.

Others

$oidc_allow

A whitespace-separated list of usernames and roles. If the user has any of the specified roles or username, and has none of the roles or username specified in $oidc_deny, then access will be allowed. Otherwise, access will be denied.

The user’s username and roles are retrieved from the ID Token as specified by $oidc_claim_username and $oidc_claim_roles. There are also two special roles:

• ANONYMOUS – no authentication is required, access is allowed to anyone.

• AUTHENTICATED – any authenticated user is allowed.

This variable is used for conf/auth-access.conf and it can be set in the server or location context.

Default is AUTHENTICATED.

$oidc_deny

A whitespace-separated list of usernames and roles. If the user has any of the specified roles or username, then access will be denied.

The user’s username and roles are retrieved from the ID Token as specified by $oidc_claim_username and $oidc_claim_roles.

This variable is used for conf/auth-access.conf and it can be set in the server or location context.

Default is empty.

$oidc_cache_zone_tokens

Name of the proxy cache keys_zone for caching tokens.

This variable is required. ^[1]

$oidc_cookie_attrs

Set-Cookie attributes to be added to the session cookies. Some attributes are overridden for certain cookies (Max-Age and Path).

Default is Max-Age=2592000; Path=/; Secure; SameSite=lax.^[2]

$oidc_error_pages_dir

Path to the directory with error page templates. See Error Pages for more information.

$oidc_log_level

The log level threshold for messages logged by this module.

One of: debug, info, warn, error. Default is info.

$oidc_log_prefix

The prefix for log messages.

Default is [oidc] .

Error Pages

TBD

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.

---

1. It has a default value in the module, but it must be defined for proxy_cache in conf/server.conf.

2. SameSite=strict doesn’t work with e.g. Microsoft ATP (that crap used when opening links from MS Teams) – Set-Cookie is not propagated.