README.md 4.96 KB
Newer Older
1 2
## Synopsis

Alexandre's avatar
Alexandre committed
3
This module is an add-on for Django that provides WebID-OIDC accounts management. It plays two roles:
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
- The Relying Party
- The Authentification provider

## Requirements

* djangoldp~=0.5
* validators~=0.12
* pyoic~=0.15
* django-oidc-provider~=0.6

## Installation

1. Install this module and all its dependencies

```
pip install djangoldp_account
```

2. Update settings.py on your server

```
DJANGOLDP_PACKAGES = [
    ...
    'djangoldp_account',
    ...
]
30
LOGIN_URL = '/auth/login/'
31 32 33

OIDC_USERINFO = 'djangoldp_account.settings.userinfo'
OIDC_REGISTRATION_ENDPOINT_REQ_TOKEN = False
34
OIDC_REGISTRATION_ENDPOINT_ALLOW_HTTP_ORIGIN = True
35
OIDC_IDTOKEN_SUB_GENERATOR = 'djangoldp_account.settings.sub_generator'
36
OIDC_IDTOKEN_EXPIRE = 60 * 60
37 38

AUTHENTICATION_BACKENDS = [...,'djangoldp_account.auth.backends.ExternalUserBackend']
39 40 41

MIDDLEWARE = [ ..., 'djangoldp_account.auth.middleware.JWTUserMiddleware']

42 43
```

Calum Mackervoy's avatar
Calum Mackervoy committed
44
You should also ensure that `SITE_URL` and `BASE_URL` are set correctly.
Alexandre's avatar
Alexandre committed
45

46
## User registration
47 48 49 50
User registration use django_registration module : https://django-registration.readthedocs.io/en/3.0.1/

To use it :
Firts, add these settings on settings.py :
51 52

```python
Benoit Alessandroni's avatar
Benoit Alessandroni committed
53
ACCOUNT_ACTIVATION_DAYS=7 #Number of days you want to keep the activation token valid
54 55 56 57 58 59 60 61
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_USE_TLS = True
EMAIL_HOST = 'smtp.gmail.com'
EMAIL_HOST_USER = 'you@gmail.com'
EMAIL_HOST_PASSWORD = 'password'
EMAIL_PORT = 587
```

62 63 64 65 66
Optionally you can configure which user fields which you would like to include on the registration form by including `REGISTRATION_FIELDS` in settings.py
```python
REGISTRATION_FIELDS = ('username', 'email', 'password1', 'password2')
```

67 68
The workflow starts at : http://127.0.0.1:8000/accounts/register/

69 70
Then, override template by copying the directory `djangoldp_account/templates/django_registration/` to your project and modify them.

71 72 73 74 75 76 77 78
## Enabling login by email and username

Modify the `AUTHENTICATION_BACKENDS` variable in `settings.py` to replace 
`'django.contrib.auth.backends.ModelBackend'` by 
`'djangoldp_account.auth.backends.EmailOrUsernameAuthBackend'`.

Ensure `'djangoldp_account.auth.backends.EmailOrUsernameAuthBackend'` is 
first in the list.
Alexandre's avatar
Alexandre committed
79

Calum Mackervoy's avatar
Calum Mackervoy committed
80 81 82 83 84 85 86 87
## Enabling default_redirect_uri behaviour

For many linked-data platforms, there will be multiple authentication providers, and potential multiple client-side apps/websites. In this case it can be difficult to know where to redirect the user. On login it's possible to set `next` as a query parameter pointing to the new site, but the user may have come from sources without this parameter set (e.g. a forgot password link in an email). For user experience, we offer a system which keeps track of the location the user previously logged in from, and falls back onto this if there is not a `next` specified in the URL. To use system this simply add the following to your settings.py

```
LOGIN_REDIRECT_URL = '/redirect-default/'
```

88 89 90 91 92 93 94 95 96
## Authenticate from an external provider

- go to mysite.org/accounts/login
- On the second form, put your email (me@theothersite.com) or the Authorization server url (https://theothersite.com/openid) 

Note: The url provided must contains /openid-configuration (for instance : https://theothersite.com/openid/openid-configuration must exists)

Once authentication on theothersite.com an account will be create on mysite.org and you'll be authentified both on theothersite.com and on mysite.com. 

97 98
## How to know a user is authenticated (Not on any specification)
Useful in case of the client do NOT wants to store token in storage for security reason.
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125

When a user is authenticated on the server, any request will contains the header `User` with user webid
For instance :
```
GET https://mysite.com

HEADERS:
User: https://theothersite.com/users/2
```

Note that `GET https://mysite.com/user/1` will return something like :

```
HEADERS
User: https://anysite.com/users/X

BODY
{
  "@id": "https://theothersite.com/users/2",
  "first_name": "John",
}
```

Because `/user/1` is an account of an external user with webid `https://theothersite.com/users/2`  

# Extending User serialization

Alexandre's avatar
Alexandre committed
126 127
djangoldp_account uses `django.contribs.auth.User` and manages its serialization into JsonLd format
If you need to extend it with you own relation use `USER_NESTED_FIELDS` on settings.py :
128

129
```
130
USER_NESTED_FIELDS=['skills']
131 132
```

133
Also, if you need to override the default permissions on User or Group use :
134 135 136

```
GROUP_PERMISSION_CLASSES=[CustomGroupPermission]
137 138 139 140
GROUP_ANONYMOUS_PERMISSIONS=['view']
GROUP_AUTHENTICATED_PERMISSIONS=['inherit']
GROUP_OWNER_PERMISSIONS=['view', 'control', 'update']

141
USER_ANONYMOUS_PERMISSIONS=['add', 'view']
142
USER_AUTHENTICATED_PERMISSIONS=['inherit']
143
USER_OWNER_PERMISSIONS=['inherit', 'control', 'update']
144 145
```

Benoit Alessandroni's avatar
Benoit Alessandroni committed
146
On the server settings (should be overriden only one time)
147 148 149 150 151 152 153 154

# Federation
If you want to enable full federation capabilities you have to use the `LDPUser` instead of django `User`

Add to your `settings.py` :
```
AUTH_USER_MODEL = 'djangoldp_account.LDPUser'
```