chkoauth2
=========

chkoauth2 is a CGI-based wrapper which will validate OAuth2 bearer tokens before
executing another script.

chkoauth2 also includes an IndieAuth extension, which will pass the user's
profiler URL to the wrapped script. See the IndieAuth specification for more
information: https://indieauth.spec.indieweb.org/#access-token-verification


INSTALLATION
------------

You will need Rust and Cargo to build and install this project.

To install in your home directory, run:

  cargo install --path .

To disable the IndieAuth extension, add the `--no-default-features` flag. To
install elsewhere, use the --root flag. See `cargo install --help` for more
options.


USAGE
-----

You'll need a web server that can run CGI scripts, then you'll want a script
that runs chkoauth2 with the appropriate options. Something like:

    #!/bin/sh
    OAUTH2_AUTHORIZATION_URL="https://example.com/authorize" \
    OAUTH2_INTROSPECTION_URL="https://example.com/introspect" \
    OAUTH2_CLIENT_ID="<OAuth2 client id>" \
    OAUTH2_CLIENT_SECRET="<OAuth2 client secret>" \
    chkoauth2 --scope create another.cgi

The sample script is using environment variables to provide the configuration
for the OAuth2 authorization server. chkoauth2 expects your web server to
provided the Authorization header in the `HTTP_AUTHORIZATION` environment
variable. If the header contains a valid Bearer token, and the token grants the
required scope(s) ("create", in this case), then chkoauth2 will invoke
`another.cgi`. Otherwise, an appropriate error will be returned.

The full list of granted scopes is passed to the application through the
`OAUTH2_SCOPES` environment variable, allowing the wrapped CGI to check for an
optional scope. If the IndieAuth extension is enabled, the profile URL is passed
in the `INDIEAUTH_ME` environment variable.

chkoauth2 can log debug and warning information to stderr. The log level is set
by adding the `RUST_LOG` environment variable to `error`, `warn`, `info`,
`debug`, or `trace`.


CONTRIBUTING
------------

Send feedback, questions, or patches to jesse@jesterpm.net.


LICENSE
-------

This software is distributed under the MIT License. See LICENSE for more
information.