Getting authenticated user name from HTTP headers

This howto will show you how CAS can trust a HTTP header and create user session based on it.

To use this feature, you need iam-app-cas version 0.9 or later.
Steps to set up Trusted Authentication

  1. Prerequisites

  2. Security considerations

  3. Setting up your proxy server

  4. CAS configuration

  5. Testing

Prerequisites

There are no special prerequisites other than having iam-app-cas RPM version 0.9 or later.

Security considerations

Throughout this howto, we will use REMOTE_USER as the header that contains a username of logged-in user.

The Trusted Authentication brings an inherent security risk with it - the HTTP header supplied from outside the CAS. If configured improperly, it can compromise whole authentication service.

The main idea is that some kind of reverse proxy (nGinx, HTTPd, etc.) authenticates the user, sets the value of REMOTE_USER header and adds this header to the proxied request that is being passed to CAS. CAS checks if the REMOTE_USER header is present, and if it is, it considers that user as authenticated.

If a malicious user adds the REMOTE_USER header into their request and somehow manages to pass this header all the way to CAS, they will be authenticated as any other user.

Do not use Trusted Authentication unless you are 100% sure of what you are doing. And unless you are trying something special, there is almost surely some other (better) way.

It is necessary:

  • To set up reverse proxy that forwards requests to CAS.

    • This proxy must explicitly delete any REMOTE_USER header that comes inside client request.

    • If this proxy also performs user authentication, it must authenticate user and append REMOTE_USER header into the proxied request, replacing any existing values of REMOTE_USER.

    • CAS must not be reachable in any other way than through this reverse proxy.

  • In case of multiple chained proxies, all points mentioned above still hold.

    • The proxy that is dropping the REMOTE_USER header may be a different one that is doing the authentication and setting the REMOTE_USER header back to the proxied request.

Setting up your proxy server

This is up to you and your infrastructure. However, the web-proxy reverse proxy service can be used as a part of the final setup.

CAS configuration

Create file /data/volumes/cas/cas.properties.d/trusted-auth.properties with following contents:

# Whether attribute repositories should be contacted to fetch person attributes.
cas.authn.trusted.attribute-resolution-enabled=false

# When true, throws an error when principal resolution fails.
# Otherwise logs the condition as an error without raising a catastrophic error.
# When you do not use any backing storage, set this to false.
cas.authn.trusted.principal-resolution-failure-fatal=false

# Name of the request header that contains the username.
cas.authn.trusted.remote-principal-header=REMOTE_USER

# For debugging.
logging.level.org.apereo.cas.adaptors.trusted=DEBUG

After you create the file, restart the application: systemctl restart iam-cas.

Testing

Testing depends on your infrastructure. However, in case you are just trying things out and do not drop the REMOTE_USER header anywhere in the proxy chain, you can add the header manually in your browser’s developer tools. When you access the https://your.server/cas/login you will be logged-in and the CAS will display the value you set as your username.