Flowpack Single sign-on Documentation¶

Features¶

• Easy integration into existing TYPO3 Flow applications
• Flow security framework integration, re-use of existing authentication providers (e.g. LDAP, UsernamePassword, OpenID)
• Flexible account data mapping (transfer custom properties of parties)
• Session expiration synchronization
• Remote session management capabilities
• Single Sign-off
• Account switching (impersonate)
• Sessions can use existing Flow cache backends (Redis, Memcache, APC)
• RSA signing of server-side requests

Architecture¶

The architecture is designed to be highly extensible and fully integratable in an existing TYPO3 Flow application.

Server¶

A Single sign-on server is a TYPO3 Flow application that provides a central authentication system which is accessed by the instances. The server consists of the Server package and a domain package that implements a party model for the authentication and provides possible extensions to the Single sign-on data exchange.

The server has a public / private key pair and exports HTTP service as the Service base URI (e.g. http://ssoserver.local/sso/). The service base URI is also used as the unique server identifier.

All the instances have to be registered as a single sign-on client with their public key and service base URI. This allows for (signed) server-side requests initiated by the client or the server. The client public key restricts access to the single sign-on only to explicitly registered clients. The clients are persisted as entities inside a configured database. A management interface for the clients can be implemented in a custom package.

See Single sign-on server for more information about implementing a custom server application.

Instance¶

An instance is a (TYPO3 Flow) application that utilizes a Single sign-on server for authentication using the Client package. The Flowpack Single sign-on can be one of multiple authentication methods on the instance. Usually there will be a larger number of instances in a typical setup.

The single sign-on client on the instance has a public / private key pair and a Service base URI as a unique client identifier. The client needs at least one configured single sign-on server with the server public key and service base URI. The client is used by the instance through the Flow security framework as a special authentication provider.

Authentication round trip¶

This is a simple round trip for access to a secured resource on an instance without prior authentication:

1. A user accesses a secured resource on an instance
2. Since no account is authenticated on the instance the user is redirected to a configured server
3. The user will authenticate on the server through a configured authentication provider (e.g. username / password)
4. The server redirects back to the instance and passes an encrypted access token
5. The instance decrypts the access token and does a server-side request to redeem the token on the server, the server verifies the token and returns the account data and authorization information (e.g. roles)
6. The instance authenticates an account locally and redirects to the original secured resource

Setting up the Vagrant demo¶

First clone the DemoVagrant repository that contains the Vagrant box setup:

$ git clone https://github.com/Flowpack/Flowpack.SingleSignOn.Demo-Vagrant.git DemoVagrant
$ cd DemoVagrant

Then install Vagrant for your operating system, install the librarian gem for downloading bundled cookbooks and start the vagrant box:

$ gem install librarian
$ librarian-chef install
  ...
$ vagrant up

The virtual machine should now boot and start to provision the demo setup (this can take a while).

Set up host entries in your /etc/hosts (or similar file, depending on your operating system):

10.11.12.23 ssodemoserver.vagrant
10.11.12.23 ssodemoinstance.vagrant ssodemoinstance2.vagrant

Browse to http://ssodemoserver.vagrant/ and you should see the demo server frontend. A second instance is available on http://ssodemoserver2.vagrant/ for running multi-instance acceptance tests.

Manually setting up the demo server and instance¶

The demo setup consists of a demo server and a demo instance bundled in two TYPO3 Flow distributions. You should follow the steps in the TYPO3 Flow Quickstart for a general setup for Flow development if not yet done.

Each distribution should be cloned into a separate directory:

$ mkdir singlesignon-demo
$ cd singlesignon-demo

$ git clone https://github.com/Flowpack/Flowpack.SingleSignOn.DemoServer-Distribution.git DemoServer
$ cd DemoServer
$ path/to/composer.phar install --dev

TYPO3:
  Flow:
    persistence:
      backendOptions:
        dbname: ssodemoserver # Create this database
        host: localhost
        user: root   # Fill in username
        password: '' # Fill in password

Flowpack:
  SingleSignOn:
    Server:
      server:
        serviceBaseUri: 'http://ssodemoserver.local/sso/'
        publicKeyFingerprint: ''

    DemoServer:
      demoInstanceUri: 'http://ssodemoinstance.local/'
      clients:
        -
          serviceBaseUri: 'http://ssodemoinstance.local/sso/'

$ ./flow doctrine:migrate
$ ./flow flowpack.singlesignon.demoserver:demo:setup

$ git clone https://github.com/Flowpack/Flowpack.SingleSignOn.DemoInstance-Distribution.git DemoInstance
$ cd DemoInstance
$ path/to/composer.phar install --dev

TYPO3:
  Flow:
    persistence:
      backendOptions:
        dbname: ssodemoinstance # Create this database
        host: localhost
        user: root   # Fill in username
        password: '' # Fill in password

Flowpack:
  SingleSignOn:
    Client:
      client:
        serviceBaseUri: 'http://ssodemoinstance.local/sso/'
        publicKeyFingerprint: ''
      server:
        DemoServer:
          serviceBaseUri: 'http://ssodemoserver.local/sso/'
          publicKeyFingerprint: ''

    DemoInstance:
      demoServerUri: 'http://ssodemoserver.local/'

$ ./flow doctrine:migrate
$ ./flow flowpack.singlesignon.demoinstance:demo:setup

Demo walkthrough¶

You could test the following scenarios:

• Go to demo instance, request secure action: A login form on the server will be displayed. After login with one of the demo credentials you should be redirected back to the secure action and be authenticated on the server and instance.
• Authenticate on server, request secure action on instance: No login form is displayed if an authenticated session already exists and the session is transferred to the instance using redirects and server-side requests.
• Authenticate on server and instance, logout from server: When going to the instance again you should see, that the session was automatically invalidated using a server-side request.
• Authenticate on server and instance, logout on instance: When going to the server you should see, that the session was automatically invalidated using a server-side request.

/**
 * @Flow\Entity
 */
class User extends AbstractParty {

    /**
     * @var string
     */
    protected $firstname = '';

    /**
     * @var string
     */
    protected $lastname = '';

    /**
     * @var string
     */
    protected $company = '';

    ...
}

class LoginController extends AbstractAuthenticationController {

    public function indexAction() {
    }

    protected function onAuthenticationSuccess(\TYPO3\Flow\Mvc\ActionRequest $originalRequest = NULL) {
        if ($originalRequest !== NULL) {
            $this->redirectToRequest($originalRequest);
        }

        $this->addFlashMessage('No original SSO request present. Account authenticated on server.', 'Authentication successful', \TYPO3\Flow\Error\Message::SEVERITY_OK);
        $this->redirect('index', 'Standard');
    }

    public function logoutAction() {
        parent::logoutAction();

        $this->addFlashMessage('You have been logged out');
        $this->redirect('index', 'Standard');
    }

}

TYPO3:
  Flow:
    security:
      authentication:
        providers:
          DefaultProvider:
            provider: PersistedUsernamePasswordProvider
            entryPoint: WebRedirect
            entryPointOptions:
              uri: 'login'

Flowpack:
  SingleSignOn:
    Server:
      server:
        keyPairFingerprint: bb5abb57faa122cc031e3c904db3d751
        serviceBaseUri: 'http://ssodemoserver.local/sso/'

-
  name: 'SingleSignOn'
  uriPattern: 'sso/<SingleSignOnSubroutes>'
  subRoutes:
    SingleSignOnSubroutes:
      package: Flowpack.SingleSignOn.Server

/**
 * @Flow\Entity
 */
class User extends \TYPO3\Party\Domain\Model\AbstractParty {

    /**
     * The username of the user
     *
     * @var string
     */
    protected $username;

    /**
     * @var string
     */
    protected $firstname = '';

    /**
     * @var string
     */
    protected $lastname = '';

    /**
     * @var string
     */
    protected $company = '';

    /**
     * @var string
     */
    protected $role = '';

    ...
}

TYPO3:
  Flow:
    security:
      authentication:
        providers:
          SingleSignOnProvider:
            provider: 'Flowpack\SingleSignOn\Client\Security\SingleSignOnProvider'
            providerOptions:
              server: DemoServer
              globalSessionTouchInterval: 5
            entryPoint: 'Flowpack\SingleSignOn\Client\Security\EntryPoint\SingleSignOnRedirect'
            entryPointOptions:
              server: DemoServer

Flowpack:
  SingleSignOn:
    Client:
      client:
        serviceBaseUri: http://ssodemoinstance.dev/sso
        publicKeyFingerprint: bb45dfda9f461c22cfdd6bbb0a252d8e

      server:
        DemoServer:
          serviceBaseUri: http://ssodemoserver.dev/sso/
          publicKeyFingerprint: bb5abb57faa122cc031e3c904db3d751

      accountMapper:
        typeMapping:
          # Map a user type from the server to one of the instance, more complex scenarios
          # need a specialized account mapper implementation (see GlobalAccountMapperInterface)
          'Flowpack\SingleSignOn\DemoServer\Domain\Model\User': 'Flowpack\SingleSignOn\DemoInstance\Domain\Model\User'

Components¶

This is a schematic view of the single sign-on server components:

Server key pair

The server has a public / private key pair for encryption and verification of requests. The public key is shared with all instances that should access the server.

Service base URI

The server exports HTTP services on a specific URL path. This path acts as the Service base URI (e.g. http://ssoserver.local/sso/) or server identifier.

Clients

All the instances have to be registered as a single sign-on client with their public key and service base URI. This allows for (signed) server-side requests initiated by the client or the server. The client public key restricts access to the single sign-on only to explicitly registered clients. The clients are persisted as entities inside a configured database. A management interface for the clients can be implemented in a custom package.

TODO Show usage of authentication provider and accounts on server

Configuration¶

Flowpack:
  SingleSignOn:
    Server:
      server:
        # The service base URI for this server
        serviceBaseUri: ''
        # Mandatory key pair uuid (fingerprint) for the SSO server
        keyPairFingerprint: ''
      log:
        backend: TYPO3\Flow\Log\Backend\FileBackend
        backendOptions:
          logFileURL: %FLOW_PATH_DATA%Logs/SingleSignOn_Server.log
          createParentDirectories: TRUE
          severityThreshold: %LOG_WARN%
          maximumLogFileSize: 10485760
          logFilesToKeep: 1
          logMessageOrigin: FALSE

        # Enable logging of request signing (all signed requests)
        logRequestSigning: FALSE

##
# Flowpack.SingleSignOn.Server subroutes
#

-
  name: 'SingleSignOn'
  uriPattern: 'sso/<SingleSignOnSubroutes>'
  subRoutes:
    SingleSignOnSubroutes:
      package: Flowpack.SingleSignOn.Server

Commands¶

Add a client

COMMAND:
  flowpack.singlesignon.server:ssoserver:registerclient

USAGE:
  ./flow ssoserver:registerclient <base uri> <public key>

ARGUMENTS:
  --base-uri           The client base URI as the client identifier
  --public-key         The public key fingerprint (has to be imported using the
                       RSA wallet service first)

DESCRIPTION:
  This command registers the specified client at the SSO server.

$ ./flow ssoserver:registerclient --base-uri http://ssoinstance.local/sso/ --public-key c1285a470f0fc8f14f54851c5d8eb32f

Remove expired access tokens

COMMAND:
  flowpack.singlesignon.server:ssoserver:removeexpiredaccesstokens

USAGE:
  ./flow ssoserver:removeexpiredaccesstokens

DESCRIPTION:
  This will remove all expired access tokens that were not redeemed from the underlying storage.
  This command should be executed in regular intervals for cleanup.

Logging¶

The server package Configuration configures a default logger that is used in the single sign-on package for logging various events. The default file for the logger in Production context is Data/Logs/SingleSignOn_Server.log.

The logger interface can be injected in any package to log into the same destination:

/**
 * @var \Flowpack\SingleSignOn\Server\Log\SsoLoggerInterface
 * @Flow\Inject
 */
protected $ssoLogger;

Client registration¶

Clients of single sign-on instances need to be registered on the server before they can participate in the single sign-on. The server needs the client service base URI and public key for encryption of request parameters, server-side client notification and request signing.

The server package implements the ssoserver:registerclient command for that purpose.

$ssoClient = new \Flowpack\SingleSignOn\Server\Domain\Model\SsoClient();
$ssoClient->setServiceBaseUri($baseUri);
$ssoClient->setPublicKey($publicKeyFingerprint);
$this->ssoClientRepository->add($ssoClient);

Authentication endpoint¶

The single sign-on server exposes a public controller action for handling authentication requests from clients. This is called the authentication endpoint.

The single sign-on client entry point on the instance will redirect a user to the authentication endpoint on the server if no authenticated session is present locally on the client. This redirect happens in the browser of the user to access an existing web session of the server (if the user authenticated on the server or another instance before).

To secure the parameters and guard against a possible redirection attack the parameters are signed by the client in the signature query argument. This is done using the private key of the client, so the server can verify the signature with the client public key and also verify the identity of the request.

A ClientNotFoundException will be thrown if the client was not registered on the server.

The authentication endpoint action will act as an authentication controller and eventually call $this->authenticationManager->authenticate(), so the user has to authenticate using a configured authentication provider to proceed. This approach integrates nicely with the Flow security framework and allows the usage of all available authentication providers and entry points.

Authentication callback¶

After the user was authenticated on the server or if the user was already authenticated an access token is created on the server and sent to the instance via an redirect in the browser to the client authentication callback.

Since the redirect to the client should be considered insecure the access token is encrypted and signed with the client public key and server private key.

Access token redemption¶

After the single sign-on client has verified the access token a server-side `signed request`_ is made to exchange the access token for the actual account data and single sign-on session identifier. This measure also prevents injection of arbitrary account data into the callback URI by breaking the signature.

With a valid access token the server will:

• get the original session identifier and account from the access token
• invalidate (remove) the access token
• register the single sign-on client in the session for Client notification
• perform Account mapping to transform the server account into authentication and authorization information for the client
• respond with a JSON representation of the mapped account and the server session identifier

The client will transform the returned account data into a local account (persistent or transient) using a global account mapper and authenticate this account locally.

Account mapping¶

Since the account and party information that is needed on an instance is dependent on the actual requirements of an application the single sign-on solution does not impose a fixed schema for the information.

With an implementation of the ClientAccountMapperInterface any strategy for a transformation given the account and client instance can be implemented:

 interface ClientAccountMapperInterface {

     /**
      * Map the given account as account data for an instance
      *
      * @param \Flowpack\SingleSignOn\Server\Domain\Model\SsoClient $ssoClient
      * @param \TYPO3\Flow\Security\Account $account
      * @return array
      */
     public function getAccountData(
             \Flowpack\SingleSignOn\Server\Domain\Model\SsoClient $ssoClient,
             \TYPO3\Flow\Security\Account $account
     );

}

The getAccountData method has to return the serialized account information based on the given single sign-on client and account object. It is possible to differentiate between clients and return different account information depending on the client with this approach.

accountIdentifier: 'jdoe'
roles: ['Vendor.MyPackage:User']
party:
  __type: 'Vendor\MyPackage\ExampleParty'
  company: 'Acme Inc.'

array(
    'party' => array(
            '_exposeType' => TRUE,
            '_descend' => array('name' => array())
    )
);

Client notification¶

The client notification is used to destroy sessions remotely by a server-side request to the client. This is mainly used for synchronized logout (Single sign-off) and account switching on the server.

The server declares a SsoClientNotifierInterface interface for this purpose and provides two implementations using a synchronous (SimpleSsoClientNotifier) and parallel (ParallelSsoClientNotifier) strategy for the HTTP requests. The SimpleSsoClientNotifier is the default implementation configured in the server package Objects.yaml. In scenarios that register a lot of instances for one session the ParallelSsoClientNotifier can reduce the latency on logout or account switching by using parallel HTTP requests with a multi-threading engine.

A destroyed session on the client will require authentication through the single sign-on mechanism on the next request to a secured resource on the client. This ensures an updated authentication state on the instance.

Session synchronization¶

The TYPO3 Flow session has a configurable interval for inactivity that is used to expire sessions after a certain time of inactivity on the next access or through garbage collection.

In a single sign-on scenario we have to consider multiple Flow sessions (after authentication with at least one instance):

• One global session on the single sign-on server
• One ore more local sessions on the instances

The server and instances could have different inactivity timeouts configured for the Flow session which leads to an effect where the user is still authenticated on the client but the server session is already expired due to inactivity (for most scenarios the user will access the server very infrequently). It is desirable that the session lifetime is synchronized in a single sign-on setup, such that an expired session on the server will also expire the session on the instances.

The Flowpack single sign-on solution does use a regular touch on the global session from the client through a special server-side signed request. The interval and frequency is configurable for the single sign-on client.

The server will respond with an error code SessionNotFound if the session was not found / inactive and the client will mark the authentication token as no longer authenticated.

Account impersonation¶

The authentication endpoint gets the current account that should be passed to the instance through the AccountManager service, which is implemented in the server package.

The method impersonateAccount allows to impersonate another account that will be visible as the globally authenticated account. The original account is still authenticated on the server which allows to switch back to the original or yet another account. As in the case of re-authentication on the server all registered client sessions are destroyed on impersonation.

This feature could be used to implement multi-tenant applications where one global account is able to use multiple other accounts and the user should be able to select the currently active account.

HTTP services¶

This is a list of all HTTP services (controller actions) that are exposed by the server. The URI path depends on the global Routes.yaml that mounts the package subroutes, we expect the routes to be mounted at /sso/<SingleSignOnSubroutes>.

Components¶

This is a schematic view of the single sign-on client components that are part of a TYPO Flow application which is called an instance.

Client key pair

The client has a public / private key pair for encryption and request verification. The public key is shared with all servers that are used by the client (most of the time there will be only one server).

Service base URI

The client exports HTTP services on a specific URL path. This path acts as the Service base URI (e.g. http://ssoinstance.local/sso/) or client identifier. It is used to register the client on the server.

Servers

The client configuration has a list of servers that could be used for the actual authentication provider options. From an architecture point of view it’s possible to use different single sign-on servers in the same application, although that should be a rare use-case.

Authentication provider and entry point

The client package provides a special SingleSignOnProvider authentication provider and SingleSignOnRedirect entry point which have to be configured in the TYPO3 Flow security framework for the single sign-on to be used as the authentication method. See Configuration / Authentication.

Installation¶

Installation of the single sign-on client package should be done via Composer:

$ path/to/composer.phar require flowpack/singlesignon-client

Configuration¶

Flowpack:
  SingleSignOn:
    Client:
      # SSO client configuration
      client:
        # The client service base URI as the client identifier
        # Must point to the URI where the SSO client routes are mounted
        serviceBaseUri: ''
        # The client key pair fingerprint
        publicKeyFingerprint: ''

      # A list of named SSO server configurations
      server:
        # Example server configuration
        #
        #   DemoServer:
        #     publicKeyFingerprint: 'bb5abb57faa122cc031e3c904db3d751'
        #     serviceBaseUri: 'http://ssoserver/sso'

      accountMapper:
        # Map a party type from the server to the instance, more complex scenarios
        # need a specialized account mapper implementation (see GlobalAccountMapperInterface)
        #
        # typeMapping:
        #   'Vendor\MyServer\Domain\Model\SomeParty': 'Vendor\MyApplication\Domain\Model\OtherParty'
        #
        typeMapping: []

      log:
        # Enable logging of failed signed requests (signature verification errors)
        logFailedSignedRequests: FALSE

TYPO3:
  Flow:
    security:
      authentication:
        providers:
          SingleSignOnProvider:
            provider: 'Flowpack\SingleSignOn\Client\Security\SingleSignOnProvider'
            providerOptions:
              server: DemoServer
              globalSessionTouchInterval: 60
            entryPoint: 'Flowpack\SingleSignOn\Client\Security\EntryPoint\SingleSignOnRedirect'
            entryPointOptions:
              server: DemoServer

##
# Flowpack.SingleSignOn.Client subroutes
#

-
  name: 'SingleSignOn'
  uriPattern: 'sso/<SingleSignOnSubroutes>'
  subRoutes:
    SingleSignOnSubroutes:
      package: Flowpack.SingleSignOn.Client

Commands¶

Generate key pair command

COMMAND:
  flowpack.singlesignon.client:ssokey:generatekeypair

USAGE:
  ./flow ssokey:generatekeypair

DESCRIPTION:
  Creates a new key pair and imports it into the wallet.
  Used by SSO client and server.

$ ./flow ssokey:generatekeypair
Created key with fingerprint: ee60cb20fab84db9136903e107657b7f

Export a public key

COMMAND:
  flowpack.singlesignon.client:ssokey:exportpublickey

USAGE:
  ./flow ssokey:exportpublickey <public key fingerprint>

ARGUMENTS:
  --public-key-fingerprint

$ cd path/to/instance

$ ./flow ssokey:generatekeypair
Created key with fingerprint: ee60cb20fab84db9136903e107657b7f

$ ./flow ssokey:exportpublickey ee60cb20fab84db9136903e107657b7f > instance.pub

$ cd path/to/server

$ ./flow security:importpublickey < instance.pub
The public key has been successfully imported. Use the following uuid to refer to it in the RSAWalletService:

ee60cb20fab84db9136903e107657b7f

Authentication callback¶

The client exposes a public action for authentication callback that accepts a request from the server after the authentication on the server for the single sign-on was successful. The request contains query arguments for the callbackUri, a server generated encrypted Access token and a signature over the arguments for verification.

To verify the authenticity of the request the signature is checked against the public key of the configured server and the access token is decrypted with the client private key. The next step is the Access token redemption with a server-side signed request from the instance to the server.

Account mapping¶

The server will respond with the account data of the authenticated account in the global session that is prepared through account mapping on the server.

The client needs to map this data to a local account with a GlobalAccountMapperInterface implementation:

interface GlobalAccountMapperInterface {

    /**
     * @param \Flowpack\SingleSignOn\Client\Domain\Model\SsoClient $ssoClient
     * @param array $globalAccountData
     * @return \TYPO3\Flow\Security\Account
     */
    public function getAccount(
            \Flowpack\SingleSignOn\Client\Domain\Model\SsoClient $ssoClient,
            array $globalAccountData
    );

}

A default implementation of this interface is shipped in the client package with the class SimpleGlobalAccountMapper that will be used by default.

accountIdentifier: 'jdoe'
roles: ['Vendor.MyPackage:User']
party:
  __type: 'Vendor\MyPackage\ExampleParty'
  company: 'Acme Inc.'

Logging¶

The client package performs no special logging besides a logging aspect for signed request debugging. The aspect to log failed signed requests with signature verification errors can be enabled via the Flowpack.SingleSignOn.Client.log.logFailedSignedRequests setting. The requests are logged to the Flow security logger.

HTTP services¶

This is a list of all HTTP services (controller actions) that are exposed by the client. The URI path depends on the global Routes.yaml that mounts the package subroutes, we expect the routes to be mounted at /sso/<SingleSignOnSubroutes>.

Running the tests¶

We have a test suite that covers all scenarios of the single sign-on with acceptance tests through Behat in the TestSuite repository. The tests need a running demo setup with two different instances (configured via subcontexts).

Install Behat via Composer:

$ git clone https://github.com/Flowpack/Flowpack.SingleSignon.TestSuite.git TestSuite
$ cd TestSuite
$ path/to/composer.phar install

The default behat.yml.dist configuration expects the demo installation with the URL http://ssodemoinstance.dev/, http://ssodemoinstance2.dev/ and http://ssodemoserver.dev/. A custom configuration for Behat can be used by copying the file behat.yml.dist to behat.yml.

Running the Behat tests:

$ bin/behat

This should execute all features and display the results of the scenarios.