1. Please rewrite this README.md file to be longer and nicer
2.  
3. # VMP Authentication
4. Package for authentication in cloud micro-services.
5. Works with aiohttp and django.
6.  
7. To install it add following line to your requirements.txt:
8. Aiohttp:
9. `git+https://git.otvs.tv/api-services/python-packages/vmp-authentication@<SPECIFIY_VERSION_HERE>#egg=vmp_authentication[aiohttp]`
10.  
11. Django:
12. `git+https://git.otvs.tv/api-services/python-packages/vmp-authentication@<SPECIFIY_VERSION_HERE>#egg=vmp_authentication[django]`
13.  
14. # Development
15.  
16. 1. Make sure you have docker and docker-compose installed and ready to use.
17. 2. Clone repository
18.     ```bash
19.     git clone git@git.otvs.tv:api-services/python-packages/vmp-authentication.git
20.     ```
21.  
22. 3. Build and run tests.
23.     ```bash
24.     docker-compose up --build
25.     ```
26.  
27. # Using middleware for authentication
28.  
29. ## Aiohttp
30. Example usage:
31. ```python
32. import vmp_authentication.aiohttp.middleware as authentication_middleware
33. import vmp_authentication.aiohttp.authentication_backends as authentication_backends
34. from aiohttp import web
35.  
36. app = web.Application()
37.  
38. config = app['config']
39.  
40. common_backend_opts = dict(
41.     # note: In local development we use only http so in such environment
42.     #       we need to disable SSL verification on public keys discovery.
43.     key_jar=keyio.KeyJar(verify_ssl=config.entitlement.verify_ssl),
44.     # DEBT: We don't know how to handle audiences yet for Entitlement.
45.     # DEBT: With Aiakos we can't control the audience so we don't
46.     #       verify it
47.     jose_options={'verify_aud': False},
48. )
49.  
50. backends = [
51.     # 1: Entitlement cookie takes precedence over all auth schemes.
52.     authentication_backends.TVCloudEntitlementCookie(
53.         trusted_issuers=config.entitlement.trusted_issuers,
54.         **common_backend_opts,
55.     ),
56.  
57.     # 2: Next are PET tokens in Token Bearer auth as we can differentiate
58.     #    them easily from OIDC JWT Access Tokens in Token Bearer auth.
59.     authentication_backends.TVCloudEntitlementBearer(
60.         trusted_issuers=config.entitlement.trusted_issuers,
61.         **common_backend_opts,
62.     ),
63.  
64.     # 3: Last are OIDC JWT Access Tokens in Token Bearer.
65.     authentication_backends.TVCloudAccessTokenBearer(
66.         trusted_issuers=config.oidc.trusted_issuers,
67.         # DEBT: With Aiakos we can't control the audience so we don't
68.         #       verify it.
69.         jose_options={'verify_aud': False},
70.     ),
71. ]
72.  
73. app.middlewares.append(authentication_middleware.authentication_middleware_factory(backends))
74. ```
75.  
76. ## Django
77.  
78. We use `drf-oidc-auth` library as a basis for authenticating users in
79. DRF-based services. It is included by default in this package requirements and
80. it means that [documentation of drf-oidc-auth] aplies here when consiguring the
81. authentication. `dja-toolkit` also includes some custom modifications to
82. authentication classes that are not included upstream.
83.  
84. Following is example auth configuration that enables both cookie-based and
85. header-based JWT authentication:
86.  
87. ```python
88. REST_FRAMEWORK = DJA_TOOLKIT_REST_FRAMEWORK # Look for this in dja_toolkit package
89. REST_FRAMEWORK.update(
90.     {
91.         'DEFAULT_AUTHENTICATION_CLASSES': (
92.             'vmp_authentication.django.AuthBakerEntitlementCookieAuthentication',
93.             'vmp_authentication.django.AuthBakerEntitlementHeaderAuthentication',
94.             'vmp_authentication.django.authentication.A4DEntitlementHeaderAuthentication',
95.         ),
96.     }
97. )
98.  
99. OIDC_AUTH = {
100.     # Here we use url of auth-baker instance deployed in the same environment.
101.     # Configuration will be automatically done based on the discovery document found
102.     # at <endpoint>/.well-known/openid-configuration
103.     'OIDC_ENDPOINT': 'https://url-to-auth-baker',
104.  
105.     # Function that resolves token into user. This function receives a
106.     # request and token dict and expects to return a User object.
107.     # For our services it is recommended to use the
108.     # `dja_toolkit.auth.authentication.claims_as_user` as it always returns
109.     # authenticated user object that gives access to users' claims.
110.     'OIDC_RESOLVE_USER_FUNCTION': 'vmp_authentication.django.user_resolver.claims_as_user',
111.  
112.     # Number of seconds in the past valid tokens can be issued. This is only
113.     # to account for clock skews. Keep it small like seconds (default 600).
114.     'OIDC_LEEWAY': 10,
115.  
116.     # Time before signing keys will be refreshed (default 24 hrs)
117.     'OIDC_JWKS_EXPIRATION_TIME': 24 * 60 * 60,
118.  
119.     # Token prefix in JWT authorization header (default 'JWT', we use `Bearer`)
120.     'JWT_AUTH_HEADER_PREFIX': 'Bearer',
121.     # Cookie name used in cookie-based JWT authentication
122.     'JWT_COOKIE_NAME': 'TVCloudAccessToken',
123. }
124. ```
125.