feat: add partner SSO authorization and account integration

Implements partner-based SSO with automatic authentication,
account linking, and `external_user_id` automatic update.

It includes:
- A custom OAuth authorization view to handle partner SSO flows
- An SSO registration model to link local users with partner identities
- Django admin configuration for managing SSO registrations
- Test coverage for the main SSO scenarios

The authorization flow supports:
- First-time users without an SSO registration (login + registration)
- Users with an existing SSO registration (automatic authentication)
- Users with an existing registration but a different external_user_id
  (login + account link update)

Author: Tiago-Salles

nau_openedx_extensions/migrations/0010_ssopartnerintegration.py

@@ -0,0 +1,30 @@
+# Generated by Django 4.2.23 on 2025-12-11 13:23
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+import nau_openedx_extensions.custom_registration_form.models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('nau_openedx_extensions', '0009_partnerapiclient'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='SSOPartnerIntegration',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('external_user_id', models.CharField(max_length=128)),
+                ('partner_client', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='nau_openedx_extensions.partnerapiclient')),
+                ('user', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'unique_together': {('user', 'external_user_id')},
+            },
+        ),
+    ]

nau_openedx_extensions/models.py

@@ -8,4 +8,7 @@
     EnrollmentAllowedDomain,
     EnrollmentAllowedList,
 )
-from nau_openedx_extensions.partner_integration.models import PartnerAPIClient  # pylint: disable=unused-import
+from nau_openedx_extensions.partner_integration.models import (  # pylint: disable=unused-import
+    PartnerAPIClient,
+    SSOPartnerIntegration,
+)

nau_openedx_extensions/partner_integration/README.md

@@ -1,6 +1,6 @@
 # Partner Integration Module
 
-The `partner_integration` module provides secure, scalable REST APIs for partner clients to interact with LMS data. It leverages the **Facade pattern** to encapsulate data extraction logic while enforcing strict security and validation rules.
+The `partner_integration` module provides secure, scalable REST APIs for partner clients to interact with LMS data. It leverages the **Facade pattern** to encapsulate data extraction logic while enforcing strict security and validation rules. It also includes the SSO implementation, where it has the possibility of linking partner's users's account.
 
 ## Features
 
@@ -308,3 +308,152 @@ The `partner_integration` module provides:
 - **Test coverage** for all critical use cases.
 
 This module lays the foundation for future partner integrations and ensures compliance with organizational security policies.
