py-logingov-client 0.0.0__tar.gz

py_logingov_client-0.0.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Earth Advantage
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

py_logingov_client-0.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE.md
+recursive-include tests/ *
+global-exclude __pycache__
+global-exclude *.py[co]

py_logingov_client-0.0.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.1
+Name: py-logingov-client
+Version: 0.0.0
+Summary: Python Implementation of Login.gov Client
+Home-page: https://github.com/Earth-Advantage/py-logingov
+Author: Fable Turas
+Author-email: fable@rainsoftware.tech
+Maintainer: Earth-Advantage
+Maintainer-email: admin@greenbuildingregistry.com
+License: BSD-3-Clause
+Keywords: login.gov,logindotgov,oidc,python,client
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+License-File: LICENSE

py_logingov_client-0.0.0/README.md

@@ -0,0 +1,219 @@
+# py-logingov
+Python client implementation for the Login.gov SSO
+
+## About
+py-logingov provides framework-agnostic support for integrating with the Login.gov SSO (currently only the OIDC protocol with private_key_jwt).
+It can be used with any Python based application that needs to authenticate users via the Login.gov SSO,
+but there are some convenience integrations for the Django framework.
+
+## Installation
+```bash
+pip install py-logingov
+```
+
+## Django Integration (optional)
+If you are using the Django framework, and wish to manage LoginGovOIDCClient settings via Django settings,
+and/or use the provided Django management command for saving a private key, from a string or env var, to a file,
+you will need to add `logingov` to your `INSTALLED_APPS` in your Django settings file and add your settings
+under the `LOGIN_GOV_OIDC` namespace (see below for more information about available settings).
+
+```python
+INSTALLED_APPS = [
+    ...
+    'logingov',
+    ...
+]
+```
+
+#### Django Management Command
+The `logingov` app provides a management command for saving a private key string to a file.
+This is useful for saving the private key to a file, in conjunction with the `PVT_KEY_PATH` setting,
+particularly when the private key is stored in an environment variable,
+as might be necessary for handling in container deployments.
+When storing a private key as and environment variable, you may find it necessary to escape the newlines in the key string. ie (`\n` -> `\\n`).
+
+```bash
+# Save private key from key argument to file
+python manage.py logingov_pk_to_file --key 'your-private-key-string'
+
+# Save private key from environment variable to file (default env var name is LOGIN_GOV_OIDC_PVT_KEY)
+# You may provide a custom environment variable name with the --env option
+python manage.py logingov_pk_to_file --env LOGIN_GOV_OIDC_PVT_KEY
+
+```
+
+## LoginGovOIDCClient Usage
+
+### Settings
+The `LoginGovOIDCClient` class requires a number of login.gov specific settings be provided,
+either from Django settings (the `LOGIN_GOV_OIDC` namespace),
+or on instantiation as a dict or instance of OIDCSettings.
+
+```python
+LOGIN_GOV_OIDC = {
+    'CLIENT_ID': '',
+    'LOGIN_REDIRECT_URI': '',
+    'LOGOUT_REDIRECT_URI': '',
+    'PVT_KEY_PATH': '',
+    'PVT_KEY_PEM': '',
+    'ACR_VALUES': 'http://idmanagement.gov/ns/assurance/ial/1',
+    'SCOPE': 'openid email',
+    'ENVIRONMENT': 'sandbox',
+    'BASE_URL': '',
+    'PROMPT': 'select_account',
+    'RESPONSE_TYPE': 'code',
+    'GRANT_TYPE': 'authorization_code',
+    'CLIENT_ASSERTION_TYPE': (
+        'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
+    ),
+    'SIGNING_ALGORITHM': 'RS256',
+    'DISCOVERY_ENDPOINT': '.well-known/openid-configuration',
+    'ACCEPTED_LOCALES': ['es', 'fr']
+}
+```
+
+#### CLIENT_ID
+The client ID registered with Login.gov for your application.
+
+#### LOGIN_REDIRECT_URI
+The URI to redirect to after a successful login. This must be registered with Login.gov.
+
+#### LOGOUT_REDIRECT_URI
+The URI to redirect to after a successful logout. Required if you wish to use the `logout_redirect` method.
+
+#### PVT_KEY_PATH
+The path to the private key file used to sign the JWT assertion. This must match with the public key registered with Login.gov.
+You must supply either this setting or `PVT_KEY_PEM`.
+
+#### PVT_KEY_PEM
+The private key as a PEM string. This must match with the public key registered with Login.gov.
+You must supply either this setting or `PVT_KEY_PATH`.
+
+#### ACR_VALUES
+A string containing a space separated list of Login.gov ACR values to specify the type of service level or AAL. Defaults to `http://idmanagement.gov/ns/assurance/ial/1`.
+See [Login.gov OIDC documentation](https://developers.login.gov/oidc/authorization) for more information.
+
+#### SCOPE
+A string containing a space separated list of the scopes being requested. Defaults to `openid email`.
+See [Login.gov OIDC documentation](https://developers.login.gov/attributes/) for more information on available scopes
+and the required IAL levels you must set as `ACR_VALUES` for your requested scopes.
+
+#### ENVIRONMENT
+The environment to use for the Login.gov OIDC base url for discovery.
+Allows the client to select from hard coded values for the login.gov sandbox or production URLs. Valid values: `sandbox`, `production`. Defaults to `sandbox`.
+Either this setting or `BASE_URL` must not be empty.
+
+#### BASE_URL
+The base URL for the Login.gov OIDC service. Either this setting or `ENVIRONMENT` must not be empty.
+Provided to allow for custom URLs in the event the Login.gov URLs change and a package update is not yet available, and for testing purposes.
+
+#### PROMPT
+Provided as a configurable setting in the event login.gov changes the required value before a package update can be released. Defaults to `select_account`.
+
+#### RESPONSE_TYPE
+Provided as a configurable setting in the event login.gov changes the required value before a package update can be released. Defaults to `code`.
+
+#### GRANT_TYPE
+Provided as a configurable setting in the event login.gov changes the required value before a package update can be released. Defaults to `authorization_code`.
+
+#### CLIENT_ASSERTION_TYPE
+Required for `private_key_jwt`. Provided as a configurable setting in the event login.gov changes the required value before a package update can be released. Defaults to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
+
+#### SIGNING_ALGORITHM
+Provided as a configurable setting in the event login.gov changes the required value before a package update can be released. Defaults to `RS256`.
+
+#### DISCOVERY_ENDPOINT
+The OIDC discovery endpoint. Provided as a configurable setting in the event login.gov changes the required value before a package update can be released. Defaults to `.well-known/openid-configuration`.
+
+#### ACCEPTED_LOCALES
+Provided as a configurable setting in the event login.gov changes the required value before a package update can be released. Defaults to `['es', 'fr']`.
+
+#### Required settings
+The following settings must not be empty: `CLIENT_ID`, `LOGIN_REDIRECT_URI`, `SCOPE`, `ACR_VALUES`.
+At least one of each set of the following settings must not be empty: `PVT_KEY_PATH` or `PVT_KEY_PEM`, `BASE_URL` or `ENVIRONMENT`.
+
+### Client Usage
+
+#### Authorization
+The LoginGovOIDCClient provides a method to generate the authorization URL for redirecting users to the Login.gov OIDC service.
+Since this is only a redirect URL, it is up to the calling code to handle the redirect at the `LOGIN_REDIRECT_URI`.
+The calling code must also handle the creation and management of the state and nonce parameters.
+These values are required by the authorization redirect and must be stored for later use in the token exchange.
+Each must be unique and at least 22 characters long.
+See the [Login.gov OIDC documentation](https://developers.login.gov/oidc/authorization) for more information.
+
+```python
+import secrets
+from logingov import LoginGovOIDCClient
+settings = {
+    'CLIENT_ID': 'your-client-id',
+    'LOGIN_REDIRECT_URI': 'your-login-redirect-uri',
+    'PVT_KEY_PATH': 'your-private-key-path',
+}
+state = secrets.token_urlsafe(16)
+nonce = secrets.token_urlsafe(16)
+client = LoginGovOIDCClient(state=state, nonce=nonce, settings=settings)
+auth_redirect_url = client.authorize_redirect
+```
+
+#### Token Exchange/User Info
+The LoginGovOIDCClient provides a method to exchange the authorization code, which is returned from login.gov
+as a query parameter in the redirect URL, for an access token and retrieve the user info.
+This method requires the authorization response and the state, and nonce from the initiating authorization redirect.
+The authorization response must be the query parameters from the redirect URL as either a dict of params
+or as a URL query string. (Hint: you may pass the entire login redirect URL to the client.)
+
+You may request the tokens independent of the user info by using the `token_response` property method,
+but it is assumed that general usage will require the user info as well.
+See the [Login.gov OIDC documentation](https://developers.login.gov/oidc/user-info) for more information 
+about the user info response and available scopes.
+
+Note that both the `userinfo_id_token` and `token_response` results include the `id_token` as the decoded JWT.
+The decoded JWT includes a `jti` claim that can be used to validate the token against replay attacks.
+The LoginGovOIDCClient does not provide a method for this validation, but it is recommended that you implement this in your application.
+
+```python
+from logingov import LoginGovOIDCClient
+
+settings = {
+    'CLIENT_ID': 'your-client-id',
+    'LOGIN_REDIRECT_URI': 'your-login-redirect-uri',
+    'PVT_KEY_PATH': 'your-private-key-path',
+}
+state = your_session_storage.state
+nonce = your_session_storage.nonce
+auth_response = 'your-login-redirect-uri?state=state-returned-from-login&code=login.gov-provided-code'
+client = LoginGovOIDCClient(state=state, nonce=nonce, settings=settings,
+                            authorization_response=auth_response)
+user_info, tokens = client.userinfo_id_token
+```
+
+#### Logout
+The LoginGovOIDCClient provides a method to generate the logout URL for redirecting users to the Login.gov OIDC service.
+You must provide a `LOGOUT_REDIRECT_URI` in the settings to use this method.
+Since this is only a redirect URL, it is up to the calling code to handle the redirect at the `LOGOUT_REDIRECT_URI`.
+The state parameter is optional for a logout redirect, but if desired,
+must be managed by the calling code, and must be unique and at least 22 characters long.
+See the [Login.gov OIDC documentation](https://developers.login.gov/oidc/logout) for more information.
+
+```python
+import secrets
+from logingov import LoginGovOIDCClient
+state = secrets.token_urlsafe(16)
+settings = {
+    'CLIENT_ID': 'your-client-id',
+    'LOGIN_REDIRECT_URI': 'your-login-redirect-uri',
+    'LOGOUT_REDIRECT_URI': 'your-logout-redirect-uri',
+    'PVT_KEY_PATH': 'your-private-key-path',
+}
+client = LoginGovOIDCClient(state=state, settings=settings)
+logout_redirect_url = client.logout_redirect
+```
+
+#### Exceptions
+The LoginGovOIDCClient may raise the following exceptions:
+- `LoginGovOIDCClientError`: Base exception for all client errors.
+- `LoginGovOIDCClientConfigError`: Raised when the client has improperly configured settings and/or instantiation params.
+- `LoginGovOIDCClientRequestError`: Raised when there is an error in the request to the Login.gov OIDC service.
+- `LoginGovOIDCAuthorizationError`: Raised when there is an error in the authorization response.
+- `LoginGovOIDCInvalidTokenError`: Raised when the id_token from login.gov is invalid or cannot be decoded.

py_logingov_client-0.0.0/logingov/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class LoginGovConfig(AppConfig):
+    name = "logingov"
+    label = "logingov"
+    verbose_name = "Login.gov authentication client"

py_logingov_client-0.0.0/logingov/helpers.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+# encoding: utf-8
+"""
+copyright (c) 2024- Earth Advantage.
+All rights reserved
+..codeauthor::Fable Turas <fable@rainsoftware.tech>
+
+"""
+
+# Imports from Standard Library
+import base64
+import hashlib
+
+# Imports from Third Party Modules
+
+# Imports from Django
+
+# Local Imports
+
+# Setup
+
+# Constants
+
+# Data Structure Definitions
+
+# Private Functions
+
+
+# Public Classes and Functions
+def load_private_key(key_path):
+    """load private key from file for encoding."""
+    with open(key_path, 'rb') as pem_in:
+        return pem_in.read()
+
+
+def encode_left128bits(string):
+    # 128 bits / 8 bits per byte = 16
+    # ref https://github.com/18F/identity-idp/blob/799fc62621a30c54e7edba17e376d94606d0c956/app/services/id_token_builder.rb#L69  # noqa
+    hashed = hashlib.sha256(string.encode("utf-8")).digest()[0:16]
+    b64 = base64.urlsafe_b64encode(hashed)
+    return b64.decode("utf-8").rstrip("=")

py_logingov_client-0.0.0/logingov/management/commands/logingov_pk_to_file.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python
+# encoding: utf-8
+"""
+copyright (c) 2023- Earth Advantage.
+All rights reserved
+..codeauthor::Fable Turas <fable@rainsoftware.tech>
+
+"""
+
+# Imports from Standard Library
+import os
+
+# Imports from Django
+from django.core.management.base import BaseCommand
+
+from logingov.settings.oidc_settings import oidc_settings
+
+# Setup
+
+# Constants
+
+# Data Structure Definitions
+
+# Private Functions
+
+
+# Public Classes and Functions
+class Command(BaseCommand):
+    help = (
+        'Write Private Key from env vars, or argument, to file'
+    )
+
+    def add_arguments(self, parser):                         # pragma: no cover
+        parser.add_argument(
+            '-k', '--key',
+            help=(
+                'Private key string, with escaped line '
+                'breaks, to write to file.'
+            )
+        )
+        parser.add_argument(
+            '-e', '--env',
+            help=(
+                'Environment variable name where private key is stored'
+            )
+        )
+
+    def handle(self, *args, **options):                      # pragma: no cover
+        pk = options['key']
+        env = options['env'] or 'LOGIN_GOV_OIDC_PVT_KEY'
+        pk = pk if pk else os.environ[env]
+        pk = pk.replace('\\n', '\n')
+        with open(oidc_settings.PVT_KEY_PATH, 'w') as file:
+            file.write(pk)
+            self.stdout.write(self.style.SUCCESS(
+                f'Successfully generated private key file '
+                f'at {oidc_settings.PVT_KEY_PATH}'
+            ))