Integration of Safe Exam Browser into Exam Solutions

SEB integration into learning management systems (LMS) and other exam solutions has the following objectives:

  1. Make sure a quiz can only be taken using Safe Exam Browser, display an error message if trying to open the quiz in another web browser.
  2. Check if legitimate SEB settings and the correct version of SEB are used.
  3. Quit SEB (and/or unlock the device) automatically after the exam was submitted.
  4. Facilitate starting SEB with the correct settings for the exam.
  5. Don't display any links inside an exam which would allow to navigate to other sections of the LMS or even other websites. 

Below we’ll discuss possible solutions to achieve these objectives and provide links to detailed specifications for the according solutions.

1.   Make sure a quiz can only be taken using Safe Exam Browser

There are basically three different possible ways to achieve this:

  1. In your exam solution, check for the string “SEB” in the user agent reported by the web browser.
    This is the classic check for SEB, which is used in the built-in Safe Exam Browser requirements in the LMS Moodle and ILIAS. We don’t recommend this SEB check, it is very easy to trick, as most web browsers allow in a more or less easy way to modify the user agent.
  2. Use a custom user agent string (or suffix) in your SEB settings and check if this string is sent back from the browser in your exam solution.
    If properly implemented, this is significantly more secure. SEB settings (configuration files) can be encrypted using an exam (settings) password or a X.509 certificate + key, which can be installed in the secure key store (Windows Certificate Store or macOS/iOS Keychain) of the exam devices. So it wouldn’t be easy to find out the individual user agent, given that the internet connection from SEB to the exam system is properly secured (use https, don’t allow to navigate to other web servers in SEB while the settings using the individual user agent string are active).
    To use an individual user agent string, the following SEB setting keys can be used:
    • In newer SEB versions (starting Windows 2.2, macOS 2.1.3, iOS 2.1.12): browserUserAgent (suffix string which is appended to the current user agent)
    • In older SEB versions: browserUserAgentMacCustom, browserUserAgentWinDesktopModeCustom, browserUserAgentWinTouchModeCustom (replaces current browser user agent completely, only SEB/<version number> is appended).
  3. Use the request header check for one of the keys generated by SEB and sent to the exam system, see 2.

2.   Check if legitimate SEB settings and the correct version of SEB are used

SEB allows to individually configure your exam environment, for example allowing specific resources to be used for some exams, configure URL filters or even use permitted third party applications. So it is important to make sure a specific exam is accessed in SEB with the according correct settings. The easiest (but also least secure) way how to achieve that legitimate SEB settings for a specific exam are used, would be to keep the URL of that exam strictly secret:

  • Make sure the exam can only be accessed using a complex URL containing a randomly generated one-time-login query string valid only for that one single exam, taken at one specific moment in time only and simultaneously by all examinees. If you need to repeat the exam or examinees to take it in batches, you would need to use a different URL for each repetition or batch.
  • Use strictly (!) only https with fully trusted certificates (in addition you could use the certificate pinning feature of SEB).
  • Use this exam URL strictly only as the Start URL parameter in properly encrypted SEB configuration files. Never let anyone use the URL with another browser than SEB (to keep it really secret, in regular browsers it would show up in browsing history and caches).
  • Use SEB config files stored on a server (saved with the option “use for starting an exam” and not “for configuring a client”). Use server-side technology to make sure the exam config file is only accessible at the time of the exam (not before). 
  • On unmanaged student devices (BYOD), use a settings password which is unique per exam and communicate this password directly before the exam starts and only to students sitting in the exam hall (they should not be able to communicate to people outside the exam hall at this moment). Of course you need proctors/invigilators in your exam hall.
  • Use server-side technology in your exam system to make sure that the exam cannot be started in SEB and then continued in another, regular browser (using session cookies, preventing that the IP address of the connected client can change during the exam etc.).

If you strictly follow these rules, then no one should be able to access the exam with another browser than SEB and with different settings, because they cannot find out the URL without decrypting the exam config file in SEB (containing those legit settings). 

As mentioned this method isn’t the safest. One reason for that is that you really need to strictly follow the security measures mentioned above. You would need to create a workflow to follow those security measures with acceptable effort for the exam administrator. Also in BYOD scenarios on student desktop OS computers risks of manipulating the installed SEB version are higher, therefore we recommend one of the more secure methods described below.

