EXT: Single Sign-On¶

Third Party Application ID (as configured in SSO Agent)¶

SSO Agent URL¶

Invocation Type¶

Link Display Text (for "Link in Content")¶

Frame Target (for "Link in Content")¶

Custom Frame Target Name (overrides: Frame Target)¶

Select a Usermapping Table¶

Link Lifetime (sec)¶

Require SSL¶

HTML before¶

HTML after¶

Allow to create the user in the Third Party Application¶

FE-Userdata that should not be updated or commited to the tpa¶

User Mapping Tables¶

[not yet fully implemented (e.g. sync existing tables against TYPO3 users) + documented ! ]

To work with User Mapping Tables, click "Usermapping" in the "Tools" section in the TYPO3 backend (Note: After freshly installing the extension, you will of course have to refresh the page in order to see the new option).

Here can select from the following actions (using the drop-down menu):

• Info
• Create a new User Mapping Table
• Edit a User Mapping Table
• Delete a User Mapping Table
• Duplicate (copy) a User Mapping Table

Since a User Mapping Table is related to a TYPO3 user storage, you first have to select the proper sysfolder when creating a new table. For this purpose, a list of the existing sysfolders is presentd to you. Choose one by clicking on it.

Inside the User Mapping Table, you enter its name (this is the name displayed in the selection for the content element) and a "Mapped Name" per TYPO3 user. Also you can define the behaviour for users with an empty "Mapped Name". If the checkbox [currently: "allow user but do not change the name"] is checked, these user names will be sent unchanged. If unchecked, for them access will be denied.

Prerequisites for the TYPO3 Server¶

