Middlebury

Difference between revisions of "CAS Directory"

(Actions: Added search_groups 'base' parameter)
(Added tag: 'CAS')
Line 240: Line 240:
  
 
</pre>
 
</pre>
 +
[[Category:CAS]]

Revision as of 12:43, 9 May 2011

About

The CAS Directory is a user/group search and look-up web-service that provides access to the same users and groups known to the CAS system. The CAS Directory is a RESTful web service located at:

https://login.middlebury.edu/directory/

For more information about CAS, see the CAS page in this wiki.

Response Format

Success

Responses to successful queries will have a root cas:results node that contains zero or more cas:entry elements.

cas:entry elements will have a cas:user element or a cas:group element as well as zero or more cas:attribute elements.

<?xml version="1.0" encoding="utf-8"?>
<cas:results xmlns:cas="http://www.yale.edu/tp/cas">
<cas:entry>
<cas:user>B0F836FCDADFDDFF7A17C02C62CDB227</cas:user>
<cas:attribute name="FirstName" value="Adam"/>
<cas:attribute name="LastName" value="Franco"/>
<cas:attribute name="Status" value="Staff"/>
<cas:attribute name="EMail" value="afranco@middlebury.edu"/>
<cas:attribute name="Login" value="afranco"/>
<cas:attribute name="TelephoneNumber" value="802.443.2244"/>
<cas:attribute name="MemberOf" value="CN=DFS-LIS-Circulation Services,OU=DFS_Permissions,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=DFS-LIS-LISstaff,OU=DFS_Permissions,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=DFS-LIS,OU=DFS_Permissions,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=Student Org Advisors,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=webmkover-platform,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=LIS Liaisons,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=LIS Resource Development &amp; Services,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=Digital Media Tutors,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=Brainerd Affiliates,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=LIS Systems &amp; Infrastructure Cluster,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=district-lis,OU=Staff Districts,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=Blog Administrators,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=LIS Educational Services Group,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=VC Web Admin,OU=VC Groups,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=All Staff,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
<cas:attribute name="MemberOf" value="CN=HEATUsers,OU=General,OU=Groups,DC=middlebury,DC=edu"/>
</cas:entry>
<cas:entry>
<cas:group>CN=All Staff,OU=General,OU=Groups,DC=middlebury,DC=edu</cas:group>
<cas:attribute name="EMail" value="All_Staff@middlebury.edu"/>
</cas:entry>
</cas:results>

Identifiers and Reference Attributes

Applications should use the value of the cas:user or cas:group elements to identify users or groups. These values will always exist and are guaranteed to be globally unique identifiers.

Member and MemberOf attributes reference user and group identifiers respectively and can be provided in a user or group lookup to access other objects.

All other attributes are optionally provided by the service and may not exist for all users or groups. Applications should not make assumptions about the existence of attributes.

Optional Attributes - users

These options may or may not exist for all users. Applications should not make assumptions about the existence of these attributes.

  • FirstName - The given name of an entry
  • LastName - The surname of an entry
  • EMail - The email address of an entry
  • TelephoneNumber - The telephone number of an entry
  • Status - A field that indicates the status of an entry in relation to Middlebury College. May be one of 'Staff', 'Faculty', 'Student', 'Visitor'.
  • Login - A field that indicates a 'short name' or 'login handle' of a user. For users with status' of 'Staff', 'Faculty', or 'Student' this field will be the user's sAMAccount name.
    Applications should use this attribute to update their data to map existing usage of sAMAccount names to numeric identifiers.
    Applications should not use this field as the primary identifier for users as will not be unique over time and may change for some users depending on marital status or other factors.
    Visitors may or may not have a value for this attribute. Values of this attribute for visitors may collide with values for Faculty, Staff, and Students.

Optional Attributes - groups

These options may or may not exist for all groups. Applications should not make assumptions about the existence of these attributes.

  • EMail - The email address of an entry

Failure

When a failure occurs HTTP status codes will be used to indicate the reason for failure. The codes used are the following:

  • 400 Bad Request - Used for null or invalid arguments. For example, if the get_user action is requested without an id parameter or with an id of the wrong format.
  • 403 Forbidden - This status is returned if authentication failed or if the user is unauthorized to access the resource.
  • 404 Not Found - This status is returned if either an invalid action is specified or the id specified is unknown.
  • 500 Internal Server Error - An unintended error has occurred internal to the server.


Request Format

All requests must be HTTP GET requests to https://login.middlebury.edu/directory/

