https://github.com/jirutka/nginx-oidc-njs

OpenID Connect and OAuth 2.0 module for NGINX written in njs.
https://github.com/jirutka/nginx-oidc-njs
nginx njs oidc-proxy oidc-resource-server openid-connect
Last synced: 2 months ago
JSON representation
OpenID Connect and OAuth 2.0 module for NGINX written in njs.
Host: GitHub
URL: https://github.com/jirutka/nginx-oidc-njs
Owner: jirutka
License: mit
Created: 2023-06-09T13:25:27.000Z (about 3 years ago)
Default Branch: master
Last Pushed: 2024-03-07T15:49:19.000Z (over 2 years ago)
Last Synced: 2025-10-06T20:32:41.636Z (9 months ago)
Topics: nginx, njs, oidc-proxy, oidc-resource-server, openid-connect
Language: TypeScript
Homepage:
Size: 383 KB
Stars: 10
Watchers: 1
Forks: 1
Open Issues: 3
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project

README

          = NGINX OpenID Connect

:proj-name: nginx-oidc-njs

:gh-name: jirutka/{proj-name}

:version: 0.1.1

:ngx-docs-url: https://nginx.org/en/docs/http

:ngx-http-core-url: {ngx-docs-url}/ngx_http_core_module.html

ifdef::env-github[]

image:https://github.com/{gh-name}/workflows/CI/badge.svg[Binaries Workflow, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22]

endif::env-github[]

OpenID Connect and OAuth 2.0 module for NGINX written in https://nginx.org/en/docs/njs/[njs] (NGINX JavaScript).

== Installation

=== Requirements

.*Runtime:*

* http://nginx.org[nginx] with:

** http://nginx.org/en/docs/http/ngx_http_js_module.html[ngx_http_js_module] ≥ 0.7.0

** https://github.com/kjdev/nginx-keyval[ngx_http_keyval_module] ≥ 0.1.0

** https://github.com/kjdev/nginx-auth-jwt[ngx_http_auth_jwt_module] ≥ 0.2.1

.*Build:*

* https://nodejs.org[Node.js] 14.15+

* https://docs.npmjs.com/cli/commands/npm[npm] (distributed with Node.js)

* npm packages specified in link:package.json[] (will be installed using npm)

=== From release tarball

. Download and verify the latest release tarball:

+

[source, sh, subs="+attributes"]

curl -sSLO https://github.com/{gh-name}/releases/download/v{version}/{proj-name}-{version}.tar.gz

curl -sSL https://github.com/{gh-name}/releases/download/v{version}/{proj-name}-{version}.tar.gz.sha256 | sha256sum -c

. Install files somewhere, e.g. _/usr/local/share/{proj-name}_:

+

[source, sh, subs="+attributes"]

mkdir -p /usr/local/share/{proj-name}

