Documentation upgrade

* Update configuration.
* Update documentation.
* Update documentation system and provide steps to build the documentation locally.
* Use Docker Compose to build a live documentation server.

.gitattributes

@@ -7,3 +7,6 @@
 infection.json.dist export-ignore
 grumphp.yml.dist export-ignore
 phpspec.yml.dist export-ignore
+/docs export-ignore
+/docker export-ignore
+docker-compose.yaml

Resources/config/packages/dev/cas_framework.yaml

@@ -3,3 +3,5 @@ framework:
         default_options:
             verify_peer: false
             verify_host: false
+            headers:
+                'User-Agent': 'SymfonyCasBundle'

Resources/config/packages/dev/cas_security.yaml

@@ -2,9 +2,3 @@ security:
     providers:
         cas:
             id: cas.userprovider
-    firewalls:
-        default:
-            guard:
-                provider: cas
-                authenticators:
-                    - cas.guardauthenticator

docker-compose.yaml

@@ -0,0 +1,10 @@
+version: "3"
+
+services:
+    doc:
+        container_name: sphinx_documentation
+        build: docker/doc
+        volumes:
+            - ./docs:/etc/Sphinx/source
+        ports:
+            - 8100:80

docker/doc/Dockerfile

@@ -0,0 +1,11 @@
+FROM alpine:latest
+WORKDIR /etc/
+RUN mkdir -p /etc/Sphinx/build
+
+RUN apk add --no-cache python3 make git
+
+RUN pip3 install git+https://github.com/sphinx-doc/sphinx
+RUN pip3 install sphinx-autobuild
+RUN pip3 install sphinx-rtd-theme
+
+CMD sphinx-autobuild -b html --host 0.0.0.0 --port 80 /etc/Sphinx/source /etc/Sphinx/build

docs/conf.py

@@ -17,7 +17,6 @@
 
 lexers['php'] = PhpLexer(startinline=True, linenos=1)
 
-primary_domain = 'php'
 highlight_language = 'php'
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -136,12 +135,12 @@
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = 'favicon.ico'
+# html_favicon = 'favicon.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -156,11 +155,6 @@
 # typographically correct entities.
 #html_use_smartypants = True
 
-
-def setup(app):
-    app.add_stylesheet('custom.css')
-    app.add_stylesheet('highlight.css')
-
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 

docs/pages/development.rst

@@ -8,10 +8,22 @@ Maintainers
 
 See the `MAINTAINERS.txt`_ file.
 
+Documentation
+-------------
+
+Documentation can be built locally using `Sphinx`_.
+
+To render the documentation locally do the following steps:
+
+* ``docker-compose up``
+* Navigate to `http://127.0.0.1:8100/`_
+
 Contributors
 ------------
 
 See the `Github insights page`_.
 
 .. _MAINTAINERS.txt: https://github.com/ecphp/cas-bundle/blob/master/MAINTAINERS.txt
 .. _Github insights page: https://github.com/ecphp/cas-bundle/graphs/contributors
+.. _Sphinx: https://www.sphinx-doc.org/
+.. _http://127.0.0.1:8100/: http://127.0.0.1:8100/

docs/pages/installation.rst

@@ -40,60 +40,34 @@ Recursively copy the content of the `Resources/config` folder in `config/` folde
 Step 4
 ~~~~~~
 
-Register new firewall for CAS authentication, e.g.
+This is the crucial part of your application's security configuration.
 
-.. code:: yaml
+Edit the security settings of your application by edition the file `config/packages/security.yaml`.
 
-    firewalls:
-        main:
-            guard:
-                provider: cas
-                authenticators:
-                    - cas.guardauthenticator
-
-Example of configuration:
-
-.. code:: yaml
+.. code-block:: yaml
 
     security:
         firewalls:
-            dev:
-                pattern: ^/(_(profiler|wdt)|css|images|js)/
-                security: false
             main:
-                anonymous: true
-                provider: cas
-                switch_user: true
-                pattern: ^/
+                anonymous: ~
                 guard:
+                    provider: cas
                     authenticators:
                         - cas.guardauthenticator
+
         access_control:
             - { path: ^/api, role: ROLE_CAS_AUTHENTICATED }
+            - { path: ^/admin, 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.
+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 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 :ref:`configuration` page for that.
-
-Step 6
-~~~~~~
-
 The CAS protocol requires HTTPS on both side (client and server) in order
 to communicate.
 
@@ -104,17 +78,54 @@ 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`
+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 6
+~~~~~~
+
+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 :ref:`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`_.
+
 .. _Composer: https://getcomposer.org
 .. _symfony/http-client: https://packagist.org/packages/symfony/http-client
 .. _https://heroku-cas-server.herokuapp.com/cas/: https://heroku-cas-server.herokuapp.com/cas/
-.. _the Symfony documentation about security and Guard authentication: https://symfony.com/doc/current/security/guard_authentication.html
+.. _the Symfony documentation about security and Guard authentication: https://symfony.com/doc/current/security/guard_authentication.html
+.. _this page: https://apereo.github.io/cas/6.1.x/index.html#demos
+.. _Proxy authentication: https://apereo.github.io/cas/6.1.x/installation/Configuring-Proxy-Authentication.html#proxy-authentication
+.. _source: https://github.com/drupol/heroku-cas-server
+.. _Docker project: https://github.com/crpeck/cas-overlay-docker
+.. _Apereo: https://www.apereo.org/
+.. _https://casserver.herokuapp.com/cas/: https://casserver.herokuapp.com/cas/

docs/pages/usage.rst

@@ -14,10 +14,11 @@ Configure the configuration files accordingly and the security of your Symfony a
 Step 3
 ~~~~~~
 
-If you try to reach a path that is protected by the firewall, you should be automatically
+Once setup, if you try to reach a path that is protected by the firewall, you will 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 you try to reach a path using Ajax (`X-Requested-With: XMLHttpRequest`), there won't be any redirection but
+an error **401** (`Unauthorized`).
 
-If the credentials that you provided were valid, then you'll be authenticated.
+Once authenticated on the CAS server, you will be redirected back to the Symfony application and continue the
+authentication process.