lua-resty-http-digest

HTTP Digest Access Authentication in Lua for OpenResty

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.

Authors

Jian Zeng (knight42)

License

mit

Versions