# Django-staff-sso-client
[](https://circleci.com/gh/uktrade/django-staff-sso-client/tree/master)
[](https://codecov.io/gh/uktrade/django-staff-sso-client)
A Django client for `staff-sso`
## Requirements
[Python 3.7](https://www.python.org/downloads/release/python-370/)
[Django>=3.2](https://www.djangoproject.com/)
Version 4+ of this package drops support for Django version 2.2.
For Django versions `Django==2.2` install v3.1.1:
`pip install django-staff-sso-client==3.1.1`
Version 2+ of this package drops support for Django versions below 2.2.
For Django versions `1.11 <= Django < 2.2` install v1.0.1:
`pip install django-staff-sso-client==1.0.1`
This client assumes your app has either `raven` or `sentry_sdk` installed
[Raven Python](https://github.com/getsentry/raven-python)
[Sentry SDK](https://github.com/getsentry/sentry-python)
## Upgrade to version 3.0.0 considerations
The default ID field has been changed to `email_user_id`. Previously the `user_id` (guid) was the default field - see below for details on how to revert to `user_id` if needed.
`MIGRATE_EMAIL_USER_ON_LOGIN` logic has been removed.
## Installation
`pip install django-staff-sso-client`
## Configuration
Add the following to your settings file:
```
INSTALLED_APPS=[
[...]
'authbroker_client',
]
```
```
# authbroker config
AUTHBROKER_URL = 'speak-to-webops-team-for-access'
AUTHBROKER_CLIENT_ID = 'speak-to-webops-team-for-access'
AUTHBROKER_CLIENT_SECRET = 'speak-to-webops-team-for-access'
AUTHBROKER_STAFF_SSO_SCOPE = 'any-additional-scope-values'
AUTHBROKER_ANONYMOUS_PATHS = (Tuple/list of paths that should be unprotected)
AUTHBROKER_ANONYMOUS_URL_NAMES = (list of url names that should be unprotected)
```
Add the `'authbroker_client.backends.AuthbrokerBackend'` authentication backend, e.g:
```
AUTHENTICATION_BACKENDS = [
'django.contrib.auth.backends.ModelBackend',
'authbroker_client.backends.AuthbrokerBackend',
]
```
Add the LOGIN_URL ( it must be '/auth/login' )
```
LOGIN_URL = reverse_lazy('authbroker_client:login')
```
Add the LOGIN_REDIRECT_URL for e.g.
```
LOGIN_REDIRECT_URL = reverse_lazy('home_page')
```
Then finally add this to your main `urls.py` file:
`path('auth/', include('authbroker_client.urls'))`
or, if you're using Django<2:
`url('^auth/', include('authbroker_client.urls', namespace='authbroker', app_name='authbroker_client'))`
You should now have an `/auth/login/` URL which directs users through the `staff-sso` login flow. Once a user is
authenticated via `staff-sso` (and chosen identify provider), they will be redirected back to your application.
A local django user with a matching email address will then be logged in. The user entry will be created if it does
not already exist in the database.
Once authenticated, the user will be redirected to `settings.LOGIN_REDIRECT_URL`
Use the django `@login_required` decorator to protect individual views, or if you want to protect all views use this middleware:
```
MIDDLEWARE = [
[...]
'authbroker_client.middleware.ProtectAllViewsMiddleware',
]
```
## Change the default user id field
Staff-sso maintains two unique user ids for each user: the `email_user_id` field, which is in an email format [NOTE: it is purely a unique id, not a valid email address] and the `user_id` field, which is a GUID. By default (from version 3.0.0 onwards) django-staff-sso-client identifies users based on the `email_user_id` field. This is the preferred option for most cases. If however, you need to use the `user_id` field, then add this to your settings.py file:
```
AUTHBROKER_USE_USER_ID_GUID = True
```
When creating new users django-staff-sso-client attempts to store the user id in the `User.USERNAME_FIELD` field. With the stock django model this will be the `username` field. If you use a custom user model you can override this field as needed, for example:
```
class YourCustomUserModel(...):
USERNAME_FIELD = 'sso_email_id'
```
NOTE: As per django's documentation, the `USERNAME_FIELD` should be the user model's primary key.
## Change the user creation mapping
Here's an example staff-sso profile, which is available at the point of user creation:
```
{
'user_id': '6fa3b542-9a6f-4fc3-a248-168596572999',
'email_user_id': 'john.smith-6fa3b542@id.trade.gov.uk',
'email': 'john.smith@someplace.gov.uk',
'contact_email': 'john.smith@someemail.com',
'related_emails': [ 'jsmith@someotherplace.com',
'me@johnsmith.com'],
'first_name': 'John',
'last_name': 'Smith',
'groups': [ ... ],
'permitted_applications': [ ... ],
'access_profiles': [ ... ]
}
```
The default mapping is:
```
{
'email': profile['email'],
'first_name': profile['first_name'],
'last_name': profile['last_name'],
}
```
You can change this default mapping by subclassing the authentication backend `authbroker_client.backends.AuthbrokerBackend` and overriding the `user_create_mapping` method.
Here's an example:
```
from authbroker_client.backends import AuthbrokerBackend
class CustomAuthbrokerBackend(AuthbrokerBackend):
def user_create_mapping(self, profile):
return {
"is_active": True,
"first_name": profile["first_name"],
"last_name": profile["last_name"],
}
```
### Exclude page from SSO Auth check
In order to allow anonymous access to a page on a site protected using this client, add the following setting to your Django settings file:
```
AUTHBROKER_ANONYMOUS_PATHS = ('anonymous/path',)
```
Alternatively, you can use the `AUTHBROKER_ANONYMOUS_URL_NAMES` setting to specify a list of url names.
```
AUTHBROKER_ANONYMOUS_URL_NAMES = ('url-name',)
```
## Use with UKTrade mock-sso package
It is possible to configure this package to work with the [mock-sso service](https://github.com/uktrade/mock-sso).
Mock SSO requires that you provide a non-standard parameter in the query string of the initial GET call of the OAuth flow. (See the [mock-sso docs](https://github.com/uktrade/mock-sso/blob/master/README.md) for more detail.)
This parameter is called `code`. Any services which use THIS library (django-mock-sso-client) could need to undertake automated tests of a stack which uses Staff SSO for downstream components (example: testing an app which in return requires access to another service's API, both of which use SSO for authentication).
For circumstances like these you will need to prime mock-sso with this `code` parameter.
This is achieved by changing the Django settings for the app which is importing THIS library. In those settings, add:
```
TEST_SSO_PROVIDER_SET_RETURNED_ACCESS_TOKEN = 'someCode'
```
where 'someCode' will then be provided as the 'access token' during the OAuth callback to mock-sso. (Again, see the [mock-sso docs](https://github.com/uktrade/mock-sso/blob/master/README.md) for more detail.)
Raw data
{
"_id": null,
"home_page": "https://github.com/uktrade/django-staff-sso-client/",
"name": "django-staff-sso-client",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Department for International Trade",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/64/49/c88bfba9d626e0f061330310ef909fcb5b5a03a1cb5295627e6c8990008c/django_staff_sso_client-4.2.2.tar.gz",
"platform": null,
"description": "# Django-staff-sso-client\n\n[](https://circleci.com/gh/uktrade/django-staff-sso-client/tree/master)\n[](https://codecov.io/gh/uktrade/django-staff-sso-client)\n\n\n\n\n\nA Django client for `staff-sso`\n\n\n## Requirements\n\n[Python 3.7](https://www.python.org/downloads/release/python-370/)\n\n[Django>=3.2](https://www.djangoproject.com/)\n\nVersion 4+ of this package drops support for Django version 2.2.\n\nFor Django versions `Django==2.2` install v3.1.1:\n\n`pip install django-staff-sso-client==3.1.1`\n\nVersion 2+ of this package drops support for Django versions below 2.2.\n\nFor Django versions `1.11 <= Django < 2.2` install v1.0.1:\n\n`pip install django-staff-sso-client==1.0.1`\n\nThis client assumes your app has either `raven` or `sentry_sdk` installed\n\n[Raven Python](https://github.com/getsentry/raven-python)\n\n[Sentry SDK](https://github.com/getsentry/sentry-python)\n\n\n## Upgrade to version 3.0.0 considerations\n\nThe default ID field has been changed to `email_user_id`. Previously the `user_id` (guid) was the default field - see below for details on how to revert to `user_id` if needed.\n\n`MIGRATE_EMAIL_USER_ON_LOGIN` logic has been removed.\n\n## Installation\n\n`pip install django-staff-sso-client`\n\n## Configuration\n\nAdd the following to your settings file:\n\n```\nINSTALLED_APPS=[\n [...]\n 'authbroker_client',\n]\n```\n\n```\n# authbroker config\nAUTHBROKER_URL = 'speak-to-webops-team-for-access'\nAUTHBROKER_CLIENT_ID = 'speak-to-webops-team-for-access'\nAUTHBROKER_CLIENT_SECRET = 'speak-to-webops-team-for-access'\nAUTHBROKER_STAFF_SSO_SCOPE = 'any-additional-scope-values'\nAUTHBROKER_ANONYMOUS_PATHS = (Tuple/list of paths that should be unprotected)\nAUTHBROKER_ANONYMOUS_URL_NAMES = (list of url names that should be unprotected)\n```\n\nAdd the `'authbroker_client.backends.AuthbrokerBackend'` authentication backend, e.g:\n\n```\nAUTHENTICATION_BACKENDS = [\n 'django.contrib.auth.backends.ModelBackend',\n 'authbroker_client.backends.AuthbrokerBackend',\n]\n```\n\nAdd the LOGIN_URL ( it must be '/auth/login' )\n\n```\nLOGIN_URL = reverse_lazy('authbroker_client:login')\n```\n\nAdd the LOGIN_REDIRECT_URL for e.g.\n```\nLOGIN_REDIRECT_URL = reverse_lazy('home_page')\n```\n\nThen finally add this to your main `urls.py` file:\n\n`path('auth/', include('authbroker_client.urls'))`\n\nor, if you're using Django<2:\n\n`url('^auth/', include('authbroker_client.urls', namespace='authbroker', app_name='authbroker_client'))`\n\n\nYou should now have an `/auth/login/` URL which directs users through the `staff-sso` login flow. Once a user is\nauthenticated via `staff-sso` (and chosen identify provider), they will be redirected back to your application.\nA local django user with a matching email address will then be logged in. The user entry will be created if it does\nnot already exist in the database.\n\nOnce authenticated, the user will be redirected to `settings.LOGIN_REDIRECT_URL`\n\nUse the django `@login_required` decorator to protect individual views, or if you want to protect all views use this middleware:\n\n```\nMIDDLEWARE = [\n [...]\n 'authbroker_client.middleware.ProtectAllViewsMiddleware',\n]\n```\n\n## Change the default user id field\n\nStaff-sso maintains two unique user ids for each user: the `email_user_id` field, which is in an email format [NOTE: it is purely a unique id, not a valid email address] and the `user_id` field, which is a GUID. By default (from version 3.0.0 onwards) django-staff-sso-client identifies users based on the `email_user_id` field. This is the preferred option for most cases. If however, you need to use the `user_id` field, then add this to your settings.py file:\n\n```\nAUTHBROKER_USE_USER_ID_GUID = True\n```\n\nWhen creating new users django-staff-sso-client attempts to store the user id in the `User.USERNAME_FIELD` field. With the stock django model this will be the `username` field. If you use a custom user model you can override this field as needed, for example:\n\n```\nclass YourCustomUserModel(...):\n USERNAME_FIELD = 'sso_email_id'\n```\n\nNOTE: As per django's documentation, the `USERNAME_FIELD` should be the user model's primary key.\n\n## Change the user creation mapping\n\nHere's an example staff-sso profile, which is available at the point of user creation:\n\n```\n{\n 'user_id': '6fa3b542-9a6f-4fc3-a248-168596572999', \n 'email_user_id': 'john.smith-6fa3b542@id.trade.gov.uk', \n 'email': 'john.smith@someplace.gov.uk',\n 'contact_email': 'john.smith@someemail.com',\n 'related_emails': [ 'jsmith@someotherplace.com',\n 'me@johnsmith.com'], \n 'first_name': 'John',\n 'last_name': 'Smith', \n 'groups': [ ... ], \n 'permitted_applications': [ ... ],\n 'access_profiles': [ ... ]\n}\n```\n\nThe default mapping is:\n\n```\n{\n 'email': profile['email'],\n 'first_name': profile['first_name'],\n 'last_name': profile['last_name'],\n}\n```\n\nYou can change this default mapping by subclassing the authentication backend `authbroker_client.backends.AuthbrokerBackend` and overriding the `user_create_mapping` method.\n\nHere's an example:\n\n```\nfrom authbroker_client.backends import AuthbrokerBackend\n\n\nclass CustomAuthbrokerBackend(AuthbrokerBackend):\n def user_create_mapping(self, profile):\n return {\n \"is_active\": True,\n \"first_name\": profile[\"first_name\"],\n \"last_name\": profile[\"last_name\"],\n }\n```\n\n### Exclude page from SSO Auth check\n\nIn order to allow anonymous access to a page on a site protected using this client, add the following setting to your Django settings file:\n\n```\nAUTHBROKER_ANONYMOUS_PATHS = ('anonymous/path',)\n```\n\nAlternatively, you can use the `AUTHBROKER_ANONYMOUS_URL_NAMES` setting to specify a list of url names.\n```\nAUTHBROKER_ANONYMOUS_URL_NAMES = ('url-name',)\n```\n\n## Use with UKTrade mock-sso package\n\nIt is possible to configure this package to work with the [mock-sso service](https://github.com/uktrade/mock-sso).\n\nMock SSO requires that you provide a non-standard parameter in the query string of the initial GET call of the OAuth flow. (See the [mock-sso docs](https://github.com/uktrade/mock-sso/blob/master/README.md) for more detail.)\n\nThis parameter is called `code`. Any services which use THIS library (django-mock-sso-client) could need to undertake automated tests of a stack which uses Staff SSO for downstream components (example: testing an app which in return requires access to another service's API, both of which use SSO for authentication).\n\nFor circumstances like these you will need to prime mock-sso with this `code` parameter.\n\nThis is achieved by changing the Django settings for the app which is importing THIS library. In those settings, add:\n```\nTEST_SSO_PROVIDER_SET_RETURNED_ACCESS_TOKEN = 'someCode'\n```\nwhere 'someCode' will then be provided as the 'access token' during the OAuth callback to mock-sso. (Again, see the [mock-sso docs](https://github.com/uktrade/mock-sso/blob/master/README.md) for more detail.)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Reusable Django app to facilitate gov.uk Staff Single Sign On",
"version": "4.2.2",
"project_urls": {
"Homepage": "https://github.com/uktrade/django-staff-sso-client/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fb996ccbf1ade5f81fa514f79ec1d5190442046051833b52c04fb8930b4e8630",
"md5": "0a295f109e2eb806daaf055f0593d6bb",
"sha256": "de94952af49fd14b8b4c32a26bcf47ab6369377fb4798683ca0654cca878f817"
},
"downloads": -1,
"filename": "django_staff_sso_client-4.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0a295f109e2eb806daaf055f0593d6bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14929,
"upload_time": "2024-02-21T11:49:28",
"upload_time_iso_8601": "2024-02-21T11:49:28.623856Z",
"url": "https://files.pythonhosted.org/packages/fb/99/6ccbf1ade5f81fa514f79ec1d5190442046051833b52c04fb8930b4e8630/django_staff_sso_client-4.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6449c88bfba9d626e0f061330310ef909fcb5b5a03a1cb5295627e6c8990008c",
"md5": "12d2fa29a0e4dfaf05b8bbfdceb99e48",
"sha256": "1a36b3d740d4360b44221004156443092163277cb467b5775ba2a522345b8786"
},
"downloads": -1,
"filename": "django_staff_sso_client-4.2.2.tar.gz",
"has_sig": false,
"md5_digest": "12d2fa29a0e4dfaf05b8bbfdceb99e48",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14154,
"upload_time": "2024-02-21T11:49:29",
"upload_time_iso_8601": "2024-02-21T11:49:29.770291Z",
"url": "https://files.pythonhosted.org/packages/64/49/c88bfba9d626e0f061330310ef909fcb5b5a03a1cb5295627e6c8990008c/django_staff_sso_client-4.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-21 11:49:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "uktrade",
"github_project": "django-staff-sso-client",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"circle": true,
"lcname": "django-staff-sso-client"
}
JSON