Exam administrators might want to make sure that only some specific SEB versions are used to access exams, for example only the newest official SEB version with the latest security patches. To achieve this, SEB can generate special key strings and send these (encrypted) to the exam system. The exam system can then verify if such a key matches the key which was entered by the exam administrator when setting up the exam or if it matches the key generated for the exam settings used for a particular exam. 

Current SEB versions are using the Browser Exam Key (BEK), which as its name suggests is used to ensure that:

  • the right version of Safe Exam Browser (SEB) is used to complete the exam;
  • the SEB exam client is correctly configured/secured for this specific exam. 

Exam administrators can copy the Browser Exam Key hash value which is displayed in the SEB Config Tool or Preferences window in the Exam tab and paste it to the Exam/quiz settings inside of an e-assessment system which supports SEB. Whenever any of the setting options in SEB are changed, the BEK also changes. Therefore, you should first configure SEB appropriately, then save those settings as a config file and then copy-paste the BEK.

In current (Windows/macOS) versions of SEB, the Browser Exam Key is different for each build version of SEB. Whenever you want students to use a new release of SEB, you have to load the settings used for that exam into the according new SEB version and copy-paste the new BEK to your exam system. Therefore all integrations for SEB using the BEK have to allow to enter several Browser Exam Keys. If you support several SEB versions, you need to copy-paste all required keys to your exam settings. This also applies to SEB versions for different platforms. SEB Config Files are compatible and usually you would only use one config for all platforms. But when using the BEK check, 

  • you need to save the config file in one SEB version,
  • then load the same config file in each SEB version on each platform you want to support and copy-paste each different BEK. In this step it is essential to not save the SEB Config File again, as that usually would alter the BEK for all other versions.

For the Browser Exam Key to be secure, it is essential that it cannot easily be generated outside of the SEB application, that’s why you need to copy-paste it from each SEB version. This can be inconvenient if you create many exam configurations. If you don’t need to change SEB settings for every exam, then you could also use a general config file which uses a general link (for the SEB Start URL setting) and then forwards to the current exam or displays an exam portal page where students select the exam they are supposed to take. This would decrease the efforts for generating config files and copy-pasting its Browser Exam Keys.

You can find more information about how to implement support for the Browser Exam Key in the specification PDF document.

Upcoming SEB versions will support two additional hash keys, which will help to overcome those disadvantages of the Browser Exam Key. The first of these new keys, the Config Key, is currently implemented in SEB for macOS.

3.   Quit SEB (and/or unlock the device) automatically after the exam was submitted

While an exam is running, examinees should not be able to leave SEB. Only after finishing/submitting the exam, students should be allowed to end the kiosk mode and quit SEB. At the same time, exam supporters must be able to quit SEB anytime in case of a technical problem. How to achieve this:

  • The exam administrator defines a quit password when setting up an exam in SEB. Only exam supporters know that quit password and can exit SEB manually if necessary (using the quit button in the SEB task bar or Ctrl/Cmd + Q). 
  • You could define a unique quit password for each exam and communicate this password to students as soon as the time for the exam is over. 
  • Another, easier way of ending the lock down of an exam device and quit SEB is the Quit Link functionality: In SEB settings, you define an arbitrary Quit URL. Then you place a hyperlink with this exact same URL on the page which is displayed after the exam was submitted. This can usually be the feedback page, which in most systems allows to display a customized message text including a hyperlink. You could use a text similar to “Unlock device” or “Quit exam session” for this link.
  • You set the address of the page displayed after the exam was submitted as Quit URL in SEB’s settings. Then examinees don’t have to click any additional link, SEB will quit as soon as it detects that address being loaded (you should disable the SEB setting option “Confirm quitting” for the Quit Link feature in this case).
  • You can also build in an automated/timed “end exam” feature into your exam solution: Just invoke a redirect to the Quit URL from your server at the time you want to unlock the exam devices. This prevents students using other applications on their devices in case some of them submit the exam ahead of the scheduled exam duration.

4.   Facilitate starting SEB with the correct settings for the exam

