Admin Guide

This guide covers how to configure and manage Safe Exam Support (SES) as an administrator.

---

Overview

SES connects your Exam Management System (EMS) to Safe Exam Browser (SEB), providing a secure exam environment for students. As an administrator, you configure the bridge between your EMS and the SES platform.

Architecture Overview

Figure 1: SES architecture — EMS → SES Proxy → SEB Client

Key Components

Component	Purpose
Admin Panel	Web interface for managing exams, sessions, and institutes
Smart Proxy	Routes SEB traffic to the correct EMS with validation
Load Balancer	Distributes traffic across multiple proxy and server instances
pgBouncer	Connection pooler for PostgreSQL
Redis	Session caching and rate limiting

---

Accessing the Admin Panel

URL

The admin panel is available at:

https://admin.example.com

Login

1. Navigate to the admin URL
2. Sign in with your administrator credentials (Azure AD/Entra SSO or local account)
3. If prompted, complete TOTP two-factor authentication

Figure 2: Admin panel login with TOTP

---

Managing Institutes

Creating an Institute

An institute represents a school or organization that uses SES.

1. Navigate to Institutes in the admin sidebar
2. Click Add institute
3. Fill in the required fields:

Field	Description	Example
Name	Institute name	"University of Amsterdam"
Institute ID	Unique identifier	"uva"
Proxy URL	Public URL for SEB clients	https://ems1.example.com

Figure 3: Adding a new institute

Institute Settings

Each institute has configurable settings:

• Rate limits: Maximum requests per second (global and per-institute)
• Session token TTL: How long exam tokens remain valid
• Cleanup delay: Minutes after exam end before sessions close

---

Managing EMS Environments

What is an EMS Environment?

An EMS (Exam Management System) environment is the backend system that hosts your exams (e.g., Moodle, Canvas, TestVision). Each EMS environment connects to a unique subdomain on SES.

Adding an EMS Environment

1. Navigate to EMS Environments in the admin sidebar
2. Click Add EMS environment
3. Configure the following:

Field	Description	Example
Name	Display name	"Production Moodle"
EMS Base URL	Backend URL of your EMS	https://moodle.biqforge.com
Public Proxy URL	Subdomain students will access	https://ems1.example.com
Institute	Associated institute	Select from dropdown

Figure 4: Adding a new EMS environment

EMS Base URL

The EMS Base URL must use HTTPS with a valid SSL certificate. SES validates the certificate chain (verify depth 2).

Subdomain Mapping

Each EMS environment gets a unique subdomain:

ems1.example.com → moodle.biqforge.com (backend)
ems2.example.com → moodle2.example.com (backend)

Students access their exams via the subdomain, and SES proxies the request to the correct EMS backend.

---

Managing Exams

Creating an Exam

1. Navigate to Exams in the admin sidebar
2. Click Add exam
3. Fill in the exam details:

Field	Description	Example
Title	Exam name	"Mathematics Final 2026"
EMS Environment	Which EMS hosts this exam	Select from dropdown
Start Date	When students can begin	2026-07-01 09:00
End Date	When the exam closes	2026-07-01 12:00
Status	Exam state	active
Cleanup Delay (min)	Grace period after end	30

Figure 5: Creating a new exam

Exam Statuses

Status	Description
draft	Not yet published, no sessions can be created
active	Live — students can start sessions
ended	Past end date — no new sessions, existing sessions close after cleanup delay

Session Pre-warming

Pre-warming allocates streaming seats before the exam starts, ensuring students can begin immediately.

Setting	Description	Default
Required Seats	Total seats needed for the exam	0
Warmup Percentage	Percentage of seats to pre-warm	80%
Pre-warm State	not_started, in_progress, completed	—

Pre-warming works in two tiers:

1. Pre-warm tier (80%): Allocated before exam start
2. On-demand tier (20%): Allocated as students arrive

Capacity Planning

Set Required Seats to the expected number of concurrent students. The pre-warm percentage ensures most seats are ready, while on-demand handles overflow.

---

Managing Sessions

Viewing Sessions

1. Navigate to Exam Sessions in the admin sidebar
2. Filter by exam, status, or institute
3. Each session shows:

Field	Description
Session ID	Unique 64-character hex identifier
State	pending, active, or closed
Exam	Associated exam
Allocated Seat	Streaming seat assigned
Created At	When the session was created
Accessed At	Last keep-alive timestamp
Closed At	When the session was closed

Figure 6: Exam sessions list view

Session Lifecycle

pending → active → closed
   │                    │
   └──(activate)──┘    └──(cleanup after end_date + delay)

Transition	Trigger
pending → active	Student loads landing page via SEB
active → closed	Exam end date + cleanup delay elapsed

Closing Sessions Manually

To close a specific session:

1. Find the session in the Exam Sessions list
2. Select the session
3. Choose Close selected sessions from the action dropdown
4. Confirm the action

Manual Close

Manually closing a session will immediately disconnect the student. Only use this for troubleshooting or security incidents.

---

Web Resources

Web resources define which URLs students can access during an exam via SEB.

Adding Permitted Resources

1. Navigate to Web Resources in the admin sidebar
2. Click Add web resource
3. Configure:

Field	Description	Example
Title	Resource name	"Formula Site"
URL	Permitted URL	https://formulas.example.com
Service ID	SEB service identifier	External URL

Figure 7: Adding a permitted web resource

---

SEB Configuration

SEB Config Generation

SES generates .seb configuration files for each exam. These files tell SEB:

• Which URL to open (the exam's start URL)
• Which resources are permitted
• Browser security settings (no screenshots, no other apps)

Never Distribute .seb Files to Students

Students download the SEB configuration automatically when they open the exam's start URL in SEB. Do not email, share via LMS, or distribute .seb files manually — this would bypass the secure start URL mechanism.

1. Navigate to SEB Configurations in the admin sidebar
2. Select the exam's SEB configuration
3. Verify the settings are correct (start URL, permitted resources, browser rules)

Figure 8: Reviewing SEB configuration

Automatic Regeneration

SEB configurations are automatically regenerated when related settings change (exam dates, resources, browser rules).

---

Monitoring

Health Checks

Endpoint	URL	Purpose
Health	/health	Returns {"status":"healthy"} if all services are up
Session Status	/api/session-status/	Validates a session (requires X-Session-ID header)

System Logs

Navigate to System Logs in the admin sidebar to view audit events:

• Session creation, activation, and closure
• Configuration changes
• Login attempts (successful and failed)

Figure 9: System audit logs

---

Rate Limiting

SES applies configurable rate limits to protect against abuse:

Setting	Description	Default
RATE_LIMIT_GLOBAL	Max requests/second across all institutes	500000
RATE_LIMIT_INSTITUTE	Max requests/second per institute	500000

To change rate limits:

1. Update the environment variable on the server
2. Restart the services: make prod-deploy

---

Security

TLS Configuration

All traffic between SEB clients and SES uses HTTPS. The proxy validates the EMS backend certificate:

SEB Client ←→ [HTTPS] ←→ SES Proxy ←→ [HTTPS verified] ←→ EMS Backend

Token Security

• Session tokens use HMAC-SHA256 signing
• Tokens have a configurable TTL (default: 8 hours)
• Tokens are validated statelessly (no database lookup required)

Audit Trail

All administrative actions are logged in the AuditLogEntry table with:

• Who made the change
• What changed (field-level diffs)
• When it changed
• Which institute was affected

Audit logs are retained for 30 days by default (AUDIT_RETENTION_DAYS).