Welcome to txcasproxy’s documentation!¶

Endpoint Specifications¶

Endpoints are string descriptions of a socket connection a client or server makes. For more details, see the Twisted endpoints documentation.

TLS Options¶

Whenever the software attempts to make an HTTPS connection to a proxied site or to a CAS service, it must establish a trust model based on certificates that are signed by some authority. By default, the service uses the platform’s underlying certificate authority (CA) trust store. You can extend the default trust store using the addCA option.

You can exercise complete and independent control over the trust stores for the CAS web client and/or the proxy web client by specifying client TLS endpoints. Client endpoints allow you to control many aspects of the underlying connection, including client certificates, trust roots, and even the type of underlying connetion (e.g. TCP IP address or UNIX domain socket).

The REMOTE_USER Header¶

The reverse proxy attempts to transmit the authenticated user name to the proxied web site as the HTTP header, ‘REMOTE_USER’. Some web servers will modify or reject certain headers.

For example, Apache2 will discard ‘REMOTE_USER’. It will convert ‘Remote-User’ into ‘HTTP_REMOTE_USER’ by the time it reaches the proxied site.

The --header option lets you specify the name of the header to pass on to the proxied site.

Ending the Session¶

The logout option allows you to specify a URL pattern that will be intercepted by the proxy and cause it to terminate its authenticated session. This option may be specified multiple times.

The logout pattern may be a regular URL less the scheme and netlocation. Additionally, the path may include globbing meta-characters.

A query string does not need to be supplied in the pattern. In this case, any query string will match the pattern. This is also the case if the entire query string for the pattern is ‘*’. If the pattern query string is ‘!’, then a URL will only match if it has no query string (or an empty query string).

If the pattern contains query string parameters, then a URL will only match if it contains all the query parameters and values specified in the pattern. A URL may contain addtional query string parameters and still match.

If the cas-logout URL option is also specified, an HTTP redirect is issued to that URL to terminate the SSO session.

If the cas-logout option is not specified, the proxy will reverse proxy the resource (it is not protected). This can be useful if your application allows you to specify a logout URL which you can point to the CAS logout URL. This allows the application to perform its own session termination before the SSO session is ended. It is also useful if the service does not participate in an SSO session but simply uses a CAS service to authenticate.

The logout-passthrough option can be used to alter the cas-logout behavior. The initial request will be passed through to the proxied service, but its response will be silently discarded. The proxy will issue a response to redirect the requesting agent to the CAS logout URL. This is useful if you require the proxied service to terminate its own local session in addition to terminating the CAS session.

Authentication Information Service¶

If you specify an endpoint for the auth-info-endpoint option, a web site will be created at that endpoint. The site responds to HTTP GET requests for resources of the form /$USERNAME, where $USERNAME must be a user name that has authenticated with the proxy. The response will be a JSON document that maps attribute names to lists of values.

The intention is that access to this site should be limited to the protected service (e.g. with a host based firewall). The protected service can then use this site to retreive attributes for authenticated users using a simple RESTful web service.

Authentication Information Resource¶

The auth-info-resource can be used to specify a resource on the main site which will respond with a JSON document containing mappings for username and attributes. The attributes key maps to an attribute map identical to the one provided by the authentication information service.

This resource is valid only for requests associated with an already authenticated session. It is therefore more convenient for a client which has authenticated with the proxy to access than for code from the protected service.

Error Handling¶

The debug option causes any unexpected errors (i.e. bugs) to be output to HTML.

There are two expected error scenarios when the proxy may be required to display its own content. If a browser presents a URL to the proxy which contains a CAS service ticket that fails validation, the proxy will emit a 403 (Forbidden) HTTP response code. By default, no content is included.

The second case is when something external to the proxy has gone wrong (perhaps the CAS service is unavailable). In this case, a HTTP 500 response code is returned by the proxy. Again, there is no content by default.

You can provide custom error pages by specifying the template_dir option. This should be the path to a folder that contains subfolders static and error. The error folder should contain templates 403.jinja2 and 500.jinja2, which should be Jinja2 templates. These templates can access the HTTP request object as the name request. The static folder may contain any static assets required for rendering the final HTML pages (e.g. images, stylesheets, scripts). These will be served from /_templates/static by default. You can change the root resource with the template-resource option. The name static_base is made available to the templates and can be used as a prefix for static resources (the prefix includes a trailing slash).

Apache + PHP¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

<?php
# txcasproxy PHP integration example.
?>
<html>
<head>
<title></title>
</head>
<body>
<h2>Server Variables</h2>
<pre>
<?php
print htmlspecialchars(print_r($_SERVER, $return=TRUE));
?>
</pre>
<?php
$username = $_SERVER['HTTP_REMOTE_USER'];
if($username)
{
?>
<h2>txcasproxy CAS Authenticated User Info for <strong><?php echo htmlspecialchars($username);?></strong></h2>
<pre>
<?php
    $ch = curl_init(); 
    // set url
    curl_setopt($ch, CURLOPT_URL, "http://127.0.0.1:9444/$username");
    //return the transfer as a string
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    // $output contains the output string
    $output = curl_exec($ch);
    // close curl resource to free up system resources
    curl_close($ch);      
    $jsonIterator = new RecursiveIteratorIterator(
        new RecursiveArrayIterator(json_decode($output, TRUE)),
        RecursiveIteratorIterator::SELF_FIRST);

    foreach ($jsonIterator as $key => $val) 
    {
        if(is_array($val)) 
        {
            echo htmlspecialchars("$key:\n");
        } 
        else 
        {
            echo htmlspecialchars("$key => $val\n");
        }
    }
?>
</pre>
<?php
}
else
{
?>
<h2>No REMOTE_USER</h2>
<?php
}
?>
</body>
</html>
<?php
?>

Full example: proxy-test.php

Serve proxy-test.php from Apache (or some other web server that will server up PHP). Protect the URL with txcasproxy. Browse to the web page to see info about the logged in user and associated attributes.

Example command line:

$ twistd -n casproxy \
    -e 'ssl:9443:certKey=/path/to/server.crt.pem:privateKey=/path/to/server.key.pem' \
    -c 'https://cas.example.net/login' \
    -s 'https://cas.example.net/serviceValidate' \
    -p 'http://protected.example.org/' \
    -a 'tcp:9444' \
    -H 'Remote-User'