How WebCheckout Uses SSO

WebCheckout supports a variety of Single Sign-On (SSO) systems. SSO requires several components:

  • An identity provider (IdP) where user accounts are managed, and which is responsible for vetting credentials.
  • The application, in this case WebCheckout, participating in SSO.
  • A service provider (SP), running on the WebCheckout server, which is the glue between the SP and the IDP.

All applications including WebCheckout, the Patron Portal, the Dashboard, and Personnel Scheduling support SSO, and in all cases the system works in the same manner.

When users open WebCheckout or its related applications for the first time, that request comes to the Apache web server on the WebCheckout server, the SP intercepts the request, and identifies that it is lacking a session.

Normally at this point, the SP will redirect users to a login portal. This is a centrally managed website which first determines whether the user already has an authentication session. If not, the login portal prompts users for their credentials. Different SSO technologies work in different fashions, but in most cases, sessions are tracked using a secure token, normally an HTTP cookie.

So, assuming users logged into the central portal, an authentication session is created. At this point the login portal provides a session token to the user, and redirects the user back from whence that came, in this case, WebCheckout and the service provider it is running behind.

Again the SP intercepts the request, but this time the request indicates a secure token. The service provider checks the validity of the token with the IDP, and if all is well, allows the request to continue. However, the SP isn’t merely passing the request through, it adds a special header to the request which tells WebCheckout that yes, this user has authentication, and provides the userid.

Since this is the first time WebCheckout is seeing the request, this requires a WebCheckout session as well. Whereas normally WebCheckout would prompt the user for their credentials, in SSO mode, WebCheckout instead checks the inbound request for the special header. Using the userid in that header, WebCheckout makes sure it can identify which user the session is for. The session is created, using a cookie, and the user is prompted for a Checkout Center (if necessary).

All subsequent requests from this user will have the same identifying header.

Supported SSO Systems

WebCheckout supports any SSO provider which has an Apache authentication module capable of setting headers on proxied requests.

Some examples of known supported SSO solutions:

The Shibboleth Apache service provider, combined with the Apache authentication module ‘mod_shib’, is a very interoperatable SAML 2 client. A number of SAML 2 compliant SSO solutions should interoperate with this combination. Some information concerning interoperability can be found in the Shibboleth documentation.

Requirements

  1. Apache must be configured to a header indicating the user on the requests are proxied to WebCheckout applications.
  2. Customers are encouraged to make use of SSL in conjunction with SSO. This protects client security tokens (usually HTTP cookies) from man-in-the-middle attacks. SSL is not required, however.
  3. Customer must provide a valid SSO account so that WebCheckout Support can use for testing and continued support services.
  4. The user identification present in the header containing the userid must literally match the userid to log into the SSO system including case sensitivity.
    • Mapping functions could be formulated and provided but will require development of such mapping functions and can require paid customization.

Many SSO systems can be configured to use environment variables rather than setting headers in the request as it is proxied to WebCheckout. It is important that the customer not configure the system this way as it will not work: the WebCheckout process is not a descendent of any Apache process and does not inherit its environment.

 

Delegation of Responsibility

With Single Sign-On, customer take responsibility that users are securely identified. Customer must accept responsibility for the maintenance, security and integrity of the authorization process. WebCheckout authorization is bypassed, and instead, the backend simply trusts that the indicated user really is authenticated. In other words, passwords stored in WebCheckout are invalid. Likewise, the administration of the federated identity server (usually called an IDP or Identity Provider) is the responsibility of the customer.

For customers who we host

WebCheckout Support is responsible for: 

  • The configuration of the service provider.
  • Configuration of Apache module which links inbound requests with the local service provider.
  • Working with client’s system administrator to configure authentication method and trouble-shoot any authentication issues if the need arises.

