Overview
This document outlines the authentication and session management architecture for the Party Registration application. The system is designed to provide Single Sign-On (SSO) for university members (students, staff, and admins) via SAML and a separate, credential-based login for police. All authenticated sessions are managed by a two-token model (Access and Refresh tokens).
Authentication Flows
The system supports two initial authentication methods. Upon successful authentication by either method, the flow merges into the unified two token system.
University Member Authentication: SAML SSO
The login process for all university members (students, staff, and admins) uses the university's SAML Identity Provider (IdP) as the source of truth for identity.
- Initiation: The user begins the login process from the application.
- Redirect: The system redirects the student to the Onyen sign on portal.
- Verification: The university is solely responsible for verifying the student's credentials.
- Assertion: Upon successful login, the university redirects the user back to our application with a signed SAML Assertion. This assertion contains the user's identity information (email, name, etc.).
- Token Exchange: The Next.js server securely communicates the verified user data to the application backend. This is done via a server-to-server call protected by a shared internal secret, which exchanges the proven identity for the application's internal session tokens.
- Role: Role is not provided by the IdP. It is determined by which login portal the user authenticates from. The Next.js server passes the intended role to the backend alongside the IdP data.
- Trust Model: Student login is self-provisioning — if no account exists, one is created alongside a corresponding Student record with null phone number and contact preference. Both the Account and Student records are created at SSO login; contact info is populated later by the student before their first party registration. Staff and admin login requires a matching pending invite token in the database with an email that matches the incoming SSO assertion. If no matching token is found, the backend returns 403 Forbidden. On a successful match, a fully-populated Account record is created from the IdP assertion and the invite token is deleted.
SAML Assertion Attributes
The university's IdP provides the following attributes in the SAML assertion. Of the available attributes, the system consumes first name, last name, Onyen, PID, and email.
| Description |
HTTP Header Variable |
LDAP Variable |
Consumed |
| First Name |
HTTP_GIVENNAME |
givenName |
✓ |
| Preferred First Name |
HTTP_EDUPERSONNICKNAME |
eduPersonNickname |
|
| Last Name |
HTTP_SN |
sn |
✓ |
| Preferred Last Name |
HTTP_UNCPREFERREDSURNAME |
uncPreferredSurname |
|
| Display Full Name |
HTTP_DISPLAYNAME |
displayName |
|
| Onyen |
HTTP_UID |
uid |
✓ |
| PID |
HTTP_PID |
pid |
✓ |
| Email |
HTTP_MAIL |
mail |
✓ |
| Host |
HTTP_HOST |
host |
|
| Affiliation |
HTTP_AFFILIATION |
affiliation |
|
The affiliation attribute was considered for automatically mapping users to student, staff, or admin roles, but was excluded because some users hold dual student-staff roles. Role assignment is instead managed within the application itself.
Staff/Admin Invitation Flow
Staff and admin accounts are provisioned through an invite-based flow rather than being pre-seeded by an admin.
- An OCSL admin creates an invitation from the Accounts table by providing only an email address and role (staff or admin)