Metadata-Version: 2.4
Name: govuk-onelogin-django
Version: 0.4.17
Summary: OpenID Connect client that works with GOV.UK One Login
Project-URL: homepage, https://github.com/uktrade/govuk-onelogin-django
Project-URL: source, https://github.com/uktrade/govuk-onelogin-django
Project-URL: releasenotes, https://github.com/uktrade/govuk-onelogin-django/releases
Project-URL: issues, https://github.com/uktrade/govuk-onelogin-django/issues
Author-email: Matthew Holmes <matthew.holmes@digital.trade.gov.uk>
Maintainer-email: Matthew Holmes <matthew.holmes@digital.trade.gov.uk>
License: MIT License
        
        Copyright (c) 2024-2026 Department for Business and Trade
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: GOV.UK One Login,OpenID Connect
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: authlib==1.7.2
Requires-Dist: django-log-formatter-asim>=1.3.0
Requires-Dist: django>=4.2
Requires-Dist: requests>=2.32.4
Description-Content-Type: text/markdown

# govuk-onelogin-django
OpenID Connect client that works with GOV.UK One Login.

Package provides the following endpoints:
- `one-login/login/` to login via GOV.UK One Login.
- `one-login/callback/` endpoint GOV.UK One Login will send logged-in users back to.
- `back-channel-logout/` endpoint GOV.UK One Login will send logout notifications to.

The example project also provides an [example logout view](example_project/example/views.py) that will log the user out of your service as well as GOV.UK One Login.

See `class ExampleLogoutView` for example that includes `post_logout_redirect_uri`

## Documentation:
- GOV.UK One Login admin tool used to create a test application: https://admin.sign-in.service.gov.uk/
- GOV.UK One Login documentation: https://www.sign-in.service.gov.uk/documentation
- GOV.UK One Login technical documentation: https://docs.sign-in.service.gov.uk/


## Quick start
Before starting, you should create an example app using the GOV.OK One Login [admin tool](https://admin.sign-in.service.gov.uk/).

1. Add "govuk_onelogin_django" to your INSTALLED_APPS setting like this:
    ```python
    INSTALLED_APPS = [
        ...,
        "govuk_onelogin_django",
    ]
    ```
2. Include the govuk_onelogin_django URLconf in your project urls.py like this:
    ```python
    path("one-login/", include("govuk_onelogin_django.urls")),
    ```
3. Include OneLoginBackend to your AUTHENTICATION_BACKENDS like this:
    ```python
    AUTHENTICATION_BACKENDS.append("govuk_onelogin_django.backends.OneLoginBackend")
    ```

4. Include the following settings in your settings.py file
    ```python
    # Required start page that includes a link to log in to GOV.UK One Login
    LOGIN_URL = "your-login-start-page"
    # A view name that the logged-in user will be redirected to after logging in via GOV.UK One Login
    LOGIN_REDIRECT_URL = "view-to-send-logged-in-users-to"

    # All other GOV.UK One Login settings required to configure govuk-onelogin-django
    GOV_UK_ONE_LOGIN_CLIENT_ID = "Your client ID"
    GOV_UK_ONE_LOGIN_CLIENT_SECRET = "Your client secret"
    GOV_UK_ONE_LOGIN_OPENID_CONFIG_URL = "Either integration or production config url."
    GOV_UK_ONE_LOGIN_SCOPE = "Required scopes"
    GOV_UK_ONE_LOGIN_AUTHENTICATION_LEVEL = "Required authentication level"
    GOV_UK_ONE_LOGIN_CONFIDENCE_LEVEL = "Required confidence level"
    ```
    **Note:** `GOV_UK_ONE_LOGIN_CLIENT_SECRET` is a base64 encoded string of your private key. e.g. `base64 -i private_key.pem`

    See [this document](https://docs.sign-in.service.gov.uk/before-integrating/set-up-your-public-and-private-keys/#set-up-your-public-and-private-keys) detailing how to generate your keys.

## Configuration
See [configuration](documentation/configuration.md) document detailing how to override the following:
- Service logout behaviour of back-channel-logout/ endpoint
- Override how GOV.UK One Login config is fetched
- how GOV_UK_ONE_LOGIN_CLIENT_ID is loaded
- How GOV_UK_ONE_LOGIN_CLIENT_SECRET is loaded

## Example project
See the example_project [README.md](example_project/README.md) for details on how to build and run the example project.


## Commands to build and test govuk-onelogin-django
- Install [uv](https://docs.astral.sh/uv/)
- Update the project's environment: `uv sync`
- Run tests using local venv: `uv run pytest`
- Running the tests against all supported python versions:
  - Install tox and tox-uv: `uv tool install tox --with tox-uv`
  - Check tox is installed: `tox --version`
  - run the tests: `tox run`
- Install pre-commit hooks: `uv run pre-commit install`
- Run pre-commit against all files: `uv run pre-commit run --all-files`

## linting / formatting
- Run the Ruff linter: `uv run ruff check`
- Resolve fixable errors: `uv run ruff check --fix`
- Run the Ruff formatter: `uv run ruff format`
- mypy: `uv run mypy --config-file=pyproject.toml`

## Publishing
- View the current project version: `uv version`
- Update the project version with dryrun: `uv version --bump minor --dry-run`
- Update the project version: `uv version --bump minor`
- Publish to PyPI: `uv publish --token <token>`
