The first security advice (initializeSecurity in the F3\FLOW3\Security\Aspect\RequestDispatchingAspect) initializes the security context holder for the current request. The default implementation (F3\FLOW3\Security\ContextHolderSession), shipped with FLOW3, lies in session scope and holds context data like the current authentication status. That means, if you need data related to security, the security context (you can get it easily from the security context holder) will be your main information source. The details of the context's data will be described in the next chapters.

First, let's see how you can use FLOW3's authentication features. There is a special controller in the security package: the AuthenticationController. This controller has two actions, namely authenticateAction() and logoutAction(), an appropriate route is configured. If you call http://localhost/flow3/authenticate in your Browser, the default authentication mechanism will be triggered. This mechanism, implemented in a so called authentication provider, authenticates an user account by checking an username and password against accounts stored in the content repository. ^[7]

The configuration for this default provider, which is shipped with FLOW3's default configuration looks like this:

FLOW3:
  security:
    authentication:
      providers:
        DefaultProvider:
          providerClass: PersistedUsernamePasswordProvider

This registers the PersistedUsernamePasswordProvider authentication provider under the name "DefaultProvider" as the only, global authentication mechanism. To successfully authenticate an account with this default provider, you'll obviously have to provide a username and password. This is done by sending two POST variables to the authentication controller. Have a look at the following HTML snippet with a simple login form you can use for that:

<form action="flow3/authenticate" method="post" name="loginform">
  <input type="text" id="username" name="F3\FLOW3\Security\Authentication\Token\UsernamePassword::username" value="" tabindex="1" />
  <input type="password" id="password" name="F3\FLOW3\Security\Authentication\Token\UsernamePassword::password" value="" tabindex="2" />
  <input type="submit" value="Login" tabindex="3" />
</form>

After submitting the form, the internal authentication process will be triggered and if you provided valid credentials an account will be authenticated afterwards^[8].

Now that you know, how you can authenticate someone, let's have a look at the internal process, how this works internally. The following sequence diagram shows the participating components and their interaction:

Figure 13.1. Internal authentication process

As already explained, the security framework is initialized in the dispatcher by vowing in an AOP advice, which resides in the RequestDispatchingAspect class. This advice intercepts the request dispatching before any controller is called. Regarding authentication, you can see, that a so called authentication token will be stored in the security context and some credentials will be updated in it.

In the previous section you have seen, how accounts can be authenticated in FLOW3. What was concealed so far is, how these accounts are created or what is exactly meant by the word "account". First of all let's define what accounts are in FLOW3 and how they are used for authentication. Following the OASIS CIQ V3.0^[10] specification, an account used for authentication is separated from an user or more general a party. The advantage of this separation is the possibility of one user having more than one account. E.g. an user could have an account for the UsernamePassword provider and one account connected to a LDAP authentication provider. Another scenario would be to have different accounts for different parts of your FLOW3 application. Read the next section "Advanced authentication configuration" to see how this can be accomplished.

As explained above, the account stores the credentials needed for authentication. Obviously these credentials are provider specific and therefore every account is only valid for a specific authentication provider. This provider - account connection is stored in a property of the account object named "authenticationProviderName". Appropriate getters and setters are provided. The provider name is configured in the Settings.yaml file. If you look back to the default configuration, you'll find the name of the default authentication provider: "DefaultProvider". Besides that, each account has another property called "credentialsSource", which points to the place or describes the credentials needed for this account. This could be a LDAP query string, or in case of the PersistedUsernamePasswordProvider provider, the username, password hash and salt are stored directly in this member variable.

It is the responsibility of the authentication provider to check the given credentials from the authentication token^[11], find the correct account for them and to decide about the authentication status of this account.

$account = $this->objectFactory->create('F3\Party\Domain\Model\Account');

$username = 'andi';
$password = 'secret';
$salt = 'someRandomSalt';

$credentials = md5(md5($password) . $salt) . ',' . $salt;

$roles = array(
  $this->objectFactory->create('F3\FLOW3\Security\ACL\Role', 'Administrator'),
);

$account->setAccountIdentifier($username);
$account->setCredentialsSource($credentials);
$account->setAuthenticationProviderName('TYPO3BEProvider');
$account->setRoles($roles);

$this->accountRepository->add($account);

One question that has not been answered so far is: what happens if the authentication process fails? In this case the authentication manager will throw an AuthenticationRequired exception. It might not be the best idea to let this exception settle its way up to the browser, right? Therefore we introduced a concept called authentication entry points. These entry points catch the mentioned exception and should redirect the user to a place where she can provide proper credentials. This could be a login page for the username/password provider or a HTTP header for HTTP authentication. An entry point can be configured for each authentication provider. Look at the following example, that redirects to a login page (Using the WebRedirect entry point).

security:
  authentication:
    providers:
      DefaultProvider:
        providerClass: PersistedUsernamePasswordProvider
        entryPoint:
          WebRedirect:
            uri: login/

This section explains the details of each authentication mechanism shipped with FLOW3. Mainly the configuration options and usage will be exposed, if you want to know more about the entire authentication process and how the components will work together, please have a look in the previous sections.

array(
  'username' => 'admin',
  'password' => 'plaintextPassword'
);

MD5HashOfThePassword,Salt

md5(md5($plaintextPasswordFromToken) . $saltFromCrendentialsSource) === $passwordHashFromCredentialsSource

$postArguments = $environment->getRawPostArguments();

$credentials['username'] = $postArguments['F3\FLOW3\Security\Authentication\Token\UsernamePassword::username'];
$credentials['password'] = $postArguments['F3\FLOW3\Security\Authentication\Token\UsernamePassword::password'];

