[squid-users] Squid CAS integration

[Amos Jeffries]

On 6/09/19 9:36 pm, Dario Basset wrote:
> Thanks.
> 
> ->  With CAS I mean the Central Authentication Service, which is supported
> here: https://github.com/apereo/cas  or here:
> https://www.apereo.org/projects/cas     It is a system for Single Sign On
> authentication with Service Ticket, and it is quite used in Universities. We
> want to integrate Squid with CAS auth.
> The authentication provided by CAS is based on a mechanism which redirect
> user navigation to CAS University site, and proceed only when credentials
> are valid. In this way the site that picks the credentials is not an
> application site, but it is University CAS itself. The application that uses
> University CAS is simply redirecting user navigation, that it takes the
> control.
> 
> ->  Ok for PHP
> 
> ->  For what concerns Squid helpers, I saw some examples, but most of those
> examples are based never-ending loops that wait for standard input and then
> proceed with authentication. In this loop, the credentials are picked by
> Squid web server. We do not want this. We want credentials to be inputted in
> our CAS portal system. But I don't know how to code configuration file for
> Squid and related helpers.

Ah, you are misunderstanding the purpose of the helpers.

In order to handle a clients traffic Squid needs to process the rules
you configured. Sometimes those rules need the answers to questions
Squid cannot answer by itself; eg "are the user credentials valid", or
"should this URL be redirected elsewhere?"

What Squid does then is send a query to the helper which can answer that
question, and the helper responds with OK/ERR (yes or no) and maybe some
parameters Squid can use to continue the processing. To the helper HTTP
traffic is just an infinite series of "Can I do X?" questions from Squid.


Looking at the CAS documentation, they have helpfully provided a message
flow diagram for how web traffic needs to be handled and authenticated
against the CAS server.

see "Web Flow Diagram" at
 <https://apereo.github.io/cas/4.2.x/protocol/CAS-Protocol.html>

Squid and  URL-redirect helper would be doing the actions in the
"Protected App" column, and generating the 302 responses.

[ It occurs to me, that if you ask about the CAS community you may find
someone who already did this integration and has a Squid helper. Even
though CAS has not been mentioned here before. ]


Your squid.conf would look like this:

 # check every URL to see if 302 redirect is needed
 url_rewrite_helper /path/to/your/helper

 # tell the URL helper about any Cookie header
 url_rewrite_extras %#>h{Cookie}

 # do not try to redirect clients visiting the CAS login page
 acl CAS_server dstdomain cas.example.com
 url_rewrite_access deny !CAS_server

 # add a Set-Cookie header supplied by the URL helper (if any)
 acl CAS_cookie note cas-cookie_
 reply_header_add Cookie "%note{cas-cookie_}" CAS_cookie


For every HTTP request Squid handles, it will send your helper one line
ending with a newline (\n) character. That line will contain the URL the
client was trying to visit, followed by the Cookie header(s) straight
from HTTP message with URL / %-encoding.


The helper needs to respond back with a line containing some values
depending on which of the yellow boxes is happening.

* When there is no CAS Cookie in the ones supplied by Squid (or Squid
cannot deliver any), *and* no CAS ticket on the URL then the first / top
yellow box is happening.
 The helper should produce:

  OK status=302 url=https://cas.example.com/cas/login?service=...

where "..." is the %-encoded value of URL Squid said the client was
trying to fetch. Notice how these details correlate to what the CAS
diagram first column is saying.


* When there is no Cookie etc and there _is_ a ticket parameter. The
second yellow box has been reached.
 The helper needs to do the background GET request to verify the ticket
with the CAS server. GET /serviceValidate request to the CAS server and
process the response to find the value needing to go into Set-Cookie header.
 When it has those details it should produce:

  OK status=302 url=... cas-cookie_=BLAH

where "..." is the URL the client was trying to fetch but without the
"ticket=" parameter; and "BLAH" is the string to put in the Cookie header.

NOTE: since Cookie header values contain quotes, whitespace and special
characters the BLAH string should be %-encoded. Squid should decode it
before use.


* When there is a CAS server Cookie and no ticket parameter. The third
(or fourth) yellow box has been reached. The helper should just validate
the cookie.

If the Cookie validates the helper should produce:

  ERR

Despite what the letters may imply this just means not to redirect.

If the Cookie failed to validate. I guess you redirect to the CAS server
login page as per earlier at the first yellow box, maybe? the diagram
does not mention that situation.



PS. If you are interested the full details of helper protocol for URL
redirector is at:
 <https://wiki.squid-cache.org/Features/AddonHelpers#URL_manipulation>

Since the Cookie handling could be quite slow, you might want to use the
concurrency channels feature to allow parallel processing by the helper.
Get the helper working with the basics first though.

Amos