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.
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 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.
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line