Document available options

[deadghost]

I'm having difficulty figuring out how all the middleware and options work together.

There are three middleware: wrap-access-rules, wrap-authentication, wrap-authorization. How do these work together and which are necessary? It seems like if I use wrap-access-rules, I may omit wrap-authorization.

What options are available for backends? I see :unauthorized-handler, does a :unauthenticated-handler exist?
What options are available for wrap-access-rules? I see :rules and :on-error. Does/should :on-error handle unauthenticated requests? Unauthorized requests? When should :on-error be used instead of the :unauthorized-handler option specified in the backend?

These concerns should be better documented.

[niwinz]

Thanks for the suggestion, I'll try to improve the documentation with your considerations.

[morgancmartin]

Just adding on to this:

The token backends (jws/jwe/token) will not authenticate a request unless a token-name is specified when creating the backend. I followed your jws-backend example (which does not specify a :token-name) and was unable to properly authenticate my requests. It took a fair amount of digging into the source to figure out that it was the lack of a :token-name that was causing it to silently fail.

So, either I missed something in the docs/example, or the docs/example need to be updated to reflect the necessity of the :token-name. And it would likely make sense to go one step further and just document all of the options passed to the backends.

I would be happy (and honored!) to make a PR if you'd like. Cheers!