CAS Bundle¶

A Central Authentication Service bundle for Symfony 4 & 5.

The Central Authentication Service (CAS) is an Open-Source single sign-on protocol for the web. Its purpose is to permit a user to access multiple applications while providing their credentials only once. It also allows web applications to authenticate users without gaining access to a user’s security credentials, such as a password. The name CAS also refers to a software package that implements this protocol.

In order to foster a greater adoption of this bundle, it has been built with interoperability in mind. It only uses PHP Standards Recommendations interfaces.

PSR-3 for logging,
PSR-4 for classes autoloading,
PSR-6 for caching,
PSR-7 for HTTP messages (requests, responses),
PSR-12 for coding standards,
PSR-17 for HTTP messages factories,
PSR-18 for the HTTP client.

Requirements¶

PHP¶

PHP greater or equal to 7.2.5.

Symfony¶

The minimal required version of Symfony is 5.

Extensions¶

These PHP extensions are required:

json
libxml
simplexml

Packages¶

In order to get the CAS bundle working, you will require some dependencies.

To give a maximum freedom to the users using, each required dependencies is a well defined standardized PHP class.

See the PHP-FIG framework group for more information.

Dependency	PSR	Implementations	Example package
Logger	PSR-3	log-implementation	monolog/monolog
Cache	PSR-6	cache-implementation	symfony/cache
HTTP factories	PSR-17	http-factory-implementations	nyholm/psr7
HTTP Client	PSR-18	http-client-implementations	symfony/http-client

You are free to use any package you want, as long as they are implementing the proper requirement.

Installation¶

This package does not yet have a Symfony Flex recipe. Installation steps must be done manually.

Default configuration files will be copied in the dev environment except for the file defining the services.

Step 1¶

The easiest way to install it is through Composer

composer require drupol/cas-bundle

Step 2¶

Make sure that the bundle is enabled in config/bundles.php.

You should see a line that looks like the following:

drupol\CasBundle\CasBundle::class => ['all' => true],

Step 3¶

Recursively copy the content of the Resources/config folder in config/ folder.

cp -ar vendor/drupol/cas-bundle/Resources/config/* config/

Step 4¶

Register new firewall for CAS authentication, e.g.

firewalls:
    main:
        guard:
            provider: cas
            authenticators:
                - cas.guardauthenticator

Example of configuration:

security:
    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false
        main:
            anonymous: true
            provider: cas
            switch_user: true
            pattern: ^/
            guard:
                authenticators:
                    - cas.guardauthenticator
    access_control:
        - { path: ^/api, role: ROLE_CAS_AUTHENTICATED }

This example configuration example will trigger the authentication on paths starting with /api, 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 5¶

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://heroku-cas-server.herokuapp.com/cas/.

You should normally already be able to authenticate using the following credentials:

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.

Step 6¶

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.

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

Configuration¶

Hereunder an example of configuration for CAS Bundle.

Tip

Based on this configuration, the behavior of the bundle can change.

base_url: https://heroku-cas-server.herokuapp.com/cas
protocol:
  login:
    path: /login
    allowed_parameters:
      - service
      - renew
      - gateway
    default_parameters:
      service: https://my-app/homepage
  serviceValidate:
    path: /p3/serviceValidate
    allowed_parameters:
      - format
      - pgtUrl
      - service
      - ticket
    default_parameters:
      format: JSON
      pgtUrl: https://my-app/casProxyCallback
  logout:
    path: /logout
    allowed_parameters:
      - service
    default_parameters:
      service: https://my-app/homepage
  proxy:
    path: /proxy
    allowed_parameters:
      - targetService
      - pgt
  proxyValidate:
    path: /proxyValidate
    allowed_parameters:
      - format
      - pgtUrl
      - service
      - ticket
    default_parameters:
      format: JSON
      pgtUrl: https://my-app/casProxyCallback

Usage¶

Step 1¶

Follow the Installation procedure.

Step 2¶

Configure the configuration files accordingly and the security of your Symfony application.

Step 3¶

If you try to reach a path that is protected by the firewall, you should be automatically redirected to the CAS server login page.

Once you’re authenticated, the CAS server will redirect you back to the Symfony application and continue the authentication process.

If the credentials that you provided were valid, then you’ll be authenticated.

Tests, code quality and code style¶

Every time changes are introduced into the library, Travis CI and Github Actions run the tests written with PHPSpec.

PHPInfection is also triggered used to ensure that your code is properly tested.

The code style is based on PSR-12 plus a set of custom rules. Find more about the code style in use in the package drupol/php-conventions.

A PHP quality tool, Grumphp, is used to orchestrate all these tasks at each commit on the local machine, but also on the continuous integration tools (Travis, Github actions)

To run the whole tests tasks locally, do

composer grumphp

or

./vendor/bin/grumphp run

Here’s an example of output that shows all the tasks that are setup in Grumphp and that will check your code

./vendor/bin/grumphp run
GrumPHP is sniffing your code!
Running task  1/13: SecurityChecker... ✔
Running task  2/13: Composer... ✔
Running task  3/13: ComposerNormalize... ✔
Running task  4/13: YamlLint... ✔
Running task  5/13: JsonLint... ✔
Running task  6/13: PhpLint... ✔
Running task  7/13: TwigCs... ✔
Running task  8/13: PhpCsAutoFixerV2... ✔
Running task  9/13: PhpCsFixerV2... ✔
Running task 10/13: Phpcs... ✔
Running task 11/13: PhpStan... ✔
Running task 12/13: Phpspec... ✔
Running task 13/13: Infection... ✔

Contributing¶

See the file CONTRIBUTING.md but feel free to contribute to this project by sending Github pull requests.

CAS Bundle¶

Requirements¶

PHP¶

Symfony¶

Extensions¶

Packages¶

Installation¶

Step 1¶

Step 2¶

Step 3¶

Step 4¶

Step 5¶

Step 6¶

Configuration¶

Usage¶

Step 1¶

Step 2¶

Step 3¶

Tests, code quality and code style¶

Contributing¶

Development¶