Cassava CAS Server

Description

Cassava allows WordPress to act as a single sign-on authenticator using the Central Authentication Service (CAS) protocol.

That way, users on your WordPress install may be able to access different applications that support the CAS protocol by providing a single set of credentials and without exposing the user’s password.

By default, CAS method URIs are provided under the wp-cas endpoint:

  • /wp-cas/login: Allows a remote service to request that a user authenticate on the CAS server. Will redirect back to the remote service along with a service ticket.
  • /wp-cas/logout: Terminates the single sign-on session. May optionally redirect the user back to the remote service.
  • /wp-cas/validate [CAS 1.0]: Allows a remote service to validate a service ticket forwarded by the user on redirect. Returns a plaintext response.
  • /wp-cas/proxy [CAS 2.0]: Provides access to remote services with proxy tickets in exchange for proxy-granting tickets. Returns an XML response.
  • /wp-cas/proxyValidate [CAS 2.0]: Allows a remote service to validate a service or proxy ticket forwarded by the user on redirect. Returns an XML response.
  • /wp-cas/serviceValidate [CAS 2.0]: Allows a remote service to validate a service ticket forwarded by the user on redirect. Returns an XML response.
  • /wp-cas/p3/proxyValidate [CAS 3.0]: Allows a remote service to validate a service or proxy ticket forwarded by the user on redirect. Returns an XML response.
  • /wp-cas/p3/serviceValidate [CAS 3.0]: Allows a remote service to validate a service ticket forwarded by the user on redirect. Returns an XML response.

There are a few client integration libraries available for CAS, as well as a handy guide for CASifying several existing applications. Independent WordPress installations may integrate with Cassava using a client plugin such as CAS Maestro.

Please follow and contribute to Cassava’s development on Github.

Hooks

Action: cas_server_before_request

Fires before a CAS request is processed.

Parameters:

  • string $path: Requested URI path.

Action: cas_server_after_request

Fires after a CAS request is processed.

Parameters:

  • string $path: Requested URI path.

Action: cas_server_error

Fires if the CAS server has to return an XML error.

Parameters:

  • WP_Error $error: WordPress error to return as XML.

Action: cas_server_validation_success

Fires on successful ticket validation.

Parameters:

  • WP_User $user: WordPress user validated by ticket.
  • string $ticket: Valid ticket string.

Filter: cas_enabled

Allows developers to disable CAS.

Parameters:

  • boolean $cas_enabled: Whether the server should respond to single sign-on requests.

Filter: cas_server_routes

Allows developers to override the default controller mapping, define additional endpoints and provide alternative implementations to the provided controllers.

Controllers provided in this fashion should extend the \Cassava\CAS\Controller\BaseController class.

Parameters:

  • array $cas_routes: CAS endpoint to controller mapping.

Filter: cas_server_response

Lets developers change the CAS server response string.

Parameters:

  • string $output: Response output string.
  • string $path: Requested URI path.

Filter: cas_server_dispatch_args

Filters the callback arguments to be dispatched for the request. Plugin developers may return a WP_Error object here to abort the request.

Parameters:

  • array $args: Arguments to pass the callback.
  • (string|array) $callback: Callback function or method.
  • string $path: Requested URI path.

Filter: cas_server_login_args

Allows developers to change the request parameters passed to a /login request.

Parameters:

  • array $args: HTTP request (GET, POST) parameters.

Filter: cas_server_redirect_service

Filters the redirect URI for the service requesting user authentication.

Parameters:

  • string $service: Service URI requesting user authentication.
  • WP_User $user: Logged in WordPress user.

Filter: cas_server_custom_auth_uri

Allows developers to redirect the user to a custom login form.

Parameters:

  • string $custom_login_url: URI for the custom login page.
  • array $args: Login request parameters.

Filter: cas_server_ticket_expiration

This filter allows developers to override the default ticket expiration period.

Parameters:

  • int $expiration: Ticket expiration period (in seconds).
  • string $type: Type of ticket to set.
  • WP_User $user: Authenticated user associated with the ticket.

Filter: cas_server_validation_user_attributes

Allows developers to change the list of (key, value) pairs before they’re included in a /serviceValidate response.

Parameters:

  • array $attributes: List of attributes to output.
  • WP_User $user: Authenticated user.

Filter: cas_server_settings_user_attribute_options

Allows developers to change the list of user attributes that appear in the dashboard for an administrator to set to return on successful validation requests.

Options are stored in an associative array, with user attribute slugs as array keys and option labels as array values.

These settings are valid only for CAS 2.0 validation requests.

Parameters:

  • array $attributeOptions Attribute options an administrator can set on the dashboard.

Screenshots

  • Administration settings panel.

Installation

