From 633e97d6cd575bff8efc1d7e50097ef50a423306 Mon Sep 17 00:00:00 2001 From: Adam Franco Date: Thu, 4 Oct 2012 10:54:07 -0400 Subject: [PATCH 1/3] CASAuthentication - Added support for enabling phpCAS's debug log. This addition allows optional troubleshooting of issues by looking at phpCAS's detailed debug log. --- doc/mw/CASAuthentication.rst | 5 +++++ lib/Authentication/CASAuthentication.php | 3 +++ 2 files changed, 8 insertions(+) diff --git a/doc/mw/CASAuthentication.rst b/doc/mw/CASAuthentication.rst index ff30e99de..b57fb14d9 100644 --- a/doc/mw/CASAuthentication.rst +++ b/doc/mw/CASAuthentication.rst @@ -44,6 +44,10 @@ 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"``. +Other optional parameters: + +* *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"`` + .. code-block:: ini [cas] @@ -55,6 +59,7 @@ to Kurogo to display full names and support group-based :doc:`authorization`. CAS_PORT = 443 CAS_PATH = "/cas/" CAS_CA_CERT = "" + CAS_DEBUG_LOG = "" ATTRA_EMAIL = "EMail" ATTRA_FIRST_NAME = "FirstName" ATTRA_LAST_NAME = "LastName" diff --git a/lib/Authentication/CASAuthentication.php b/lib/Authentication/CASAuthentication.php index 272cf5724..9064edc2e 100644 --- a/lib/Authentication/CASAuthentication.php +++ b/lib/Authentication/CASAuthentication.php @@ -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); From cb8d668d01678abd0129f277817768f92fa2b8db Mon Sep 17 00:00:00 2001 From: Adam Franco Date: Thu, 4 Oct 2012 11:46:38 -0400 Subject: [PATCH 2/3] CASAuthentication - Added support for database storage of proxy-granting-tickets. Storing proxy-granting-tickets (PGTs) in a shared database facilitates serving Kurogo from a cluster of web-hosts. Since the end-user and the CAS server may each make requests to different hosts in the cluster the PGTs provided by the CAS server must be placed in a shared location available to all other hosts. This facility is provided by the underlying phpCAS library. This patch simply allows its configuration via the Kurogo ini files. --- doc/mw/CASAuthentication.rst | 89 ++++++++++++++++++------ lib/Authentication/CASAuthentication.php | 16 +++++ 2 files changed, 85 insertions(+), 20 deletions(-) diff --git a/doc/mw/CASAuthentication.rst b/doc/mw/CASAuthentication.rst index b57fb14d9..73d22c829 100644 --- a/doc/mw/CASAuthentication.rst +++ b/doc/mw/CASAuthentication.rst @@ -18,6 +18,10 @@ Configuration The CASAuthentication authority relies on the `phpCAS library `_ 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* @@ -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`. @@ -44,25 +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"``. -Other optional parameters: +----------------------- +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_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"`` +* *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 `_ 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 `_ 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 = "" - CAS_DEBUG_LOG = "" - 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 = "" diff --git a/lib/Authentication/CASAuthentication.php b/lib/Authentication/CASAuthentication.php index 9064edc2e..6104d4920 100644 --- a/lib/Authentication/CASAuthentication.php +++ b/lib/Authentication/CASAuthentication.php @@ -99,9 +99,25 @@ 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']) && !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'])) 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']); } From c6cf40c84db5aac9497b2765e0aa97af87865e47 Mon Sep 17 00:00:00 2001 From: Adam Franco Date: Wed, 9 Jan 2013 11:28:45 -0500 Subject: [PATCH 3/3] CASAuthentication - Fix for a change in the arguments for phpCAS::setPGTStorageFile() phpCAS 1.3+ no longer takes a 'format' argument for phpCAS::setPGTStorageFile(). This change allows proxy-ticket storage to work with all versions of phpCAS. --- lib/Authentication/CASAuthentication.php | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/lib/Authentication/CASAuthentication.php b/lib/Authentication/CASAuthentication.php index 272cf5724..f9d9c7b20 100644 --- a/lib/Authentication/CASAuthentication.php +++ b/lib/Authentication/CASAuthentication.php @@ -96,8 +96,13 @@ 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'])) { + 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_FIXED_CALLBACK_URL'])) phpCAS::setFixedCallbackURL($args['CAS_PROXY_FIXED_CALLBACK_URL']);