$ opm get knight42/lua-resty-http-digest

Name

lua-resty-http-digest

Status

beta

Description

lua-resty-http-digest library implements "HTTP Digest Access Authentication"(specified by RFC7616) in Lua for OpenResty.

Synopsis

    lua_package_path "/path/to/lua-resty-http-digest/lib/?.lua;;";
    
    location = /protected {
        access_by_lua_block {
            local http_digest = require 'resty.http_digest'
            local t, err = http_digest:new({
                get_password = function(name) return 'root' end,
                realm = 'example.com',
                nonce_age = 60,
                auth_timeout = 60,
                max_replays = 20,
                algorithm = http_digest.MD5,
                redis = {
                    db = '0',
                    host = '127.0.0.1',
                    port = 6379,
                    timeout = 1000,
                    keepalive_idle_timeout = 20000,
                    keepalive_pool_size = 5,
                },
            })
            if err then
                ngx.status = 500
                ngx.log(ngx.ERR, err)
                ngx.exit(500)
            end
            local auth, err = t:authenticate()
            if ngx.status == ngx.HTTP_UNAUTHORIZED then
                -- send challenge
                ngx.exit(ngx.status)
            end
    
            if err then
                ngx.log(ngx.ERR, err)
                ngx.exit(ngx.status)
            end
    
            ngx.say('Welcome ' .. auth.username)
        }
    }

Methods

new

syntax: t, err = class:new(opts)

Creates an authenticator object. Returns nil and a message string on error.

It accepts a opts table argument. The following options are supported:

• get_password: a function that returns (password, error) for the given username.

  Required. The signature of the function is: (username: string) -> (password: string, error)

• realm

  Optional. Default: ngx.var.http_host

• nonce_age: TTL of nonce in seconds

  Optional. Default: 60

• auth_timeout: Specify how many seconds challenges will remain valid after server sends them to clients.

  Optional. Default: 60

• max_replays: The times that a nonce can be re-used.

  Optional. Default: 20

• algorithm

  Optional. Default: http_digest.MD5. Available: http_digest.MD5, http_digest.SHA256

• redis.db

  Optional. Default: 0

• redis.host

  Optional. Default: 127.0.0.1

• redis.port

  Optional. Default: 6379

• redis.timeout

  Optional. Default: 1000(1 sec)

• redis.keepalive_idle_timeout

  Optional. Default: nil. See also https://github.com/openresty/lua-resty-redis#set_keepalive

• redis.keepalive_pool_size

  Optional. Default: nil See also https://github.com/openresty/lua-resty-redis#set_keepalive

authenticate

syntax: info, err = t:authenticate()

Validates the Authorization header and returns information extracted from Authorization header. In case of errors, it will set corresponding status code and returns an error message.

Installation

Limitations

• realm cannot contain space char or quote

• only support MD5 and SHA256 algorithms, *-sess algorithms are not implemented

• only auth qop is supported

Author

GitHub @knight42

License

lua-resty-http-digest is licensed under the MIT license.