One of the main goals for the authentication architecture was to provide an easily extensible infrastructure. Now that the authentication process has been explained, you'll find here the steps needed to implement your own authentication mechanism:

Authentication token

You'll have to provide an authentication token, that implements the interface F3\FLOW3\Security\Authentication\TokenInterface:

Authentication provider

After that you'll have to implement your own authentication strategy by providing a class, that implements the interface F3\FLOW3\Security\Authentication\AuthenticationProviderInterface:

The most general thing, which you want to protect in every application is the invocation of certain methods. By controlling, which methods are allowed to be called and which not, it can be globally ensured, that no unprivileged action will be executed at any time. This is what you would usually do, by adding an access check at the beginning of your privileged method. In FLOW3, there is the opportunity to enforce these checks without touching the actual method at all. Of course FLOW3's AOP features are used to realize this completely new perspective on authorization. If you want to learn more about AOP, please refer to the corresponding chapter in this reference.

First, let's have a look at the following sequence diagram to get an overview of what is happening when an authorization decision is formed and enforced:

Figure 13.2. How an authorization decision is formed and enforced in FLOW3

As already said, the whole authorization starts with an intercepted method, or in other words with a method that should be protected and only be called by privileged users. In the chapter about AOP you've already read, that every method interception is implemented in a so called advice, which resides in an aspect class. Here we are: the F3\FLOW3\Security\Aspect\PolicyEnforcementAspect. Inside this aspect there is the enforcePolicy() advice, which hands over to FLOW3's authorization components.

The next thing to be called is a security interceptor. This interceptor calls the authentication manager before it continues with the authorization process, to make sure that the authentication status is up to date. Then an access decision manager is called, which has to decide, if it is allowed to call the intercepted method. If not it throws an access denied exception. If you want, you could implement your own access decision manager. However, there is a very flexible one shipped with FLOW3 (F3\FLOW3\Security\Authorization\AccessDecisionVoterManager), which uses the following voting process to meet its decision:

On access decision voters

As you have seen, the default way of deciding on access is done by voting. This makes the whole authorization process very flexible and very easily extensible. You can at any time write your own voter classes and register them, just make sure to implement the interface F3\FLOW3\Security\Authorization\AccessDecisionVoterInterface. Then you have to register your custom voter as shown below:

security:
  authorization:
    accessDecisionVoters: [F3\FLOW3\Security\Authorization\Voter\Acl, F3\MyPackage\Security\MyCustomVoter]

If asked, each voter has to return one of the three possibles votes: grant, deny or abstain. There are appropriate constants defined in the voter interface, which you should use for that. You might imagine that a voter has to return an abstain vote, if it is not able to give a proper grant or deny vote.

Now it could be the case that all registered voters abstain. Usually the access decision manager will deny access then. However, you can change set by configuring the following option:

security: authorization: allowAccessIfAllVotersAbstain: FALSE

Besides the AOP powered authorization, there is another line of defense: the filter firewall. This firewall is triggered directly when a request arrives at the MVC dispatcher. After that the request is analyzed and can be blocked/filtered out. This adds a second level of security right at the beginning of the whole framework run, which means that a minimal amount of potentially insecure code will be executed before that.

Figure 13.3. Blocking request with FLOW3's filter firewall

The firewall itself is added to the MVC dispatcher by AOP, to completely decouple security from the MVC framework and to have the possibility of disabling security. Blocking requests with the firewall is not a big thing at all, basically a request filter object is called, which consists of a request pattern and a security interceptor. The simple rules is: if the pattern matches on the request, the interceptor is invoked. Request patterns are also used by the authentication components and are explained in detail there. Talking about security interceptors: you already know the policy enforcement interceptor, which triggers the authorization process. Here is a table of available interceptors, shipped with FLOW3:

Of course you are able to configure as many requests filters as you like. Have a look at the following example to get an idea how a firewall configuration will look like:

FLOW3:
  security:
    firewall:
      rejectAll: n

      filters:
        -
          patternType:  URL
          patternValue: /some/url/.*
          interceptor:  AccessGrant
        -
          patternType:  URL
          patternValue: /some/url/blocked.*
          interceptor:  AccessDeny
        -
          patternType:  F3\MyPackage\Security\MyOwnRequestPattern
          patternValue: some pattern value
          interceptor:  F3\MyPackage\Security\MyOwnSecurityInterceptor

Now that the policy is technically enforced, these rules should also be reflected in the view. E.g. a button or link to delete a customer should not be shown, if the user has not the privilege to do so. If you are using the recommended Fluid templating engine, you can simply use the security view helpers shipped with Fluid. Otherwise you would have to ask the policy service (F3\FLOW3\Security\ACL\PolicyService) for the current privilege situation and implement the view logic on your own, however this seems not to be the best idea one can have. Below you'll find a short description of the available Fluid view helpers.

<f:security.ifAccess resource="someResource">
  This is being shown in case you have access to the given resource
</f:security.ifAccess>

<f:security.ifAccess resource="someResource">
  <f:then>
    This is being shown in case you have access.
  </f:then>
  <f:else>
    This is being displayed in case you do not have access.
  </f:else>
</f:security.ifAccess>

<f:security.ifHasRole role="Administrator">
  This is being shown in case you have the Administrator role (aka role).
</f:security.ifHasRole>

<f:security.ifHasRole role="Administrator">
  <f:then>
    This is being shown in case you have the role.
  </f:then>
  <f:else>
    This is being displayed in case you do not have the role.
  </f:else>
</f:security.ifHasRole>