lua-resty-openidc

[![CI Status](https://github.com/zmartzone/lua-resty-openidc/actions/workflows/docker-ci.yml/badge.svg)](https://github.com/zmartzone/lua-resty-openidc/actions/workflows/docker-ci.yml)
[<img width="184" height="96" align="right" src="http://openid.net/wordpress-content/uploads/2016/04/oid-l-certification-mark-l-rgb-150dpi-90mm@2x.png" alt="OpenID Certification">](https://openid.net/certification)

# lua-resty-openidc

**lua-resty-openidc** is a library for [NGINX](http://nginx.org/) implementing the
[OpenID Connect](http://openid.net/specs/openid-connect-core-1_0.html) **Relying Party (RP)**
and/or the [OAuth 2.0](https://tools.ietf.org/html/rfc6749) **Resource Server (RS)** functionality.

When used as an OpenID Connect Relying Party it authenticates users against an OpenID Connect
Provider using [OpenID Connect Discovery](http://openid.net/specs/openid-connect-discovery-1_0.html)
and the Basic Client Profile (i.e. the Authorization Code flow). When used as an OAuth 2.0
Resource Server it can validate OAuth 2.0 Bearer Access Tokens against an Authorization Server or, in
case a JSON Web Token is used for an Access Token, verification can happen against a pre-configured secret/key .

It maintains sessions for authenticated users by leveraging `lua-resty-session` thus offering
a configurable choice between storing the session state in a client-side browser cookie or use
in of the server-side storage mechanisms `shared-memory|memcache|redis`.

It supports server-wide caching of resolved Discovery documents and validated Access Tokens.

It can be used as a reverse proxy terminating OAuth/OpenID Connect in front of an origin server so that
the origin server/services can be protected with the relevant standards without implementing those on
the server itself.

## Dependencies

**lua-resty-openidc** depends on the following packages:

- [NGINX](http://nginx.org/) and [`ngx_devel_kit`](https://github.com/simpl/ngx_devel_kit)
- [Lua](http://www.lua.org/) or [LuaJIT](http://luajit.org/luajit.html)
- [`lua-nginx-module`](https://github.com/openresty/lua-nginx-module)
- [`lua-cjson`](http://www.kyne.com.au/~mark/software/lua-cjson.php)
- [`lua-resty-string`](https://github.com/openresty/lua-resty-string)

The dependencies above come automatically with [OpenResty](http://openresty.org/). You will need
to install two extra pure-Lua dependencies that implement session management and HTTP client functions:

- [`lua-resty-http`](https://github.com/pintsized/lua-resty-http)
- [`lua-resty-session`](https://github.com/bungle/lua-resty-session)

Typically - when running as an OpenID Connect RP or an OAuth 2.0 server that consumes JWT
access tokens - you'll also need to install the following dependency:

- [`lua-resty-jwt`](https://github.com/cdbattags/lua-resty-jwt)

The `lua-resty-jwt` dependency above is *not* required when running as an OAuth 2.0 Resource Server (only) using remote
introspection for access token validation.

## Installation

Using `luarocks` execu