How to: Single Sign-on, a Convenient Way to Authenticate Users

Single sign-on (SSO) is a way to authenticate users on multiple related, but independent software systems. Once logged in, a user can switch from one system to the next without the need to login again. Conversely, single sign-off is a way to log out and terminate access to multiple software systems with a single sign-off action.

In contrast, a shared authentication scheme that requires the user to log in multiple times using the same identity is not called SSO. An example is a central user directory such as Active Directory, where users login to their Windows desktop, then enter login name and password again to login into a TWiki server using the same credentials (done via LDAP talking to the directory server).

There are many benefits in favor of SSO:

• Usability:
  • Users only need to remember one login and password.
• Security:
  • Centralized reporting for compliance adherence.
  • SSO reduces the risk of phishing because users do not need to login multiple times.
• Productivity:
  • Reduced time spent re-entering passwords.
  • Reduced IT costs due to lower number of IT help desk calls related to passwords.

There are also disadvantages. An obvious one is single point of failure: All systems go down if the SSO authentication server fails. Another one is security: All systems will be accessible by an intruder if a user account is compromised.

Many SSO implementations are available. Here are a few:

• Central Authentication Service (CAS): SSO protocol defined by Yale University.
• Distributed Access Control System (DACS): Distributed Systems Software, open source.
• Facebook connect: Facebook specific SSO.
• JBoss SSO: SSO solution by JBoss, open source.
• Kerberos: Popular SSO protocol defined by MIT.
• OneLogin: SSO with SAML and Active Directory integration, commercial and free, by OneLogin Inc.
• SAML: XML-based open standard protocol, by OASIS.
• Shibboleth: SAML-based open source access control.
• Windows Live ID: Microsoft SSO web service, commercial.

I just created an SSO integration for a TWiki site. The sponsor, Wave Systems Corporations, was generous enough to open source the integration, now available at SsoLoginContrib. The SSO will be rolled out shortly at the developer.scrambls.com TWiki site.

Here is what is happening behind the scenes:

1. A user logs in to the www.example.com domain.
2. 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.
3. 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.
4. The SsoLoginContrib looks for the presence of x-example-authtoken and, if present, will pass its value to the SSO authentication server on www.example.com for verification.
   • The actual SSO API call is something like https://d8ngmj9w22gt0u793w.roads-uae.org/api/auth/<authtoken>, where <authtoken> is replaced by the cookie value.
   • Some SSO authentication servers 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
5. 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 on success, 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 sets the authenticated user (e.g. login name) to the value specified in the JSON response.
6. TWiki responds to the request using the login name received from the SSO server.

Have you done an SSO integration for TWiki? If so I invite you to share what you learned. For TWiki administrators, do you think SSO is useful for your own site?

-- PeterThoeny - founder of TWiki.org

Related:

• http://3020mby0g6ppvnduhkae4.roads-uae.org/wiki/Single_sign-on - SSO article on Wikipedia
• http://3020mby0g6ppvnduhkae4.roads-uae.org/wiki/List_of_single_sign-on_implementations - list of single sign-on implementations
• SsoLoginContrib - SSO integration package for TWiki

Comments

The SSO is now rolled out at the developer.scrambls.com TWiki site. BTW, the Scrambls is an interesting technology to scramble content in any social media site. Check it out, it is free to use.

-- Peter Thoeny - 2012-07-01

X.509 Client certificates are another implementation of SSO - which TWiki supports via a plugin. Certificates allow access control at both the webserver and application level. They can eliminate password entry, or make it happen only in the web browser. And they support non-web applications natively (e.g. signed/encrypted e-mail.) Centralized SSO has many tradeoffs. It's important to look at all the technologies, your user base & application environment before making a choice.

-- Timothe Litt - 2012-07-27

Hi Peter, This solution seems not working for Foswiki with Jasig CAS. I followed the instruction and replace all TWiki with Foswiki. The site is loaded without problem. When I clicked "Log In" it will direct to CAS login page. After entering user name and password, it still stayed in the CAS site showing "Log In Successfully" and did not redirect back to the Foswiki site.

Can you give me some idea on this? Thanks,

-- Winson Huang - 2012-08-16

I can't talk for the fork, my focus is usability and quality code on TWiki.org. In your case, if you navigate to TWiki are you actually logged in? If so, the redirect is not working properly. Check the %ORIGURL% redirect variable in the $TWiki::cfg{SsoLoginContrib}{LoginUrl} configure setting. Test this manually. Make sure your SSO login supports redirect. Don't reply here, better to open a support question in the Support web.

-- Peter Thoeny - 2012-08-16

Hello Peter, I'm trying to setup a instalation with TWiki and OpenERP with SSO. I've a server with CAS Jasig and ldap and, With this SSO package I manage to autenticate but after that I' stuck in the CAS page like Winson above. Any ideias? I'm using twiki, last version.

My configurations parameters are:

$TWiki::cfg{SsoLoginContrib}{AuthTokenName} = 'x-authtoken-MYDOMAIN'; $TWiki::cfg{SsoLoginContrib}{VerifyAuthTokenUrl} = 'https://uhh0czkumqmfr7fg3w.roads-uae.org:8443/cas/validate/%AUTHTOKEN%'; $TWiki::cfg{SsoLoginContrib}{VerifyAuthTokenHeader} = 'x-sso-api-key, API key value'; $TWiki::cfg{SsoLoginContrib}{VerifyResponseLoginRE} = '"loginName":"([^"]*)'; $TWiki::cfg{SsoLoginContrib}{LoginUrl} = 'https://uhh0czkumqmfr7fg3w.roads-uae.org:8443/cas/login?service=%ORIGURL%'; $TWiki::cfg{SsoLoginContrib}{LogoutUrl} = 'https://uhh0czkumqmfr7fg3w.roads-uae.org:8443/cas/logout?service=%ORIGURL%';

If this works I will be glad to describe the entire solution, with detailed instalation procedures.

Regards

-- Antonio Sequeira - 2013-09-22

Antonio: If you use TWiki older than 5.1.1 you need to apply the patch. Upgrade to the latest SsoLoginContrib. Make sure your SSO login server supports redirect after login; verify that you specify the proper redirect URL for login. Best to open a new Support question to debug this further.

-- Peter Thoeny - 2013-09-26

.