py-logingov-client 0.0.0__py3-none-any.whl

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"

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("=")

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}'
+            ))

logingov/oidc.py

@@ -0,0 +1,388 @@
+#!/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 secrets
+import time
+from collections import OrderedDict
+from urllib.parse import urljoin, urlencode, urlparse, parse_qsl
+
+# Imports from Third Party Modules
+import jwt
+import requests
+from jwcrypto import jwk
+
+# Local Imports
+from logingov.settings.oidc_settings import (
+    oidc_settings,
+    OIDCSettings,
+    DEFAULTS
+)
+from logingov.helpers import load_private_key, encode_left128bits
+
+# Setup
+
+# Constants
+SANDBOX_URL = 'https://idp.int.identitysandbox.gov/'
+PRODUCTION_URL = 'https://secure.login.gov/'
+CONFIG_SETTINGS_ATTRIBS = {
+    'ACR_VALUES': 'acr_values_supported',
+    'SIGNING_ALGORITHM': 'token_endpoint_auth_signing_alg_values_supported',
+    'GRANT_TYPE': 'grant_types_supported',
+    'RESPONSE_TYPE': 'response_types_supported',
+    'SCOPE': 'scopes_supported',
+}
+SPACE_SEPARATED_ATTRIBS = [
+    'ACR_VALUES',
+    'SCOPE'
+]
+
+# Data Structure Definitions
+
+# Private Functions
+
+
+# Public Classes and Functions
+class LoginGovOIDCClientError(Exception):
+    pass
+
+
+class LoginGovOIDCAuthorizationError(LoginGovOIDCClientError):
+    """Exception for errors in the Login.gov authorization response"""
+    pass
+
+
+class LoginGovOIDCRequestError(LoginGovOIDCClientError):
+    """Exception for raising errors from Login.gov API requests"""
+    pass
+
+
+class LoginGovOIDCInvalidTokenError(LoginGovOIDCClientError):
+    """
+    Exception for raising errors when Login.gov tokens are invalid
+    or cannot be decoded
+    """
+    pass
+
+
+class LoginGovOIDCConfigurationError(LoginGovOIDCClientError):
+    """
+    Exception for raising errors where the provided settings or
+    client instantiation parameters are invalid
+    """
+    pass
+
+
+class LoginGovOIDCClient(object):
+    """
+    A client for handling login.gov OIDC requests and responses.
+    The client is framework-agnostic, and can be used in any Python
+    application that needs to interact with the login.gov OIDC service.
+
+    The client does not generate state or nonce values, or provide for
+    storage of these values for use in later calls.  The calling code
+    is responsible for generating and managing these values.
+
+    Since the authorization is a redirect to the login.gov site, and the
+    response is a redirect back to the client uri, with query params,
+    the client does not handle the actual redirect. Therefore, it cannot
+    directly call for the authorization response. The calling code must
+    handle the redirect and pass the query params to the client, as a
+    dict, or query string, for token and user info requests.
+
+    Most of the client parameters are handled via settings. Settings must be
+    passed to the client on instantiation as a dict or OIDCSettings instance,
+    or may be configured within Django settings under the `LOGIN_GOV_OIDC`
+    space (assuming the calling code is a Django app and has added `logingov`
+    to the `INSTALLED_APPS`).
+    """
+
+    def __init__(self, state=None, nonce=None, locale=None,
+                 authorization_response=None, settings=None):
+        if isinstance(settings, OIDCSettings):               # pragma: no cover
+            self.settings = settings
+        else:
+            self.settings = OIDCSettings(
+                user_settings=settings, defaults=DEFAULTS
+            ) if settings else oidc_settings
+        self.settings.check_required_settings()
+
+        self.state = state
+        self.nonce = nonce
+        self.locale = locale
+        self.discovery_data = self._discovery()
+        self._validate_settings()
+        self.code = None
+        self.jti = None
+        if authorization_response:
+            if isinstance(authorization_response, str):
+                query = urlparse(authorization_response).query
+                authorization_response = OrderedDict(parse_qsl(query))
+            self._validate_authorization_response(authorization_response)
+            self.code = authorization_response.get('code')
+
+    def _get_base_url(self):
+        """
+        Get the base url for talking to the login.gov servers
+        based on the `ENVIRONMENT` setting or the `BASE_URL` setting.
+        """
+        base_url = self.settings.BASE_URL
+        env = self.settings.ENVIRONMENT
+        if base_url:
+            return base_url
+        else:
+            if env.lower().startswith('sand'):
+                return SANDBOX_URL
+            if env.lower().startswith('prod'):
+                return PRODUCTION_URL
+
+    def _discovery(self):
+        """
+        Uses the base url and DISCOVERY_ENDPOINT to get the OIDC discovery
+        data. All other endpoints are pulled from the discovery results,
+        rather than being hard-coded, or settings values, to ensure the client
+        is always using the most up-to-date login.gov information.
+        """
+        endpoint = self.settings.DISCOVERY_ENDPOINT
+        url = urljoin(self._get_base_url(), endpoint)
+        return self.get(url)
+
+    def _validate_settings(self):
+        """
+        Validates the relevant settings values against the discovery data
+        supported values.
+        """
+        invalid = []
+        for setting, config_key in CONFIG_SETTINGS_ATTRIBS.items():
+            setting_val = getattr(self.settings, setting)
+            config_val = self.discovery_data[config_key]
+            if setting in SPACE_SEPARATED_ATTRIBS:
+                setting_val = setting_val.split(' ')
+                if any([val not in config_val for val in setting_val]):
+                    invalid.append(setting)
+            elif setting_val not in config_val:
+                invalid.append(setting)
+        if invalid:
+            raise LoginGovOIDCConfigurationError(
+                f'The following "LOGIN_GOV_OIDC" settings have values '
+                f'that do not match the Login.gov supported values: '
+                f'{", ".join(invalid)}'
+            )
+
+    def _prepare_authorize_params(self):
+        """
+        Prepares the query string parameters for inclusion in the authorization
+        redirect URL based on provided settings and the client instantiation
+        values.
+        Both state and nonce are required, and should be setup and managed
+        inside the code calling the client.  The same state and nonce will be
+        needed again later to validate the authorization and token responses.
+        """
+        if not self.state or not self.nonce:
+            raise LoginGovOIDCConfigurationError(
+                'You must provide a state and nonce to the client '
+                'to prepare an authorization redirect'
+            )
+        scope = self.settings.SCOPE.split(' ')
+        if 'openid' not in scope:
+            scope.insert(0, 'openid')
+        params = {
+            'acr_values': self.settings.ACR_VALUES,
+            'client_id': self.settings.CLIENT_ID,
+            'prompt': self.settings.PROMPT,
+            'response_type': self.settings.RESPONSE_TYPE,
+            'redirect_uri': self.settings.LOGIN_REDIRECT_URI,
+            'state': self.state,
+            'nonce': self.nonce,
+        }
+        if self.locale in self.settings.ACCEPTED_LOCALES:
+            params['locale'] = self.locale
+        return f'?{urlencode(params)}&scope={"+".join(scope)}'
+
+    def _validate_authorization_response(self, auth_response):
+        """
+        Ensures the authorization response is not an error, contains a code,
+        and that the state used to generate the authorization request matches
+        the state returned in the response.
+        """
+        err = auth_response.get('error') or ''
+        if err:
+            err_desc = auth_response.get('error_description') or ''
+            err_msg = ': '.join([err, err_desc])
+            raise LoginGovOIDCAuthorizationError(err_msg)
+        if not auth_response.get('code'):
+            raise LoginGovOIDCAuthorizationError(
+                'No authorization code provided'
+            )
+        if not self.state:
+            raise LoginGovOIDCConfigurationError(
+                'You must provide the state from your authorization request '
+                'to the client to validate the authorization response.'
+            )
+        if auth_response.get('state') != self.state:
+            raise LoginGovOIDCAuthorizationError('Invalid state in response')
+
+    def _prepare_token_assertion(self):
+        """Prepares the client assertion JWT for use in the token request."""
+        self.jti = secrets.token_hex(16)
+        args = {
+            'iss': self.settings.CLIENT_ID,
+            'sub': self.settings.CLIENT_ID,
+            'aud': self.discovery_data['token_endpoint'],
+            'jti': self.jti,
+            'exp': int(time.time()) + 300,
+        }
+        if self.settings.PVT_KEY_PATH:
+            key = load_private_key(self.settings.PVT_KEY_PATH)
+        else:
+            key = self.settings.PVT_KEY_PEM
+        return jwt.encode(args, key, algorithm=self.settings.SIGNING_ALGORITHM)
+
+    def _prepare_token_params(self):
+        """Prepares the POST data for use in the token request."""
+        return {
+            'client_assertion': self._prepare_token_assertion(),
+            'client_assertion_type': self.settings.CLIENT_ASSERTION_TYPE,
+            'code': self.code,
+            'grant_type': self.settings.GRANT_TYPE,
+        }
+
+    def _login_gov_pub_keys(self):
+        """
+        Gets the login.gov public keys for use in decoding and validating
+        the token request response.
+        """
+        return self.get(self.discovery_data['jwks_uri'])['keys']
+
+    def _decoded_id_token(self, id_token):
+        """
+        Decodes the ID token using the login.gov public keys.
+        A LoginGovOIDCInvalidTokenError will be raised if the ID token cannot
+        be decoded, or the aud, iss, exp, nbf, or iat values are determined
+        to be invalid during the decoding.
+        """
+        for key in self._login_gov_pub_keys():
+            jwk_key = jwk.JWK(**key)
+            pem = jwk_key.export_to_pem().decode('utf-8')
+            try:
+                return jwt.decode(
+                    id_token, pem,
+                    algorithms=[self.settings.SIGNING_ALGORITHM],
+                    audience=[self.settings.CLIENT_ID],
+                    issuer=self.discovery_data['issuer'],
+                    leeway=2
+                )
+            except Exception:
+                continue
+        else:
+            raise LoginGovOIDCInvalidTokenError('Unable to decode ID token')
+
+    def _validated_token(self, tokens):
+        """
+        Ensures the validity of the token response.
+        Raises a LoginGovOIDCInvalidTokenError if the nonce, access token hash,
+        code hash, or any of the base JWT values are invalid.
+        """
+        if not self.nonce:
+            raise LoginGovOIDCConfigurationError(
+                'You must provide the nonce from your authorization request '
+                'to the client to validate the authorization token.'
+            )
+        id_token = self._decoded_id_token(tokens['id_token'])
+        if id_token['nonce'] != self.nonce:
+            raise LoginGovOIDCInvalidTokenError('Invalid nonce in ID token')
+        if id_token['at_hash'] != encode_left128bits(tokens['access_token']):  # pragma: no cover  # noqa
+            raise LoginGovOIDCInvalidTokenError(
+                'Invalid access token hash in ID token'
+            )
+        if id_token['c_hash'] != encode_left128bits(self.code):  # pragma: no cover  # noqa
+            raise LoginGovOIDCInvalidTokenError(
+                'Invalid code hash in ID token'
+            )
+        tokens['id_token'] = id_token
+        return tokens
+
+    @staticmethod
+    def post(url, data):
+        """
+        Sends a POST request to the provided URL with the provided data,
+        handling any error statuses as a LoginGovOIDCRequestError.
+        """
+        rsp = requests.post(url, data=data)
+        if rsp.status_code != 200:
+            raise LoginGovOIDCRequestError(
+                f'Error {rsp.status_code} from {url}: {rsp.json()["error"]}'
+            )
+        return rsp.json()
+
+    @staticmethod
+    def get(url, params=None, headers=None):
+        """
+        Sends a GET request to the provided URL with the provided params and/or
+        headers, handling any error statuses as a LoginGovOIDCRequestError.
+        """
+        rsp = requests.get(url, params=params, headers=headers)
+        if rsp.status_code != 200:
+            raise LoginGovOIDCRequestError(
+                f'Error {rsp.status_code} from {url}: {rsp.json()["error"]}'
+            )
+        return rsp.json()
+
+    @property
+    def authorize_redirect(self):
+        """Generate the login.gov authorization redirect URI."""
+        url = self.discovery_data['authorization_endpoint']
+        return urljoin(url, self._prepare_authorize_params())
+
+    @property
+    def token_response(self):
+        """
+        Request tokens from login.gov using the code from
+        the authorization login redirect.
+        """
+        if not self.code:
+            raise LoginGovOIDCConfigurationError(
+                'You must complete the Login.gov authorization and pass '
+                'the results to the client before requesting tokens '
+                'or user info.'
+            )
+        url = self.discovery_data['token_endpoint']
+        token_rsp = self.post(url, data=self._prepare_token_params())
+        return self._validated_token(token_rsp)
+
+    @property
+    def userinfo_id_token(self):
+        """
+        Request tokens and user info from login.gov using the code from
+        the authorization login redirect.
+        """
+        token_rsp = self.token_response
+        headers = {
+            'Authorization':
+                f'{token_rsp["token_type"]} {token_rsp["access_token"]}'
+        }
+        url = self.discovery_data['userinfo_endpoint']
+        return self.get(url, headers=headers), token_rsp['id_token']
+
+    @property
+    def logout_redirect(self):
+        """Generate the login.gov logout redirect URI."""
+        redirect = self.settings.LOGOUT_REDIRECT_URI
+        if not redirect:
+            raise LoginGovOIDCConfigurationError(
+                'You must configure a LOGOUT_REDIRECT_URI.'
+            )
+        params = {
+            'client_id': self.settings.CLIENT_ID,
+            'post_logout_redirect_uri': redirect
+        }
+        if self.state:
+            params['state'] = self.state
+        url = self.discovery_data['end_session_endpoint']
+        return urljoin(url, f'?{urlencode(params)}')

