SsoForwardCookiePlugin

Page contents

• Usage
• Advanced Usage
• Examples
• Technical Information
• Installation Instructions
• Plugin Info

Plugin to add credential cookie forwarding handler for external HTTP requests

Usage

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.

Examples

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.

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

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.

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

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