diff options
Diffstat (limited to 'python-django-staff-sso-client.spec')
| -rw-r--r-- | python-django-staff-sso-client.spec | 700 |
1 files changed, 700 insertions, 0 deletions
diff --git a/python-django-staff-sso-client.spec b/python-django-staff-sso-client.spec new file mode 100644 index 0000000..2fb4973 --- /dev/null +++ b/python-django-staff-sso-client.spec @@ -0,0 +1,700 @@ +%global _empty_manifest_terminate_build 0 +Name: python-django-staff-sso-client +Version: 4.1.1 +Release: 1 +Summary: Reusable Django app to facilitate gov.uk Staff Single Sign On +License: MIT +URL: https://github.com/uktrade/django-staff-sso-client/ +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/da/bb/72c4e748008683cadf89bef11211557d754ed99e20d433416fa6ff8f04a0/django_staff_sso_client-4.1.1.tar.gz +BuildArch: noarch + +Requires: python3-Django +Requires: python3-requests-oauthlib +Requires: python3-pytest +Requires: python3-pytest-cov +Requires: python3-pytest-django +Requires: python3-flake8 +Requires: python3-requests-mock +Requires: python3-codecov +Requires: python3-build +Requires: python3-twine +Requires: python3-wheel +Requires: python3-setuptools +Requires: python3-raven + +%description +# 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.) + + +%package -n python3-django-staff-sso-client +Summary: Reusable Django app to facilitate gov.uk Staff Single Sign On +Provides: python-django-staff-sso-client +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-django-staff-sso-client +# 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.) + + +%package help +Summary: Development documents and examples for django-staff-sso-client +Provides: python3-django-staff-sso-client-doc +%description help +# 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.) + + +%prep +%autosetup -n django-staff-sso-client-4.1.1 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-django-staff-sso-client -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Mon May 15 2023 Python_Bot <Python_Bot@openeuler.org> - 4.1.1-1 +- Package Spec generated |