Previously the OpenID Connect backend was only allowing to provide
a refresh token in authorization header for convenient access token
renewal when querying a GraphQL service outside of a browser.

When one wants to query a GraphQL service inside a browser, the
access tokens are usually created and renewed client-side so also
allow to provide an access token in the authorization header.
In that case, the backend will simply try to decode it in order
to authenticate the user.

Related to swh-graphql#4652

GitLab will display the content of the README file when browsing the
repository. But in case the file is a symlink, it will display the
path pointed by the symlink. There is a 6 year old issue about this:
https://gitlab.com/gitlab-org/gitlab/-/issues/15093

We can workaround the issue by having the content at the root of the
repository and a symlink to this file in the `docs/` directory.

Tested in swh/devel/swh-py-template!27

swh-auth is compatible with latest django version so we can safely
remove the version restriction.

Related to swh/devel/swh-web#4734

Related to swh/meta#4960

Related to swh/meta#4959

accepts Keycloak server details and an aiocache cache instance
returns a starlette SimpleUser along with permissions

This fixes python 3.7 support due to poetry, a dependency of isort, that
removed support for that Python version in a recent release.

In order to remove warnings about /apidoc/*.rst files being included
multiple times in toc when building full swh documentation, prefer to
include module indices only when building standalone package documentation.

Also include them the proper sphinx way.

Related to T4496

- pre-commit from 4.1.0 to 4.3.0,
- codespell from 2.2.1 to 2.2.2,
- black from 22.3.0 to 22.10.0 and
- flake8 from 4.0.1 to 5.0.4. Also freeze flake8 dependencies.

Also change flake8's repo config to github (the gitlab mirror
being outdated).

It enables to align that parameter name with the one used in
django.contrib.auth.

The scope and state query parameters in the authorization URL are now
handled by the KeycloakOpenID.auth_url method since the release of
python-keycloak 1.8.1.

To keep backward compatibility with older python-keycloak versions, like
the one used in production, while ensuring support for recent ones we need
to ensure scope and state query parameters will be overridden if provided
in extra_params dict.

Add support for mapping Keycloak groups to Django ones in OIDCUser
model by overriding the groups member of Django base User model.

It enables to manipulate user groups declared in Keycloak using
Django standard User model API.

That hook can be frustrating as it can discard a long commit message
if it finds a typo in it so better removing it.

When catching KeycloakError exceptions, other exception types
will be then raised like ValueError or AuthenticationFailed.

Those will be processed by django applications using these auth
middlewares so there is no need to duplicate error reports in
sentry here.

Related to T3922

black is considered stable since release 22.1.0 and the version
we are currently using is quite outdated and not compatible with
click 8.1.0, so it is time to bump it to its latest stable release.

Please note that E501 pycodestyle warning related to line length
is replaced by B950 one from flake8-bugbear as recommended by black.
https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length

Related to T3922

pytest-postgresql 3.1.3 and pytest-redis 2.4.0 added support for
pytest >= 7 so we can now drop the pytest pinning.

This reverts commit 4083f796.

There is an incompatibility between latest django-stubs release (1.10.0)
and current release of djangorestframework-stubs.

So temporarily pin django-stubs to < 1.10.0 until the issue is fixed.

pytest: Exclude build directory for tests discovery\n\nDue to test modules being copied in subdirectories of the\nbuild directory by setuptools, it makes pytest fail by raising\nImportPathMismatchError exceptions when invoked from root\ndirectory of the module.\n\nSo ignore the build folder to discover tests.

To install the new hook:

  $ pre-commit install -t commit-msg

Related to T3916

This also drops spurious copyright headers to those files if present.

Related to T3812

This should help debugging keycloak authentication issues.

When a user session has been terminated without using the logout view
(for instance a user can logout from all its authenticated sessions
using the Keycloak account UI), the expired OIDC profile is still
in webapp cache which causes errors and prevent new user logins.

So ensure to remove expired profile from cache when detecting Keycloak
session is no longer active in django authentication backend.

Related to T3496

Migrate auth command group from swh-web-client package to the
swh-auth package.

Related to T3385

Enable to check package documentation can be built without producing
sphinx warnings.

The sphinx environment is designed to be used in continuous integration
in order to prevent breaking documentation build when committing changes.

The sphinx-dev environment is designed to be used inside a full swh
development environment.

Related to T3258

Sphinx complains about an unexpected indentation if a constructor
docstring is missing.

Keycloak also allow to define user roles at realm level to define
permissions at a global level not tight to a client.

Include these extra roles in the user permissions set from the
decoded token content.

Related to T3213