Using [Composer](https://getcomposer.org)

  1. Install the plugin package using composer require goblindegook/wp-cas-server.

Using the WordPress Dashboard

  1. Navigate to the ‘Add New’ in the plugins dashboard
  2. Search for ‘wp cas server’
  3. Click ‘Install Now’
  4. Activate the plugin on the Plugin dashboard

Uploading in WordPress Dashboard

  1. Navigate to the ‘Add New’ in the plugins dashboard
  2. Navigate to the ‘Upload’ area
  3. Select wp-cas-server.zip from your computer
  4. Click ‘Install Now’
  5. Activate the plugin in the Plugin dashboard

Using FTP

  1. Download wp-cas-server.zip
  2. Extract the wp-cas-server directory to your computer
  3. Upload the wp-cas-server directory to the /wp-content/plugins/ directory
  4. Activate the plugin in the Plugin dashboard

FAQ

How does CAS work?

The CAS protocol requires three entities to function: the user’s web browser, a web application requesting authentication, and a CAS server as implemented by this plugin.

When a user accesses an application and attempts to authenticate to it, the application sends the user to the CAS server for validation. The CAS server will look for an active session or else explicitly request the user to insert their credentials.

Upon authenticating the user, the CAS server returns the user to the application they came from along with a security ticket.

Behind the scenes, the application then contacts the CAS server over a secure connection to independently verify that the security ticket is valid. The CAS server responds with information about the user’s status, confirming they are who they claim to be.

Does the plugin require HTTPS to function?

Yes. Because applications trade security tickets via HTTP requests, it is very important that this information be encrypted so as not to be easily intercepted. By running a single sign-on service over an unencrypted channel such as plain HTTP, you would be at considerable risk of allowing unauthorized persons into your network.

What do I do if a malicious agent forges or alters my security tickets?

If you suspect someone may have compromised the integrity of the security tickets generated by the CAS server, you should immediately generate a new set of secret keys and swap them out in WordPress’s wp-config.php file.

I’m getting a `Class ‘DOMDocument’ not found` error. What’s going on?

The plugin requires the PHP DOM extension to generate and read XML data, and the error is likely due to the extension not being installed on the server.

While the extension is enabled by default on most setups, some systems require manual activation. It may also have been disabled by a systems administrator. Depending on your operating system, you may be able to install it by running yum install php-dom (RPM) or apt-get install php5-dom (APT). If not, contact your hosting provider or systems administrator to enable it for you.

What is the default endpoint for the CAS server?

By default, the plugin provides methods under the wp-cas endpoint. So, if you’re configuring a CAS client to authenticate using your server at https://www.my-site.com/, then the full URI should be something like https://www.my-site.com/wp-cas/.

The endpoint may be changed at any time by navigating to Settings > Permalinks in the dashboard. Bear in mind that if you change the endpoint you will also need to reconfigure all CAS clients currently using the service.

How can I make information besides the user’s login name available to external applications?

To return user data along with a validation response, navigate to Settings > Cassava CAS Server and check the attributes you want the server to return.

Only versions 2.0 and above of the protocol can disclose user attributes, these options will not change how the earlier CAS 1.0 validation method works. Also note that making user attributes visible does not guarantee the remote application will use them.

How can I change other settings?

At the moment, the only way to change the plugin’s behaviour is through the Hooks API. Please refer to the Other Notes page for a list of actions and filters supported by the plugin.

Where can I read about the CAS protocol specification?

You may peruse the CAS protocol specifications in complete detail at the official project site.

What types of tickets does this plugin support?

Cassava sets and receives Service Tickets (ST), Proxy-Granting Tickets (PGT), Proxy-Granting Ticket IOUs (PGTIOU) and Proxy Tickets (PT).

Contributors & Developers

“Cassava CAS Server” is open source software. The following people have contributed to this plugin.

Contributors

“Cassava CAS Server” has been translated into 1 locale. Thank you to the translators for their contributions.

Translate “Cassava CAS Server” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.

Changelog

1.2.3

  • Requirement checks and admin error on pre-PHP 5.3 setups.

1.2.2

  • Fixed endpoint registration in mixed HTTP/HTTPS installs. The server will now respond to requests over unencrypted HTTP, but will throw an error and tell the user to switch to HTTPS.

1.2.1

  • Fixed missing autoloader in the SVN repository.

1.2.0

  • Added support for the CAS 3.0 /p3/serviceValidate and /p3/proxyValidate endpoints.
  • Fixed a bug that prevented setting a custom CAS endpoint permalink.
  • Fixed the handling of service URLs containing pipe characters.
  • Developers: The cas_server_routes filter no longer deals with callbacks, controller classes are handled instead. Controller classes must extend \Cassava\CAS\Controller\BaseController.
  • WordPress 4.1.1 compatibility.
  • Cleaner, easier to maintain codebase.
  • Improved tests and test coverage.

1.1.2

  • WordPress 4.0 compatibility.
  • Portuguese (pt_PT) localization.

1.1.1

  • Fixed a bug that broke the permalinks page.

1.1.0

  • Settings now allow a successful CAS 2.0 validation response to return user attributes.
  • Miscellaneous under-the-hood improvements and bug fixes.
  • Developers: New filter cas_server_validation_user_attribute_options.
  • Developers: Renamed filter cas_server_validation_extra_attributes to cas_server_validation_user_attributes.
  • Developers: Removed filter cas_server_validation_error.

1.0.1

  • SSL is a requirement. No endpoints are exposed over unencrypted HTTP.

1.0.0

  • Initial release.