authentication1Add my vote for this tag integration1Add my vote for this tag create new tag
, view all tags


Plugin to add credential cookie forwarding handler for external HTTP requests


On the intranet, users enjoy single sign-on for almost all the sites including locally installed TWiki. In order to use an intranet URL for %INCLUDE{...}%, the single sign-on token needs to be forwarded to the included URL.

This plugin hooks any HTTP requests from TWiki to external resources inside the intranet, so that the credential token in the cookie from the browser is forwarded to the destination.

The administrator needs to configure the following values via the configure script.

  • $cfg{Plugins}{SsoForwardCookiePlugin}{Domains} (required, separated by commas or spaces)
    • List of domain names to match each requested URL to determine if cookies should be forwarded.
      • $cfg{Plugins}{SsoForwardCookiePlugin}{Domains} = "app1.example.com, app2.example.com"
    • If a specified domain starts with a dot (.), it matches any subdomains. Otherwise, only the exact domain is matched.
      • $cfg{Plugins}{SsoForwardCookiePlugin}{Domains} = ".example.com"
    • Specific port numbers can optionally be added.
      • $cfg{Plugins}{SsoForwardCookiePlugin}{Domains} = "example.com:8080"
      • Note: If the port number is omitted, only the default port (80 for HTTP; 443 for HTTPS) is matched. The default ports should not be explicitly specified in the config parameter.
    • Alternatively, a topic name can be specified as topic:Web.Topic. For example,
      • $cfg{Plugins}{SsoForwardCookiePlugin}{Domains} = "topic:%SYSTEMWEB%.SsoForwardCookieDomains"
        • where variables with percent signs (%) will be expanded; or
      • $cfg{Plugins}{SsoForwardCookiePlugin}{Domains} = "topic:SsoForwardCookieDomains"
        • if only a topic name is given, it defaults to %SYSTEMWEB%.
    • The specified topic is expected to contain domain names in the table format as below. This plugin comes with an example SsoForwardCookieDomains topic, which can be edited and used.
      | *Domain* |
      | example.com |
      | .example.com |
  • $cfg{Plugins}{SsoForwardCookiePlugin}{CookieNames} (required, separated by commas or spaces)
    • Names of cookies that are allowed to be forwarded. Specify a single star (*) to forward all the cookies, although it is not recommended.

For troubleshooting, try turning on the Debug flag and see the debug log:

  • $cfg{Plugins}{SsoForwardCookiePlugin}{Debug} = 1;

For audit logging, enable the Logging option. Whenever the user credentials are forwarded, it is recorded in the debug log.

  • $cfg{Plugins}{SsoForwardCookiePlugin}{Logging} = 1;
Or, set it to 2 so that the event is recorded regardless of whether the credentials are forwarded.
  • $cfg{Plugins}{SsoForwardCookiePlugin}{Logging} = 2;

Advanced Usage

  • $cfg{Plugins}{SsoForwardCookiePlugin}{CookieDomain} (optional)
    • If this parameter is set, the "domain" part of the forwarded cookie is set to the domain. Without this option by default, the "domain" part is automatically configured, based on the matched domain name.
  • $cfg{Plugins}{SsoForwardCookiePlugin}{LocalDomain} (optional)
    • Specify local domain(s). For example, specify ".example.com" if "hostname" should be the same as "hostname.example.com".
    • If this option is present, all the domain settings in Domains or MdrepoTable configs must omit the local domain suffix.
  • $cfg{Plugins}{SsoForwardCookiePlugin}{MdrepoTable} (optional)
    • This option allows you to manage the domain names in mdrepo. It can be used as a substitute of $cfg{Plugins}{SsoForwardCookiePlugin}{Domains} or can be used in addition at the same time.
    • $cfg{Plugins}{SsoForwardCookiePlugin}{MdrepoTable} = "ssoforward"
    • and in order for the table name to be available, also add the table name like this:
      • $cfg{Mdrepo}{Tables} = ['webs:b', 'sites', 'ssoforward'];
    • The domain name entry should be the record ID in the mdrepo table. This plugin does not require the values of the record. In other words, whatever values are set, they are ignored, so use them for your own purpose.


Suppose your TWiki server is running at http://twiki.example.com. In the example.com intranet, there are many single sign-on sites, such as http://abc.example.com, http://xyz.example.com, and so on.