Customer is responsible for:

  • Providing a secure means by which the locally running service provider communicates with the identity provider. Commonly, HTTPS is used for this.
  • Providing the below information to enable and test SSO:
  1. File containing the IdP metadata or a URI, accessible from the WebCheckout server, that points to it.
  2. Which EntityID in the above metadata will WebCheckout use as the SSO IdP?
  3. Coordinate with your Webcheckout administrator to confirm that the value they have configured as the WebCheckout userID is available via the IdP and uniquely identifies a single user.
  4. What is the ID and SAML name of the attribute when searching the WebCheckout userID values for the authenticated user? For example: id =”uid”, SAML 2 name=”urn:oid:0.9.2342.19200300.100.1.1″ Please note this attribute value must match the value in the WebCheckout userid exactly, including case sensitivity.
  5. When a user logs out of the WebCheckout SP, to what URL, if any, should the session result to to log them out of the IdP?
  6. WebCheckout Support requires a testing userID and password on the IdP or a contact who can work with us via phone to perform the authentication testing. How will we receive the credentials or whom will we be working with for testing?

For customers who we do not host

WebCheckout Support has no visibility into client’s identity provider and limited access to the service provider. Due to these limitations, the configuration and management of authentication related issues is the client’s responsibility.

Customer is responsible for: 

  • Installation of the service provider.
  • Installation of Apache authentication.

Commonly, IT departments have a standard method of SP configuration. WebCheckout requires a secure, agreed-upon request header which accompanies every SSO request (not just login). This header must be provided to the backend servers (WebCheckout and/or Patron Portal) only when the user has been properly authenticated. In cases where assistance is required, we can assist with configuration of the Service Provide and/or the Apache module, however, you will be charged a standard hourly rate for this work.

For both WebCheckout-hosted and customer-hosted servers, it is the customers responsibility that the userIDs in WebCheckout match the inbound userID found in the authentication header, described above. In order to facilitate the mapping of userids, it is common that SSO customers have Patron Data integration setup as well. This is a recommended combination, but note that integration charges are not included in the base SSO price.

Detail Configuration Notes

To explain how this works, first a quick overview of how user requests come into our applications:

  1. Browser makes request to server
  2. Apache handles request, possibly rewriting and rerouting the request
  3. Apache hands the conditioned request to the application server

Apache mediates all transactions between the application and the user.

When SSO is enabled, as part of the second step, an Apache module of some sort is used for the purposes of user authentication. Several authentication providers are available, including mod_shib, which acts as a Shibboleth Service Provider, or mod_auth_basic, combined with static htpassword files.

WebCheckout Configuration

If SSO is disabled for a particular application, the user will see the usual login form.

If SSO is enabled, the trusted header is present in the incoming request, and its value a valid user for the given application, the login form will be bypassed, a session created, and the next page in the login process served up.

If SSO is enabled but the header is not present, or if its value is not a valid user, an HTTP status code 403 will be returned.

Example of Apache config, mod_shibd

Assuming you have Apache mod_shib configured properly, and pointing at the correct Identity Provider, this is all you need to Shibboleth-enable
one or more applications.

<Location />
    AuthType shibboleth
    ShibUseHeaders On
    ShibRequireSession On
    require valid-user
</Location>

Adjust the URL in Location as desired. Here’s how to do it just for PIR:

<Location /pir/>
  AuthType shibboleth
  ShibUseHeaders On
  ShibRequireSession On
  require valid-user
</Location>

Example of Apache config, basic authentication

For the purposes of testing, its sometimes helpful to testing using basic apache authentication. This allows you to simulate SSO without requiring any 3rd party servers such as Shibboleth or LDAP.

Here’s the appropriate apache snippet:

# SSO testing
<Location />
  AuthType Basic
  AuthName "Candidate2 SSO testing"
  AuthBasicProvider file
  AuthUserFile /etc/apache2/sso.passwd
  Require valid-user
</Location>

RewriteCond %{LA-U:REMOTE_USER} (.+)
RewriteRule . - [E=RU:%1]
RequestHeader add REMOTE_USER %{RU}e

You will have to use ‘htpasswd’ to setup some user accounts in /etc/apache2/sso.passwd. Remember to make the account login with the WebCheckout userid.

Supplementary Modules