django-staff-sso-client 5.2.1

Reusable Django app to facilitate gov.uk Staff Single Sign On

Django-staff-sso-client

A Django client for staff-sso

Requirements

Python 3.9

Django>=4.2

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

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',
]

For local development with https://github.com/uktrade/mock-sso, where it runs under a port 8001 as a Docker service called sso for example, add the following to your settings file.

AUTHBROKER_INTERNAL_URL = 'http://sso:8001'

For remote deployments, AUTHBROKER_INTERNAL_URL can be ommitted or equal to AUTHBROKER_URL.

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': '[e-mail]',    
    'email': '[e-mail]',
    'contact_email': '[e-mail]',
    'related_emails': [   '[e-mail]',
                          '[e-mail]'],  
    '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.

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 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 for more detail.)