First, install the pip package.
pip install django-helusers
Second, implement your own custom User model in your application's
models.py
.
# users/models.py
from helusers.models import AbstractUser
class User(AbstractUser):
pass
- Add
social-auth-app-django
to yourrequirements.in
orrequirements.txt
file and install the package. - Add
helusers
andsocial_django
to theINSTALLED_APPS
setting:
INSTALLED_APPS = (
'helusers',
...
'social_django',
...
)
Note helusers
must be the first one in the list to properly override the default admin site templates.
- Configure the following settings:
AUTHENTICATION_BACKENDS = (
'helusers.tunnistamo_oidc.TunnistamoOIDCAuth',
'django.contrib.auth.backends.ModelBackend',
)
AUTH_USER_MODEL = 'users.User'
LOGIN_REDIRECT_URL = '/'
- If you need to be able to control Tunnistamo login process language, add also setting
SOCIAL_AUTH_TUNNISTAMO_AUTH_EXTRA_ARGUMENTS = {'ui_locales': 'fi'}
fi
there is the language code that will be used when no language is requested, so change it if you you prefer some
other default language. If you don't want to set a default language at all, use an empty string ""
as the language
code.
When that setting is in place, languages can be requested using query param ui_locales=<language code>
when starting
the login process, for example in your template
<a href="{% url 'helusers:auth_login' %}?next=/foobar/&ui_locales=en">Login in English</a>
- Add URLs entries (to
<project>/urls.py
):
urlpatterns = patterns('',
...
path('', include('social_django.urls', namespace='social'))
...
)
- Configure your client ID, secret and OIDC endpoint locally (for example in
local_settings.py
):
TUNNISTAMO_BASE_URL = 'https://tunnistamo.example.com'
SOCIAL_AUTH_TUNNISTAMO_KEY = 'abcd-12345-abcd-12356789'
SOCIAL_AUTH_TUNNISTAMO_SECRET = 'abcd1234abcd1234abcd1234abcd1234'
SOCIAL_AUTH_TUNNISTAMO_OIDC_ENDPOINT = TUNNISTAMO_BASE_URL + '/openid'
- Set the session serializer to PickleSerializer
helusers stores the access token expiration time as a datetime which is not serializable to JSON, so Django needs to be configured to use the built-in PickeSerializer:
SESSION_SERIALIZER = 'django.contrib.sessions.serializers.PickleSerializer'
- Configure REST framework to use the
ApiTokenAuthentication
class insettings.py
:
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'helusers.oidc.ApiTokenAuthentication',
),
}
- Set your deployment-specific variables in
local_settings.py
, e.g.:
OIDC_API_TOKEN_AUTH = {
'AUDIENCE': 'https://api.hel.fi/auth/projects',
'API_SCOPE_PREFIX': 'projects',
'REQUIRE_API_SCOPE_FOR_AUTHENTICATION': True,
'ISSUER': 'https://api.hel.fi/sso/openid'
}
If you need to access the Tunnistamo API from your JS code, you can include the Tunnistamo base URL in your template context using helusers's context processor:
TEMPLATES = [
{
'OPTIONS': {
'context_processors': [
'helusers.context_processors.settings'
]
}
}
]
If you're not allowing users to log in with passwords, you may disable the
username/password form from Django admin login page by setting HELUSERS_PASSWORD_LOGIN_DISABLED
to True
.