+
+## SSO integration
+
+It classifies mainly in three states, in quick words:
+
+- A user that comes from the partner platform and has no SSO register. It redirects to login page.
+- A user that comes from the partner platform and has SSO register. It redicts to the `redirect_uri` in the url.
+- A user that comes from the partner platform and has SSO register, but with a different `external_user_id`. It redirects to login page and after authenticating it updates the `external_user_id` on the SSO register.
+
+### Important
+- All the flow respects our instance as the SSO authentication server.
+- All the features applied were created respecting the current available resources from Open Edx upstream, that is, it does not install new packages, nor uses new resources, it only implements the platform resources in a way that meets the SSO requirements. 
+
+## The key concepts
+
+#### Partner JWT
+- Issued by the partner
+- Validated by ClientJWTAuthentication
+- Identifies which partner client is calling us
+
+#### external_user_id
+- The user identifier on the partner system
+- Stored locally in SSOPartnerIntegration
+- Used as the primary lookup key during SSO
+
+#### SSOPartnerIntegration
+- This model represents “this local user is linked to this partner user”. In other words "User X in our system corresponds to external user Y from partner Z"
+
+## How it works
+
+### `Applications`
+
+The Open Edx Applications model, the one that manages the SSO applications. In this model we creates an application for each partner who wants to use our SSO integration.
+
+### `PartnerAPIClient`
+
+The model that represents each partner client that consumes our partner integration solutions (SSO and webservice).
+
+### URL format
+```bash
+http://lms.local.nau.fccn.pt/nau-openedx-extensions/partner-integration/sso/authorize/
+?client_id=wFkgI0PDXXSYkrLwC4I3pe4t7lhwmWbjScJUULW3
+&redirect_uri=https://example.com
+&jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMiIsInVzZXJuYW1lIjoiZ3RyYWluaW5nIiwiZXhwIjoxNzY3MDM3NzM5LCJpYXQiOjE3NjcwMzA1MzksImlzcyI6Imh0dHA6Ly9sbXMubG9jYWwubmF1LmZjY24ucHQvb2F1dGgyIiwiYXVkIjoib3BlbmVkeCJ9.5uf1q78l9jdKJ9n-Wu94IYPgtCRQknTCacHtjeGI0m0
+&external_user_id=123456789
+```
+#### client_id
+Setup via `Applications` model, the client id of an application register. 
+
+#### redirect_uri
+Dynamically setup, the partner changes the `redirect_uri` in order to redirect the user to the corresponding course he must to go.
+
+#### jwt_token
+Obtained via webservice authentication, the `PartnerAPIClient` uses the authentication endpoint to obtain a valid jwt token.
+`https://lms.nau.edu.pt/nau-openedx-extensions/partner-integration/auth-token/`
+
+#### external_user_id
+Dynamically setup, this is the information that identifies the user in the partner's platform, e.g. email, NIF, user_id or username. The user on our platform has no possibility to edit his register.
+
+### `SSOPartnerIntegrations`
+
+The model responsible for managing the SSO registers. Visible via Django admin.
+
+## The entry point: `CustomAuthorizationView`
+
+This view overrides the OAuth2 authorization process.
+
+### Two important overridden methods
+`dispatch()` → decision & authentication
+`get()` → final redirect handling
+
+### Methods descriptions:
+`dispatch()`: decides who the user is and what to do
+`get()`: decides where to send the user
+`handle_sso_registration()`: creates or updates the user SSO register.
+
+
+## Flow description
+1. Partner calls the endpoint
+
+The partner redirects the user’s browser to this endpoint with:
+- client_id
+- jwt_token
+- external_user_id
+
+2. Partner and application validation
+
+Inside `dispatch()`:
+- The JWT is validated
+- If invalid → redirect to default partner URL: 
+    - The OAuth Application is fetched using `client_id`
+    - If it doesn’t exist → redirect to default partner URL settings (e.g. NAU home page) 
+
+This ensures only known and active partners can use the flow.
+
+## The three scenarios
+
+### Scenario 1: User has no SSO registration
+No `SSOPartnerIntegration` exists for the given `external_user_id`:
+
+#### What we do:
+- Redirect the user to the login page
+- After login, `handle_sso_registration()` is called
+- A new `SSOPartnerIntegration` is created
+- links the local user
+- stores the `external_user_id`
+- User is redirected back to the partner callback
+
+#### Outcome:
+First-time SSO users get properly linked. From now on, future logins are seamless. This is first-time partner access.
+
+### Scenario 2: User already has an SSO registration
+
+#### A `SSOPartnerIntegration` exists for:
+- this `partner_client`
+- this `external_user_id`
+
+#### What we do:
+- Authenticate the request
+- If the user is not logged in, login programmatically
+- Continue the OAuth flow and redirect
+
+#### Outcome:
+- User is transparently logged in
+- No screens, no interaction
+- Clean SSO experience
+
+This is the success path.
+
+### Scenario 3: User exists, but `external_user_id` has changed
+
+The user already has an SSO record, but the incoming `external_user_id` is different from the stored one.
+
+#### This usually happens when:
+- Partner migrates users
+- Partner reissues accounts
+- External IDs change over time
+
+#### What we do:
+- Force the user to authenticate again
+- Update the existing SSO record with the new `external_user_id`
+- Redirect back to the partner callback
+
+#### Outcome:
+- The account link is repaired
+- No duplicate users are created
+- The system remains consistent
+
+It corrects automatically a register that has changed its main information (`external_user_id`).

nau_openedx_extensions/partner_integration/admin.py

@@ -5,7 +5,7 @@
 from django.contrib import admin
 from django.utils.crypto import get_random_string
 
-from .models import PartnerAPIClient
+from .models import PartnerAPIClient, SSOPartnerIntegration
 
 
 class PartnerAPIClientForm(forms.ModelForm):
@@ -64,3 +64,9 @@ def get_form(self, request, obj=None, change=False, **kwargs):
         if not obj:
             current_form.base_fields["password"].initial = get_random_string(64)
         return current_form
+
+
+@admin.register(SSOPartnerIntegration)
+class SSOPartnerIntegrationAdmin(admin.ModelAdmin):
+    """Admin registration for SSOPartnerIntegration model"""
+    list_display = ('partner_client', 'user', 'external_user_id')

nau_openedx_extensions/partner_integration/factories.py

@@ -1,7 +1,8 @@
 """Factory classes for Data Extractor models."""
 import factory
