ai-sso - a Single Sign-On implementation
EXPERIMENTAL - DO NOT USE IN PRODUCTION
This is a Single Sign-On (SSO) implementation, comprehensive of a login server and various client (middleware) modules that cover application setups such as Apache and WSGI.
The service uses cryptographically signed tickets, short-term authorization credentials generated by a central login service, whose validity can be independently verified by the authentication client.
The protocol works over HTTP, using cookies to store tickets. This makes it work out-of-the-box for browsers, but programmatic access is also possible (an example Python client is provided).
Note that, as with all cookie-based authentication systems, possession of the cookie is sufficient for authentication purposes: this makes them vulnerable to XSS and XSRF techniques. Users and application developers are expected to take the necessary preventive measures.
The login service is fully stateless and can be easily replicated (for
large setups). Authentication is ultimately performed by pluggable
authentication modules (PAM and LDAP support are included in the
source distribution). You can write your own following the API in
A service is just an application that supports SSO. Since these are usually served over HTTP, the service specification is modeled after the URL syntax:
The https URL scheme is implied, thus forcing all client interactions with the system to happen over SSL. Note that the service name should always end with a slash.
Currently, a domain is simply a high-level namespace for authentication, and it is not really used except that it needs to match between the clients and the login service. It can be set to any domain name (which does not necessarily need to exist).
This section discusses briefly the implementation details.
Here is an example interaction between the browser, an SSO-enabled application and the login server:
1) When a client connects to a SSO-enabled application, we search for a local, service-specific, SSO cookie. If a valid cookie is found, the request will be successfully handled by the application:
2) The application redirects the client to the SSO login server, asking it to generate a new ticket (we're skipping URL quoting for readability):
3) The SSO server checks for its own SSO cookie (using login.some.com/ as the service name). If the cookie is not valid, show username/password prompt page, and check the credentials against the authentication database
The SSO server redirects to the original application:
5) The application sets the local, service-specific, SSO cookie to the value provided in the t parameter, and redirects the client to the original URL (d).
Each service supporting SSO must provide support for two special URLs:
- Called with the t and d parameters, it should set the SSO ticket to the (base64-decoded) value of t, and redirect the client to the URL specified by d (eventually checking that it lies within its own service namespace).
- Clear the SSO ticket for this service and any other application-specific credentials. This handler should return an HTML page containing just the text "OK".
The login server supports the following parameters:
- s - Service name
Note that all service names should end with a slash. The service name is used to generate the sso_login URL, in the following way (abusing shell syntax for clarity):
- d - Redirect URL
- When the login process is complete, redirect the user to this URL.
- g - Requested group membership
- A comma-separated list of group names. When authenticating the user, the login service will also check that it is a member of one or more of the specified groups, or the authentication will fail.
https://login.some.com/logout will log the user out of all
the applications by calling their
/sso_logout handlers (using
SSO Ticket Format
An SSO ticket is just a signed string consisting of fields separated
by the pipe (
|) character. It includes the ticket format version,
username, service name, domain name, and group memberships.
The current format version number is 3.
To compile the software you'll need to install a few dependencies first:
- Apache2 development headers and libraries for your favorite threading model
- Python development environment
On a Debian/Ubuntu system this can be accomplished with the following command (including dependencies required to run tests):
$ sudo apt-get install swig libpam0g-dev apache2-dev \ python-dev python-setuptools python-nose python-m2crypto
Then it should be just a matter of running:
$ sh autogen.sh $ ./configure --enable-mod-sso --enable-pam-sso $ make install
To run the internal test suite:
$ make check
Configuring Apache with mod_sso
You can add SSO support to Apache using mod_sso, which will be
installed if you pass
configure. It adds
SSO authentication method, which can be used with the standard
require directive as follows:
<Location /> AuthType SSO SSOService this.host.name/ require valid-user </Location>
require user and
require group also works as expected.
Note that in some cases you might have to exclude the sso_login and sso_logout URLs from being handled by another module, for instance if you are using mod_proxy this should be added to your config:
ProxyPass !sso_login ProxyPass !sso_logout
The following directives can be used to configure mod_sso:
- Service name for the local application. Can appear anywhere.
- URL of the login server. Must appear only once, in the top-level configuration.
- The shared authentication domain. Must appear only once, in the top-level configuration.
- Location of the file containing the login service public key.
Python / WSGI
The source distribution includes Python WSGI middleware to use for your Python web applications. An example:
from sso.middleware import SSOMiddleware app = SSOMiddleware(app, service='test.example.com/', domain='example.com')
An SSO-aware PAM module is available, for integration with other services. It knows about the following parameters:
- Service name.
- Shared authentication domain.
- URL of the login server.
- Location of the file containing the login service public key.
The login service is a WSGI application so you can adapt it to
whatever deployment strategy is required. It can also run standalone
from the command line, which is useful for debugging. In all cases, it
needs a configuration file (located using the
environment variable if not specified on the command line), which
supports the following variables (and has Python syntax):
- Location of the file with the secret key (
- Location of the file with the public key (
- Module to use for authentication, specified as a Python import path
(the default of
sso_server.auth.auth_testshould definitely be changed).
- A list of regular expression patterns defining the services which are allowed. If left unset (the default), no checks will be performed on the destination service upon authentication. Production instances should not leave this unset.
- Time to live for the main SSO login ticket (in seconds).
- Time to live for service-specific SSO tickets (in seconds).
- HTML_TITLE, HTML_BANNER
- A minimal attempt at customizing the user-facing login page.
You can use
ssotool to generate the key pair for the login
$ ssotool --gen-keys --output public.key --secret-key secret.key