gateway

This page documents the Gateway feature of the CAS protocol and the protocol-implementing CAS Server.

What is the Gateway feature?

CAS Server includes a feature whereby you can set the request parameter "gateway" to "true" on the request for CAS login. If "gateway" is "true", then CAS will not paint the user login screen. If it can accomplish authentication by single sign on – that is, by detecting the CAS ticket granting cookie – then it will redirect to the URL specified by the "service" parameter with a valid service ticket. If it cannot accomplish single sign on, then it will redirect to the "service" URL without painting any login screen.

This allows your application to detect and take advantage of user single sign on without bothering the user with a login screen in the case where he or she is not yet logged on. This is useful for main pages and is probably a "best practice", since it allows the user to learn about the service to which he might authenticate before being abruptly presented with the CAS login screen out of context.

What is required of a CAS Client to support this feature?

A gateway-supporting CAS client should:
1) provide a mechanism for the application developer/deployer/htaccess writer to elect the gateway behavior
2) when gateway is elected:
a) set the request parameter "gateway" to be "true" on the CAS login request
b) provide a way to indentify the request when it is redirected back from CAS as one that has already been gatewayed (e.g., a special parameter on the URL-encoded "service", setting a cookie, using already-present session support from your environment, etc.)
3) receive requests redirected back from CAS. These may have the "ticket" parameter set, in which case validate the ticket, etc. If gatewaying failed to pick up a single sign on session, the request will be for the URL specified as the "service" parameter "bare" - the "ticket" parameter will not be set, and CAS does not set any other parameter to indicate that it had gatewayed. The client needs to recognize the request as having already come through gateway. The client should not redirect already-gatewayed requests back to CAS for more gatewaying, because this will lead to an infinite loop of redirecting back and forth between server and client.

CAS is authentication, not authorization. The standard use case for CAS is that the client application wants to consume the authenticated username. Under gateway, when there is no authenticated username because we came back from CAS ticketless, the client should do something like returning "null" when the client application asks for the authenticated username, or fail to set the remote user header, or put null into the session where the application expected to lookup the authenticated user, etc., as applicable to the CAS client implementation.

In the case where one is using CAS for authorization (probably a bad idea in the first place) – users able to authenticate are authorized to access the resource, and users unable to authenticate are not authorized – then GATEWAY should not be used.

There's a pretty good Powerpoint explaining Gateway attached to this page.