If you want to use different settings for each exam, then it might not be feasible to create those manually. The best option would be to integrate automatic creation of SEB exam settings into your exam solution. We have general specifications for the SEB Config File format (including encryption) and the supported setting keys. As you can see there, SEB configuration files are basically XML files with key/value pairs, following the Apple plist (property list) format. They can also be converted to JSON directly (with the exception of binary data values which must be converted to strings with base64 encrypted data first). There would be several possible levels of supporting SEB Config Files:

  1. Support only plain text (unencrypted) SEB files. This is the method easiest to implement, but you will have to make sure that only the correct, unmodified config is being used for an exam, by placing it on an authenticated server and providing it only to users which are allowed to access the exam (candidates taking the exam) and just at the time of the exam start. You should also use the Browser Exam Key (or the new Config Key) which will basically provide a checksum of the correct exam settings to verify in your exam system that those correct settings are being used by SEB clients.
  2. Implement support for password encrypted SEB Config Files. SEB uses the RNCryptor framework to encrypt and decrypt SEB Config Files using an exam (settings) password. This framework is available for various platforms (macOS, iOS, .NET Windows, Java, PHP etc.), see the specification document for details.
  3. If you want to prevent that examinees have to enter an SEB exam password for encrypted configuration files, you would need to implement encryption for exam settings using a X.509 certificate plus provide them with a SEB client config file to deploy this certificate to their devices ahead of the exam. See the specification document for details and this presentation which explains how to configure SEB in various scenarios.

There are several ways how to open those SEB Config Files to either start an exam with the contained settings or to configure SEB clients:

  • By double clicking the file (from Windows File Explorer or the Finder), then SEB is started, decrypts (if necessary) and reads the file. The contained settings determine how SEB will proceed (changing client settings, opening the predefined Start URL etc.). This method usually is only used when clients and exams are manually operated.
  • By downloading a SEB Config File in SEB or another web browser and opening it from there. If SEB is configured accordingly, it will directly download and open a file with the file name extension .seb. Other browsers might ask if the downloaded file should be just saved or also opened with an application. Usually the browser should suggest Safe Exam Browser as it has been registered in the operating system for the .seb file type. Other web browsers just show that a file was downloaded and users have to open it from the downloads list/menu or open it manually from the downloads directory. This method has the disadvantage that some users might be confused how to exactly open the SEB Config File. The advantage is that downloading config files works also from web servers which require users to authenticate. The preferred method described below works with authenticated servers only in specific SEB versions.
  • By clicking (loading) a special hyperlink with the custom URL protocol scheme seb/sebs. The link should contain the address of a SEB Config File. The advantage of using a custom URL protocol is that other browsers and basically all applications which can open URLs will start SEB and open the link there, similar like opening a .seb file with SEB. But using a SEB Config Link doesn’t require to download and save the SEB Config File to the local file system. SEB itself will just load the configuration temporarily into memory, when it’s ment to start an exam. The process is also smoother with this method, applications usually just ask if it’s ok to open the link in SEB. As mentioned before, opening SEB Config Links which direct to a SEB Config File saved on a web server which requires authentication works only in specific SEB versions, currently in SEB for macOS 2.1.1 and newer and SEB for Windows 2.2. In the latter there is currently the limitation that loading a configuration file on an authenticated server works only when opening a seb/sebs link from within SEB, not from another browser/application. But otherwise  the link doesn’t even have to contain the config file name with extension .seb, it can also be an indirect link similar to mylms.com/file.php?id=34. 

The information in this section and the linked documents should allow you to implement directly starting your exams with correct settings in SEB.

5.   Don’t display any navigation links which allow to exit from the exam

This point should be obvious, but especially when using quiz modules in widely customizable open source learning management systems like Moodle, you still might want to make sure that there are no links inside an exam which would allow to navigate to other sections of the LMS or even other websites. In the case of an LMS for example course navigation, link to the user's profile, logout, link to the University homepage (maybe inside a logo) etc. need to be disabled/hidden. Only the quiz navigation (to navigate to other questions) and the button or link to submit an exam should be visible.

This part should be be done inside the exam system. Alternatively a URL filter could to be defined in SEB settings to only allow access to the exam.