• OpenSSL, preferrably compiled into PHP [otherwise the OpenSSL executable currently needs to be in the searchpath of the webserver's uid]
• currently only tested on Unix Servers.
• currently only tested with Apache.

Prerequisites for the Sigsso Server¶

OpenSSL, preferrably compiled into PHP [otherwise the OpenSSL executable currently needs to be in the searchpath of the webserver's uid]

• currently only tested on Unix Servers.
• currently only tested with Apache.

SSO Agent – Overview¶

The SSO Agent needs to be deployed and configured on every TPA system.

download the SSO Agent of your choice from [1]

unpack where needed (depending on your implementation)

Example:

cd htdocstar xfzf sigsso.php.tar.gz

set the file access rights as needed

Example (Unix):

chmod 500chown wwwrun:nogroup sigsso.php

make sure the webserver is able to correctly invoke the SSO Agent

Now you need to deploy the OpenSSL public key file from your TYPO3 server to here. You may put it in any place accessible from the SSO Agent.

Finally, configure the SSO Agent.

Although by time there may be more then one implementation of the SSO Agent, there is a common set of configuration options, typically to be defined in a file called sigsso.conf .

The following is a sample description based on the definitions of an early version of the sigsso.php implementation of the SSO Agent. See [1] for current implementations, versions and appropriate documentation on installation and configuration.

In the current sigsso.php, the location of the config file is coded in the php script. To change the location, you need to change the line

$configfile="/usr/local/sigsso/etc/sigsso.conf";

to the proper value.

The sigsso.php configuration file is divided into subparts:

[global],

[errorcodes] and

[main].

Every part has different options and values, separated by a colon (":"). Whitespaces (blanks etc.) are allowed.

Comments are prefixed by the pound sign ("#").

Prerequisites for the SSO Agent on the Server¶

OpenSSL, preferrably compiled into PHP [otherwise the OpenSSL executable currently needs to be in the searchpath of the webserver's uid]

• currently only tested on Unix Servers.
• currently only tested with Apache.

SSO Agent - The [global] Section¶

sigsso.conf [main] section¶

For each TPA you need to add one line here. The syntax is:

<tpa_id> (as configured in the Single Sign-On content element in TYPO3) followed by a colon ":" and the system call to the TPA Adapter.

[new since version 0.5.3: php system call also possible. Use <tpa_id>: and <call> in the config file. Where <call> is one of: "cmd://" or "php://".]

Normally, this system call will require parameters, some of them dynamic (i.e. variables). These can be given, represented by keywords in percent signs. Currently, the following variables are supported by sigsso.php:

SSO Agent - The [errorcodes] Section¶

This section allows you to override the default messages that are displayed to the browser in case of an error.

Instead of a different message text, you may also give a URL to redirect to; this is recognized by the leading "http://" or "https://".

The following table gives the keyword and default message text for each error situation:

TPA Adapter¶

For installation and configuration, see the documentation that comes with your TPA Adapter.

Increase Logging¶

If a request does reach the SSO Agent, then most likely you will be able to find helpful information by increasing the log level. See SSO Agent - The [global] Section configuration of sigsso.conf, [global] section or your SSO Agent's documentation for details.

The place of the logfile is configured in the sigsso.conf. The Log for a successful use of the link/redirect looks like this (loglevel:2)

Wed Oct 22 11:29:16 CEST 2003 IP:192.168.1.59 USER:kasper TPA_ID:MyOwnApp

At the beginning, the date followed by the users IP, the username itself, and the accessed tpa_id. If something goes wrong the errorcode is attached at the end of the line followed by the errordesciption. Looks like:

Wed Oct 22 13:31:19 CEST 2003 IP:192.168.1.59 USER:kasper TPA:MyOwnApp ERROR:31 ERRORTEXT:sigsso: validation error - SSO Link has been used before

For a higher loglevel the expiration time and the full signature will be logged too. Also look Abbildung 4 configuration of sigsso.conf, [global] section

In case something goes wrong, here are the most common means of analysis.

Understanding Error Messages¶

Try the TPA Adapter manually¶

To find out whether the TPA Adapter works ok, you may try it manually and copy&paste the result to your browser's URL field. Of course, this will only work if the TPA does not require a cookie to be set.

• Logon as apache user on the TPA machine
• Invoke the TPA Adapter as defined
• Copy the resulting "Redirect URL" to your browser's URL field.

Design¶

Security has been the major objective throughout the development of the TYPO3 Single Sign-On extension. As of today, a carefully configured system is considered safe due to the following measures:

• No TPA passwords are stored in or even known to TYPO3 and the SSO Agents.
• The SSO Link (providing TPA access without password) has a limited lifetime (configurable).
• The SSO Link cannot be faked (it is signed by the TYPO3 server using a OpenSSL signature).
• Each SSO Link can only be used once (replay protection).
• Since the transfer of the SSO Link should be protected (otherwise it may be sniffed and used by an offender), the usage of SSL can be enforced in the plugin.

A remaining disadvantage by design is that an administrator (a TYPO3 admin as well as the system administrator of the TPA machine) can find ways to logon to the TPA as another user, without knowing his password. It may be added that this is true for many applications even without TYPO3 Single Sign-On.

If you are going to create a very high security environment, you will find that any Single Sign-On solution is a tradeoff between security gains and losses, and you may even find that you are better off without single sign?on (see [3] for additional thoughts on this matter.)

Afterall, TYPO3 Single Sign-On provides a remarkably secure solution. And since both architecture and implementation are truly open, they are being examined (and, if necessary, improved) by a large community to make TYPO3 Single Sign-On as trustworthy as you need it.

Limitations¶

Remember that TYPO3 Single Sign-On provides no control about what a user is able to do inside a TPA or not. All you get is the user's identity, so you still need to

• set up each user inside each TPA,
• define each user's roles or rights inside each TPA,
• make sure that each TPA is free of exploits,
• think about implementing a firewall system on port filter level,
• think about implementing a firewall system on HTTP level.

Please be aware that logoff from TYPO3 does not include logoff from any TPAs.

For high security environments you may consider a commercial product (like Tivoli Access Manager) with central access control provided by a reverse proxy, terminating all HTTPS.

Security Configuration Tasks¶

TYPO3: Use SSL!

The usage of HTTPS for TYPO3 Logon and espacially for the logged-on user (i.e. the session where the SSO Link is transferred) is highly recommended.

Accessing the SSO Agent (sigsso.php) via SSL is also recommended but not mandatory.

Consider using SSL for your TPA access, too (depends on the nature of your TPA).

TYPO3: Encrypt frontend user passwords!

Use MD5 hashing for frontend user passwords (as described on TYPO3.org). Storing user passwords in clear is not acceptable for any serious environment.

TYPO3: Protect the plugin and its components!

Make sure only the designed SSO admins are allowed to access the global plugin configuration, the Single Sign-On content elements and most of all the User Mappings. Whoever can edit a TPA User Mapping, can also gain access to the TPA as any user desired. Thus, it has to be carefully protected from non-admin access.

TYPO3: Use user restriction for non-mapped TPAs!

If you do not have full control of the user administration on your TYPO3, make sure to use the "user restriction for non-mapped TPAs" feature. By doing so, you prevent others from just creating not-yet- existing TYPO3 users that correspond to existing TPA users.

TYPO3 system: Protect the OpenSSL Private Key file!

Since the signatur of the SSO Link' is a central part of the security concept, it is crucial to keep the OpenSSL private key file in a safe place. Obviously, it must not be accessible from the web.

TYPO3: Protect the OpenSSL Private Key passphrase!

As well as the OpenSSL Private Key file, also it's passphrase should be protected. It is configured in the extension setup, thus the access to this should be restricted.

TYPO3: Keep the entire system safe!

Since the security of the Single Sign-On relies on the integrity of the underlying system, all measures should be taken to keep this safe as well. Please follow the appropriate guidelines for TYPO3, mysql, PHP, Apache, Linux or whatever.

TYPO3: Consider system separation!

A security component like a Single Sign-On framework should ideally be as lean as possible, in order to reduce complexity and therefore bug or error probability. This is slightly contrary to the idea of integrating it to a system as complex as TYPO3. As an improvement, you may consider splitting up your TYPO3 environment into different systems.

Target System: Protect the TPA Adapter!

Make sure nobody but the SSO Agent (sigsso.php) (and root - maybe :-) can call the TPA adapter from the command line,

Target System: Protect the server instance running sigsso.php!

Since the web server serving the SSO Agent is able to execute sigsso.php and therefore generate valid user sessions, make sure to keep the risks to it low. In doubt, run a seperate httpd instance (under a different uid).

Target System: Protect the UsedTokens file!

Since the UsedTokens file (as configured in the SSO Agent's config) provides the replay prevention, fiddling it would be useful for an offender (in conjunction with snooping legal access to the SSO Agent). This appears to be a rather theoretical scenario, though.

TYPO3 and Target System: Use PHPSafeMode!

[...]

Ways of Sign-On Integration¶

If you are going to integrate another TPA into your TYPO3 Single Sign- On environment, the first look will always be for existing TPA Adapters or generic ways like an adapter for an underlying Application Server.

In case the is no such TPA Adapter available, you will need to create your own. The two major options you have are:

Use an existing single sign-on method supported by your TPA that is trust-based (i.e. does not require the user's password). Although this is rather uncommon, it is the recommended way if possible. What you effectively do is build an adapter to the single sign-on method supported by your TPA; the TPA itself is not affected.

Find a way to create a user session in your TPA. This may be done by hooks in your TPA, patching it, external code, by direct access to some session database etc. - it all depends on the nature of your TPA. Obviously, all this may become pretty tough if your TPA is not open source.

This leads to a considerable number of alternative variants; some of them are shown in the following picture.

As a convention, each of these variants is called "TPA Adapter", even there if is no dedicated (or no TPA-specific) adapter software.

In rare cases, implementations may make sense that do not seperate the SSO Agent functionality from the TPA adapter. These are called "Monolithic TPA Adapters".

Format Definitions: SSO Link --- SSO Agent¶

Format Definitions: SSO Agent --- TPA Adapter¶

The invocation of a TPA Adapter is done via system call. Command line parameters are given for input values. Output values are to be returned on STDOUT.

Input values:

The TPA Adapter is called as it is configured in sigsso.conf you can add some dynamic entries (see SSO Agent - The [global] Section configuration options in sigsso.conf, [main] section) and some static entries.

Example:

/path/to/tpa/script --remote_addr=%remote% --agent=%agent% ??url=https://redirect.url/index.php ??user=%user% --moreparameters=anything_you _need

Output values:

The TPA Adapter must return a redirecturl. The TPA Adapter can also return Cookie Parameters. for the parameternames). Each parametername and value is separated by a whitespace (<tab> or <space>). Each pair in one new line.

Every Cookie must start with 'CookieName'. If you need to set more than one Cookie you only need to send as many Cookie parameter sets as you need. The SSO Agent will notice that different Cookies are to be set.

An example output of the TPA Adapter for two cookies may look like:

redirecturl https://redirect.url/index.php CookieName valuename1CookieValue value1CookieExpires expires1CookiePath path1CookieName valuename2CookieValue value2CookieExpires expires2CookiePath path2CookieDomain domain2CookieSecure secure2

Adapter Developement¶

To develop your own adapter, one way would to inspect the existing TPA code, find the point where user logon happens and patch this directly.

In the long run you may find it a better idea to duplicate that piece of code and patch this copy, since future upgrades of the TPA software won't affect the adapter (as long as the session handling is unchanged). You may also strip down the code to the necessary parts for the adapter.

Now, what exactly does "patching the code" mean here?

• The patched code create a new session for the given user without a password
• this session data will be stored in the TPA database
• The TPA Adapter must return a redirect URL where the browser should be redirected to.
• Optionally, the TPA Adapter can return cookie parameters (see above)

If your TPA is using the "Basic Authentication" mechanism, it may be a bit more tricky to adapt this - probably you will have to patch the actual application instead of just adding an external adapter.

Make sure that the TPA Adapter cannot be called from outside e.g. via web access. A way to do this is would be to place the file in a safe directory, or to check for the existence of environment parameters.

TPA Adapters - Enhanced Features¶

TPA "Change Password" Handling

If you want to avoid some potential confusion, you should hide any existing "change password" functionality in your TPA from users that came in via SSO. Otherwise such a user may use this "change password" and expect the new password to work with TYPO3 (which it does not, since this "change password" only affects the TPA's own user registry).

An even better way would be redirect the TPA's "change password" link to TYPO3's "change password", again: for SSO users only.

Anyway: What you need to implement is

· some flag in the user session that marks it as an "SSO-session" and

· a switch that hides or changes the TPA's "change password" link for "SSO-sessions".

[Of course... If you happen to have a nice environment with a common user/password repository (e.g. shared LDAP) in place, you will not need all this. Beyond the scope of this document, though...]

Policy Enforcement for Single Sign-On

As another enhancement, you may want to check the user's role (i.e. group membership) during TPA Adapter sign-on. A possible policy would be to deny single sign-on access for administrators, another would be to restrict certain users or roles to special IP addresses or networks.