# django-cloudspotlicense
Django package to integrate the authentication of the Cloudspot License Server in other django applications.
## Getting started
### Install
Install with pip.
```python
pip install django-cloudspotlicense
```
### Quick start
1. Add ```django_cloudspotlicense``` to your INSTALLED_APPS
```python
INSTALLED_APPS = [
...
'django_cloudspotlicense'
]
```
2. Include the URLConf in your project urls.py
```python
urlpatterns = [
path('auth/', include('django_cloudspotlicense.urls')),
]
```
3. Run ``python manage.py migrate`` to create all the required models
4. Use the ```LoginView``` to let users log in using the Cloudspot License Server
```python
import django_cloudspotlicense.views as auth_views
urlpatterns = [
path('login', auth_views.LoginView.as_view(), name='login')
]
```
A basic html template with no styling will be provided. You can overwrite this template by simply creating a new template at ```templates/auth/login.html```.
The only requirement for this template is that it includes two input elements with the name ```username``` and ```password```.
```html
<input type="text" name="username" />
<input type="password" name="password" />
```
5. Add the application ID as given by the Cloudspot License server to your ```settings.py```.
```python
# settings.py
CLOUDSPOT_LICENSE_APP = config('CLOUDSPOT_LICENSE_APP')
```
6. Done
## Setting up the User model
You can extend the User model as usual to add more attributes. ```django_cloudspotlicense``` also uses the User model to store additional information, such as tokens and the company id.
If you want to add additional attributes, import the User class from the package and add your attributes as usual.
```python
from django_cloudspotlicense.models import CloudspotUser
class User(CloudspotUser):
extra_data = models.CharField(max_length=500, default='foobar')
```
Use as normal.
```python
print(user.extra_data) # foobar
```
## Permission checking
There are a few ways to check if the current user has the correct permission on the Cloudspot License server to do an action.
It's important that you **do not use the built-in permission checker from Django**. This will always return ```False``` on any given permission.
1. **Class-based views**
When using class-based views, you can import the modified ```PermissionRequiredMixin``` and ```LoginRequiredMixin```.
When using ```PermissionRequiredMixin```, the ```LoginRequiredMixin``` is implied as an anonymous user can not have any permissions.
```python
from django_cloudspotlicense.mixins import PermissionRequiredMixin, LoginRequiredMixin
# Use as is normal within Django
# The user needs the permission 'use_dashboard' to be able to view this template
class Dashboard(PermissionRequiredMixin, TemplateView):
permission_required = 'use_dashboard' # use the permission code as shown in the Cloudspot License server
template_name = '...'
# OR
# The user needs to be logged in and be assigned a company (which is always required) before he's able to see this view
class Projects(LoginRequiredMixin, TemplateView):
template_name = '...'
```
2. **Functions**
You can use the utility function ```has_perm()``` to check if a user has a permission.
```python
from django_cloudspotlicense.utils import has_perm
if has_perm(user, 'use_dashboard'):
# user has the permission use_dashboard in Cloudspot License server
else:
# user does not have the permission
```
**! At this moment it's not possible to check multiple permissions at once. You will need to call the function for each permission.**
3. **Templates**
Inside a template, you can use a templatetag to check for the correct permission.
```html
<!-- This is REQUIRED, else the tag will not work -->
{% load license_tags %}
<!-- Use the tag 'has_perm' on a user object -->
{% if request.user|has_perm:'list_projects' %}
<!-- This piece of HTML will only be rendered if the user has the 'list_projects' permission -->
<h3>Projects</h3>
<ul>
<li>...</li>
</ul>
{% endif %}
```
## Webhook
This package also provides a webhook where the Cloudspot License Server will send updates to whenever the permissions for a user changes.
The webhook is located at ```https://example.com/auth/webhook```. This webhook is automatically activated when importing the URLConf.
## Migrating to the License server from an existing application
Migrating to the license server from an existing Django application that is using the local built-in user authentication is possible, but should be done with **extreme care** and careful consideration.
The following guide will step you through the required actions to succesfully migrate all the authentication to the license server.
**!! BACKUP YOUR DATABASE AND FILES BEFORE PROCEEDING**
Failure to follow the provided steps can result in breaking changes. Always have a backup ready.
### Setup
Copy the `merge_with_license_server.py` script located under `scripts` to your management commands directory in your Django project.
### 1. Add a new field 'backup_email' to the existing User model
This field will be used to copy the current username/email to, which will be needed later on. Be sure to allow null as it will be empty at first.
```python
# models.py
# THIS IS YOUR LOCAL USER MODEL
class User(AbstractUser):
backup_email = models.CharField(max_length=500, null=True)
# ...
```
### 2. Make migrations and migrate
```python
python manage.py makemigrations
python manage.py migrate
```
### 3. Run the first step of the migration script
This step will copy the existing username/email to the newly created `backup_email` field.
```python
python manage.py merge_with_license_server --step1
```
### 4. Install this package and add it to your INSTALLED_APPS
```python
pip install django-cloudspotlicense
```
```python
# settings.py
INSTALLED_APPS = [
...
'django_cloudspotlicense'
]
```
### 5. Modify the existing User model
The existing User model should not inherit from `AbstractUser` anymore, but should be changed to a normal model at this point.
```python
# models.py
# THIS IS YOUR LOCAL USER MODEL
class User(models.Model): # WAS: class User(AbstractUser)
# ...
```
Add the following fields at the top of the User model:
```python
# models.py
# THIS IS YOUR LOCAL USER MODEL
class User(models.Model): # WAS: class User(AbstractUser)
REQUIRED_FIELDS = []
USERNAME_FIELD = 'id'
is_anonymous = False # can be either true or false, doesnt matter
is_authenticated = True # can be either true or false, doesnt matter
# ...
```
### 6. Make migrations and migrate
```python
python manage.py makemigrations
python manage.py migrate
```
### 7. Set AUTH_USER_MODEL in settings.py
Change the `AUTH_USER_MODEL` in your `settings.py` to `django_cloudspotlicense.CloudspotUser`.
```python
# settings.py
AUTH_USER_MODEL = 'django_cloudspotlicense.CloudspotUser'
```
### 8. Remove fields from existing User model and add new field
Remove the fields that we added in **step 5**.
Import the CloudspotUser and CloudspotCompany models and add a new field: `cloudspotuser_ptr` with a ForeignKey to CloudspotUser.
```python
# models.py
from django_cloudspotlicense.models import CloudspotUser, CloudspotCompany
# THIS IS YOUR LOCAL USER MODEL
class User(models.Model):
cloudspotuser_ptr = models.ForeignKey(CloudspotUser, on_delete=models.SET_NULL, null=True)
```
### 9. Make migrations and migrate
```python
python manage.py makemigrations
python manage.py migrate
```
### 10. Run the second step of the migration script
This step will duplicate the existing users and companies to the newly created CloudspotUser and CloudspotCompany, preserving ID's and usernames.
**!! You may have to modify the script to import your local User and Company models**
```python
python manage.py merge_with_license_server --step2
```
### 11. Modify the existing User model again
Remove the `cloudspotuser_ptr` and `id` fields and let the User model inherit from `CloudspotUser`.
In this step you can also remove any other garbage fields that will not be used anymore.
```python
# models.py
# THIS IS YOUR LOCAL USER MODEL
class User(CloudspotUser):
# ...
```
### 12. Make migrations and migrate
During `makemigrations`, you will have to provide a one-off default UUID for `cloudspotuser_ptr`. This UUID needs to be v4 but can be **any** UUID you like. This will not affect the existing data.
You can generate one here: https://www.uuidgenerator.net/
```python
python manage.py makemigrations # if asked, provide a one-off default for cloudspotuser_ptr and use a random UUIDv4
python manage.py migrate
```
### 13. Remove any other garbage fields
If there are any more garbage fields, you can delete them in this step and migrate again.
### 14. Set AUTH_USER_MODEL back to your local User model in settings.py
Change the `AUTH_USER_MODEL` again to point at your local User model.
```python
# settings.py
AUTH_USER_MODEL = 'main.User'
```
### 15. Migration done
The migration is now done. Follow the quick start from step 2.
Raw data
{
"_id": null,
"home_page": "https://github.com/Ecosy-EU/django-cloudspotlicense",
"name": "django-cloudspotlicense",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "cloudspot,django",
"author": "Alexander Schillemans",
"author_email": "alexander.schillemans@lhs.global",
"download_url": "https://files.pythonhosted.org/packages/25/2e/ac4da6317810440e9ed5f31e2b91f4e1fa02f65fe6b6070637829a0400c7/django-cloudspotlicense-6.3.0.tar.gz",
"platform": null,
"description": "# django-cloudspotlicense\r\nDjango package to integrate the authentication of the Cloudspot License Server in other django applications.\r\n\r\n\r\n## Getting started\r\n\r\n### Install\r\n\r\nInstall with pip.\r\n\r\n```python\r\npip install django-cloudspotlicense\r\n```\r\n\r\n### Quick start\r\n\r\n1. Add ```django_cloudspotlicense``` to your INSTALLED_APPS\r\n\r\n```python\r\nINSTALLED_APPS = [\r\n ...\r\n 'django_cloudspotlicense'\r\n]\r\n```\r\n\r\n2. Include the URLConf in your project urls.py\r\n\r\n```python\r\nurlpatterns = [\r\n path('auth/', include('django_cloudspotlicense.urls')),\r\n]\r\n```\r\n\r\n3. Run ``python manage.py migrate`` to create all the required models\r\n\r\n4. Use the ```LoginView``` to let users log in using the Cloudspot License Server\r\n\r\n```python\r\nimport django_cloudspotlicense.views as auth_views\r\n\r\nurlpatterns = [\r\n path('login', auth_views.LoginView.as_view(), name='login')\r\n]\r\n```\r\n\r\nA basic html template with no styling will be provided. You can overwrite this template by simply creating a new template at ```templates/auth/login.html```.\r\nThe only requirement for this template is that it includes two input elements with the name ```username``` and ```password```.\r\n\r\n```html\r\n<input type=\"text\" name=\"username\" />\r\n<input type=\"password\" name=\"password\" />\r\n```\r\n\r\n5. Add the application ID as given by the Cloudspot License server to your ```settings.py```.\r\n\r\n```python\r\n# settings.py\r\n\r\nCLOUDSPOT_LICENSE_APP = config('CLOUDSPOT_LICENSE_APP')\r\n```\r\n\r\n6. Done\r\n\r\n## Setting up the User model\r\n\r\nYou can extend the User model as usual to add more attributes. ```django_cloudspotlicense``` also uses the User model to store additional information, such as tokens and the company id.\r\nIf you want to add additional attributes, import the User class from the package and add your attributes as usual.\r\n\r\n```python\r\nfrom django_cloudspotlicense.models import CloudspotUser\r\n\r\nclass User(CloudspotUser):\r\n extra_data = models.CharField(max_length=500, default='foobar')\r\n```\r\n\r\nUse as normal.\r\n\r\n```python\r\nprint(user.extra_data) # foobar\r\n```\r\n\r\n## Permission checking\r\n\r\nThere are a few ways to check if the current user has the correct permission on the Cloudspot License server to do an action.\r\nIt's important that you **do not use the built-in permission checker from Django**. This will always return ```False``` on any given permission.\r\n\r\n1. **Class-based views**\r\n\r\nWhen using class-based views, you can import the modified ```PermissionRequiredMixin``` and ```LoginRequiredMixin```.\r\nWhen using ```PermissionRequiredMixin```, the ```LoginRequiredMixin``` is implied as an anonymous user can not have any permissions.\r\n\r\n```python\r\nfrom django_cloudspotlicense.mixins import PermissionRequiredMixin, LoginRequiredMixin\r\n\r\n# Use as is normal within Django\r\n# The user needs the permission 'use_dashboard' to be able to view this template\r\nclass Dashboard(PermissionRequiredMixin, TemplateView):\r\n permission_required = 'use_dashboard' # use the permission code as shown in the Cloudspot License server\r\n template_name = '...'\r\n# OR\r\n# The user needs to be logged in and be assigned a company (which is always required) before he's able to see this view\r\nclass Projects(LoginRequiredMixin, TemplateView):\r\n template_name = '...'\r\n```\r\n\r\n2. **Functions**\r\n\r\nYou can use the utility function ```has_perm()``` to check if a user has a permission.\r\n\r\n```python\r\nfrom django_cloudspotlicense.utils import has_perm\r\n\r\nif has_perm(user, 'use_dashboard'):\r\n # user has the permission use_dashboard in Cloudspot License server\r\nelse:\r\n # user does not have the permission\r\n```\r\n\r\n**! At this moment it's not possible to check multiple permissions at once. You will need to call the function for each permission.**\r\n\r\n3. **Templates**\r\n\r\nInside a template, you can use a templatetag to check for the correct permission.\r\n\r\n```html\r\n<!-- This is REQUIRED, else the tag will not work -->\r\n{% load license_tags %} \r\n\r\n<!-- Use the tag 'has_perm' on a user object -->\r\n{% if request.user|has_perm:'list_projects' %}\r\n <!-- This piece of HTML will only be rendered if the user has the 'list_projects' permission -->\r\n <h3>Projects</h3>\r\n <ul>\r\n <li>...</li>\r\n </ul>\r\n{% endif %}\r\n```\r\n\r\n\r\n## Webhook\r\n\r\nThis package also provides a webhook where the Cloudspot License Server will send updates to whenever the permissions for a user changes.\r\nThe webhook is located at ```https://example.com/auth/webhook```. This webhook is automatically activated when importing the URLConf.\r\n\r\n\r\n## Migrating to the License server from an existing application\r\n\r\nMigrating to the license server from an existing Django application that is using the local built-in user authentication is possible, but should be done with **extreme care** and careful consideration.\r\nThe following guide will step you through the required actions to succesfully migrate all the authentication to the license server.\r\n\r\n**!! BACKUP YOUR DATABASE AND FILES BEFORE PROCEEDING**\r\nFailure to follow the provided steps can result in breaking changes. Always have a backup ready.\r\n\r\n### Setup\r\nCopy the `merge_with_license_server.py` script located under `scripts` to your management commands directory in your Django project.\r\n\r\n### 1. Add a new field 'backup_email' to the existing User model\r\nThis field will be used to copy the current username/email to, which will be needed later on. Be sure to allow null as it will be empty at first.\r\n\r\n```python\r\n# models.py\r\n\r\n# THIS IS YOUR LOCAL USER MODEL\r\nclass User(AbstractUser):\r\n \r\n backup_email = models.CharField(max_length=500, null=True)\r\n # ...\r\n```\r\n\r\n### 2. Make migrations and migrate\r\n\r\n```python\r\npython manage.py makemigrations\r\npython manage.py migrate\r\n```\r\n\r\n### 3. Run the first step of the migration script\r\nThis step will copy the existing username/email to the newly created `backup_email` field.\r\n\r\n```python\r\npython manage.py merge_with_license_server --step1\r\n```\r\n\r\n### 4. Install this package and add it to your INSTALLED_APPS\r\n\r\n```python\r\npip install django-cloudspotlicense\r\n```\r\n\r\n```python\r\n# settings.py\r\n\r\nINSTALLED_APPS = [\r\n ...\r\n 'django_cloudspotlicense'\r\n]\r\n```\r\n\r\n### 5. Modify the existing User model\r\nThe existing User model should not inherit from `AbstractUser` anymore, but should be changed to a normal model at this point.\r\n\r\n```python\r\n# models.py\r\n\r\n# THIS IS YOUR LOCAL USER MODEL\r\nclass User(models.Model): # WAS: class User(AbstractUser)\r\n # ...\r\n```\r\n\r\nAdd the following fields at the top of the User model:\r\n\r\n```python\r\n# models.py\r\n\r\n# THIS IS YOUR LOCAL USER MODEL\r\nclass User(models.Model): # WAS: class User(AbstractUser)\r\n REQUIRED_FIELDS = []\r\n USERNAME_FIELD = 'id'\r\n is_anonymous = False # can be either true or false, doesnt matter\r\n is_authenticated = True # can be either true or false, doesnt matter\r\n\r\n # ...\r\n```\r\n\r\n### 6. Make migrations and migrate\r\n\r\n```python\r\npython manage.py makemigrations\r\npython manage.py migrate\r\n```\r\n\r\n### 7. Set AUTH_USER_MODEL in settings.py\r\nChange the `AUTH_USER_MODEL` in your `settings.py` to `django_cloudspotlicense.CloudspotUser`.\r\n\r\n```python\r\n# settings.py\r\n\r\nAUTH_USER_MODEL = 'django_cloudspotlicense.CloudspotUser'\r\n```\r\n\r\n### 8. Remove fields from existing User model and add new field\r\nRemove the fields that we added in **step 5**.\r\nImport the CloudspotUser and CloudspotCompany models and add a new field: `cloudspotuser_ptr` with a ForeignKey to CloudspotUser.\r\n\r\n```python\r\n# models.py\r\nfrom django_cloudspotlicense.models import CloudspotUser, CloudspotCompany\r\n\r\n# THIS IS YOUR LOCAL USER MODEL\r\nclass User(models.Model):\r\n\r\n cloudspotuser_ptr = models.ForeignKey(CloudspotUser, on_delete=models.SET_NULL, null=True)\r\n```\r\n\r\n### 9. Make migrations and migrate\r\n\r\n```python\r\npython manage.py makemigrations\r\npython manage.py migrate\r\n```\r\n\r\n### 10. Run the second step of the migration script\r\nThis step will duplicate the existing users and companies to the newly created CloudspotUser and CloudspotCompany, preserving ID's and usernames.\r\n\r\n**!! You may have to modify the script to import your local User and Company models**\r\n\r\n```python\r\npython manage.py merge_with_license_server --step2\r\n```\r\n\r\n### 11. Modify the existing User model again\r\nRemove the `cloudspotuser_ptr` and `id` fields and let the User model inherit from `CloudspotUser`.\r\nIn this step you can also remove any other garbage fields that will not be used anymore.\r\n\r\n```python\r\n# models.py\r\n\r\n# THIS IS YOUR LOCAL USER MODEL\r\nclass User(CloudspotUser):\r\n # ...\r\n```\r\n\r\n### 12. Make migrations and migrate\r\nDuring `makemigrations`, you will have to provide a one-off default UUID for `cloudspotuser_ptr`. This UUID needs to be v4 but can be **any** UUID you like. This will not affect the existing data.\r\nYou can generate one here: https://www.uuidgenerator.net/\r\n\r\n```python\r\npython manage.py makemigrations # if asked, provide a one-off default for cloudspotuser_ptr and use a random UUIDv4\r\npython manage.py migrate\r\n```\r\n\r\n### 13. Remove any other garbage fields\r\nIf there are any more garbage fields, you can delete them in this step and migrate again.\r\n\r\n### 14. Set AUTH_USER_MODEL back to your local User model in settings.py\r\nChange the `AUTH_USER_MODEL` again to point at your local User model.\r\n\r\n```python\r\n# settings.py\r\n\r\nAUTH_USER_MODEL = 'main.User'\r\n```\r\n\r\n### 15. Migration done\r\nThe migration is now done. Follow the quick start from step 2.\r\n\r\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Django package to integrate the authentication of the Cloudspot License Server in other django applications",
"version": "6.3.0",
"project_urls": {
"Download": "https://github.com/Ecosy-EU/django-cloudspotlicense/archive/refs/tags/6.3.0.tar.gz",
"Homepage": "https://github.com/Ecosy-EU/django-cloudspotlicense"
},
"split_keywords": [
"cloudspot",
"django"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "252eac4da6317810440e9ed5f31e2b91f4e1fa02f65fe6b6070637829a0400c7",
"md5": "61618202ddebcd30d737c6c280ffc95b",
"sha256": "8f50c047fc8f06ec5cc3b4497f3e12bdbda94fbc919b5cdabb561e6a5f8ba05c"
},
"downloads": -1,
"filename": "django-cloudspotlicense-6.3.0.tar.gz",
"has_sig": false,
"md5_digest": "61618202ddebcd30d737c6c280ffc95b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27577,
"upload_time": "2023-06-14T14:02:20",
"upload_time_iso_8601": "2023-06-14T14:02:20.822825Z",
"url": "https://files.pythonhosted.org/packages/25/2e/ac4da6317810440e9ed5f31e2b91f4e1fa02f65fe6b6070637829a0400c7/django-cloudspotlicense-6.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-14 14:02:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Ecosy-EU",
"github_project": "django-cloudspotlicense",
"github_not_found": true,
"lcname": "django-cloudspotlicense"
}
JSON
