.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt .. role:: underline =================== EXT: Single Sign-On =================== :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed: 2012-04-27T16:22:16.390000000 :Description: Version 0.15 :Author: Dietrich Heise :Email: heise@naw.de :Info 3: :Info 4: .. _EXT-Single-Sign-On: EXT: Single Sign-On =================== Extension Key: **naw\_single\_signon** Copyright 2003-2005, Dietrich Heise, Version 2.1.1 This document is published under the Open Content License available from http:// **www.opencontent.org** /opl.shtml The content of this document is related to TYPO3 \- a GNU/GPL CMS/Framework available from www.TYPO3.com .. _Table-of-Contents: Table of Contents ----------------- **EXT: Single Sign-On 1** **Introduction 1** What does it do? 1 Screenshots 2 **Administration 3** A Typical Scenario 3 Configuration of the plugin in the TYPO3 backend 4 SSO Content Element Parameter Reference 4 User Mapping Rules 5 **Configuration 6** Architectural Overview 6 Installation and Configuration of the Extension 7 Creating RSA public/private key pair with OpenSSL 7 Extension Installation Screenshot 8 Installation and Configuration of the SSO Agent and TPA Adapters 9 Troubleshooting 11 Security Considerations 12 TPA Sign-On Integration / TPA Adapter Development 14 **Terms and Acronyms 16** **Ressources 16** Additional Readings 16 Commercial SSO products 16 Exemption from Liability 16 .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ The TYPO3 Single Sign-On (SSO) framework provides seamless integration of Third Party (i.e. non-TYPO3) Applications (TPAs) into TYPO3. This includes - Frontend user access to TPAs with no additional logon (for authenticated TYPO3-users) via "SSO Link" provided by TYPO3, - role-based integration of the SSO-link into TYPO3 navigation or content, - a sophisticated three-layer security architecture, - no need for server-to-server communication, no need for a common/shared/synchronized password database or even user database. In order to integrate a TPA, it needs to be adapted to the TYPO3 Single Sign-On framework. This can be achived by - using an existing TPA Adapter for your specific proprietary application - check adapter repository [1], - using an existing TPA Adapter for an underlying generic trust-based authentication mechanism, e.g. for application servers like IBM Websphere or Bea Weblogic, - creating your own adapter (this can be amazingly easy but completly depends on your TPA). Guidelines are given below. - In Version 2.0.0 the all user data will be updated in the tpa's by the SSO-Framework, you only need to maintain all userdata on the TYPO3 Server. .. _Screenshots: Screenshots ^^^^^^^^^^^ |img-1| *Picture 1 Frontend-User single-signon view while login* |img-2| *Picture 2 Frontend-User single-signon view after login - with third party application (OWL) in a iframe* .. _Administration: Administration -------------- .. _A-Typical-Scenario: A Typical Scenario ^^^^^^^^^^^^^^^^^^ Install and configure the TYPO3 Single Sign-On extension, if not yet done (see Extension Installation Screenshot). Install and configure the TPA's SSO Agent including the TPA Adapter (this example's TPA\_ID to configure in the SSO Agent config is "MyOwnApp"), if not yet done (see Configuration of the plugin in the TYPO3 backend). Now, there are several ways of integrating the SSO Link into your TYPO3 navigation or content. Here is a typical scenario: - You want the TPA in the navigation menu, but only for authorized users. - You want the TPA to open up automatically when selected from the navigation. - At the same time, you want some explaination displayed in your content frame, plus a clickable link in case opening the TPA in a new window (through JavaScript) failed. So what you might do is: - Set up a new page in your tree with the desired display name for your TPA ("My Own Application"). - Limit the access to this page to the group of authorized users ("General Options" – "Access"). - Inside this page, create some regular content as usual. (Example: "My Own Application has been opened in a new browser window." And maybe a nice picture, too :-) - At a position of your choice, insert the "Single Sign-On" plugin |img-3| *Picture 3 Insert the "Single Sign-On" plugin* and configure as follows in the flexform - Third Party Application ID: enter e.g. "MyOwnApp" - SSO Agent URL: enter e.g. " `http://www.my.tpa/sso/sigsso.php `_ " - Invocation Type: select "New Window (JavaScript) AND Link in Content" - Link Display Text: enter "Click here to access My Own Application" - Frame Target: select "\_blank" - Link Lifetime: enter e.g. 1800 - Finally: Logon and try! Note: Befor using this in a productive environment, make sure to read and understand at least the "Security Configuration Tasks" section ! .. _Configuration-of-the-plugin-in-the-TYPO3-backend: Configuration of the plugin in the TYPO3 backend ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |img-4| *Picture 4 Configuration of the SSO-Server Part1* |img-5| *Picture 5 Configuration of the SSO-Server Part2* |img-6| *Picture 6 Configuration of the SSO-Server Part3* .. _SSO-Content-Element-Parameter-Reference: SSO Content Element Parameter Reference ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. ### BEGIN~OF~TABLE ### .. _Third-Party-Application-ID-as-configured-in-SSO-Agent: Third Party Application ID (as configured in SSO Agent) """"""""""""""""""""""""""""""""""""""""""""""""""""""" .. container:: table-row Field Third Party Application ID (as configured in SSO Agent) Explaination A unique string that identifies the TPA. This TPA\_ID is sent to the SSO Agent which calls the corresponding TPA Adapter based on its local configuration data.No blanks etc. allowed; case sensitive. Example: "MyOwnApp" .. _SSO-Agent-URL: SSO Agent URL """"""""""""" .. container:: table-row Field SSO Agent URL Explaination The URL of the SSO Agent that handles this TPA, without parameters.Example: "http://www.my.tpa/sso/sigsso.php" .. _Invocation-Type: Invocation Type """"""""""""""" .. container:: table-row Field Invocation Type Open in new window (requires JavaScript) Open here (HTTP redirect) Display "Link in Content" New Window (JavaScript) AND Link in Content Explaination What you want to happen when the users navigates to this page. Immediatly open the TPA in a new window - requires Javascript (!) Immediatly open the TPA in the present window (Frameset: in the content frame). This is done by HTTP redirect. Just display a link (SSO Link to the TPA) in the page content. Configurable by additional options below. Combination of 1. and 3. .. _Link-Display-Text-for-Link-in-Content: Link Display Text (for "Link in Content") """"""""""""""""""""""""""""""""""""""""" .. container:: table-row Field Link Display Text (for "Link in Content") Explaination Link Text to be shown in the content (if empty, the TPA\_ID is displayed.) Example: "Click here to access My Own Application". .. _Frame-Target-for-Link-in-Content: Frame Target (for "Link in Content") """""""""""""""""""""""""""""""""""" .. container:: table-row Field Frame Target (for "Link in Content") Explaination Choose from standard targetsExample: "\_blank" .. _Custom-Frame-Target-Name-overrides-Frame-Target: Custom Frame Target Name (overrides: Frame Target) """""""""""""""""""""""""""""""""""""""""""""""""" .. container:: table-row Field Custom Frame Target Name (overrides: Frame Target) Explaination Enter custom frame target (optional) .. _Select-a-Usermapping-Table: Select a Usermapping Table """""""""""""""""""""""""" .. container:: table-row Field Select a Usermapping Table Explaination If you configured User Mapping Rules (see User Mapping Rules), here you can apply one to this SSO content element. Default is "Default (no mapping)" .. _Link-Lifetime-sec: Link Lifetime (sec) """"""""""""""""""" .. container:: table-row Field Link Lifetime (sec) Explaination For security reasons, the SSO Link has a limited lifetime. In case a user navigates around in TYPO3 up to a point where the SSO Link is generated, and then waits for a long time, the TPA access will fail with some "expired" message. Since for invocation types 1. and 2. the SSO Link is generated "on- the-fly", a rather short lifetime (like 10 secs) is sufficient in that case. For "Link in Content" invocation, you may want to allow some thinktime to the user. Default value (in seconds): 1800 .. _Require-SSL: Require SSL """"""""""" .. container:: table-row Field Require SSL Explaination If activated, the SSO Link will only be generated if the request method is HTTPS. Otherwise the content elements returns zero content. See Security Configuration Tasks on the importance of using SSL. .. _HTML-before: HTML before """"""""""" .. container:: table-row Field HTML before Explaination Enter here HTML Code here before the SSO Link .. _HTML-after: HTML after """""""""" .. container:: table-row Field HTML after Explaination Enter here HTML Code here after the SSO Link .. _Allow-to-create-the-user-in-the-Third-Party-Application: Allow to create the user in the Third Party Application """"""""""""""""""""""""""""""""""""""""""""""""""""""" .. container:: table-row Field Allow to create the user in the Third Party Application Explaination This allows the SSO Agent to update the Userdata in the Third Party application. .. _FE-Userdata-that-should-not-be-updated-or-commited-to-the-tpa: FE-Userdata that should not be updated or commited to the tpa """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .. container:: table-row Field FE-Userdata that should not be updated or commited to the tpa Explaination A colon seperated list of fields from your fe\_users table that should not be transferd to the third party application. .. ###### END~OF~TABLE ###### .. _User-Mapping-Rules: User Mapping Rules ^^^^^^^^^^^^^^^^^^ |img-7| *Picture 7 Edit a mapping Table* As an option, you may want to set up User Mapping Rules. This is typically needed when user names in TPAs differ from the ones used in TYPO3. User Mapping Rules may be - mapping tables that statically define "secondary" user name strings for TYPO3 user names. - pointers to external mapping data, e.g. in LDAP [not yet implemented] - rule-based transformations ("change to uppercase", "add department number", ...) [not yet implemented] User Mapping Rules are defined independently from the SSO content elements but can be assigned to them. Therefore one User Mapping Rule can be used for multiple SSO content elements. .. _User-Mapping-Tables: 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. .. _Configuration: Configuration ------------- .. _Architectural-Overview: Architectural Overview ^^^^^^^^^^^^^^^^^^^^^^ TYPO3 Single Sign-On does NOT really on a central reverse proxy but allows direct access to the TPA by securely passing a one-time-token to the browser (via URL). Thus, TPAs may be distributed across the net. Basically, we find a 3-layer architecture: TYPO3 (the Single Sign-On extension) dynamically creates a link ("SSO Link") that includes the desired TPA, user name, and security information (lifetime and signature). The SSO Agent, located on each target system (the machine where the TPA lives), validates the incoming browser request (coming from the SSO Link), talks to the TPA Adapter, and gives back an HTTP redirect to the browser that points to the TPA itself. The SSO Agent is not delivered with the extension but is available from [1]. Currently, the only SSO Agent implementation is a PHP script called "sigsso.php" but it can easily be ported to other languages. SSO Agents may be installed on multiple target system if you have TPAs on more then one server. The TPA Adapter is invoked by the SSO Agent via system call. It creates a valid user session ("logs on the user") by application- specific means, and returns all information needed to the SSO Agent (in a defined format). This adapter is TPA-specific - this means that you need to find or develop an appropriate adapter for every TPA that you wish to integrate. It may be written in any language you favour. See Adapter Developement for details. See [1] for a repository of existing TPA adapters. |img-8| *Picture 8Single Sign-On concept* One target server may optionally contain several TPAs, so each SSO Agent can be configured for more then one TPA adapter. Installation and Configuration of the Extension ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After installing the plugin through the EM, the first time you access the plugin module it will take you to the Configure Module option. Here you will have to enter: - Maximum displayed Users in the Backend while editing and creating Usermappings - externalOpenssl (true or false) for use command line OpenSSL if you have PHP compiled without OpenSSL. - Path to your private OpenSSL File - Passphrase (if used internalOpenSSL function in PHP) - FE-Userdata that should not be updated in the third party applications Note: Do not forget to submit this extension configuration form (click "update"). .. _Prerequisites-for-the-TYPO3-Server: 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: 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. .. _Creating-RSA-public-private-key-pair-with-OpenSSL: Creating RSA public/private key pair with OpenSSL ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The entire TYPO3 Single Sign-On mechanism is based on the authenticity of the SSO Link. This is ensured by the TYPO3 server's OpenSSL signature, created and verified by OpenSSL. Therefore you need to create and deploy a public/private key pair. Note: This is NOT related to the SSL keys you may be using for https in your web server ! In the following example OpenSSL will ask you to enter a passphrase. This is the OpenSSL private key Passphrase that you must enter for configuration when you install the Single Sign-On with the Extension Manager. :underline:`Example for usage with compiled-in OpenSSL:` Create a keypair: openssl genrsa -des3 -out sigsso\_private.key 2048 [this will ask you to define a passphrase for your key ("Enter PEM pass phrase")] openssl rsa -pubout -in sigsso\_private.key -out public.key Optional you can remove the passphrase from your key with: openssl rsa -in sigsso\_private.key -out sigsso\_private\_no\_passphrase.key :underline:`Or here is an example to create a key pair without passphrase (i.e. for external openssl invocation):` openssl genrsa -out sigsso\_private.key 2048 openssl rsa -pubout -in sigsso\_private.key -out sigsso\_public.key Make sure to move the private key file ("sigsso\_private.key") to a safe directory on your TYPO3 server, and minimize the access rights. Only the public key file ("sigsso\_public.key") must be deployed to the SSO Agent machines. See Creating RSA public/private key pair with OpenSSL for details. :underline:`Example:` mv sigsso\_private.key /usr/local/sigsso/etc/sigsso\_private.key chown wwwrun /usr/local/sigsso/etc/sigsso\_private.key chmod 400 /usr/local/sigsso/etc/sigsso\_private.key scp public.key john@www.my.tpa:/usr/local/sigsso/etc/sigsso\_public.key (plus maybe a chown/chmod on www.my.tpa) For more information on OpenSSL keys, see [4] and [5]. .. _Extension-Installation-Screenshot: Extension Installation Screenshot ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |img-9| *Picture 9Installing the extension* .. _Installation-and-Configuration-of-the-SSO-Agent-and-TPA-Adapters: Installation and Configuration of the SSO Agent and TPA Adapters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _SSO-Agent-Overview: 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) :underline:`Example:` cd htdocstar xfzf sigsso.php.tar.gz set the file access rights as needed :underline:`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: 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: SSO Agent - The [global] Section """""""""""""""""""""""""""""""" .. ### BEGIN~OF~TABLE ### .. _loglevel: loglevel ~~~~~~~~ .. container:: table-row Key loglevel Possible Values 0: no logging 1: errors (tpa\_id + user) 2: success and errors (tpa\_id + user) 3: errors (tpa\_id + user + expires + signature) 4: success and errors (tpa\_id + user + expires + signature) .. _public-key: public\_key ~~~~~~~~~~~ .. container:: table-row Key public\_key Possible Values /path/to/your/public.key .. _tokensfile: tokensfile ~~~~~~~~~~ .. container:: table-row Key tokensfile Possible Values /path/to/your/tokensfileused to store the data of used links .. _logfile: logfile ~~~~~~~ .. container:: table-row Key logfile Possible Values /path/to/your/logfile .. ###### END~OF~TABLE ###### [configuration of sigsso.conf, [global] section] :underline:`Example:` [global]loglevel:2public\_key: /path/to/your/public.keytokensfile: tokensfile.txtlogfile: sigsso.log .. _sigsso-conf-main-section: sigsso.conf [main] section """""""""""""""""""""""""" For each TPA you need to add one line here. The syntax is: (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 : and in the config file. Where 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: .. ### BEGIN~OF~TABLE ### .. _remote: %remote% ~~~~~~~~ .. container:: table-row Variable Name %remote% Explaination The IP address of the browser .. _agent: %agent% ~~~~~~~ .. container:: table-row Variable Name %agent% Explaination The browser's user agent identification string .. _user: %user% ~~~~~~ .. container:: table-row Variable Name %user% Explaination The user name to be logged on to the TPA .. ###### END~OF~TABLE ###### [configuration of sigsso.conf, [main] section, cmd:// call] :underline:`Example:` [main]MyOwnApp: cmd:///usr/lib/java/bin/java /path/to/tpa\_adapter --remote\_addr=%remote% ??url=https://redirect.url/index.jsp --uid=%user% --moreparameters=anything\_you \_need MyOwnPHPApp: php:///www/my/script.php -url=https://redirect.url/index.jsp .. _SSO-Agent-The-errorcodes-Section: 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: .. ### BEGIN~OF~TABLE ### .. _user-missing: user\_missing ~~~~~~~~~~~~~ .. container:: table-row Key user\_missing Default Value sigsso: Invocation error - missing USER .. _tpaid-missing: tpaid\_missing ~~~~~~~~~~~~~~ .. container:: table-row Key tpaid\_missing Default Value sigsso: Invocation error - missing TPA\_ID .. _expires-missing: expires\_missing ~~~~~~~~~~~~~~~~ .. container:: table-row Key expires\_missing Default Value sigsso: Invocation error - missing ExpirationTime .. _signature-missing: signature\_missing ~~~~~~~~~~~~~~~~~~ .. container:: table-row Key signature\_missing Default Value sigsso: Invocation error - missing signature .. _sslkey-missingconf: sslkey\_missingconf ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key sslkey\_missingconf Default Value sigsso: error in configfile - missing public\_ssl\_key .. _usedtokens-missingconf: usedtokens\_missingconf ~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key usedtokens\_missingconf Default Value sigsso: error in configfile - missing tokensfile entry .. _logfile-missingconf: logfile\_missingconf ~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key logfile\_missingconf Default Value sigsso: error in configfile - missing logfile .. _sslkey-missingfile: sslkey\_missingfile ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key sslkey\_missingfile Default Value sigsso: file access error - SSL public key file .. _usedtokens-missingfile: usedtokens\_missingfile ~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key usedtokens\_missingfile Default Value sigsso: file access error - UsedTokens file .. _logfile-missingfile: logfile\_missingfile ~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key logfile\_missingfile Default Value sigsso: file access error - log file .. _tpaid-unknown: tpaid\_unknown ~~~~~~~~~~~~~~ .. container:: table-row Key tpaid\_unknown Default Value sigsso: validation error - TPA\_ID is invalid or not configured .. _usedtokens-allreadyused: usedtokens\_allreadyused ~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key usedtokens\_allreadyused Default Value sigsso: validation error - SSO Link has been used before .. _signature-invalid: signature\_invalid ~~~~~~~~~~~~~~~~~~ .. container:: table-row Key signature\_invalid Default Value sigsso: validation error - signature invalid .. _expires-exeeded: expires\_exeeded ~~~~~~~~~~~~~~~~ .. container:: table-row Key expires\_exeeded Default Value sigsso: validation error - SSO Link expired (or system clock out of sync?)! .. _tpa-error: tpa\_error ~~~~~~~~~~ .. container:: table-row Key tpa\_error Default Value sigsso: An error in the Third Party Application Adapter occurred. It said: .. ###### END~OF~TABLE ###### [sigsso: default errorcodes] See Understanding Error Messages for an explaination of the error messages. :underline:`Example:` [errorcodes]signature\_missing: An error occured while trying to access the application. Please contact your system administrator.expires\_exceeded: http://my.errorpages.de/why\_expired.html .. _TPA-Adapter: TPA Adapter """"""""""" For installation and configuration, see the documentation that comes with your TPA Adapter. .. _Troubleshooting: Troubleshooting ^^^^^^^^^^^^^^^ .. _Increase-Logging: 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: Understanding Error Messages """""""""""""""""""""""""""" .. ### BEGIN~OF~TABLE ### .. _user-missing: user\_missing ~~~~~~~~~~~~~ .. container:: table-row Key user\_missing Possible Reasons can only be caused by bug in TYPO3 extension or by intentional manual manipulation of SSO Link (attack) .. _tpaid-missing: tpaid\_missing ~~~~~~~~~~~~~~ .. container:: table-row Key tpaid\_missing Possible Reasons can only be caused by bug in TYPO3 extension or by intentional manual manipulation of SSO Link (attack) .. _expires-missing: expires\_missing ~~~~~~~~~~~~~~~~ .. container:: table-row Key expires\_missing Possible Reasons can only be caused by bug in TYPO3 extension or by intentional manual manipulation of SSO Link (attack) .. _signature-missing: signature\_missing ~~~~~~~~~~~~~~~~~~ .. container:: table-row Key signature\_missing Possible Reasons can only be caused by bug in TYPO3 extension or by intentional manual manipulation of SSO Link (attack) .. _sslkey-missingconf: sslkey\_missingconf ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key sslkey\_missingconf Possible Reasons OpenSSL key not configured in SSO Agent config .. _sslkey-missingfile: sslkey\_missingfile ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key sslkey\_missingfile Possible Reasons OpenSSL key not found (or not accessible) at the location configured in SSO Agent config .. _usedtokens-missingconf: usedtokens\_missingconf ~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key usedtokens\_missingconf Possible Reasons "used tokens" file not configured in SSO Agent config .. _usedtokens-missingfile: usedtokens\_missingfile ~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key usedtokens\_missingfile Possible Reasons "used tokens" file not accessible at the location configured in SSO Agent config .. _logfile-missingconf: logfile\_missingconf ~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key logfile\_missingconf Possible Reasons logfile not configured in SSO Agent config .. _logfile-missingfile: logfile\_missingfile ~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key logfile\_missingfile Possible Reasons logfile not accessible at the location configured in SSO Agent config .. _tpaid-unknown: tpaid\_unknown ~~~~~~~~~~~~~~ .. container:: table-row Key tpaid\_unknown Possible Reasons misconfiguration in TYPO3 extension or SSO Agent config: TPA\_ID must match .. _usedtokens-allreadyused: usedtokens\_allreadyused ~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Key usedtokens\_allreadyused Possible Reasons SSO Link has been used before. This may have different reasons: - User did a doubleclick (instead of single click) - User opened TPA before and now tries to open it a second time (without TYPO3 having generated a new SSO Link) - Page containig the SSO Link is cached somewhere (server, browser, or in-between proxycache). Note: TYPO3 caching is coded to be always disabled for pages that contain Single Sign-On content elements. - Replay attack - someone intentionally tries to reuse the SSO Link .. _signature-invalid: signature\_invalid ~~~~~~~~~~~~~~~~~~ .. container:: table-row Key signature\_invalid Possible Reasons can only be caused by bug in TYPO3 extension or by intentional manual manipulation of SSO Link (attack) .. _expires-exeeded: expires\_exeeded ~~~~~~~~~~~~~~~~ .. container:: table-row Key expires\_exeeded Possible Reasons SSO Link lifetime exceeded - either it is actually exceeded because the user waited to long until clicking the link (consider increasing the Lifetime value in the configurationof the Single Sign-On content element) or the clocks are out of sync. .. _tpa-error: tpa\_error ~~~~~~~~~~ .. container:: table-row Key tpa\_error Possible Reasons TPA adapter returned an error - hopefully including some useful hints (Example: "user xy unknown in this application") .. ###### END~OF~TABLE ###### [sigsso: understanding errorcodes] .. _Try-the-TPA-Adapter-manually: 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. .. _Security-Considerations: Security Considerations ^^^^^^^^^^^^^^^^^^^^^^^ Be warned: Implementing a Single Sign-On framework requires very careful planning and implementation, since it may potentially affect the security and safety of all your TPAs! .. _Design: 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: 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: Security Configuration Tasks """""""""""""""""""""""""""" :underline:`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). :underline:`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. :underline:`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. :underline:`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. :underline:`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. :underline:`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. :underline:`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. :underline:`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. :underline:`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, :underline:`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). :underline:`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. :underline:`TYPO3 and Target System: Use PHPSafeMode!` [...] .. _TPA-Sign-On-Integration-TPA-Adapter-Development: TPA Sign-On Integration / TPA Adapter Development ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _Ways-of-Sign-On-Integration: 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. |img-10| 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 Link --- SSO Agent """""""""""""""""""""""""""""""""""""""""" .. _Format-Definitions-SSO-Agent-TPA-Adapter: 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. :underline:`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 ( or ). 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. :underline:`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: 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 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. .. _Terms-and-Acronyms: Terms and Acronyms ------------------ **one-time-token** see "SSO Link" **SSO** Single Sign-On **SSO Link** the URL of the target system's SSO Agent including parameters (user, TPA\_ID and verification data). Also referred to as the "one-time- token". **SSO Agent** located on each target system, validates the incoming browser request (coming from the SSO Link) and invokes the matching TPA adapter. **TPA** Third Party Application **TPA\_ID** TPA unique identification string, used to specify the target system of an SSO access **TPA Adapter** A system call that creates a valid user session inside the TPA and returns all necessary information to the SSO Agent. .. _Ressources: Ressources ---------- .. _Additional-Readings: Additional Readings ^^^^^^^^^^^^^^^^^^^ TYPO3 Single Sign-On Homepage and Adapter Repository `http://www.single-signon.com `_ The Open Group: "Introduction to Single Sign-On" `http://www.opengroup.org/security/sso\_intro.htm `_ Keys Botzum: "Single Sign On: A Contrarian View" `http://www-128.ibm.com/developerworks/websphere/library/techarticles/ 0108\_botzum/botzum.html `_ Making OpenSSL public/private keys `http://arch.cs.utwente.nl/courses/iwa/hwsw/x509.html `_ .. _Commercial-SSO-products: Commercial SSO products ^^^^^^^^^^^^^^^^^^^^^^^ Tivoli Access Manager Netegrity SiteMinder .. _Exemption-from-Liability: Exemption from Liability ^^^^^^^^^^^^^^^^^^^^^^^^ This software and concepts are provided as-is, without any statement or warranty regarding it's correctness, features and security. The terms of the GPL http://www.gnu.org/licenses/gpl.html apply. |img-11| EXT: Single Sign-On - 16 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :id: Grafik7 .. :name: Grafik7 .. :width: 100% .. |img-2| image:: img-2.png .. :align: left .. :border: 0 .. :id: Grafik8 .. :name: Grafik8 .. :width: 100% .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :height: 236 .. :id: Grafik2 .. :name: Grafik2 .. :width: 472 .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :id: Grafik3 .. :name: Grafik3 .. :width: 100% .. |img-5| image:: img-5.png .. :align: left .. :border: 0 .. :id: Grafik4 .. :name: Grafik4 .. :width: 100% .. |img-6| image:: img-6.png .. :align: left .. :border: 0 .. :id: Grafik5 .. :name: Grafik5 .. :width: 100% .. |img-7| image:: img-7.png .. :align: left .. :border: 0 .. :name: Edit a mapping Table .. :width: 100% .. |img-8| image:: img-8.png .. :align: left .. :border: 0 .. :name: Single Sign-On concept .. :width: 100% .. |img-9| image:: img-9.png .. :align: left .. :border: 0 .. :id: Grafik6 .. :name: Grafik6 .. :width: 100% .. |img-10| image:: img-10.png .. :align: left .. :border: 0 .. :height: 386 .. :id: Grafik1 .. :name: Grafik1 .. :width: 600 .. |img-11| image:: img-11.png .. :align: left .. :border: 0 .. :height: 32 .. :id: Graphic1 .. :name: Graphic1 .. :width: 102