SAML Integration Guide

Overview

This guide explains how SAML (Security Assertion Markup Language) authentication works in ProctorU, including user matching logic and various user scenarios for seamless single sign-on integration.

SAML Attribute Mapping

Required Fields

The following ProctorU fields are required for SAML integration:

Optional Fields

These fields can be included but are not mandatory:

Attribute Mapping Example

We can map the name of the attribute coming from your IDP to the field in our system.

So for example, if the SAML assertion looked like the following:

Sample:

{
  "name_id": "m43534534tdfsgspfgew6545",
  "audiences": [
    "https://go.proctoru.com/auth/saml/XXXXXX/metadata"
  ],
  "email": [
    "student@meazurelearning.com"
  ],
  "last-name": [
    "Smith"
  ],
  "first-name": [
    "Joe"
  ],
  "student_id": [
    "4345345435"
  ]
}

Then in our system, we'd map those SAML attributes to the ProctorU fields:

ProctorU Field Mapping:

The SAML Attribute format can vary based on the format sent from your IDP. For Email Address for example, we could map it as email, Email, email-address, email_address, etc. 

Role Assignment Details

The Role field is optional and controls user permissions in ProctorU.

Role Assignment Rules:

If Role field is not configured:

• New users default to student role upon account creation

If user already exists:

• Their existing role persists regardless of SAML role value

If Role field is configured for new users:

• ✅ SAML role matches configured student role → user created as student
• ✅ SAML role matches configured instructor role → user created as instructor
• ❌ SAML role doesn't match either configured role → user defaults to student

Note: Institution Admin roles cannot be automatically assigned through SAML. After a user is created, they can be manually promoted to Institution Admin, and this role will be maintained on future logins.

User Matching Logic

When a user attempts to log in via SAML, ProctorU follows this sequence:

1. Primary Match

🔍 Search for user with matching External Identifier (student_id)

2. Secondary Match

🔍 If no external identifier match found, search for user with matching Email Address

3. Account Linking

🔗 If no matches found, present account linking options

4. Email Update

📧 If external identifier matches but email differs, update the email address

User Login Scenarios

Scenario 1: Existing User - External Identifier Match

User Profile: John Doe has been using ProctorU with student_id "12345" and email "john.doe@university.edu"

SAML Response:

• student_id: "12345"
• Email: "john.doe@university.edu"
• FirstName: "John"
• LastName: "Doe"

System Behavior:

• ✅ Seamless login (external identifier match)
• ✅ No additional steps required

Scenario 2: Existing User - Email Address Change

User Profile: Sarah Smith has student_id "67890" but changed her email from "sarah.smith@oldschool.edu" to "s.smith@newschool.edu"

SAML Response:

• student_id: "67890"
• Email: "s.smith@newschool.edu"
• FirstName: "Sarah"
• LastName: "Smith"

System Behavior:

• ✅ Seamless login (external identifier match)
• 📧 Email automatically updated to "s.smith@newschool.edu"

Scenario 3: Existing User - Email Match Only

User Profile: Mike Johnson exists in ProctorU with email "mike.johnson@college.edu" but no external identifier

SAML Response:

• student_id: "11111"
• Email: "mike.johnson@college.edu"
• FirstName: "Mike"
• LastName: "Johnson"

System Behavior:

• ✅ Seamless login (email match)
• 🔗 External identifier "11111" added to existing account

Scenario 4: New User - No Matches

User Profile: New student Lisa Brown attempts first login

SAML Response:

• student_id: "22222"
• Email: "lisa.brown@university.edu"
• FirstName: "Lisa"
• LastName: "Brown"

System Behavior:

• ❓ Present linking options:
  • Link to Existing Account: User can provide credentials to link SAML identity to existing account
  • Create New Account: System creates new account with SAML attributes

SAML Setup Process

Initial Configuration

1. Metadata URL: Add the URL provided from Meazure Learning to your identity provider configuration:

   It will look something like this https://go.proctoru.com/auth/saml/XXX/metadata
   

2. Upload Metadata: Provide your metadata URL or metadata XML file to ProctorU support

User Login Options

Direct SSO Link (Recommended)

ProctorU can provide a direct SSO link that:

• ✅ Automatically selects your institution
• ✅ Redirects directly to your identity provider
• ✅ Returns users to ProctorU after authentication

Example Direct SSO URL:

https://go.proctoru.com/session/new?sso_identity_provider_id=c7826b53-b690-491e-8a80-7976cffeecc9

Note: The example URL above is for a test institution using Keycloak as the identity provider.

Standard Login Flow

1. Users visit: https://go.proctoru.com/session/new
2. Click "Login with single-sign-on"
3. Select institution from dropdown
4. Redirect to identity provider → authenticate → redirect back to ProctorU

Simplified Login Flow

Direct users to: https://go.proctoru.com/session/sso

• Bypasses initial "login with single sign-on" step
• Users land directly on institution selection page

API Integration with SAML

When using ProctorU APIs (AddAdhoc, AddBlueBird, or editStudent), SAML-enabled accounts receive special handling:

• ✅ Authentication URLs provided in API responses
• ✅ SSO links instead of standard URLs when SAML is configured
• ✅ Seamless identity provider authentication maintained

Support and Next Steps

For SAML configuration assistance:

• Contact: ProctorU Technical Support to talk with our solutions team