cp -r {proj-name}-{version}/* /usr/local/share/{proj-name}/

=== From source

. Install system dependencies specified in <>.

. Clone this repository and jump in:

+

[source, sh, subs="+attributes"]

git clone git@github.com:{gh-name}.git

cd {proj-name}

. Build the project:

+

[source, sh]

make build

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

+

[source, sh]

make install

+

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

== Configuration

.Example of nginx.conf:

[source, nginx]

----

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 link: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 link:{ngx-http-core-url}#include[] directive.

Alternatively, if you need to change them in any way, you can copy and paste their contents directly into your configuration.

link:conf/http.conf[http.conf]::

This snippet creates https://github.com/kjdev/nginx-keyval[keyval] variables and must be _included_ in the _http_ context.

link:conf/server.conf[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.

link:conf/auth-access.conf[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.

link:conf/auth-pages.conf[auth-pages.conf]::

TBD

link:conf/auth-proxy.conf[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 link:{ngx-docs-url}/ngx_http_auth_request_module.html#auth_request[auth_request] directive that performs a subrequest to one of the internal _locations_ defined in link:conf/server.conf[server.conf].

=== Variables

:oidc-connect-core-url: https://openid.net/specs/openid-connect-core-1_0.html

:oidc-provider-metadata-url: https://openid.net/specs/openid-connect-discovery-1_0.html

:oidc-provider-metadata-link: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata[Provider Metadata]

:rfc6749-url: https://datatracker.ietf.org/doc/html/rfc6749

:rfc7517-url: https://datatracker.ietf.org/doc/html/rfc7517

:rfc7662-url: https://datatracker.ietf.org/doc/html/rfc7662

:server-scheme-name-port: link:{ngx-http-core-url}#var_scheme[$scheme]://link:{ngx-http-core-url}#var_server_name[$server_name]:link:{ngx-http-core-url}#var_server_port[$server_port]

This module is configured using nginx _variables_, which can be set with link:{ngx-docs-url}/ngx_http_rewrite_module.html#set[set], link:{ngx-docs-url}/ngx_http_map_module.html#map[map] or link:{ngx-docs-url}/ngx_http_js_module.html#js_var[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 link:{oidc-provider-metadata-url}#ProviderMetadata[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 {oidc-provider-metadata-link}.

+

This variable is *required*.

$oidc_jwks_file::

Path to the JSON file in the link:{rfc7517-url}#section-5[JWKS] format for validating JWT signature.

This file can be downloaded from the location specified by the `jwks_uri` property in {oidc-provider-metadata-link}.

+

This variable is *required*.

$oidc_authorization_endpoint::

URL of the link:{rfc6749-url}#section-3.1[OAuth 2.0 Authorization Endpoint] at the Authorization Server.

It corresponds to property `authorization_endpoint` in {oidc-provider-metadata-link}.

+

This variable is *required*.

$oidc_token_endpoint::

URL of the link:{rfc6749-url}#section-3.2[OAuth 2.0 Token Endpoint] at the Authorization Server.

It corresponds to property `token_endpoint` in {oidc-provider-metadata-link}.

+

This variable is *required*.

$oidc_introspection_endpoint::

URL of the link:{rfc7662-url}#section-2[OAuth 2.0 Token Introspection Endpoint] at the Authorization Server.

It corresponds to property `introspection_endpoint` in {oidc-provider-metadata-link}.

+

This variable is optional.

$oidc_end_session_endpoint::

URL of the link:{oidc-rp-init-logout-url}[Logout Endpoint] for the RP-Initiated Logout at the Authorization Server.

It corresponds to property `end_session_endpoint` in {oidc-provider-metadata-link}.

+

This variable is optional.

==== Client

$oidc_client_id::

OAuth 2.0 link:{rfc6749-url}#section-2.2[Client Identifier] registered at the Authorization Server.

+

This variable is *required.*

$oidc_client_secret::

OAuth 2.0 link:{rfc6749-url}#section-2.3.1[Client Secret] (password) associated with the *$oidc_client_id*.

+

This variable is *required.*

$oidc_scope::

A space-separated set of link:{rfc6749-url}#section-3.3[OAuth 2.0 scopes] that should be requested.

+

Default is `openid`.

$oidc_claim_username::

The link:{oidc-connect-core-url}#IDToken[ID Token] link:{oidc-connect-core-url}#StandardClaims[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 link:{oidc-connect-core-url}#IDToken[ID Token] link:{oidc-connect-core-url}#StandardClaims[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 link:{rfc6749-url}#section-3.1.2[Redirection Endpoint] previously registered at the Authorization Server.

If only a path is provided (not an absolute URL), it will be prepended with `{server-scheme-name-port}`.

+

Default is `/-/oidc/callback`, which corresponds to the _location_ in link: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 link:{oidc-rp-init-logout-url}[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 link: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 link: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 {ngx-docs-url}/ngx_http_proxy_module.html#proxy_cache_path[proxy cache] keys_zone for caching tokens.

+

This variable is *required.* footnote:[It has a default value in the module, but it must be defined for `proxy_cache` in link:conf/server.conf[].]

$oidc_cookie_attrs::

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#attributes[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`.footnote:[`SameSite=strict` doesn’t work with e.g. Microsoft ATP (that crap used when opening links from MS Teams) – `Set-Cookie` is not propagated.]

$oidc_error_pages_dir::

Path to the directory with error page templates.

See <> 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 https://opensource.org/licenses/MIT[MIT License].

For the full text of the license, see the link:LICENSE[] file.

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

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/jirutka/nginx-oidc-njs

Awesome Lists containing this project

README
