Skip to content

CASAuthentication - Added support for database storage of proxy-granting-tickets. #64

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

CASAuthentication - Added support for database storage of proxy-granting-tickets. #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
633e97d
CASAuthentication - Added support for enabling phpCAS's debug log.
adamfranco Oct 4, 2012
cb8d668
CASAuthentication - Added support for database storage of proxy-grant…
adamfranco Oct 4, 2012
c6cf40c
CASAuthentication - Fix for a change in the arguments for phpCAS::set…
adamfranco Jan 9, 2013
fddf5a2
Merge branch 'CASAuth_setPGTStorageFile_fix' into CASAuth_DB_PGT_storage
adamfranco Jan 9, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 71 additions & 17 deletions doc/mw/CASAuthentication.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ Configuration

The CASAuthentication authority relies on the `phpCAS library <https://wiki.jasig.org/display/CASC/phpCAS>`_ to handle communication with the CAS server. If you don't already have phpCAS, download the latest release.

-------------------
Basic Configuration
-------------------

To configure authentication, you only need to add a few parameters:

* *USER_LOGIN* - Should be set to *LINK*
Expand All @@ -29,11 +33,13 @@ To configure authentication, you only need to add a few parameters:
* *CAS_PATH* - The path of the CAS application, e.g. ``"/cas/"``
* *CAS_CA_CERT* - The filesystem path to a CA certificate that will be used to validate the authenticity of the CAS server, e.g. ``"/etc/tls/pki/certs/my_ca_cert.crt"``. If empty, no certificate validation will be performed (not recommended for production).

If you wish to authenticate as a proxy (which will allow Kurogo to may proxy-authenticated requests to back-end data sources) then you can provide the following attributes to configure proxy authentication.
Basic optional parameters:

* *CAS_PROXY_INIT* - Set to ``1`` to initialize as a proxy.
* *CAS_PROXY_TICKET_PATH* - The path in which phpCAS should look for proxy-granting-tickets. E.g. ``"/tmp"``
* *CAS_PROXY_FIXED_CALLBACK_URL* - If your Kurogo installation isn't running under SSL but shares a filesystem with an SSL-enabled host, then you can provide an alternate proxy-granting-ticket storage URL. E.g. ``"https://host.domain.edu/storePGT.php"``
* *CAS_DEBUG_LOG* - The path of a log file in which phpCAS should log its activity. Only set this parameter for testing/debugging as the log files grow very rapidly. E.g. ``"/var/log/phpcas.log"``

---------------
User Attributes
---------------

If your CAS server returns user attributes in a SAML-1.1 or CAS-2.0 response, you can provide these attributes
to Kurogo to display full names and support group-based :doc:`authorization`.
Expand All @@ -44,20 +50,68 @@ to Kurogo to display full names and support group-based :doc:`authorization`.
* *ATTRA_FULL_NAME* - Attribute name for the user's full name, e.g. ``"displayname"``.
* *ATTRA_MEMBER_OF* - Attribute name for the user's groups, e.g. ``"memberof"``.

-----------------------
Authenticate as a Proxy
-----------------------
If you wish to authenticate as a proxy (which will allow Kurogo to make proxy-authenticated requests to back-end data sources) then you can provide the following parameters to configure proxy authentication.

* *CAS_PROXY_INIT* - Set to ``1`` to initialize as a proxy.
* *CAS_PROXY_FIXED_CALLBACK_URL* - If your Kurogo installation isn't running under SSL but shares a filesystem with an SSL-enabled host, then you can provide an alternate proxy-granting-ticket storage URL. E.g. ``"https://host.domain.edu/storePGT.php"``

When the application asks the CAS server to authenticate it as a proxy, the CAS server makes a request back to the the SSL url for the application with a proxy-granting-ticket (PGT) to verify the application's identity. phpCAS supports storage of these PGTs as either files in a webserver-writable directory or in a SQL database. File storage is the most simple, but database (DB) storage is useful when running Kurogo on a cluster of webservers.

~~~~~~~~~~~~~~~~~~~~~~
Filesystem PGT Storage
~~~~~~~~~~~~~~~~~~~~~~

* *CAS_PROXY_TICKET_PATH* - The path in which phpCAS should look for PGTs. E.g. ``"/tmp"``

~~~~~~~~~~~~~~~~~~~~
Database PGT storage
~~~~~~~~~~~~~~~~~~~~
Database storage for PGTs allows proxy authentication to work in a clustered webserver environment where the end user and the CAS server may be making requests to different hosts. PGTs are placed in a shared database accessible to all webservers in the cluster.

To use this storage method, a database table needs to be created with the following SQL:

.. code-block:: sql

CREATE TABLE cas_pgts (pgt_iou VARCHAR(255) NOT NULL PRIMARY KEY, pgt VARCHAR(255) NOT NULL);

The table name can be changed, but the structure should stay the same.