All requests must include an action parameter.

Actions

The following actions are available:

Authentication

This service makes use of CAS Proxy Authentication. A session-cookie will be returned that will allow subsequent requests to this service to avoid extra calls to the CAS service. As a CAS authentication gateway, your application will need to be able to recieve Proxy Granting Tickets (PGTs) at a HTTPS URL signed by either the Verisign CA or the Middlebury College local CA. Once the PGT is in hand, it can be passed to the directory web service to provide authenticated access.

In order to search or access attributes, your Proxy-Granting-Ticket callback URL (storePGT.php in the example below) must be in the allowed path configured in the CAS services-management system. If the PGT callback URL is not in the same path as your log-in script, the PGT callback URL can be added separately to the services-management system.


Below is an example of a basic directory client:

<?php

$name = preg_replace('/[^a-z0-9_-]/i', '', dirname($_SERVER['SCRIPT_NAME']));

session_name($name);

//
// phpCAS proxied proxy
//

// import phpCAS lib
include_once('phpcas/source/CAS.php');

// set debug mode
phpCAS::setDebug();

// initialize phpCAS
phpCAS::proxy(CAS_VERSION_2_0,'login.middlebury.edu', 443,'/cas');

// set the callback URL for the PGT to be sent to. This must be an https url
// whose certificate is trusted by CAS.
phpCAS::setFixedCallbackURL('https://example.middlebury.edu/DirectoryClient/storePGT.php');

// Our CAS server uses an SSL certificate provided by DigiCert. The Certificate Authority (CA)
// file to be used is located at:
//     https://login.middlebury.edu/DigiCertCA.crt
// Save this file to a place where your application can access it and configure its path in phpCAS:
//phpCAS::setCasServerCACert('/etc/pki/tls/certs/DigiCertCA.crt');

// The DigiCert certificate may be installed on your machine already
// (it is in the bundle at /etc/pki/tls/certs/ca-bundle.crt on Red Hat Enterprise Linux 5).
// If so, you should be able to use that bundle file:
phpCAS::setCasServerCACert('/etc/pki/tls/certs/ca-bundle.crt');

// force CAS authentication
phpCAS::forceAuthentication();

// at this step, the user has been authenticated by the CAS server
// and the user's login name can be read with phpCAS::getUser().

// moreover, a PGT was retrieved from the CAS server that will
// permit to gain accesses to new services.

$service = 'https://login.middlebury.edu/directory/?action=search_users_by_attributes&LastName=franco&strict=false';

?>
<html>
<head>
<title>phpCAS proxied proxy example</title>
</head>
<body>
<h1>phpCAS proxied proxy example</h1>
<p>the user's login is <b><?php echo phpCAS::getUser(); ?></b>.</p>
<p>Session: (id <?php print session_id(); ?>)</p>
<pre><?php print_r($_SESSION); ?></pre>
<h2>Response from service <?php echo $service; ?></h2><ul><hr>
<?php
flush();
// call a service and change the color depending on the result
if ( phpCAS::serviceWeb($service,$err_code,$output) ) {
echo '<font color="#009900">';
} else {
echo '<font color="#FF0000">';
}
echo "<pre>\n";
echo htmlspecialchars($output);
echo "</pre>";
echo '</font><hr></ul>';
?>
</body>
</html>

And here is the corresponding storePGT.php script:

<?php
$name = preg_replace('/[^a-z0-9_-]/i', '', dirname($_SERVER['SCRIPT_NAME']));

session_name($name);

//
// phpCAS proxied proxy
//

// import phpCAS lib
include_once('phpcas/source/CAS.php');

// set debug mode
phpCAS::setDebug();

// initialize phpCAS
phpCAS::proxy(CAS_VERSION_2_0,'login.middlebury.edu', 443,'/cas');

// Our CAS server uses an SSL certificate provided by DigiCert. The Certificate Authority (CA)
// file to be used is located at:
//     https://login.middlebury.edu/DigiCertCA.crt
// Save this file to a place where your application can access it and configure its path in phpCAS:
//phpCAS::setCasServerCACert('/etc/pki/tls/certs/DigiCertCA.crt');

// The DigiCert certificate may be installed on your machine already.
// If so, you should be able to use the bundle file:
phpCAS::setCasServerCACert('/etc/pki/tls/certs/ca-bundle.crt');

// Run the isAuthenticated() method to store the PGT to a temporary file.
phpCAS::isAuthenticated();

echo "Success";