Installation

This package has a Symfony Flex recipe that will install configuration files for you.

Default configuration files will be copied in the dev environment.

Step 1

The recommended way to install it is with Composer :

composer require ecphp/cas-bundle

Warning

If you use API Platform and Symfony < 5.2, then it’s possible that some URLs contains parameters with a dot inside. By default, Symfony mangles url parameters having dot with an underscore, which can lead in huge inconsistencies if you heavily rely on query parameters like in API Platform.

In order to fix that issue, the optional package loophp/unaltered-psr-http-message-bridge-bundle can be installed.

composer require loophp/unaltered-psr-http-message-bridge-bundle

Step 2

This is the crucial part of your application’s security.

Edit the security settings of your application, usually in config/packages/security.yaml.

security:
    firewalls:
        main:
            anonymous: ~
            guard:
                provider: cas
                authenticators:
                    - cas.guardauthenticator

    access_control:
        - { path: ^/api, role: ROLE_CAS_AUTHENTICATED }
        - { path: ^/admin, role: ROLE_CAS_AUTHENTICATED }

If you’re using Symfony >= 5.4, it is already possible to use the new security system (more information). This is the default in Symfony >= 6.

security:
    enable_authenticator_manager: true
    firewalls:
        main:
            custom_authenticator: cas.authenticator

    access_control:
        - { path: ^/api, role: ROLE_CAS_AUTHENTICATED }
        - { path: ^/admin, role: ROLE_CAS_AUTHENTICATED }

This configuration example will trigger the authentication on paths starting with /api or /admin, therefore make sure that at least such paths exists.

Feel free to change these configuration to fits your need. Have a look at the Symfony documentation about security and Guard authentication.

Step 3

The CAS protocol requires HTTPS on both side (client and server) in order to communicate.

Whilst it is not possible to configure the behavior of the CAS server, it is possible to configure the HTTP client in use in this bundle in order to relax the requirement and to disable SSL checks when communicating from the client to the server.

Warning

Keep in mind that the following is only for development setup, not for production.

On step 3, while copying the configuration files, the file config/packages/dev/cas_framework.yaml is copied over. That file is useful when developing, it will disable some verifications required when using SSL protocol.

Those particular settings are specific to the default HTTP client that is installed, which is symfony/http-client.

The User-Agent HTTP header used on the dev environment is SymfonyCasBundle. Feel free to customize it or remove it when switching to another environment.

If you plan to change the HTTP client, those settings will most probably need to be updated accordingly.

Step 4

The default configuration of this bundle comes with a configuration for authenticating with a real CAS server setup for testing and demo purposes at https://casserver.herokuapp.com/cas/.

Warning

It is important to note that this is the Apereo official public demo cas server, used by the project for basic showcases. They may go up and down as the project needs without notice, see this page for further information.

The credentials to use for authentication are the following:

  • User: casuser
  • Password: Mellon

Modifying the configuration file is key in this bundle and requires some understanding of the CAS protocol. See more on the dedicated Configuration page for that.

The aforementioned server provided by Apereo does not support Proxy authentication.

If you need a server with Proxy authentication, edit the cas_bundle.yaml and replace https://casserver.herokuapp.com/cas/ with https://heroku-cas-server.herokuapp.com/cas/. Make sure to enable the property pgtUrl which is by default in comment. The source of that server are hosted on Github.

If you prefer using a local CAS server, you can choose to build your own using the tool you prefer. The quickest solution for a working CAS server on any platform is this Docker project.