django-suap-auth 1.0.1__tar.gz

django_suap_auth-1.0.1/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kelsoncm
+
+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.

django_suap_auth-1.0.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: django-suap-auth
+Version: 1.0.1
+Summary: Django OAuth2 authentication backend for SUAP (IFRN academic management system)
+Author: kelsoncm
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: Django<7,>=5.2
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-django>=4.8; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Requires-Dist: python-dotenv>=1.0; extra == "dev"
+Requires-Dist: mkdocs>=1.6; extra == "dev"
+Requires-Dist: mkdocs-material>=9.5; extra == "dev"
+Dynamic: license-file
+
+# django-suap-auth
+
+[![PyPI Version](https://img.shields.io/pypi/v/django-suap-auth)](https://pypi.org/project/django-suap-auth/)
+[![Python CI and PyPI Deploy](https://github.com/kelsoncm/django-suap-auth/actions/workflows/publish.yml/badge.svg)](https://github.com/kelsoncm/django-suap-auth/actions/workflows/publish.yml)
+[![Python Versions](https://img.shields.io/pypi/pyversions/django-suap-auth.svg)](https://pypi.org/project/django-suap-auth/)
+[![Django Versions](https://img.shields.io/badge/django-5.2%20|%206.0-blue)](https://www.djangoproject.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/kelsoncm/django-suap-auth/actions/workflows/test.yml/badge.svg)](https://github.com/kelsoncm/django-suap-auth/actions/workflows/test.yml)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![Coverage](https://codecov.io/gh/kelsoncm/django-suap-auth/branch/main/graph/badge.svg)](https://codecov.io/gh/kelsoncm/django-suap-auth)
+
+Backend de autenticação OAuth2 do Django para **SUAP** (Sistema Unificado de Administração Pública), o sistema de gestão acadêmica do [IFRN](https://www.ifrn.edu.br), hospedado em [suap.ifrn.edu.br](https://suap.ifrn.edu.br).
+
+## Instalação
+
+```bash
+pip install django-suap-auth
+```
+
+## Início Rápido
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    "django_suap_auth",
+]
+
+AUTHENTICATION_BACKENDS = [
+    "django_suap_auth.backends.SuapAuthBackend",
+    "django.contrib.auth.backends.ModelBackend",
+]
+
+SUAP_CLIENT_ID = "your-client-id"
+SUAP_CLIENT_SECRET = "your-client-secret"
+SUAP_REDIRECT_URI = "https://yourapp.example.com/auth/suap/callback/"
+SUAP_AUTH_SCOPES = ["identificacao", "email"]  # opcional
+LOGIN_REDIRECT_URL = "/dashboard/"
+LOGIN_URL = "/login/"
+```
+
+```python
+# urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    path("auth/suap/", include("django_suap_auth.urls")),
+    ...
+]
+```
+
+```html
+<!-- template -->
+<a href="{% url 'suap_auth:login' %}">Login com SUAP</a>
+```
+
+## Escopos Disponíveis
+
+| Escopo | Descrição |
+|--------|-----------|
+| `identificacao` | Identificação básica (matricula, nome, campus) |
+| `email` | Endereço de email |
+| `documentos_pessoais` | Documentos pessoais (CPF, RG) |
+| `dados_academicos` | Dados acadêmicos (curso, notas, situação) |
+| `dados_pessoais` | Dados pessoais (data de nascimento, nacionalidade) |
+| `reitoria` | Dados de nível institucional |
+
+## Documentação
+
+Documentação completa disponível no diretório [`docs/`](docs/) e nas GitHub Pages do projeto.
+
+## Licença
+
+MIT © 2026 kelsoncm

django_suap_auth-1.0.1/README.md

@@ -0,0 +1,74 @@
+# django-suap-auth
+
+[![PyPI Version](https://img.shields.io/pypi/v/django-suap-auth)](https://pypi.org/project/django-suap-auth/)
+[![Python CI and PyPI Deploy](https://github.com/kelsoncm/django-suap-auth/actions/workflows/publish.yml/badge.svg)](https://github.com/kelsoncm/django-suap-auth/actions/workflows/publish.yml)
+[![Python Versions](https://img.shields.io/pypi/pyversions/django-suap-auth.svg)](https://pypi.org/project/django-suap-auth/)
+[![Django Versions](https://img.shields.io/badge/django-5.2%20|%206.0-blue)](https://www.djangoproject.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/kelsoncm/django-suap-auth/actions/workflows/test.yml/badge.svg)](https://github.com/kelsoncm/django-suap-auth/actions/workflows/test.yml)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![Coverage](https://codecov.io/gh/kelsoncm/django-suap-auth/branch/main/graph/badge.svg)](https://codecov.io/gh/kelsoncm/django-suap-auth)
+
+Backend de autenticação OAuth2 do Django para **SUAP** (Sistema Unificado de Administração Pública), o sistema de gestão acadêmica do [IFRN](https://www.ifrn.edu.br), hospedado em [suap.ifrn.edu.br](https://suap.ifrn.edu.br).
+
+## Instalação
+
+```bash
+pip install django-suap-auth
+```
+
+## Início Rápido
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    "django_suap_auth",
+]
+
+AUTHENTICATION_BACKENDS = [
+    "django_suap_auth.backends.SuapAuthBackend",
+    "django.contrib.auth.backends.ModelBackend",
+]
+
+SUAP_CLIENT_ID = "your-client-id"
+SUAP_CLIENT_SECRET = "your-client-secret"
+SUAP_REDIRECT_URI = "https://yourapp.example.com/auth/suap/callback/"
+SUAP_AUTH_SCOPES = ["identificacao", "email"]  # opcional
+LOGIN_REDIRECT_URL = "/dashboard/"
+LOGIN_URL = "/login/"
+```
+
+```python
+# urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    path("auth/suap/", include("django_suap_auth.urls")),
+    ...
+]
+```
+
+```html
+<!-- template -->
+<a href="{% url 'suap_auth:login' %}">Login com SUAP</a>
+```
+
+## Escopos Disponíveis
+
+| Escopo | Descrição |
+|--------|-----------|
+| `identificacao` | Identificação básica (matricula, nome, campus) |
+| `email` | Endereço de email |
+| `documentos_pessoais` | Documentos pessoais (CPF, RG) |
+| `dados_academicos` | Dados acadêmicos (curso, notas, situação) |
+| `dados_pessoais` | Dados pessoais (data de nascimento, nacionalidade) |
+| `reitoria` | Dados de nível institucional |
+
+## Documentação
+
+Documentação completa disponível no diretório [`docs/`](docs/) e nas GitHub Pages do projeto.
+
+## Licença
+
+MIT © 2026 kelsoncm

django_suap_auth-1.0.1/django_suap_auth/__init__.py

@@ -0,0 +1 @@
+default_app_config = "django_suap_auth.apps.SuapAuthConfig"

django_suap_auth-1.0.1/django_suap_auth/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class SuapAuthConfig(AppConfig):
+    name = "django_suap_auth"
+    verbose_name = "SUAP Auth"

django_suap_auth-1.0.1/django_suap_auth/backends.py

@@ -0,0 +1,155 @@
+from django.contrib.auth import get_user_model
+
+from .exceptions import SuapUserNotAllowedError
+from .utils import apply_user_attr_map, get_suap_settings
+
+
+def _filter_fields(attrs, allowed):
+    """Return a subset of *attrs* restricted to *allowed* field names.
+
+    ``allowed=None`` means no restriction (return all fields).
+    ``allowed=[]`` means return an empty dict.
+    """
+    if allowed is None:
+        return dict(attrs)
+    return {k: v for k, v in attrs.items() if k in allowed}
+
+
+class SuapAuthBackend:
+    """
+    Django authentication backend for SUAP OAuth2.
+
+    Looks up or creates a Django user based on the profile info returned by SUAP.
+
+    Behaviour is controlled by ``SUAP_AUTH`` settings:
+
+    * ``CREATE_USER`` (bool, default ``True``) — when ``False``, raises
+      :exc:`~django_suap_auth.exceptions.SuapUserNotAllowedError` for users
+      that do not yet have a local account.
+    * ``USER_DEFAULTS`` (dict, default ``{"is_active": True}``) — extra
+      field values applied only when creating a new user.
+    * ``UPDATE_FIELDS_ON_CREATE`` (list or ``None``, default ``None``) —
+      mapped fields written when a new user is created.  ``None`` means all
+      mapped fields; ``[]`` means none.
+    * ``UPDATE_FIELDS_ON_LOGIN`` (list or ``None``, default ``None``) —
+      mapped fields synced on every subsequent login.  ``None`` means all
+      mapped fields; ``[]`` means none.
+    * ``FIRST_USER_DEFAULTS`` (dict or ``None``, default ``None``) — when set,
+      these field values are used instead of ``USER_DEFAULTS`` if no users
+      exist yet (e.g. ``{"is_superuser": True, "is_staff": True}``).
+
+    Override individual methods to customise behaviour without rewriting
+    ``authenticate`` entirely:
+
+    * :meth:`get_user_attrs` — map raw SUAP info to model field dict.
+    * :meth:`get_lookup_value` — extract the lookup key from mapped attrs.
+    * :meth:`get_or_create_user` — fetch or create the local user.
+    * :meth:`create_user` — instantiate and save a brand-new user.
+    * :meth:`update_user` — sync fields on an existing user.
+    """
+
+    def authenticate(self, request, suap_user_info=None, **kwargs):
+        if suap_user_info is None:
+            return None
+
+        cfg = get_suap_settings()
+        lookup_field = cfg["user_lookup_field"]
+
+        attrs = self.get_user_attrs(suap_user_info, cfg)
+        lookup_value = self.get_lookup_value(attrs, lookup_field)
+        if not lookup_value:
+            return None
+
+        mapped_attrs = {k: v for k, v in attrs.items() if k != lookup_field}
+        return self.get_or_create_user(lookup_field, lookup_value, mapped_attrs, cfg)
+
+    # ------------------------------------------------------------------
+    # Extension points
+    # ------------------------------------------------------------------
+
+    def get_user_attrs(self, suap_user_info, cfg):
+        """Return a dict of model-field → value built from *suap_user_info*.
+
+        Override to add, remove, or transform attributes before the user is
+        looked up or created.
+        """
+        attrs = apply_user_attr_map(suap_user_info, cfg["user_attr_map"])
+        if cfg["json_field"]:
+            attrs[cfg["json_field"]] = suap_user_info
+        return attrs
+
+    def get_lookup_value(self, attrs, lookup_field):
+        """Return the value used to look up the local user record.
+
+        Return ``None`` to abort authentication (backend returns ``None``).
+        """
+        return attrs.get(lookup_field)
+
+    def get_or_create_user(self, lookup_field, lookup_value, mapped_attrs, cfg):
+        """Fetch the existing user or create a new one.
+
+        Raises :exc:`~django_suap_auth.exceptions.SuapUserNotAllowedError`
+        when the user does not exist and ``CREATE_USER`` is ``False``.
+        """
+        User = get_user_model()
+        try:
+            user = User.objects.get(**{lookup_field: lookup_value})
+        except User.DoesNotExist:
+            if not cfg["create_user"]:
+                raise SuapUserNotAllowedError(
+                    f"No local account for SUAP user '{lookup_value}' and CREATE_USER is disabled."
+                )
+            return self.create_user(lookup_field, lookup_value, mapped_attrs, cfg)
+
+        return self.update_user(user, mapped_attrs, cfg)
+
+    def create_user(self, lookup_field, lookup_value, mapped_attrs, cfg):
+        """Instantiate, populate, and save a brand-new local user.
+
+        When ``FIRST_USER_DEFAULTS`` is configured and no users exist yet, those
+        defaults are used instead of ``USER_DEFAULTS``.
+
+        Override to hook into the creation process (e.g. send a welcome e-mail,
+        assign groups, etc.).
+        """
+        User = get_user_model()
+        first_defaults = cfg["first_user_defaults"]
+        if first_defaults is not None and not User.objects.exists():
+            defaults = dict(first_defaults)
+        else:
+            defaults = dict(cfg["user_defaults"])
+        defaults.update(_filter_fields(mapped_attrs, cfg["update_fields_on_create"]))
+        user = User(**{lookup_field: lookup_value}, **defaults)
+        user.save()
+        return user
+
+    def update_user(self, user, mapped_attrs, cfg):
+        """Sync *mapped_attrs* onto an existing *user* and save if changed.
+
+        Override to add custom logic on every login (e.g. update group
+        membership based on SUAP roles).
+        """
+        changed = False
+
+        for field, value in _filter_fields(mapped_attrs, cfg["update_fields_on_login"]).items():
+            if getattr(user, field, None) != value:
+                setattr(user, field, value)
+                changed = True
+
+        # Always enforce user_defaults (e.g. reactivate a deactivated account)
+        for field, value in cfg["user_defaults"].items():
+            if getattr(user, field, None) != value:
+                setattr(user, field, value)
+                changed = True
+
+        if changed:
+            user.save()
+
+        return user
+
+    def get_user(self, user_id):
+        User = get_user_model()
+        try:
+            return User.objects.get(pk=user_id)
+        except User.DoesNotExist:
+            return None

django_suap_auth-1.0.1/django_suap_auth/client.py

@@ -0,0 +1,79 @@
+from urllib.parse import urlencode
+
+import requests
+
+from .exceptions import SuapTokenError, SuapUserInfoError
+
+DEFAULT_BASE_URL = "https://suap.ifrn.edu.br"
+
+AUTHORIZE_PATH = "/o/authorize/"
+TOKEN_PATH = "/o/token/"
+USER_INFO_PATH = "/api/rh/eu/"
+
+AVAILABLE_SCOPES = [
+    "identificacao",
+    "email",
+    "documentos_pessoais",
+    "dados_academicos",
+    "dados_pessoais",
+    "reitoria",
+]
+
+
+class SuapOAuth2Client:
+    """Handles the OAuth2 authorization code flow with SUAP."""
+
+    def __init__(self, client_id, client_secret, redirect_uri, scopes=None, base_url=None):
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.redirect_uri = redirect_uri
+        self.scopes = scopes or ["identificacao", "email"]
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._session = requests.Session()
+
+    def get_authorization_url(self, state):
+        """Return the full authorization URL to redirect the user to."""
+        params = {
+            "response_type": "code",
+            "client_id": self.client_id,
+            "redirect_uri": self.redirect_uri,
+            "scope": " ".join(self.scopes),
+            "state": state,
+        }
+        return f"{self.base_url}{AUTHORIZE_PATH}?{urlencode(params)}"
+
+    def exchange_code_for_token(self, code, timeout=30):
+        """Exchange an authorization code for an access token."""
+        url = f"{self.base_url}{TOKEN_PATH}"
+        data = {
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "code": code,
+            "redirect_uri": self.redirect_uri,
+            "grant_type": "authorization_code",
+        }
+        try:
+            response = self._session.post(url, data=data, timeout=timeout)
+            response.raise_for_status()
+            return response.json()
+        except requests.HTTPError as exc:
+            raise SuapTokenError(f"Token exchange failed: {exc}") from exc
+        except requests.RequestException as exc:
+            raise SuapTokenError(f"Token exchange request error: {exc}") from exc
+        except Exception as exc:
+            raise SuapTokenError(f"Token exchange unexpected error: {exc}") from exc
+
+    def get_user_info(self, access_token, timeout=30):
+        """Fetch the authenticated user's profile from SUAP."""
+        url = f"{self.base_url}{USER_INFO_PATH}"
+        headers = {"Authorization": f"Bearer {access_token}"}
+        try:
+            response = self._session.get(url, headers=headers, timeout=timeout)
+            response.raise_for_status()
+            return response.json()
+        except requests.HTTPError as exc:
+            raise SuapUserInfoError(f"Failed to fetch user info: {exc}") from exc
+        except requests.RequestException as exc:
+            raise SuapUserInfoError(f"User info request error: {exc}") from exc
+        except Exception as exc:
+            raise SuapUserInfoError(f"User info unexpected error: {exc}") from exc

django_suap_auth-1.0.1/django_suap_auth/exceptions.py

@@ -0,0 +1,26 @@
+class SuapAuthError(Exception):
+    """Base exception for django-suap-auth."""
+
+
+class SuapTokenError(SuapAuthError):
+    """Raised when the OAuth2 token exchange fails."""
+
+
+class SuapUserInfoError(SuapAuthError):
+    """Raised when fetching user info from SUAP fails."""
+
+
+class SuapStateMismatchError(SuapAuthError):
+    """Raised when the OAuth2 state parameter does not match (possible CSRF)."""
+
+
+class SuapAPIError(SuapAuthError):
+    """Raised when a SUAP API call fails."""
+
+    def __init__(self, message, status_code=None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class SuapUserNotAllowedError(SuapAuthError):
+    """Raised when a SUAP user has no local account and CREATE_USER is False."""

django_suap_auth-1.0.1/django_suap_auth/urls.py

@@ -0,0 +1,10 @@
+from django.urls import path
+
+from .views import SuapCallbackView, SuapLoginView
+
+app_name = "suap_auth"
+
+urlpatterns = [
+    path("login/", SuapLoginView.as_view(), name="login"),
+    path("callback/", SuapCallbackView.as_view(), name="callback"),
+]

django_suap_auth-1.0.1/django_suap_auth/utils.py

@@ -0,0 +1,130 @@
+import secrets
+
+from django.core.exceptions import ImproperlyConfigured
+
+# Default mapping: user model field → SUAP response key.
+# A tuple key means "split the SUAP value on the first space and assign
+# the first part to key[0] and the remainder to key[1]".
+DEFAULT_USER_ATTR_MAP = {
+    "username": "identificacao",
+    "email": "email",
+    ("first_name", "last_name"): "nome_usual",
+}
+
+
+def get_suap_settings():
+    """Read and validate SUAP settings from Django settings.
+
+    Expects a single SUAP_AUTH dictionary with all configuration:
+
+    SUAP_AUTH = {
+        'CLIENT_ID': 'your-id',
+        'CLIENT_SECRET': 'your-secret',
+        'REDIRECT_URI': 'https://example.com/callback/',
+        'BASE_URL': 'https://suap.ifrn.edu.br',  # optional
+        'SCOPES': ['identificacao', 'email'],  # optional
+        'USER_LOOKUP_FIELD': 'username',  # optional
+        'USER_ATTR_MAP': {...},  # optional
+        'USER_JSON_FIELD': None,  # optional
+        'DIRECT_REDIRECT': True,  # optional
+    }
+    """
+    from django.conf import settings
+
+    suap_auth = getattr(settings, "SUAP_AUTH", {})
+
+    # Validate required fields
+    required = ['CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URI']
+    missing = [field for field in required if not suap_auth.get(field)]
+
+    if missing:
+        raise ImproperlyConfigured(
+            f"Missing required SUAP_AUTH settings: {', '.join(missing)}. "
+            f"Configure SUAP_AUTH dictionary in settings.py"
+        )
+
+    return {
+        "client_id": suap_auth["CLIENT_ID"],
+        "client_secret": suap_auth["CLIENT_SECRET"],
+        "redirect_uri": suap_auth["REDIRECT_URI"],
+        "scopes": suap_auth.get("SCOPES", ["identificacao", "email"]),
+        "base_url": suap_auth.get("BASE_URL", "https://suap.ifrn.edu.br"),
+        "user_lookup_field": suap_auth.get("USER_LOOKUP_FIELD", "username"),
+        "user_attr_map": suap_auth.get("USER_ATTR_MAP", DEFAULT_USER_ATTR_MAP),
+        "json_field": suap_auth.get("USER_JSON_FIELD", None),
+        "direct_redirect": suap_auth.get("DIRECT_REDIRECT", True),
+        "backend": suap_auth.get("BACKEND", "django_suap_auth.backends.SuapAuthBackend"),
+        "create_user": suap_auth.get("CREATE_USER", True),
+        "user_defaults": suap_auth.get("USER_DEFAULTS", {"is_active": True}),
+        "first_user_defaults": suap_auth.get("FIRST_USER_DEFAULTS", None),
+        # None = all mapped fields; [] = none; ["field", ...] = only those listed
+        "update_fields_on_create": suap_auth.get("UPDATE_FIELDS_ON_CREATE", None),
+        "update_fields_on_login": suap_auth.get("UPDATE_FIELDS_ON_LOGIN", None),
+    }
+
+
+def _extract_nested(data, dotted_key):
+    """Extract a value from a (possibly nested) dict using a dotted key path.
+
+    Example: _extract_nested(data, "dados_pessoais.data_nascimento")
+    """
+    keys = dotted_key.split(".")
+    value = data
+    for key in keys:
+        if not isinstance(value, dict):
+            return None
+        value = value.get(key)
+        if value is None:
+            return None
+    return value
+
+
+def apply_user_attr_map(user_info, attr_map):
+    """Translate a SUAP user_info dict into a flat dict of user model field→value pairs.
+
+    The ``attr_map`` uses the convention ``{model_field: suap_key}``:
+
+    - **Plain string key**: maps the SUAP field to the given user model field.
+    - **Tuple key** ``(field_a, field_b)``: splits the SUAP value on the first space;
+      the part before the space goes to ``field_a`` and everything after to ``field_b``.
+    - **Dotted SUAP key** (e.g. ``"dados_pessoais.data_nascimento"``): traverses nested
+      dicts in the SUAP response.
+    - Special key ``"fulljson"``: maps the entire raw SUAP response dict to the field.
+      Suitable for a ``JSONField`` or any field that accepts a dict.
+    - If the SUAP value is ``None`` or absent, the field is skipped.
+    """
+    result = {}
+    for model_field, suap_key in attr_map.items():
+        if suap_key == "fulljson":
+            result[model_field] = user_info
+            continue
+        value = _extract_nested(user_info, suap_key)
+        if value is None:
+            continue
+        if isinstance(model_field, (list, tuple)) and len(model_field) == 2:
+            field_a, field_b = model_field
+            parts = str(value).split(" ", 1)
+            result[field_a] = parts[0]
+            result[field_b] = parts[1] if len(parts) > 1 else ""
+        else:
+            result[model_field] = value
+    return result
+
+
+def get_oauth2_client():
+    """Return a SuapOAuth2Client configured from Django settings."""
+    from .client import SuapOAuth2Client
+
+    cfg = get_suap_settings()
+    return SuapOAuth2Client(
+        client_id=cfg["client_id"],
+        client_secret=cfg["client_secret"],
+        redirect_uri=cfg["redirect_uri"],
+        scopes=cfg["scopes"],
+        base_url=cfg["base_url"],
+    )
+
+
+def generate_state():
+    """Generate a cryptographically secure random state token for OAuth2 CSRF protection."""
+    return secrets.token_urlsafe(32)