diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..2c0dd4c --- /dev/null +++ b/README.md @@ -0,0 +1,70 @@ +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_CLIENT_ID="<OAuth2 client id>" \ + OAUTH2_CLIENT_SECRET="<OAuth2 client secret>" \ + chkoauth2 \ + https://example.com/oauth/authorize \ + https://example.com/oauth/introspect \ + --scope create \ + another.cgi + +The sample script uses environment variables to provide the OAuth2 client +identity for interacting with the introspection endpoint, which is hosted at +example.com. 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. + |