+from common.djangoapps.student.tests.factories import UserFactory
 
-from nau_openedx_extensions.partner_integration.models import PartnerAPIClient
+from nau_openedx_extensions.partner_integration.models import PartnerAPIClient, SSOPartnerIntegration
 
 
 class PartnerAPIClientFactory(factory.django.DjangoModelFactory):
@@ -12,3 +13,14 @@ class Meta:
 
     name = factory.Sequence(lambda n: f"partner-{n}")
     is_active = True
+
+
+class SSOPartnerIntegrationFactory(factory.django.DjangoModelFactory):
+    """Factory for SSOPartnerIntegration"""
+
+    class Meta:
+        model = SSOPartnerIntegration
+
+    partner_client = factory.SubFactory(PartnerAPIClientFactory)
+    user = factory.SubFactory(UserFactory)
+    external_user_id = factory.Sequence(lambda n: f"external-user-{n}")

nau_openedx_extensions/partner_integration/models.py

@@ -3,6 +3,7 @@
 import logging
 import uuid
 
+from django.contrib.auth import get_user_model
 from django.contrib.auth.models import AbstractBaseUser, BaseUserManager, PermissionsMixin
 from django.db import models
 
@@ -102,7 +103,7 @@ class DummyProfile:
 
     def __str__(self):
         """String representation of the PartnerAPIClient."""
-        return f"{self.name} ({self.client_id})"
+        return f"{self.name} - {self.client_id}"
 
     class Meta:
         app_label = "nau_openedx_extensions"
@@ -187,3 +188,21 @@ def check_value(field, value):
                     except BaseException as e:
                         logger.error(f"Removing invalid field {field} from scope: {e}")
                         del scope[field]
+
+
+User = get_user_model()
+
+
+class SSOPartnerIntegration(models.Model):
+    """This model registers the users with completed SSO process"""
+    partner_client = models.ForeignKey(PartnerAPIClient, on_delete=models.CASCADE, null=False)
+    user = models.OneToOneField(User, on_delete=models.CASCADE, null=False)
+    external_user_id = models.CharField(max_length=128, null=False, blank=False)
+
+    class Meta:
+        app_label = "nau_openedx_extensions"
+        unique_together = ('user', 'external_user_id',)
+
+    def __str__(self):
+        """String representation of the SSOPartnerIntegration."""
+        return f"{self.partner_client.name} - {self.user.username} ({self.external_user_id})"

nau_openedx_extensions/partner_integration/oauth_authentication.py

@@ -32,33 +32,41 @@ def authenticate(self, request):
         """
         Authenticate a client using JWT from Authorization header or cookies.
         """
-        raw_token = self.get_token_from_request(request)
-        if raw_token is None:
-            raise exceptions.AuthenticationFailed("Missing token")
+        try:
+            raw_token = self.get_token_from_request(request)
+            if raw_token is None:
+                raise exceptions.AuthenticationFailed("Missing token")
+
+            client = self.validate_token_data_and_return_client(raw_token)
+            request.partner_client = client
 
-        token_data = self.get_validated_token(raw_token)
-        client_id = token_data.get("user_id")
+            return (AnonymousUser(), raw_token)
+        except Exception as e:
+            raise e
 
+    def validate_token_data_and_return_client(self, token):
+        """this method decodes the token and returns the `PartnerAPIClient`"""
         try:
+            token_data = self.decode_token(token)
+            client_id = token_data.get("user_id")
             client = PartnerAPIClient.objects.get(id=client_id, is_active=True)
+            return client
         except PartnerAPIClient.DoesNotExist as e:
             logger.error("ClientJWTAuthentication: Invalid client ID provided in token.")
             raise exceptions.AuthenticationFailed("Invalid client") from e
-
-        request.partner_client = client
-
-        return (AnonymousUser(), raw_token)
+        except Exception as e:
+            raise e
 
     @classmethod
-    def get_validated_token(cls, raw_token):
+    def decode_token(cls, raw_token):
         """
         Decode JWT and validate using Open edX configured handler.
         """
         try:
             payload = cls.jwt_decode_token(raw_token)
         except Exception as e:
-            logger.error("ClientJWTAuthentication: Invalid token provided.")
-            raise exceptions.AuthenticationFailed(f"Invalid token: {e}")
+            logger.error("ClientJWTAuthentication: Invalid token provided.", exc_info=e)
+            raise exceptions.AuthenticationFailed("Invalid token, renew the authentication and try again.")
 
         return payload