Merge pull request #3 from eadwinCode/docs

Docs

Author: eadwinCode

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright 2017 David Sanders
+Copyright 2021 Ezeudoh Tochukwu
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

docs/docs/auth_integration.md

@@ -0,0 +1,57 @@
+
+Ninja JWT uses Django Ninja `HttpBearer` as a way to authenticate users reaching your api endpoint.
+Authenticated user can be found in `request.user` or `request.auth`
+
+### Route Authentication - Class Based
+
+``` {.sourceCode .python}
+from ninja_extra import APIController, router, route
+from ninja_jwt.authentication import JWTAuth
+
+@router('')
+class MyController(APIController):
+    @route.get('/some-endpoint', auth=JWTAuth())
+    def some_endpoint(self):
+        ...
+```
+
+### Route Authentication - Function Based
+
+``` {.sourceCode .python}
+from ninja import router
+from ninja_jwt import JWTAuth
+
+router = router('')
+
+@router.get('/some-endpoint', auth=JWTAuth())
+def some_endpoint(self):
+    ...
+```
+
+Custom Auth Implement
+-------
+If you wish to use a different implementation of `JWTAuth`, then you need to inherit from `JWTBaseAuthentication`.
+Please read more on [Django Ninja - Authentication](https://django-ninja.rest-framework.com/tutorial/authentication/), if you want to use a different approach that is not `bearer`.
+
+example:
+``` {.sourceCode .python}
+from ninja.security import APIKeyHeader
+from ninja_jwt.authentication import JWTBaseAuthentication
+from ninja import router
+
+class ApiKey(APIKeyHeader):
+    param_name = "X-API-Key"
+
+    def authenticate(self, request, key):
+        if key == "supersecret":
+            return self.jwt_authenticate(request, token=key)
+
+
+header_key = ApiKey()
+router = router('')
+
+@api.get("/headerkey", auth=header_key)
+def apikey(request):
+    return f"Token = {request.auth}"
+
+```

docs/docs/blacklist_app.md

@@ -0,0 +1,50 @@
+
+Ninja JWT includes an app that provides token blacklist functionality.
+To use this app, include it in your list of installed apps in
+`settings.py`:
+
+``` {.sourceCode .python}
+# Django project settings.py
+
+...
+
+INSTALLED_APPS = (
+    ...
+    'ninja_jwt.token_blacklist',
+    ...
+)
+```
+
+Also, make sure to run `python manage.py migrate` to run the app\'s
+migrations.
+
+If the blacklist app is detected in `INSTALLED_APPS`, Ninja JWT will
+add any generated refresh or sliding tokens to a list of outstanding
+tokens. It will also check that any refresh or sliding token does not
+appear in a blacklist of tokens before it considers it as valid.
+
+The Ninja JWT blacklist app implements its outstanding and blacklisted
+token lists using two models: `OutstandingToken` and `BlacklistedToken`.
+Model admins are defined for both of these models. To add a token to the
+blacklist, find its corresponding `OutstandingToken` record in the admin
+and use the admin again to create a `BlacklistedToken` record that
+points to the `OutstandingToken` record.
+
+Alternatively, you can blacklist a token by creating a `BlacklistMixin`
+subclass instance and calling the instance's `blacklist` method:
+
+``` {.sourceCode .python}
+from ninja_jwt.tokens import RefreshToken
+
+token = RefreshToken(base64_encoded_token_string)
+token.blacklist()
+```
+
+This will create unique outstanding token and blacklist records for the
+token's `jti` claim or whichever claim is specified by the
+`JTI_CLAIM` setting.
+
+The blacklist app also provides a management command,
+`flushexpiredtokens`, which will delete any tokens from the outstanding
+list and blacklist that have expired. You should set up a cron job on
+your server or hosting platform which runs this command daily.

docs/docs/blacklist_app.rst

@@ -3,7 +3,7 @@
 Blacklist app
 =============
 
-Simple JWT includes an app that provides token blacklist functionality.  To use
+Ninja JWT includes an app that provides token blacklist functionality.  To use
 this app, include it in your list of installed apps in ``settings.py``:
 
 .. code-block:: python
@@ -21,12 +21,12 @@ this app, include it in your list of installed apps in ``settings.py``:
 Also, make sure to run ``python manage.py migrate`` to run the app's
 migrations.
 
-If the blacklist app is detected in ``INSTALLED_APPS``, Simple JWT will add any
+If the blacklist app is detected in ``INSTALLED_APPS``, Ninja JWT will add any
 generated refresh or sliding tokens to a list of outstanding tokens.  It will
 also check that any refresh or sliding token does not appear in a blacklist of
 tokens before it considers it as valid.
 
-The Simple JWT blacklist app implements its outstanding and blacklisted token
+The Ninja JWT blacklist app implements its outstanding and blacklisted token
 lists using two models: ``OutstandingToken`` and ``BlacklistedToken``.  Model
 admins are defined for both of these models.  To add a token to the blacklist,
 find its corresponding ``OutstandingToken`` record in the admin and use the

docs/docs/creating_tokens_manually.md

@@ -0,0 +1,20 @@
+
+Sometimes, you may wish to manually create a token for a user. This
+could be done as follows:
+
+``` {.sourceCode .python}
+from ninja_jwt.tokens import RefreshToken
+
+def get_tokens_for_user(user):
+    refresh = RefreshToken.for_user(user)
+
+    return {
+        'refresh': str(refresh),
+        'access': str(refresh.access_token),
+    }
+```
+
+The above function `get_tokens_for_user` will return the serialized
+representations of new refresh and access tokens for the given user. In
+general, a token for any subclass of `ninja_jwt.tokens.Token` can be
+created in this way.

docs/docs/customizing_token_claims.md

@@ -0,0 +1,65 @@
+
+If you wish to customize the claims contained in web tokens which are
+generated by the `SimpleJWTDefaultController` and `SimpleJWTSlidingController`
+views, create a subclass for the desired controller as well as a subclass for
+its corresponding serializer. Here\'s an example :
+
+``` {.sourceCode .python}
+from ninja_jwt.schema import TokenObtainPairSerializer
+from ninja_jwt.controller import TokenObtainPairController, router, route
+from ninja_schema import Schema
+
+
+class UserSchema(Schema):
+    first_name: str
+    email: str
+    
+    
+class MyTokenObtainPairOutSchema(Schema):
+    refresh: str
+    access: str
+    user: UserSchema
+
+
+class MyTokenObtainPairSchema(TokenObtainPairSerializer):
+    def output_schema(self):
+        out_dict = self.dict(exclude={"password"})
+        out_dict.update(user=UserSchema.from_orm(self._user))
+        return MyTokenObtainPairOutSchema(**out_dict)
+
+@router('/token', tags=['Auth'])
+class MyTokenObtainPairController(TokenObtainPairController):
+    @route.post(
+        "/pair", response=schema.MyTokenObtainPairOutSchema, url_name="token_obtain_pair"
+    )
+    def obtain_token(self, user_token: MyTokenObtainPairSchema):
+        return user_token.output_schema()
+    
+```
+
+As with the standard controller, you\'ll also need to include register the controller as shown in `getting_started`
+
+#### Use Django Ninja Router
+If you interested in using functions rather than classes, then you are also covered.
+Here is an example
+
+``` {.sourceCode .python}
+from ninja import router
+from ninja_schema import Schema
+
+router = router('/token')
+
+@router.post(
+    "/pair", response=schema.MyTokenObtainPairOutSchema, url_name="token_obtain_pair"
+)
+def obtain_token(self, user_token: MyTokenObtainPairSchema):
+    return user_token.output_schema()
+```
+
+Register the `router` to the django-ninja `api` like so:
+``` {.sourceCode .python}
+from ninja import NinjaAPI
+
+api = NinjaAPI()
+api.add_router('', tags=['Auth'], router=router)
+```

docs/docs/development_and_contributing.md

@@ -0,0 +1,19 @@
+
+To do development work for Ninja JWT, make your own fork on Github,
+clone it locally, make and activate a virtualenv for it, then from
+within the project directory:
+
+``` {.sourceCode .bash}
+make install
+```
+
+To run the tests:
+
+``` {.sourceCode .bash}
+make test
+```
+To run the tests with coverage:
+
+``` {.sourceCode .bash}
+make test-cov
+```

docs/docs/development_and_contributing.rst

@@ -3,7 +3,7 @@
 Development and contributing
 ============================
 
-To do development work for Simple JWT, make your own fork on Github, clone it
+To do development work for Ninja JWT, make your own fork on Github, clone it
 locally, make and activate a virtualenv for it, then from within the project
 directory:
 

docs/docs/experimental_features.md

@@ -0,0 +1,25 @@
+subtitle: JWTTokenUserAuthentication backend
+title: Experimental features
+---
+
+The `JWTTokenUserAuthentication` backend\'s `authenticate` method does
+not perform a database lookup to obtain a user instance. Instead, it
+returns a `ninja_jwt.models.TokenUser` instance which acts as a
+stateless user object backed only by a validated token instead of a
+record in a database. This can facilitate developing single sign-on
+functionality between separately hosted Django apps which all share the
+same token secret key. To use this feature, add the
+`ninja_jwt.authentication.JWTTokenUserAuthentication` backend (instead
+of the default `JWTAuthentication` backend) to the Django REST
+Framework\'s `DEFAULT_AUTHENTICATION_CLASSES` config setting:
+
+``` {.sourceCode .python}
+REST_FRAMEWORK = {
+    ...
+    'DEFAULT_AUTHENTICATION_CLASSES': (
+        ...
+        'ninja_jwt.authentication.JWTTokenUserAuthentication',
+    )
+    ...
+}
+```

docs/docs/getting_started.md

@@ -0,0 +1,98 @@
+
+#### Requirements
+- Python >= 3.6
+- Django >= 2.1
+- Django-Ninja >= 0.16.1
+- Ninja-Schema >= 0.12.2
+- Django-Ninja-Extra >= 0.11.0
+
+These are the officially supported python and package versions. Other
+versions will probably work. You\'re free to modify the tox config and
+see what is possible.
+
+Installation
+============
+
+Ninja JWT can be installed with pip:
+
+    pip install ninja-jwt
+
+Also, you need to register `SimpleJWTDefaultController` controller to you Django-Ninja api.
+The `SimpleJWTDefaultController` comes with three routes `obtain_token`, `refresh_token` and `verify_token`
+
+``` {.sourceCode .python}
+from ninja_jwt.controller import SimpleJWTDefaultController
+from ninja_extra import NinjaExtraAPI
+
+api = NinjaExtraAPI()
+api.register_controller(SimpleJWTDefaultController)
+
+```
+
+The `SimpleJWTDefaultController` comes with three routes `obtain_token`, `refresh_token` and `verify_token`. 
+It is a combination of two subclass `TokenVerificationController` and `TokenObtainPairController`.
+If you wish to customize these routes, you can inherit from these controllers and change its implementation
+
+``` {.sourceCode .python}
+from ninja_jwt.controller import TokenObtainPairController, router
+
+@router('token', tags=['Auth']
+class MyCustomController(TokenObtainPairController):
+    """obtain_token and refresh_token only"
+...
+api.register_controller(MyCustomController)
+```
+
+If you wish to use localizations/translations, simply add `ninja_jwt` to
+`INSTALLED_APPS`.
+
+``` {.sourceCode .python}
+INSTALLED_APPS = [
+    ...
+    'ninja_jwt',
+    ...
+]
+```
+
+Usage
+=====
+
+To verify that Ninja JWT is working, you can use curl to issue a couple
+of test requests:
+
+``` {.sourceCode .bash}
+curl \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"username": "davidattenborough", "password": "boatymcboatface"}' \
+  http://localhost:8000/api/token/pair
+
+...
+{
+  "access":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3BrIjoxLCJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiY29sZF9zdHVmZiI6IuKYgyIsImV4cCI6MTIzNDU2LCJqdGkiOiJmZDJmOWQ1ZTFhN2M0MmU4OTQ5MzVlMzYyYmNhOGJjYSJ9.NHlztMGER7UADHZJlxNG0WSi22a2KaYSfd1S-AuT7lU",
+  "refresh":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3BrIjoxLCJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImNvbGRfc3R1ZmYiOiLimIMiLCJleHAiOjIzNDU2NywianRpIjoiZGUxMmY0ZTY3MDY4NDI3ODg5ZjE1YWMyNzcwZGEwNTEifQ.aEoAYkSJjoWH1boshQAaTkf8G3yn0kapko6HFRt7Rh4"
+}
+```
+
+You can use the returned access token to prove authentication for a
+protected view:
+
+``` {.sourceCode .bash}
+curl \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3BrIjoxLCJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiY29sZF9zdHVmZiI6IuKYgyIsImV4cCI6MTIzNDU2LCJqdGkiOiJmZDJmOWQ1ZTFhN2M0MmU4OTQ5MzVlMzYyYmNhOGJjYSJ9.NHlztMGER7UADHZJlxNG0WSi22a2KaYSfd1S-AuT7lU" \
+  http://localhost:8000/api/some-protected-view/
+```
+
+When this short-lived access token expires, you can use the longer-lived
+refresh token to obtain another access token:
+
+``` {.sourceCode .bash}
+curl \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"refresh":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3BrIjoxLCJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImNvbGRfc3R1ZmYiOiLimIMiLCJleHAiOjIzNDU2NywianRpIjoiZGUxMmY0ZTY3MDY4NDI3ODg5ZjE1YWMyNzcwZGEwNTEifQ.aEoAYkSJjoWH1boshQAaTkf8G3yn0kapko6HFRt7Rh4"}' \
+  http://localhost:8000/api/token/refresh/
+
+...
+{"access":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3BrIjoxLCJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiY29sZF9zdHVmZiI6IuKYgyIsImV4cCI6MTIzNTY3LCJqdGkiOiJjNzE4ZTVkNjgzZWQ0NTQyYTU0NWJkM2VmMGI0ZGQ0ZSJ9.ekxRxgb9OKmHkfy-zs1Ro_xs1eMLXiR17dIDBVxeT-w"}
+```