* *CAS_PROXY_TICKET_DB_DSN* - The `PDO "Data Source Name" or DSN <http://www.php.net/manual/en/pdo.construct.php>`_ to connect to, e.g. ``"mysql:dbname=kurogo_data;host=127.0.0.1"``
* *CAS_PROXY_TICKET_DB_USER* - The username to use when connecting to the database.
* *CAS_PROXY_TICKET_DB_PASS* - The password to use when connecting to the database.
* *CAS_PROXY_TICKET_DB_TABLE* - Optional. The table in which to store proxy-granting-tickets. The default table name is ``cas_pgts``.
* *CAS_PROXY_TICKET_DB_DRIVER_OPTS* - Optional. PDO driver-specific options for the database connection. See the `PDO Documentation <http://www.php.net/manual/en/pdo.construct.php>`_ for details.

==========================
Example Configuration File
==========================

.. code-block:: ini

[cas]
CONTROLLER_CLASS = "CASAuthentication"
TITLE = "Central Authentication Service (CAS)"
USER_LOGIN = "LINK"
CAS_PROTOCOL = "2.0"
CAS_HOST = "login.example.edu"
CAS_PORT = 443
CAS_PATH = "/cas/"
CAS_CA_CERT = ""
ATTRA_EMAIL = "EMail"
ATTRA_FIRST_NAME = "FirstName"
ATTRA_LAST_NAME = "LastName"
ATTRA_FULL_NAME = "DisplayName"
ATTRA_MEMBER_OF = "MemberOf"
CONTROLLER_CLASS = "CASAuthentication"
TITLE = "Central Authentication Service (CAS)"
USER_LOGIN = "LINK"
CAS_PROTOCOL = "2.0"
CAS_HOST = "login.example.edu"
CAS_PORT = 443
CAS_PATH = "/cas/"
CAS_CA_CERT = ""
CAS_DEBUG_LOG = ""
ATTRA_EMAIL = "EMail"
ATTRA_FIRST_NAME = "FirstName"
ATTRA_LAST_NAME = "LastName"
ATTRA_FULL_NAME = "DisplayName"
ATTRA_MEMBER_OF = "MemberOf"
CAS_PROXY_INIT = 0
CAS_PROXY_FIXED_CALLBACK_URL = ""
CAS_PROXY_TICKET_PATH = ""
CAS_PROXY_TICKET_DB_DSN = ""
CAS_PROXY_TICKET_DB_USER = ""
CAS_PROXY_TICKET_DB_PASS = ""
CAS_PROXY_TICKET_DB_TABLE = ""
CAS_PROXY_TICKET_DB_DRIVER_OPTS = ""

28 changes: 26 additions & 2 deletions lib/Authentication/CASAuthentication.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,9 @@ public function init($args)
else
require_once($args['CAS_PHPCAS_PATH'].'/CAS.php');

if (!empty($args['CAS_DEBUG_LOG']))
phpCAS::setDebug($args['CAS_DEBUG_LOG']);

if (empty($args['CAS_PROTOCOL']))
throw new KurogoConfigurationException('CAS_PROTOCOL value not set for ' . $this->AuthorityTitle);

Expand All @@ -96,8 +99,29 @@ public function init($args)
} else {
phpCAS::proxy($args['CAS_PROTOCOL'], $args['CAS_HOST'], intval($args['CAS_PORT']), $args['CAS_PATH'], false);

if (!empty($args['CAS_PROXY_TICKET_PATH']))
phpCAS::setPGTStorageFile('', $args['CAS_PROXY_TICKET_PATH']);
if (!empty($args['CAS_PROXY_TICKET_PATH']) && !empty($args['CAS_PROXY_TICKET_DB_DSN']))
throw new KurogoConfigurationException('Only one of CAS_PROXY_TICKET_PATH or CAS_PROXY_TICKET_DB_DSN may be set for ' . $this->AuthorityTitle);

if (!empty($args['CAS_PROXY_TICKET_PATH'])) {
if (version_compare(PHPCAS_VERSION, '1.3', '>=')) {
phpCAS::setPGTStorageFile($args['CAS_PROXY_TICKET_PATH']);
} else {
phpCAS::setPGTStorageFile('', $args['CAS_PROXY_TICKET_PATH']);
}
}

if (!empty($args['CAS_PROXY_TICKET_DB_DSN'])) {
$user = $pass = $table = $driver_opts = '';
if (!empty($args['CAS_PROXY_TICKET_DB_USER']))
$user = $args['CAS_PROXY_TICKET_DB_USER'];
if (!empty($args['CAS_PROXY_TICKET_DB_PASS']))
$pass = $args['CAS_PROXY_TICKET_DB_PASS'];
if (!empty($args['CAS_PROXY_TICKET_DB_TABLE']))
$table = $args['CAS_PROXY_TICKET_DB_TABLE'];
if (!empty($args['CAS_PROXY_TICKET_DB_DRIVER_OPTS']))
$driver_opts = $args['CAS_PROXY_TICKET_DB_DRIVER_OPTS'];
phpCAS::setPGTStorageDb($args['CAS_PROXY_TICKET_DB_DSN'], $user, $pass, $table, $driver_opts);
}

if (!empty($args['CAS_PROXY_FIXED_CALLBACK_URL']))
phpCAS::setFixedCallbackURL($args['CAS_PROXY_FIXED_CALLBACK_URL']);
Expand Down