Security¶

Security context¶

The first security advice (initializeSecurity in the TYPO3\FLOW3\Security\Aspect\RequestDispatchingAspect) initializes the security context for the current request. The security context (TYPO3\FLOW3\Security\Context) 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 with dependency injection) will be your main information source. The details of the context’s data will be described in the next chapters.

Using the authentication controller¶

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 a user account by checking a username and password against accounts stored in the content repository. [1]

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

Example: Configuration of the default username/password authentication mechanism in Settings.yaml

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:

Example: A simple login form

<form action="flow3/authenticate" method="post" name="loginform">
        <input type="text" id="username"
                name="__authentication[TYPO3][FLOW3][Security][Authentication][Token][UsernamePassword][username]"
                value="" tabindex="1" />
        <input type="password" id="password"
                name="__authentication[TYPO3][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. [2]

The internal authentication process¶

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

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.

Account management¶

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 [4] specification, an account used for authentication is separated from a user or more general a party. The advantage of this separation is the possibility of one user having more than one account. E.g. a user could have an account for the UsernamePassword provider and one account connected to an 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 an 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, find the correct account for them [5] and to decide about the authentication status of this account.

$identifier = 'andi';
$password = 'secret';
$roles = array('Administrator');
$authenticationProviderName = 'DefaultProvider';

$account = $this->accountFactory->createAccountWithPassword($identifier, $password, $roles, $authenticationProviderName);
$this->accountRepository->add($account);

Advanced authentication configuration¶

security:
  authentication:
    providers:
      DefaultProvider:
        providerClass: PersistedUsernamePasswordProvider

security:
  authentication:
    providers:
      MyLDAPProvider:
        providerClass: TYPO3\MyCoolPackage\Security\Authentication\MyLDAPProvider
        options: 'Some LDAP configuration options'
      DefaultProvider:
        providerClass: PersistedUsernamePasswordProvider

configuration:
  security:
    authentication:
      authenticationStrategy: allTokens

security:
  authentication:
    providers:
      DefaultProvider:
        providerClass: PersistedUsernamePasswordProvider
        tokenClass: UsernamePasswordHttpBasic

security:
  authentication:
    providers:
      MyLDAPProvider:
        providerClass: TYPO3\MyCoolPackage\Security\Authentication\MyLDAPProvider
        options: 'Some LDAP configuration options'
        requestPatterns:
         controllerObjectName: TYPO3\MyApplication\AdministrationArea\.*
      DefaultProvider:
        providerClass: PersistedUsernamePasswordProvider
        requestPatterns:
         controllerObjectName: TYPO3\MyApplication\UserArea\.*

Authentication entry points¶

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 an 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).

Example: Redirect an ``AuthenticationRequired`` exception to the login page

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

Available authentication entry points

Authentication mechanisms shipped with FLOW3¶

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'
);

$postArguments = $this->environment->getRawPostArguments();
$username = \TYPO3\FLOW3\Reflection\ObjectAccess::getPropertyPath($postArguments,
    '__authentication.TYPO3.FLOW3.Security.Authentication.Token.UsernamePassword.username');
