README

A collection of Stack middlewares designed to help authentication middleware implementors adhere to the STACK-2 Authentication conventions.

Installation

Through Composer as dflydev/stack-authentication.

Middlewares

Authentication Middleware

The Authentication middleware takes care of setting up the handling of an inbound request by taking care of some STACK-2 Authentication housekeeping tasks:

• If the stack.authn.token is set, it wraps the application in WwwAuthenticateStackChallenge and delegates.
• Checks the request by calling the check callback. The return value is a boolean. If true, the authenticate callback is called and its return value is returned. If false, we should not. The default check is to see if there is an Authorization header.
• If anonymous requests are received and anonymous requests are allowed, it wraps the application in WwwAuthenticateStackChallenge and delegates.
• Otherwise, it returns the result of the challenge callback.

Usage

<?php

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\HttpKernelInterface;

$check = function (
 Request $request,
 $type = HttpKernelInterface::MASTER_REQUEST,
 $catch = true
) {
 // This is the default 'check' callback if a check callback is not defined.
 // This is here merely for demonstration purposes; if authentication relies
 // on the existence of an 'authorization' header a 'check' callback does not
 // need to be defined.
 return $request->headers->has('authorization');
};

$challenge = function (Response $response) {
 // Assumptions that can be made:
 // * 401 status code
 // * WWW-Authenticate header with a value of "Stack"
 //
 // Expectations:
 // * MAY set WWW-Authenticate header to another value
 // * MAY return a brand new response (does not have to be
 // the original response)
 // * MUST return a response
 return $response;
};

$authenticate = function (HttpKernelInterface $app, $anonymous) {
 // Assumptions that can be made:
 // * The $app can be delegated to at any time
 // * The anonymous boolean indicates whether or not we
 // SHOULD allow anonymous requests through or if we
 // should challenge immediately.
 // * Additional state, like $request, $type, and $catch
 // should be passed via use statement if they are needed.
 //
 // Expectations:
 // * SHOULD set 'stack.authn.token' attribute on the request
 // when authentication is successful.
 // * MAY delegate to the passed $app
 // * MAY return a custom response of any status (for example
 // returning a 302 or 400 status response is allowed)
 // * MUST return a response
};

$app = new Authentication($app, [
 'challenge' => $challenge,
 'check' => $check,
 'authenticate' => $authenticate,
 'anonymous' => true, // default: false
]);

WwwAuthenticateStackChallenge Middleware

The WwwAuthenticateStackChallenge middleware takes care of setting up the handling of an outbound response by taking care of some STACK-2 Authentication housekeeping tasks:

• If the response has a 401 status code and has a WWW-Authenticate header with the value of Stack, it returns the result of the challenge callback.
• Otherwise the original response from the delegated app is returned.

Usage

<?php

use Symfony\Component\HttpFoundation\Response;

$challenge = function (Response $response) {
 // Assumptions that can be made:
 // * 401 status code
 // * WWW-Authenticate header with a value of "Stack"
 //
 // Expectations:
 // * MAY set WWW-Authenticate header to another value
 // * MAY return a brand new response (does not have to be
 // the original response)
 // * MUST return a response
 return $response;
};

return (new WwwAuthenticateStackChallenge($app, $challenge))
 ->handle($request, $type, $catch);

License

MIT, see LICENSE.

Community

If you have questions or want to help out, join us in the #stackphp or #dflydev channels on irc.freenode.net.