](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
+
+If you're using `opm` execute the following:
+
+ opm install zmartzone/lua-resty-openidc
+
+If you're using `luarocks` execute the following:
+
+ luarocks install lua-resty-openidc
+
+Otherwise copy `openidc.lua` somewhere in your `lua_package_path` under a directory named `resty`.
+If you are using [OpenResty](http://openresty.org/), the default location would be `/usr/local/openresty/lualib/resty`.
+
+
+## Support
+
+#### Community Support
+For generic questions, see the Wiki pages with Frequently Asked Questions at:
+ [https://github.com/zmartzone/lua-resty-openidc/wiki](https://github.com/zmartzone/lua-resty-openidc/wiki)
+Any questions/issues should go to issues tracker.
+
+#### Commercial Services
+For commercial Support contracts, Professional Services, Training and use-case specific support you can contact:
+ [sales@zmartzone.eu](mailto:sales@zmartzone.eu)
+
+
+## Sample Configuration for Google+ Signin
+
+Sample `nginx.conf` configuration for authenticating users against Google+ Signin, protecting a reverse-proxied path.
+
+```
+events {
+ worker_connections 128;
+}
+
+http {
+
+ lua_package_path '~/lua/?.lua;;';
+
+ resolver 8.8.8.8;
+
+ lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
+ lua_ssl_verify_depth 5;
+
+ # cache for discovery metadata documents
+ lua_shared_dict discovery 1m;
+ # cache for JWKs
+ lua_shared_dict jwks 1m;
+
+ # NB: if you have "lua_code_cache off;", use:
+ # set $session_secret xxxxxxxxxxxxxxxxxxx;
+ # see: https://github.com/bungle/lua-resty-session#notes-about-turning-lua-code-cache-off
+
+ server {
+ listen 8080;
+
+ location / {
+
+ access_by_lua_block {
+
+ local opts = {
+ -- the full redirect URI must be protected by this script
+ -- if the URI starts with a / the full redirect URI becomes
+ -- ngx.var.scheme.."://"..ngx.var.http_host..opts.redirect_uri
+ -- unless the scheme was overridden using opts.redirect_uri_scheme or an X-Forwarded-Proto header in the incoming request
+ redirect_uri = "https://MY_HOST_NAME/redirect_uri",
+ -- up until version 1.6.1 you'd specify
+ -- redirect_uri_path = "/redirect_uri",
+ -- and could not set the hostname
+
+ -- The discovery endpoint of the OP. Enable to get the URI of all endpoints (Token, introspection, logout...)
+ discovery = "https://accounts.google.com/.well-known/openid-configuration",
+
+ -- Access to OP Token endpoint requires an authentication. Several authentication modes are supported:
+ --token_endpoint_auth_method = ["client_secret_basic"|"client_secret_post"|"private_key_jwt"|"client_secret_jwt"],
+ -- o If token_endpoint_auth_method is set to "client_secret_basic", "client_secret_post", or "client_secret_jwt", authentication to Token endpoint is using client_id and client_secret
+ -- For non compliant OPs to OAuth 2.0 RFC 6749 for client Authentication (cf. https://tools.ietf.org/html/rfc6749#section-2.3.1)
+ -- client_id and client_secret MUST be invariant when url encoded
+ client_id = "{{message}}
+ + +``` + +##### Output +```html + + + +Hello, World!
+ + +``` + +The same can be done with inline template string: + +```lua +-- Using template string +template.render([[ + + + +{{message}}
+ +]], { message = "Hello, World!" }) +``` + +## Contents + +* [Template Syntax](#template-syntax) + * [Reserved Context Keys and Remarks](#reserved-context-keys-and-remarks) +* [Installation](#installation) + * [Using LuaRocks or Moonrocks](#using-luarocks-or-moonrocks) +* [Nginx / OpenResty Configuration](#nginx--openresty-configuration) +* [Lua API](#lua-api) + * [template.caching](#boolean-templatecachingboolean-or-nil) + * [template.new](#table-templatenewview-layout) + * [template.compile](#function-boolean-templatecompileview-key) + * [template.render](#templaterenderview-context-key) + * [template.parse](#string-templateparseview) + * [template.precompile](#string-templateprecompileview-path-strip) + * [template.load](#templateload) + * [template.print](#templateprint) +* [Template Precompilation](#template-precompilation) +* [Template Helpers](#template-helpers) +* [Usage Examples](#usage-examples) + * [Template Including](#template-including) + * [Views with Layouts](#views-with-layouts) + * [Using Blocks](#using-blocks) + * [Grandfather-Father-Son Inheritance](#grandfather-father-son-inheritance) + * [Macros](#macros) + * [Calling Methods in Templates](#calling-methods-in-templates) + * [Embedding Angular or other tags / templating inside the Templates](#embedding-angular-or-other-tags--templating-inside-the-templates) + * [Embedding Markdown inside the Templates](#embedding-markdown-inside-the-templates) + * [Lua Server Pages (LSP) with OpenResty](#lua-server-pages-lsp-with-openresty) +* [FAQ](#faq) +* [Alternatives](#alternatives) +* [Benchmarks](#benchmarks) +* [Changes](#changes) +* [License](#license) + +## Template Syntax + +You may use the following tags in templates: + +* `{{expression}}`, writes result of expression - html escaped +* `{*expression*}`, writes result of expression +* `{% lua code %}`, executes Lua code +* `{(template)}`, includes `template` file, you may also supply context for include file `{(file.html, { message = "Hello, World" } )}` +* `{[expression]}`, includes `expression` file (the result of expression), you may also supply context for include file `{["file.html", { message = "Hello, World" } ]}` +* `{-block-}...{-block-}`, wraps inside of a `{-block-}` to a value stored in a `blocks` table with a key `block` (in this case), see [using blocks](https://github.com/bungle/lua-resty-template#using-blocks). Don't use predefined block names `verbatim` and `raw`. +* `{-verbatim-}...{-verbatim-}` and `{-raw-}...{-raw-}` are predefined blocks whose inside is not processed by the `lua-resty-template` but the content is outputted as is. +* `{# comments #}` everything between `{#` and `#}` is considered to be commented out (i.e. not outputted or executed) + +From templates you may access everything in `context` table, and everything in `template` table. In templates you can also access `context` and `template` by prefixing keys. + +```html +{{message}}
=={{context.message}}
+``` + +##### Short Escaping Syntax + +If you don't want a particular template tag to be processed you may escape the starting tag with backslash `\`: + +```html +\{{message}}
+``` + +This will output (instead of evaluating the message): + +```html +{{message}}
+``` + +If you want to add backslash char just before template tag, you need to escape that as well: + +```html +\\{{message}}
+``` + +This will output: + +```html +\[message-variables-content-here]
+``` + +##### A Word About Complex Keys in Context Table + +Say you have this kind of a context table: + +```lua +local ctx = {["foo:bar"] = "foobar"} +``` + +And you want to render the `ctx["foo:bar"]`'s value `foobar` in your template. You have to specify it explicitly by referencing the `context` in your template: + +```html +{# {*["foo:bar"]*} won't work, you need to use: #} +{*context["foo:bar"]*} +``` + +Or altogether: + +```lua +template.render([[ +{*context["foo:bar"]*} +]], {["foo:bar"] = "foobar"}) +``` + +##### A Word About HTML Escaping + +Only strings are escaped, functions are called without arguments (recursively) and results are returned as is, other types are `tostring`ified. `nil`s and `ngx.null`s are converted to empty strings `""`. + +Escaped HTML characters: + +* `&` becomes `&` +* `<` becomes `<` +* `>` becomes `>` +* `"` becomes `"` +* `'` becomes `'` +* `/` becomes `/` + +#### Example +##### Lua +```lua +local template = require "resty.template" +template.render("view.html", { + title = "Testing lua-resty-template", + message = "Hello, World!", + names = { "James", "Jack", "Anne" }, + jquery = '' +}) +``` + +##### view.html +```html +{(header.html)} +{{message}}
+-
+{% for _, name in ipairs(names) do %}
+
- {{name}} +{% end %} +
{{message}}
]] -- or +local view = template.new([[{{message}}
]], [[ + + + {*view*} + + +]]) +``` + +##### Example +```lua +local template = require "resty.template" +local view = template.new"view.html" +view.message = "Hello, World!" +view:render() +-- You may also replace context on render +view:render{ title = "Testing lua-resty-template" } +-- If you want to include view context in replacement context +view:render(setmetatable({ title = "Testing lua-resty-template" }, { __index = view })) +-- To get rendered template as a string, you can use tostring +local result = tostring(view) +``` + +#### function, boolean template.compile(view, key, plain) + +Parses, compiles and caches (if caching is enabled) a template and returns the compiled template as a function that takes context as a parameter and returns rendered template as a string. Optionally you may pass `key` that is used as a cache key. If cache key is not provided `view` wil be used as a cache key. If cache key is `no-cache` the template cache will not be checked and the resulting function will not be cached. You may also optionally pass `plain` with a value of `true` if the `view` is plain text string (this will skip `template.load` and binary chunk detection in `template.parse` phase). + +```lua +local func = template.compile("template.html") -- or +local func = template.compile([[{{message}}
]]) +``` + +##### Example +```lua +local template = require "resty.template" +local func = template.compile("view.html") +local world = func{ message = "Hello, World!" } +local universe = func{ message = "Hello, Universe!" } +print(world, universe) +``` + +Also note the second return value which is a boolean. You may discard it, or use it to determine if the returned function was cached. + +#### template.render(view, context, key, plain) + +Parses, compiles, caches (if caching is enabled) and outputs template either with `ngx.print` if available, or `print`. You may optionally also pass `key` that is used as a cache key. If `plain` evaluates to `true`, the `view` is considered to be plain string template (`template.load` and binary chunk detection is skipped on `template.parse`). + +```lua +template.render("template.html", { message = "Hello, World!" }) -- or +template.render([[{{message}}
]], { message = "Hello, World!" }) +``` + +##### Example +```lua +local template = require "resty.template" +template.render("view.html", { message = "Hello, World!" }) +template.render("view.html", { message = "Hello, Universe!" }) +``` + +#### string template.parse(view, plain) + +Parses template file or string, and generates a parsed template string. This may come useful when debugging templates. You should note that if you are trying to parse a binary chunk (e.g. one returned with `template.compile`), `template.parse` will return that binary chunk as is. If optional parameter `plain` evaluates to `true`, the `view` is considered to be plain string, and the `template.load` and binary chunk detection is skipped. + +```lua +local t1 = template.parse("template.html") +local t2 = template.parse([[{{message}}
]]) +``` + +#### string template.precompile(view, path, strip) + +Precompiles template as a binary chunk. This binary chunk can be written out as a file (and you may use it directly with Lua's `load` and `loadfile`). For convenience you may optionally specify `path` argument to output binary chunk to file. You may also supply `strip` parameter with value of `false` to make precompiled templates to have debug information as well (defaults to `true`). + +```lua +local view = [[ +{{title}}
+-
+{% for _, v in ipairs(context) do %}
+
- {{v}} +{% end %} +
-
+{% for _, person in ipairs(context) do %}
+ {*html.li(person.name)*}
+{% end %}
+
-
+
- Emma +
- James +
- Nicholas + +
| Emma | +
| James | +
| Nicholas | +
| + |
-
+{% for _, user in ipairs(users) do %}
+ {(user.html, user)}
+{% end %}
+
-
+
- User Jane is of age 29 +
- User John is of age 25 +
{{message}}
+``` + +##### layout.html +```html + + + +{{message}}
+``` + +##### section.html +```html +
+ {*view*}
+
+```
+
+##### layout.html
+```html
+
+
+
+
+
+
+
+```
+
+### Using Blocks
+
+Blocks can be used to move different parts of the views to specific places in layouts. Layouts have placeholders for blocks.
+
+##### Lua
+```lua
+local view = template.new("view.html", "layout.html")
+view.title = "Testing lua-resty-template blocks"
+view.message = "Hello, World!"
+view.keywords = { "test", "lua", "template", "blocks" }
+view:render()
+```
+
+##### view.html
+```html
+Hello, World!
+{{message}}
+{-aside-} +-
+ {% for _, keyword in ipairs(keywords) do %}
+
- {{keyword}} + {% end %} +
Hello, World!
+
+ {* blocks.content *}
+
+{-main-}
+```
+
+##### layout2.html
+
+```html
+{% layout = "base.html" %}
+{-main-}
+
+
+ {* blocks.content *}
+
+ I am different from layout1
+{-main-}
+```
+
+##### page.html
+
+```html
+{% layout = "layout1.html" %}
+{-sidebar-}
+ this is sidebar
+{-sidebar-}
+
+{-content-}
+ this is content
+{-content-}
+
+{-page_css-}
+
+{-page_css-}
+
+{-page_js-}
+
+{-page_js-}
+```
+
+Or:
+
+##### page.html
+
+```html
+{% layout = "layout2.html" %}
+{-sidebar-}
+ this is sidebar
+{-sidebar-}
+
+{-content-}
+ this is content
+{-content-}
+
+{-page_css-}
+
+{-page_css-}
+
+{-page_js-}
+
+{-page_js-}
+```
+
+### Macros
+
+[@DDarko](https://github.com/DDarko) mentioned in an [issue #5](https://github.com/bungle/lua-resty-template/issues/5) that he has a use case where he needs to have macros or parameterized views. That is a nice feature that you can use with `lua-resty-template`.
+
+To use macros, let's first define some Lua code:
+
+```lua
+template.render("macro.html", {
+ item = "original",
+ items = { a = "original-a", b = "original-b" }
+})
+```
+
+And the `macro-example.html`:
+
+```lua
+{% local string_macro = [[
+{{item}}
+]] %}
+{* template.compile(string_macro)(context) *}
+{* template.compile(string_macro){ item = "string-macro-context" } *}
+```
+
+This will output:
+
+```html
+original
+string-macro-context
+```
+
+Now let's add function macro, in `macro-example.html` (you can omit `local` if you want):
+
+```lua
+{% local function_macro = function(var, el)
+ el = el or "div"
+ return "<" .. el .. ">{{" .. var .. "}}\n"
+end %}
+
+{* template.compile(function_macro("item"))(context) *}
+{* template.compile(function_macro("a", "span"))(items) *}
+```
+
+This will output:
+
+```html
+original
+original-a
+```
+
+But this is even more flexible, let's try another function macro:
+
+```lua
+{% local function function_macro2(var)
+ return template.compile("{{" .. var .. "}}
\n")
+end %}
+{* function_macro2 "item" (context) *}
+{* function_macro2 "b" (items) *}
+```
+
+This will output:
+
+```html
+original
+original-b
+```
+
+And here is another one:
+
+```lua
+{% function function_macro3(var, ctx)
+ return template.compile("{{" .. var .. "}}
\n")(ctx or context)
+end %}
+{* function_macro3("item") *}
+{* function_macro3("a", items) *}
+{* function_macro3("b", items) *}
+{* function_macro3("b", { b = "b-from-new-context" }) *}
+```
+
+This will output:
+
+```html
+original
+original-a
+original-b
+b-from-new-context
+```
+
+Macros are really flexible. You may have form-renderers and other helper-macros to have a reusable and parameterized template output. One thing you should know is that inside code blocks (between `{%` and `%}`) you cannot have `%}`, but you can work around this using string concatenation `"%" .. "}"`.
+
+### Calling Methods in Templates
+
+You can call string methods (or other table functions) in templates too.
+
+##### Lua
+```lua
+local template = require "resty.template"
+template.render([[
+