Then the Domains configuration should be set to ".example.com" (notice: the leading dot), where any subdomains under .example.com are considered as intranet sites.

IDEA! Note: If the Domains configuration is set without the leading dot, only the exactly matched domain is considered as the single sigin-on target. For example, if it is set to "example.com", the credential forwarding takes place for http://example.com/... but not for http://abc.example.com/....

When %INCLUDE{"http://xyz.example.com/..."}% is used, the credential token that comes from the browser to TWiki will be forwarded from TWiki to xyz.example.com.

The name of the cookie values must also be configured properly. If your intranet uses SiteMinder for example, the cookie name should be set to "SMSESSION". If you prefer to forward all the cookies that the browser sends to TWiki, set it to a single star (*), although it is not recommended.

Technical Information

These are the expected targets that are affected by this plugin:

  • %INCLUDE{...}%
  • TWiki::Func::getExternalResource()
  • TWiki::Func::postExternalResource()

The plugin extracts the cookie value from the HTTP_COOKIE environment variable. It does not work if this environment variable is not visible from the TWiki script (due to Apache configs, modules, or any other factors).

IDEA! If you see the error "This site does not allow %INCLUDE% of URLs", check $cfg{INCLUDE}{AllowURLs} to see if it is enabled (set to 1 in lib/LocalSite.cfg).

Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip SsoForwardCookiePlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/SsoForwardCookiePlugin.txt Plugin topic
      lib/TWiki/Plugins/SsoForwardCookiePlugin.pm Plugin Perl module
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies.

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Configure additional plugin settings in the Extensions section if needed.
    • Test if the installation was successful using the example above.

Plugin Info

Many thanks to the following sponsors for supporting this work:

  • Acknowledge any sponsors here

Plugin Author(s): TWiki:Main.MahiroAndo
Copyright: © 2012-2013 TWiki:Main.MahiroAndo
© 2012-2013 TWiki:TWiki.TWikiContributor
License: GPL (Gnu General Public License)
Plugin Version: 2013-07-10
Change History:  
2013-07-10: TWikibug:Item7292: causing "use of uninitialized value" warning in the statistics script executed from command line - TWiki:Main.HideyoImazu
2013-06-06: TWikibug:Item7279: Write audit log also when cookie is not forwarded - TWiki:Main.MahiroAndo
2013-05-21: TWikibug:Item7261: causes unitinialized value warnings when invoked from a command line - TWiki:Main.HideyoImazu
2013-04-16: TWikibug:Item7230: SsoForwardCookiePlugin: more flexible domain whitelist management and matching - TWiki:Main.MahiroAndo
2013-04-04: TWikibug:Item7212: Initialize static variable in initiPlugin - TWiki:Main.MahiroAndo
2012-11-05: TWikibug:Item7022: Accept topic:Web.Topic format for Domains - TWiki:Main.MahiroAndo
2012-10-25: TWikibug:Item7011: Renamed this plugin - TWiki:Main.MahiroAndo
2012-10-16: TWikibug:Item6989: Initial release - TWiki:Main.MahiroAndo
Dependencies: CPAN:HTTP::Cookies
Plugin Home: http://twiki.org/cgi-bin/view/Plugins/SsoForwardCookiePlugin
Feedback: http://twiki.org/cgi-bin/view/Plugins/SsoForwardCookiePluginDev
Appraisal: http://twiki.org/cgi-bin/view/Plugins/SsoForwardCookiePluginAppraisal

Related Topics: TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatmd5 SsoForwardCookiePlugin.md5 r9 r8 r7 r6 r5 manage 0.2 K 2013-07-10 - 11:58 HideyoImazu  
Compressed Zip archivetgz SsoForwardCookiePlugin.tgz r9 r8 r7 r6 r5 manage 8.9 K 2013-07-10 - 11:58 HideyoImazu  
Compressed Zip archivezip SsoForwardCookiePlugin.zip r9 r8 r7 r6 r5 manage 10.6 K 2013-07-10 - 11:58 HideyoImazu  
Unknown file formatEXT SsoForwardCookiePlugin_installer r1 manage 3.4 K 2013-07-10 - 11:58 HideyoImazu  
Edit | Attach | Watch | Print version | History: r9 < r8 < r7 < r6 < r5 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r9 - 2013-07-10 - HideyoImazu
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.