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

The first time a user sends an expired token previously used to
perform authenticated Web API calls, Keycloak will return the
following error message: "Offline session not active".

So handle that error message too for indicating a token has expired.

Related to T3121

This replaces the Keycloak error message by a more comprehensible one
for end users.

Unfortunately, there is no way to get the bearer token validity period
apart using Keycloak Admin REST API but we clearly do not want to query
it in a django authentication backend.

Related to T3121

That middleware detects when a user previously logged in using
the OpenID Connect authentication backend got his session expired.

In that case it will perform a redirection to a django view whose
name must be set in the SWH_AUTH_SESSION_EXPIRED_REDIRECT_VIEW
django setting (typically a logout view).

Related to T3150

Add a generic Django REST Framework authentication backend enabling to
authenticate a user using Keycloak and OpenID Connect bearer tokens.

The backend can be easily plugged into a DRF application by:

  * adding "swh.auth.django.backends.OIDCBearerTokenAuthentication"
    to the REST_FRAMEWORK["DEFAULT_AUTHENTICATION_CLASSES"]
    django setting.

  * configuring Keycloak URL, realm and client by adding
    SWH_AUTH_SERVER_URL, SWH_AUTH_REALM_NAME and SWH_AUTH_CLIENT_ID
    in django settings

Users will then be able to perform authenticated Web API calls by
sending their refresh token in HTTP Authorization headers.

Related to T3150

Add a generic Django authentication backend and related login / logout
views enabling to authenticate a user using Keycloak and the OpenID
Connect authorization code flow with PKCE ("Proof Key for Code Exchange").

The backend can be easily plugged into any django application by:

 - adding "swh.auth.django.backends.OIDCAuthorizationCodePKCEBackend"
   to the AUTHENTICATION_BACKENDS django setting

 - configuring Keycloak by adding SWH_AUTH_SERVER_URL, SWH_AUTH_REALM_NAME
   and SWH_AUTH_CLIENT_ID in django settings

 - adding swh.auth.django.views.urlpatterns to the django application URLs

 - using the dedicated django views: "oidc-login" and "oidc-logout"

Related to T3150

It enables to properly override those values by getting / setting them
from / to the wrapped KeycloakOpenID instance.

This will simplify fixture use in external modules that use the
pytest plugin.

Let's start to apply recommended guidelines when writing tests.

Remove the AppUser test model inheriting from OIDCUser.

Storing data related to a remote user should be done with a dedicated
django model containing a user identifier column.

Update tests accordingly.

Add fields "expires_in" and "refresh_expires_in" to OIDCUser model storing
the validity times for access and refresh tokens.

Add oidc_profile property to get the OpenID Connect profile associated to
the user as a dictionary.

Update and simplify tests for OIDCUser model.

Related to T3150

Add keycloak_oidc_client factory to instantiate KeycloakOpenIDConnect
class from the following django settings:

  - KEYCLOAK_SERVER_URL
  - KEYCLOAK_REALM_NAME
  - KEYCLOAK_CLIENT_ID

This is required before moving the generic django OIDC auth backends
from swh-web to swh-auth.

Use django stubs for mypy to remove the following error in models.py:
"Need type annotation for 'url'".

To ease transforming KeycloakError into an exception message.

Related to T3166

OIDCUser model will not be persisted to django database as those
information are already stored in the identity provider one.

So ensure no table for the model will be created in django database
by setting the auto_created meta flag to True.

Related to T3150

Prior to this commit, this raised a basic error message instead of a json dict bytes
encoded.

This commit fixes it.

Related to T2858

This will allow caller code to depend on it without leaking the exception from the
keycloak module.

In some application, those user fields might not be filled in. As it's not enforced by
keycloak, relax such constraint.

Related to T2858

In the dictionary decoded from an OIDC access token, the iat field store
the token creation date while the auth_time field store the date the
OIDC session was opened.

In order to get an accurate authentication time, the date stored in
the iat field must be used as it corresponds to the time an access
token was refreshed and thus the latest valid authentication date.

The auth_time is not always provided depending on the authentication flow used. The
field iat is provided for example in the direct grant access flow so use it instead as
fallback.

Related to T2858

Related to T2858

Tester will want to craft carefully the keycloak mock so it returns
consistent data.

Currently the decoded_token and user_info are hard-coded to consistent values. So using
the default keycloak mock is ok. As soon as other testers will want another user_info,
the decoded token will diverge and not return the correct user_info subpart of the
decoded token.

This commits fixes such behavior and allows the decoded token to stay consistent with
the user_info.

Related to T2858

Related to T3079

Related to T3079

That class is a custom User proxy model for remote users storing OpenID Connect related
data (profile containing authentication tokens, ...).

The model is also not saved to database as all users are already stored in the Keycloak
one.

That class will be used for example by both the webapp and the deposit.

Related to T3079

Related to T3079