<commit_before>nginx-dlg-auth
==============

NGINX module for delegating authentication and authorization to an HTTP gateway.

nginx-dlg-auth combines [Hawk](https://github.com/hueniverse/hawk) and [iron](https://github.com/hueniverse/iron) to enable authentication and
authorization using encapsulated tokens.

The token format has been inspired by [Oz](https://github.com/hueniverse/oz) but is
different for now, because in the long run, I think I have somewhat different use
cases than Oz is aiming at.

This is all somewhat experimental and will evolve over the next months.

The token format right now is

    {"client":"test01","pwd":"<PASSWORD><","scopes":["api.example.org|NEWS"],\
    "rw":false,"exp":1405688331,"hawkAlgorithm":"sha256"}

and combines password and algorithm to be used with Hawk as well as access rights
and token expiration time.


Status
======

nginx-dlg-auth is in pre-release state from tghe point of view of Hawk and iron support.
It could well be used without the specific token syntax by providing Hawk credentials
in another way.

There hasn't been any thorough testing
so far nor is there any production experience. However, this NGINX module will
be used in production shortly and then generate enough feedback to allow for
aiming at a public version 1.0.


Installation
============

Note: I am working on an RPM-install of NGINX including the module.

This NGINX module needs [ciron](https://github.com/algermissen/ciron)
and [hawkc](https://github.com/algermissen/hawkc). Build them separately
and adjust nginx-dlg-auth's config file to point to libciron.a and libhawkc.a.

Also, copy the header files ciron.h and hawkc.h to a standard header file location
on your machine.

Configure NGINX build like this:


    ./configure --add-module=/path/to/code/nginx-dlg-auth

You may also want to add the library file to $LINK_DEPS to make
sure nginx will correctly relink itself on make if library
changes."

NGINX Module Configuration
==========================

    dlg_auth <realm> 

    dlg_auth_iron_pwd <password>  OR <passwordID> <password>

    dlg_auth_allowed_clock_skew <allowed-skew-in-seconds>

    dlg_auth_host <hostname>

    dlg_auth_port <port>

## dlg_auth

If dlg_auth is missing or if realm is 'off', the module will not be enabled.

## dlg_auth_iron_pwd

You can use dlg_auth_iron_pwd to either set a single password, or to provide
a set of passwordIds and password to enable password rotation.



Examples
<commit_msg>Added documentation<commit_after>nginx-dlg-auth
==============

NGINX module for delegating authentication and authorization to an HTTP gateway.

nginx-dlg-auth combines [Hawk](https://github.com/hueniverse/hawk) and [iron](https://github.com/hueniverse/iron) to enable authentication and
authorization using encapsulated tokens.

The token format has been inspired by [Oz](https://github.com/hueniverse/oz) but is
different for now, because in the long run, I think I have somewhat different use
cases than Oz is aiming at.

This is all somewhat experimental and will evolve over the next months.

The token format right now is

    {"client":"test01","pwd":"<PASSWORD><","scopes":["api.example.org|NEWS"],\
    "rw":false,"exp":1405688331,"hawkAlgorithm":"sha256"}

and combines password and algorithm to be used with Hawk as well as access rights
and token expiration time.


Status
======

nginx-dlg-auth is in pre-release state from tghe point of view of Hawk and iron support.
It could well be used without the specific token syntax by providing Hawk credentials
in another way.

There hasn't been any thorough testing
so far nor is there any production experience. However, this NGINX module will
be used in production shortly and then generate enough feedback to allow for
aiming at a public version 1.0.


Installation
============

Note: I am working on an RPM-install of NGINX including the module.

This NGINX module needs [ciron](https://github.com/algermissen/ciron)
and [hawkc](https://github.com/algermissen/hawkc). Build them separately
and adjust nginx-dlg-auth's config file to point to libciron.a and libhawkc.a.

Also, copy the header files ciron.h and hawkc.h to a standard header file location
on your machine.

Configure NGINX build like this:


    ./configure --add-module=/path/to/code/nginx-dlg-auth

You may also want to add the library file to $LINK_DEPS to make
sure nginx will correctly relink itself on make if library
changes."

NGINX Module Configuration
==========================

    dlg_auth <realm> 

    dlg_auth_iron_pwd <password>  OR <passwordID> <password>

    dlg_auth_allowed_clock_skew <allowed-skew-in-seconds>

    dlg_auth_host <hostname>

    dlg_auth_port <port>

## dlg_auth

Enables access delegation checking. The parameter is the authentication realm.
Tickets must inlcude this realm in their scope list to gain access.

If dlg_auth is missing or if realm is 'off', the module will not be enabled.
The 'off' value can be used to disable authentication checking in locations
that have parent locations that enable checking.

## dlg_auth_iron_pwd

You can use dlg_auth_iron_pwd to either set a single password, or to provide
a set of passwordIds and password to enable password rotation.


## dlg_auth_allowed_clock_skew 

Explicitly set the allowed clock skew in seconds. The default is 1 second.

If you set this to 0 clock skew will not be checed. This is useful for
monitoring checks.

## dlg_auth_host <hostname>

Explicitly set the host used for signature validation.

## dlg_auth_port <port>

Explicitly set the port used for signature validation.


Examples

{'fraction_non_alphanumeric': 0.08644400785854617, 'fraction_numerical': 0.006429719592784426, 'mean_word_length': 4.4955839057899905, 'pattern_counts': {'":': 12, '<': 23, '<?xml version=': 0, '>': 21, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4834897', 'n_tokens_mistral': 1696, 'n_tokens_neox': 1586, 'n_words': 704}