$password = \TYPO3\FLOW3\Reflection\ObjectAccess::getPropertyPath($postArguments,
    '__authentication.TYPO3.FLOW3.Security.Authentication.Token.UsernamePassword.password'');

Implementing your own authentication mechanism¶

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 here find the steps needed to implement your own authentication mechanism:

Authentication token

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

1. The most interesting method is updateCredentials(). There you’ll get the current request and you’ll have to make sure that credentials sent from the client will be fetched and stored in the token.

2. Implement the remaining methods of the interface. These are mostly getters and setters, have a look in one of the existing tokens (for example TYPO3\FLOW3\Security\Authentication\Token\UsernamePassword), if you need more information.

Authentication provider

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

1. In the constructor you will get the name, that has been configured for the provider and an optional options array. Basically you can decide on your own which options you need and how the corresponding yaml configuration will look like.

2. Then there has to be a canAuthenticate() method, which gets an authentication token and returns a boolean value whether your provider can authenticate that token or not. Most likely you will call getAuthenticationProviderName() on the token and check, if it matches the provider name given to you in your provider’s constructor. In addition to this, the method getTokenClassNames() has to return an array with all authentication token classes, your provider is able to authenticate.

3. All the magic will happen in the authenticate() method, which will get an appropriate authentication token. Basically you could do whatever you want in this method, the only thing you’ll have to make sure is to set the correct status (possible values are defined as constants in the token interface and explained above). If authentication succeeds you might also want to set an account in the given token, to add some roles to the current security context. However, here is the recommended way of what should be done in this method and if you don’t have really good reasons, you shouldn’t deviate from this procedure.

1. Get the credentials provided by the client from the authentication token (getCredentials())
2. Retrieve the corresponding account object from the account repository, which you should inject into your provider by dependency injection. The repository provides a convenient find method for this task: findActiveByAccountIdentifierAndAuthenticationProviderName().
3. The credentialsSource property of the account will hold the credentials you’ll need to compare or at least the information, where these credentials lie.
4. Start the authentication process (e.g. compare credentials/call directory service/...).
5. Depending on the authentication result, set the correct status in the authentication token, by calling setAuthenticationStatus().
6. Set the account in the authentication token, if authentication succeeded. This will add the roles of this token to the security context.

Authorize method invocations¶

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:

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 TYPO3\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 (TYPO3\FLOW3\Security\Authorization\AccessDecisionVoterManager), which uses the following voting process to meet its decision:

1. Check for registered access decision voters.
2. Ask every voter, to vote for the given method call (or join point in AOP nomenclature).
3. Count the votes and grant access, if there is at least one VOTE_GRANT vote and no VOTE_DENY vote. In all other cases an access denied exception will be thrown.

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 TYPO3\FLOW3\Security\Authorization\AccessDecisionVoterInterface. Then you have to register your custom voter as shown below:

security:
  authorization:
    accessDecisionVoters: [TYPO3\FLOW3\Security\Authorization\Voter\Policy, MyCompany\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 that behavior by configuring the following option:

security:
  authorization:
    allowAccessIfAllVotersAbstain: FALSE

Application firewall¶

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.

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:

FLOW3’s built-in security interceptors

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

Example: Firewall configuration in the *Settings.yaml file*

TYPO3:
  FLOW3:
    security:
      firewall:
        rejectAll: FALSE

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

As you can see, you can easily use your own implementations for request patterns and security interceptors.

Security for persisted objects¶

FIXME: This section is not complete yet

resources:
  entities:
    Acme_MyPackage_Domain_Model_Customer:
      Acme_MyPackage_Customers_All: 'ANY'
      Acme_MyPackage_Customers_Vip: 'this.vip == TRUE'
      Acme_MyPackage_Customers_Me: 'current.securityContext.account != this.account && this.account != NULL'

The Acme_MyPacakge_Customer_All resource will match any customer object. The Acme_MyPacakge_Customer_Vip resource matches all customer’s which have their vip attribute set. The Acme_MyPackage_Customer_Me resource matches any customer object whose account property matches the currently logged in account.

• if an entity resource is defined, access is denied automatically to all who don’t have access granted to that new resource explictly defined in the ACLs.
• if there is no ANY resource defined, only objects explicitly matched by one of the other resources are denied by default.
• if there is a ANY resource define, all objects of this type will be denied for all users not have a grant privilege for this ANY resource.
• The key Acme_MyPackage_Domain_Model_Customer has to reflect the full qualified class name of your entity, while ‘’ is replaced by ‘_’ due to YAML syntax constraints.
• The DENY privilege works the same as for methods. If it is set for one of the resources you will never see entities matched by this resource, no matter how many GRANT privileges there might be set for other roles you also have.
• TODO: Explain query rewriting via aspect to the persistence layer
• NOTE: not working for DQL queries currently (only QOM!)

Security for files aka secure downloads¶

• add publishing configuration to resource objects
• publishing in subfolder named like session id
• optimization with role subdirs -> only publish once for a role
• server specific restriction publishing like .htaccess files for apache

ifAccess view helper¶

This view helper implements an ifAccess/else condition, have a look at the following example, which should be more or less self-explanatory:

Example: the ``ifAccess`` view helper

<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>

As you can imagine, the main advantage is, that the view will automatically reflect the configured policy rules, without the need of changing any template code.

ifHasRole view helper¶

This view helper is pretty similar to the ifAccess view helper, however it does not check the access privilege for a given resource, but the availability of a certain role. For example you could check, if the current user has the Administrator role assigned:

Example: the ``ifHasRole`` view helper

<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>

Hash service¶

• hashing/verifying hashes
• special hasing strategies/algorithms
• random number generation

RSA wallet service¶

• cli commands to safe keys
• crypting/decrypting/verifying signatures