logingov/settings/oidc_settings.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python
+# encoding: utf-8
+"""
+copyright (c) 2024- Earth Advantage.
+All rights reserved
+..codeauthor::Fable Turas <fable@rainsoftware.tech>
+
+Settings for py-logingov-client are all namespaced in the
+LOGIN_GOV_OIDC setting.
+For example your project's `settings.py` file might look like this:
+
+LOGIN_GOV_OIDC = {
+}
+
+This module provides the `oidc_setting` object, that is used to access
+py-logingov settings, checking for user settings first, then falling
+back to the defaults."""
+
+# Imports from Standard Library
+
+# Imports from Third Party Modules
+
+# Imports from Django
+try:                                                         # pragma: no cover
+    from django.conf import settings
+    from django.core.signals import setting_changed
+except ImportError:
+    settings = None
+
+# Local Imports
+
+# Setup
+
+# Constants
+DEFAULTS = {
+    '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',
+    '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',
+    'ENVIRONMENT': 'sandbox',
+    'BASE_URL': '',
+    'ACCEPTED_LOCALES': ['es', 'fr']
+}
+REQUIRED_SETTINGS = (
+    'CLIENT_ID',
+    'LOGIN_REDIRECT_URI',
+    'SCOPE',
+    'ACR_VALUES'
+)
+ALTERNATE_REQUIRED_SETTINGS = (
+    ('PVT_KEY_PATH', 'PVT_KEY_PEM'),
+    ('ENVIRONMENT', 'BASE_URL')
+)
+# Data Structure Definitions
+
+# Private Functions
+
+
+# Public Classes and Functions
+class OIDCSettings:
+    """
+    A settings object, that allows settings to be accessed as properties.
+    For example:
+
+        from django_logingov_oidc.settings import oidc_settings
+        print(oidc_settings.DEFAULTS)
+
+    For Django usage, settings must be namespaced under
+    the `LOGIN_GOV_OIDC` name.
+    """
+
+    def __init__(self, user_settings=None, defaults=None):
+        self._user_settings = user_settings
+
+        self.defaults = defaults or DEFAULTS
+        self._registered_attrs = set()
+
+    @property
+    def user_settings(self):
+        return (
+            self._user_settings or getattr(settings, "LOGIN_GOV_OIDC", {})
+        )
+
+    def __getattr__(self, attr):
+        if attr != 'user_settings' and attr not in self.defaults:
+            raise AttributeError(f"Invalid OIDC setting: '{attr}'")
+        try:
+            val = self.user_settings[attr]
+        except KeyError:
+            val = self.defaults[attr]
+
+        self._registered_attrs.add(attr)
+        setattr(self, attr, val)
+        return val
+
+    def check_required_settings(self):
+        """Validates that all required settings are present and not empty"""
+        for setting in REQUIRED_SETTINGS:
+            setting_val = getattr(self, setting, None)
+            if setting_val in ['', None]:
+                raise ValueError(f"Setting {setting} must not be empty")
+        for keys in ALTERNATE_REQUIRED_SETTINGS:
+            vals = [
+                getattr(self, setting, None)
+                for setting in keys
+            ]
+            if not any(vals):
+                raise ValueError(
+                    f'At least one of {", ".join(keys)} must not be empty'
+                )
+
+    def reload(self):
+        """
+        Resets all registered settings to ensure prior set values are not
+        lingering when Django settings are changed.
+        """
+        for attr in self._registered_attrs:
+            delattr(self, attr)
+        self._registered_attrs.clear()
+        self._user_settings = {}
+
+
+oidc_settings = OIDCSettings(None, DEFAULTS)
+
+
+def reload_oidc_settings(setting=None, *args, **kwargs):     # pragma: no cover
+    if setting == "LOGIN_GOV_OIDC":
+        oidc_settings.reload()
+
+
+if settings:                                                 # pragma: no cover
+    setting_changed.connect(reload_oidc_settings)