SSO Login Contrib Package

Generic SSO (Single Sign-on) module for Foswiki

Introduction

Single sign-on (SSO) is a property of access control of multiple related, but independent software systems. With this property a user logs in once and gains access to all systems without being prompted to log in again at each of them. Conversely, Single sign-off is the property whereby a single action of signing out terminates access to multiple software systems.

The SsoLoginContrib is a login manager for Foswiki that handles cookie based SSO authentication. This requires a SSO authentication service on the same domain.

Detailed Documentation

• A user logs in to the example.com domain; a domain-level cookie named x-example-authtoken is set; the value of the cookie is an auth token, such as auth:1234-5678-9abcd.
• The user visits twiki.example.com; because the x-example-authtoken cookie is a domain level cookie, the browser will send that cookie to all requests on that site.
• The SsoLoginContrib looks for the presence of x-example-authtoken and, if present, will pass its value to an SSO API on example.com for verification.
• The actual SSO API is something like https://example.com/api/auth/<authtoken>, where <authtoken> is replaced by the cookie value.
• Some SSO APIs require to pass an API key in the HTTP header as part of that API call; such as:
  x-example-key: abcd-ef01-2345-6789
• The SSO API call returns either:
  • A 403 error code, which means it's either a bad/expired auth token or the API key is not valid/present/has-been-denied-access
  • A 200 code with JSON in the response body
• The JSON response depends on the SSO API, and may look something like the following:
  {"type":"named", "displayName":"Jimmy Neutron", "loginName":"jimmy@example.com"}
• The SsoLoginContrib uses the login name found in the JSON response to set the authenticated user in Foswiki. Foswiki has three representations for authenticated users:
  • USERNAME (login name), example jimmy@example.com, you are guest
  • Canonical User ID, example jimmy_40example_2ecom, this is built from the login name
  • WIKINAMENAME, example Jimmyexamplecom or JimmyNeutron, you are WikiGuest

• If the user is not logged in, Foswiki will show a "login" link that points to the SSO service to login, else a "logout" link is shown that points to the SSO service to log out.

• Users do not need to register in Foswiki, but they can if they want to have their own Foswiki profile page, or if their WikiName needs to be added to FoswikiGroups.
  • Unregistered users will have a "WikiName" built by stripping out non-ASCII characters from the login name. For example, jimmy@example.com becomes Jimmyexamplecom, and user signatures point to Main.Jimmyexamplecom.
  • Registered users will have profile page with their WikiName as the page name, such as JimmyNeutron. The mapping from login name to WikiName is done in the FoswikiUsers page - fix entries there in case login names change.

Configuration

Run the configure script and set the following settings. Alternatively, edit the lib/LocalSite.cfg configure file directly. Settings:

# ---+ Security setup section

# ---++ Authentication

# enable SSO login:
$Foswiki::cfg{LoginManager} = 'Foswiki::LoginManager::SsoLogin';

# remove the "@" character from the login name filter in case users login with an e-mail address:
$Foswiki::cfg{LoginNameFilterIn} = '^[^\\s\\*?~^\\$%`"\'&;|<>\\x00-\\x1f]+$';

# ---++ Registration

# allow login name, and don't ask for password in registration page:
$Foswiki::cfg{Register}{AllowLoginName} = 1;

# ---++ Passwords

# no password manager:
$Foswiki::cfg{PasswordManager} = 'none';

# ---+ Extensions section

# name of auth token cookie:
$Foswiki::cfg{SsoLoginContrib}{AuthTokenName} = 'x-authtoken-cookie-name';

# URL of SSO API to verify an auth token; %AUTHTOKEN% is set to the cookie value of the auth token
$Foswiki::cfg{SsoLoginContrib}{VerifyAuthTokenUrl} = 'https://example.com/api/auth/%AUTHTOKEN%';

# Some SSO APIs require to pass a key in the header of the http request; use comma-space delimited list:
$Foswiki::cfg{SsoLoginContrib}{VerifyAuthTokenHeader} = 'x-sso-api-key, API key value';

# regular expression to extract the login name from the JSON response:
$Foswiki::cfg{SsoLoginContrib}{VerifyResponseLoginRE} = '"loginName":"([^"]*)';

# login URL; %ORIGURL% is set to the original URL where the user is sent after login:
$Foswiki::cfg{SsoLoginContrib}{LoginUrl} = 'https://example.com/login?redirect=%ORIGURL%';

# logout URL; %ORIGURL% is set to the original URL where the user is sent after logout:
$Foswiki::cfg{SsoLoginContrib}{LogoutUrl} = 'https://example.com/logout?redirect=%ORIGURL%';

Installation Instructions

Note: You do not need to install anything on the browser to use this contrib package. The following instructions are for the administrator who installs the package on the server where Foswiki is running.

• 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 SsoLoginContrib.zip in your twiki installation directory. Content:

    File:	Description:
    data/Foswiki/SsoLoginContrib.txt	Documentation topic
    lib/Foswiki/Contrib/SsoLoginContrib.pm	Contrib Perl module
    lib/Foswiki/Contrib/SsoLoginContrib/Config.spec	Configure spec file
    lib/Foswiki/LoginManager/SsoLogin.pm	SSO Perl module

  • Set the ownership of the extracted directories and files to the webserver user.

• Contrib module configuration:
  • Run the configure script and set the {SsoLoginContrib}{...) settings in the Extensions section as described above.

Contrib Info

This contrib is sponsored by:

• Wave Systems Corp.

Short description:

• Set SHORTDESCRIPTION = Generic SSO (Single Sign-on) module for Foswiki

Dependencies:	CPAN:LWP in case SSL is used to verify the auth token
Change History:
2013-09-26:	TWikibug:Item7353: Prepare for TWiki-6.0 release
2012-06-28:	TWikibug:Item6895: Initial version
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/SsoLoginContribDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/SsoLoginContribAppraisal

Related Topics: UserAuthentication