seb open edx documentation
TRANSCRIPT
SEB Open edX documentationeduNEXT
2 What is Open edX? 5
3 What is this plugin? 7
4 Getting started 9
5 Table of Content 11 5.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.1.1 Docker Devstack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.1.2 Native Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.1.3 Other Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2 Usage and configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.2.1 Plugin Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.2.2 Key Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.2.3 Access Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.2.4 Advanced usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.3 Connection with the SEB Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.3.1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.3.2 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6 Project Background 31
7 Implementation notes 33
Contents 1
2 Contents
CHAPTER 1
What is Safe Exam Browser (SEB)?
Safe Exam Browser (SEB) is an application to carry out e-assessments safely. The freeware application is available for Windows, macOS and iOS. It turns any computer temporarily into a secure workstation. It controls access to resources like system functions, other websites and applications and prevents unauthorized resources being used during an exam. Safe Exam Browser can work with Open edX to control what a student can access during a Open edX quiz attempt. With the SEB Open edX plugin you activate the SEB support in Open edX and now only students using an approved version of SEB and the correct settings will be able to access the quiz in your Open edX course. The Safe Exam Browser is offered under a Mozilla Public License and supported by the SEB Consortium.
4 Chapter 1. What is Safe Exam Browser (SEB)?
CHAPTER 2
What is Open edX?
Open edX is the massively scalable learning software platform behind edX
6 Chapter 2. What is Open edX?
CHAPTER 3
What is this plugin?
The SEB Open edX plugin is an extension to the Open edX platform to add support for the Safe Exam Browser.
8 Chapter 3. What is this plugin?
CHAPTER 4
Getting started
You can find the documentation in the main project website.
10 Chapter 4. Getting started
CHAPTER 5
5.1 Installation
To install the SEB Open edX plugin in an Open edX instance you need to complete 3 steps.
• Use pip to install the plugin into the same virtualenv that has all the dependencies for edxapp (edx-platform)
• Include seb_openedx.middleware.SecureExamBrowserMiddleware into the list of Middleware Classes for the django application.
• Run the database migrations needed for the User Banning feature
We will go into detail on how to achieve this for the two more common ways of running Open edX.
5.1.1 Docker Devstack
The devstack install based on docker is a very popular way of launching a development environment of the Open edX services. If you are running this environment then follow this steps.
1. First step is to get the code and install it.
In the directory where you created your devstack you also have now a src directory. You can download the code there.
cd src sudo mkdir edxapp sudo chown $USER edxapp/ cd edxapp git clone https://github.com/eduNEXT/seb-openedx.git
Now we need to install it in the virtualenv.
cd ../../devstack docker-compose exec lms bash -c 'source /edx/app/edxapp/edxapp_env && cd / →edx/src/edxapp/seb-openedx && pip install -e .'
(continues on next page)
(continued from previous page)
Or more interactively if you prefer
Note: If you already ran the previous instructions you can skip ahead to the second step.
cd ../../devstack make lms-shell cd /edx/src/edxapp/seb-openedx/ pip install -e . exit make lms-restart
Note: It is not required for development but we do recommended to install in studio as well.
make studio-shell cd /edx/src/edxapp/seb-openedx/ pip install -e . exit make studio-restart
Note: We are running the installation in editable mode (-e). When developing or testing, if you make any changes to the code, the server should restart automatically. This will happen if you checkout different tags or branches of the code as well. To see the server restart in action you can see the logs using
docker logs edx.devstack.lms -f
make lms-restart
2. Add the seb_opened middleware to the lms and studio.
So far we have installed the plugin. You can already see if the installation was successful by navigat- ing to http://localhost:18000/seb-openedx/seb-info after login as a superuser. You will see the exact version of the plugin you have installed along with the git commit ID
Now, in order for the plugin to function properly, and be able to control the interactions with the Safe Exam Browser, you need to include the middleware.
We recommend to do that through the EXTRA_MIDDLEWARE_CLASSES configuration setting.
In versions up to the open-release/ironwood of the codebase:
12 Chapter 5. Table of Content
docker-compose exec lms bash -c "sed -i -e 's/\"EXTRA_MIDDLEWARE_ →CLASSES\": \[\]/\"EXTRA_MIDDLEWARE_CLASSES\": \[\"seb_openedx. →middleware.SecureExamBrowserMiddleware\"\]/g' /edx/app/edxapp/ →lms.env.json" docker-compose exec studio bash -c "sed -i -e 's/\"EXTRA_ →MIDDLEWARE_CLASSES\": \[\]/\"EXTRA_MIDDLEWARE_CLASSES\": \[\"seb_ →openedx.middleware.SecureExamBrowserMiddleware\"\]/g' /edx/app/ →edxapp/cms.env.json" make lms-restart && make studio-restart
Or as always, you can do it interactively
For the lms
For studio
make studio-shell vi ../cms.env.json # edit the file by adding "seb_openedx.middleware. →SecureExamBrowserMiddleware" # into the EXTRA_MIDDLEWARE_CLASSES array. exit make studio-restart
Note: In versions starting from to the open-release/juniper of the codebase the lms.env.json or cms.env.json file have been moved to /edx/etc/lms.yml and /edx/etc/studio.yml
3. Run the database migrations
To run the database migration in the devstack environment
make lms-update-db
Running migrations: Applying seb_openedx.0001_initial... OK
Note: The database is shared between lms and studio so you only need to migrate once for both applications.
4. Commit the docker image
Since this is a docker based environment, once you run make down, all your temporary changes will be gone. This includes the installation we just made.
If you want to preserve your changes across installations, then you need to commit your docker image.
5.1. Installation 13
SEB Open edX documentation, Release 1.0
(a) Make lms image work for studio. We will use a single image to start both the lms and studio containers. This means we need to add the seb_openedx middleware to the cms.env.json as well.
docker-compose exec lms bash -c "sed -i -e 's/\"EXTRA_MIDDLEWARE_CLASSES\ →": \[\]/\"EXTRA_MIDDLEWARE_CLASSES\": \[\"seb_openedx.middleware. →SecureExamBrowserMiddleware\"\]/g' /edx/app/edxapp/cms.env.json"
(a) Now we want to commit the current container to an docker image.
docker container ls | grep edx.devstack.lms
The result will be a line describing the current container filtered by the name edx.devstack.lms. Something similar to:
<CONTAINER_ID> edxops/edxapp:master "bash -c 'source /ed..." 5 →minutes ago Up 5 minutes 0.0.0.0:18000->18000/tcp, 0.0.0. →0:19876->19876/tcp, 18010/tcp edx.devstack.lms
Then we use that container ID to commit the container into a named image.
docker commit <CONTAINER_ID> edxops/edxapp_seb
Finally, we need to edit the docker-compose.yml file to use the new image. This is out of the container, so use your favorite editor to modify it.
Where it normally says:
...
(continued from previous page)
...
Note: If you want to go back to a version of the platform that does not have the openedx_seb plugin installed, you only need to remove the changes to docker-compose.yml and restart the environment.
You can also commit the changes into the edxops/edxapp:latest image. This will however affect all your environments.
Upgrading existing code
To upgrade the current running version of the plugin, you need to obtain the correct version of the source code and then restart the lms. This example is done from the outside of the container but you can work from the container shell as well.
1. Use git to pull the version that you want
cd src/edxapp/seb-openedx git fetch origin
# Checkout tag 1.1.0 on branch 'branch_v1_1_0' git checkout -b branch_v1_1_0 tags/v1.1.0
2. Restart the lms
Since we installed it in the editable mode with the -e flag, there is no need to re-install. A simple restart will do.
cd ../../devstack
make lms-restart
5.1.2 Native Installation
The native environment is regarded as a base ubuntu 16.04 server where the ansible playbooks from the configuration repository where run.
Using ansible
If you use ansible to create or update your instance of the Open edX project, then most likely you have a serve-vars.yml directory or you have some form of secure data repository.
To install the SEB Open edX plugin in there you need to change some ansible variables and re-run your installation playbooks.
5.1. Installation 15
EDXAPP_EXTRA_REQUIREMENTS: # SEB Plugin
EDXAPP_EXTRA_MIDDLEWARE_CLASSES: - 'seb_openedx.middleware.SecureExamBrowserMiddleware
If you want to check that your installation was successful you need to verify:
• The /edx/app/edxapp/lms.env.json file must include the seb_openedx middleware in EXTRA_MIDDLEWARE_CLASSES.
• The /edx/app/edxapp/cms.env.json file must include the seb_openedx middleware in EXTRA_MIDDLEWARE_CLASSES.
• /edx/bin/pip.edxapp list| grep seb must return the correct version of seb.
Or you can:
Navigate to https://<yourdomain>/seb-openedx/seb-info as a superuser and you will see the info on your browser.
Note: Some site operators prefer not to run database migration during the playbook runs. If this is you, then please run the migrations manually.
/edx/bin/edxapp-migrate-lms
Installing manually
To run the installation without the help of any script you still need to run the same basic steps.
1. Install the code
2. Activate the middleware
3. Restart the services
16 Chapter 5. Table of Content
/edx/bin/edxapp-migrate-lms
Upgrading existing code
Upgrading the existing code on an already running installation is exactly the same as installing from scratch.
For ansible managed installations this means running the installation scripts again, but make sure you have upgraded the version on the EDXAPP_EXTRA_REQUIREMENTS variable.
EDXAPP_EXTRA_REQUIREMENTS: # SEB Plugin
- name: 'git+https://github.com/edunext/seb-openedx.git@<NEW_VERSION_TAG>#egg=seb- →openedx==<NEW_VERSION>'
For manually managed installations install again with the same steps as before and restart the processes.
1. Install the new code
sudo su edxapp -s /bin/bash /edx/bin/pip.edxapp install git+https://github.com/edunext/seb-openedx. →git@<NEW_VERSION_TAG>#egg=seb-openedx==<NEW_VERSION>
2. Restart the services
/edx/bin/supervisorctl restart all
As before, you can navigate to https://<yourdomain>/seb-openedx/seb-info as a superuser to find the exact version that is running on the platform.
5.1.3 Other Distributions
Being open source, there are a lot of ways of installing the Open edX platform. This document will not pretend to list them all. We do want to give you the information you need to install this plugin in your environment.
1. Install the code
Run pip install git+https://github.com/edunext/seb-openedx.git@v1. 0.0#egg=seb-openedx==1.0.0 in the same virtualenv, or with the same user and permissions you used when installing all the dependencies of the edx-platform repository.
2. Activate the middleware
You can do so by altering the EXTRA_MIDDLEWARE_CLASSES setting.
You can also add it directly into the MIDDLEWARE_CLASSES key in the lms.envs.common.py & cms.envs.common.py module. Whichever method works best for your use case.
3. Restart the services
After installing the SEB Open edX plugin and adding the middleware you always need to restart your processes.
4. Run the database migrations
This is necessary to create the tables that store the user banning. Running the migrations is obligatory. Do so with any available methods from your distribution of Open edX.
5.1. Installation 17
5.2 Usage and configuration
The SEB Open edX plugin is a very flexible plugin and most of its options can be configured.
5.2.1 Plugin Settings
The first thing than can be configured is the plugin itself. For this, the plugin works together with the Open edX platform so that the global settings can be defined in the same way every other property in the platform is.
Both for Native or for Devstack environments there is a set of files lms.env.json, cms.env.json, that allow the instance administrators to change the global settings of the plugin.
If you want to modify any of this settings, you need to add a new key inside of the json files for the lms and cms and restart the server.
Example:
to globally modify the available permissions you would modify the SEB_PERMISSION_COMPONENTS
{ ... "SEB_PERMISSION_COMPONENTS": [
] ...
}
If you are using ansible and the configuration project, then you want to modify the EDXAPP_LMS_ENV_EXTRA and EDXAPP_CMS_ENV_EXTRA variables.
The same change done in ansible:
EDXAPP_LMS_ENV_EXTRA: ... SEB_PERMISSION_COMPONENTS:
Variables
This is the list of variables that you can alter globally
• SEB_PERMISSION_COMPONENTS Default: ['AlwaysAllowStaff', 'CheckSEBHashBrowserExamKeyOrConfigKey']
List of permission classes for the project. If one of the enabled classes grants access, the user will have access to the course. Can be modified on a per-course basis.
• SEB_KEY_SOURCES Default: ['from_global_settings', 'from_other_course_settings', 'from_django_model', 'from_site_configuration']
List of locations where the course settings will be read from.
18 Chapter 5. Table of Content
• SEB_KEY_DESTINATIONS Default: ['to_django_model', 'to_other_course_settings', 'to_site_configuration']
List of locations where the course settings will be stored to.
• SEB_USER_BANNING_BACKEND Default: 'DatabaseBannedUsersBackend'
The user banning backend will determine where the status of banning for a course-user pair is stored. The only available backend in this version is the database backend.
• SEB_USER_BANNING_ENABLED Default: False
Global feature toggle for the user banning feature. Can be modified on a per-course basis.
• SEB_UPDATE_MODULESTORE Default: 'seb_openedx.edxapp_wrapper.backends. get_course_module_h_v1'
This setting controls the backend implementation for the update module wrapper. Defaults to the hawthorn compatible implementation.
• SEB_COURSE_MODULE Default: 'seb_openedx.edxapp_wrapper.backends. get_course_module_h_v1'
This setting controls the backend implementation for the course_module wrapper. Defaults to the hawthorn compatible implementation.
• SEB_COURSEWARE_MODULE Default: 'seb_openedx.edxapp_wrapper.backends. get_courseware_module_h_v1'
• SEB_COURSEWARE_INDEX_VIEW Default: 'seb_openedx.edxapp_wrapper.backends. get_courseware_index_view_h_v1'
• SEB_GET_CHAPTER_FROM_LOCATION Default: 'seb_openedx.edxapp_wrapper. backends.get_chapter_from_location_h_v1
This setting controls the backend implementation for the chapter locator wrapper. Defaults to the hawthorn compatible implementation.
• SEB_CONFIGURATION_HELPERS Default: 'seb_openedx.edxapp_wrapper.backends. get_configuration_helpers_h_v1'
• SEB_EDXMAKO_MODULE Default: 'seb_openedx.edxapp_wrapper.backends. edxmako_module_h_v1'
This setting controls the backend implementation for the mako renderer wrapper. Defaults to the hawthorn compatible implementation.
5.2.2 Key Hashes
One of the properties of the Safe Exam Browser is that it can send a HTTP header with every request, to inform the server of the current configuration for the browser.
This headers are of two distinct types. The Safe Browser Key and the Config Key. The SEB Open edX plugin supports both types of keys.
5.2. Usage and configuration 19
SEB Open edX documentation, Release 1.0
For more advanced information about the keys, you can refer to the official SEB documentation. We will only mention that the keys are viable at the Browser settings under the Exam tab. This exact keys are what you need to copy at the BROWSER_KEYS and CONFIG_KEYS lists on the Access Settings configuration.
5.2.3 Access Settings
The idea with the Safe Exam Browser is to control the access from students in the course to the course itself. To configure this you need to let the Open edX server know what requirements for access you will impose on the course.
This is done on a per-course basis and can be modified in 3 different locations as configured in the SEB_KEY_SOURCES variable.
1. Global settings from_global_setting
As before for the global settings, you can add a key SAFE_EXAM_BROWSER to the lms.env.
20 Chapter 5. Table of Content
SEB Open edX documentation, Release 1.0
json file and inside of it, a dictionary with objects containing the <course_id> and configura- tions.
Here is an example of setting restrictions on two different courses at the same time. The course course-v1:seb-openedx+course_1+2019 uses the simple list notation and the course-v1:seb-openedx+course_2+2019 uses a more advanced notation with more set- tings.
"SAFE_EXAM_BROWSER":{ "course-v1:seb-openedx+course_1+2019":[
2. Advanced studio settings from_other_course_settings
The other course settings is a new field in the Studio Advanced configurations that is available short after the Hawthorn release was cut. It can be backported to Hawthorn easily, but officially it is only available starting at the Ironwood release.
5.2. Usage and configuration 21
SEB Open edX documentation, Release 1.0
In this json field you can add the SAFE_EXAM_BROWSER key and inside of it the configurations for this course.
You could optionally use the course key as well
3. Site Configuration in the admin from_site_configuration
On the site configurations you can add a key SAFE_EXAM_BROWSER to the site values and inside of it, a dictionary with objects containing the <course_id> and configurations. Very similar to the from_global_settings.
Here is an example with the same configuration as before:
22 Chapter 5. Table of Content
SEB Open edX documentation, Release 1.0
Note: The site configuration module uses a cache to improve the read performance for succesive reads. Unlike other caches in the platform that use memcached, this is a local thread cache that is implemented in the django-crud package.
When you change values in the site configuration object, the easiest way to break the cache is to do a process restart.
make lms-restart
Add the settings using a line break between them.
5.2. Usage and configuration 23
SEB Open edX documentation, Release 1.0
Note: It is required to run the migrations.
5.2.4 Advanced usage
The basic usage of the SEB Open edX plugin grants or denies access to a complete course. This means that every page of the course will be blocked for access without the configured Safe Exam Browser.
More advanced users can make use of the Path Whitelisting and Chapter Blacklisting options to provide a more flexible approach.
Path Whitelisting
As we mentioned before, the default of a course requiring a given SEB Key for access is to be completely blocked. Now, some pages of the course might not require such a restriction. For those you can grant access even without the Safe Exam Browser by using the WHITELIST_PATHS list.
24 Chapter 5. Table of Content
SEB Open edX documentation, Release 1.0
"course-v1:seb-openedx+course_1+2019": { "BROWSER_KEYS":[ "cd8827e4555e4eef82........5088a4bd5c9887f32e590" ], "CONFIG_KEYS":[ "9887f32e590cd8827e........5088a4bd5c4555e4eef82" ], "WHITELIST_PATHS": ["wiki", "about"]
}
This will grant access to the course wiki and the external course about page even without the special browser or configurations.
Some important paths that can be whitelisted are:
• "about"
• "course-outline"
• "courseware"
• "discussion"
• "progress"
• "wiki"
Chapter Blacklisting
In the previous section we mentioned that "courseware" can be whitelisted. This would grant a user complete access to the course content thus defeating the purpose of the SEB Open edX plugin. For this the Chapter Blacklisting allows you to mark specific chapters for secure access.
Here it is worth noting that the naming convention is used differently in the user visible pages and in the code.
Code
Both the Code and the OLX or Open Learning XML use a hierarchy composed of course > chapter > sequential > vertical. This is the convention used for development here.
Studio
On Studio, the exact same hierarchy is composed of course > section > subsection > unit.
This means that a chapter is the same a a section and a sequential the same as a subsection.
Example:
}
You will find the ID of the chapter in the URL
5.2. Usage and configuration 25
https://courses.yourdomain.com/courses/course-v1:seb-openedx+course_1+2019/courseware/ →e87b8744ea3949989f8aa113ad428515/10ddf7ff3a0a4e2f80c8838528e8c93e/1
Which means your chapter ID is e87b8744ea3949989f8aa113ad428515.
As always you can use a list of IDs for multiple chapters.
Note: Currently only chapters are supported for blacklisting. Support for sections or verticals might come in the future.
User Banning
The user banning feature allows the administrator of a course to permanently ban a user from access if the user has attempted to access with a different browser of an incorrectly configured SEB.
This feature is by default turned off, but can be turned on either on the global Plugin Settings with the SEB_USER_BANNING_ENABLED key or per course on the Access Settings using the USER_BANNING_ENABLED key.
When a user has been banned, a message will appear on the page saying that the user is banned and that the teacher or systems administrator can assist them.
26 Chapter 5. Table of Content
SEB Open edX documentation, Release 1.0
When this happens, a staff member can unlock the user by navigating to the seb-openedx dashboard.
It is located at: https://courses.yourdomain.com/seb-openedx/dashboard/
5.2. Usage and configuration 27
5.3.1 Summary
The SEB Server is a web application that is external both to the Safe Exam Browser and the Open edX server. It’s purpose is to make operation of courses restricted by the Safe Exam Browser easier.
5.3.2 API
The API for manipulating the Browser Keys (BEK) and Config Keys (CK) is a RESTful API over http. It uses Json as the payload format.
The API has one resource, namely the Course SEB Configuration. This resource is located at:
https://courses.yourdomain.com/seb-openedx/api/v1/course/<COURSE_ID>/ configuration/
Methods
The API has the usual available methods to read, update, create and delete SEB Configurations.
GET
}
If the internal representation of the configuration uses the simple format (list of mixed SEB and CK keys), the API will render the detailed representation.
It the course_id does not have a SEB configuration then a 404 error will be returned.
POST
Issuing a POST request to https://courses.yourdomain.com/seb-openedx/api/v1/course/ <COURSE_ID>/configuration/ will create a new configuration for the give COURSE_ID. If the resource already exists the API will return a 422 ‘unable to process request’ error.
The payload data must be a json object that contains a valid configuration as detailed on the usage section. Otherwise a http 400 error will be returned.
The list of keys for the json object must include either a BEK or CK list, but may also include optionally:
28 Chapter 5. Table of Content
• BROWSER_KEYS: List of valid BEK.
• CONFIG_KEYS: List of valid CK.
• WHITELIST_PATHS: List of whitelisted course paths that do not require SEB for access.
• BLACKLIST_CHAPTERS: List of chapters that do require a valid SEB for access when courseware was whitelisted.
• SEB_PERMISSION_COMPONENTS: Ordered list of permission components.
• USER_BANNING_ENABLED: Boolean that determines the state of the user banning feature for the course.
PUT
Issuing a PUT request is very similar to a POST request, but in this case the object will be updated. If the object does not exist, then it will be created. Calling put is an idempotent operation.
PATCH
The API allows the use of the PATCH request to issue a partial update. This case is similar to a PUT request, but with all the fields being optional
DELETE
Sending a DELETE request to https://courses.yourdomain.com/seb-openedx/api/v1/course/ <COURSE_ID>/configuration/ will delete the SEB configuration for the course in question.
Note: The API can alter the information stored at the django model, site configuration and other_course_settings in studio. However the information stored in the global_settings is out of reach for the python process serving the API and therefore not deletable. Editing is valid since the configuration stored in the other sources will override the global_settings.
Authentication
The API uses the standard mechanisms for authenticating APIs in the Open edX platform. This means that both OAuth2 or Session-based authentication are available. In any mechanism of authentication, the permissions will be given only for global staff users. This means that the session or the user-account linked to the Oauth2 token must have the is_staff flag set.
Storage internals
When available, the API will try to store the configuration in the django model, then in the other_course_settings field that is available in Studio. When this is not possible, then it will defer to use the site_configuration object. The precedence of the storage locations for the API can be configured via the SEB_KEY_DESTINATIONS django setting. See ‘Variables‘_.
5.3. Connection with the SEB Server 29
SEB Open edX documentation, Release 1.0
30 Chapter 5. Table of Content
CHAPTER 6
Project Background
This project was build thanks to the contributions of the ETH Zürich, the Safe Exam Browser Open Source project and the Swiss Mooc Service. It is currently build and maintained by eduNEXT.
32 Chapter 6. Project Background
CHAPTER 7
Implementation notes
• Uses the Open edX plugin architecture
• This plugin can be installed in versions of the project starting at the Hawthorn open release (Released in June 2018) and requires no modifications to the core source code of the edx-platform repository. Support for the Hawthorn version is guaranteed and it should as well work with newer versions.
33
What is Open edX?
What is this plugin?
Summary
API
2 What is Open edX? 5
3 What is this plugin? 7
4 Getting started 9
5 Table of Content 11 5.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.1.1 Docker Devstack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.1.2 Native Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.1.3 Other Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2 Usage and configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.2.1 Plugin Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.2.2 Key Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.2.3 Access Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.2.4 Advanced usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.3 Connection with the SEB Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.3.1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.3.2 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6 Project Background 31
7 Implementation notes 33
Contents 1
2 Contents
CHAPTER 1
What is Safe Exam Browser (SEB)?
Safe Exam Browser (SEB) is an application to carry out e-assessments safely. The freeware application is available for Windows, macOS and iOS. It turns any computer temporarily into a secure workstation. It controls access to resources like system functions, other websites and applications and prevents unauthorized resources being used during an exam. Safe Exam Browser can work with Open edX to control what a student can access during a Open edX quiz attempt. With the SEB Open edX plugin you activate the SEB support in Open edX and now only students using an approved version of SEB and the correct settings will be able to access the quiz in your Open edX course. The Safe Exam Browser is offered under a Mozilla Public License and supported by the SEB Consortium.
4 Chapter 1. What is Safe Exam Browser (SEB)?
CHAPTER 2
What is Open edX?
Open edX is the massively scalable learning software platform behind edX
6 Chapter 2. What is Open edX?
CHAPTER 3
What is this plugin?
The SEB Open edX plugin is an extension to the Open edX platform to add support for the Safe Exam Browser.
8 Chapter 3. What is this plugin?
CHAPTER 4
Getting started
You can find the documentation in the main project website.
10 Chapter 4. Getting started
CHAPTER 5
5.1 Installation
To install the SEB Open edX plugin in an Open edX instance you need to complete 3 steps.
• Use pip to install the plugin into the same virtualenv that has all the dependencies for edxapp (edx-platform)
• Include seb_openedx.middleware.SecureExamBrowserMiddleware into the list of Middleware Classes for the django application.
• Run the database migrations needed for the User Banning feature
We will go into detail on how to achieve this for the two more common ways of running Open edX.
5.1.1 Docker Devstack
The devstack install based on docker is a very popular way of launching a development environment of the Open edX services. If you are running this environment then follow this steps.
1. First step is to get the code and install it.
In the directory where you created your devstack you also have now a src directory. You can download the code there.
cd src sudo mkdir edxapp sudo chown $USER edxapp/ cd edxapp git clone https://github.com/eduNEXT/seb-openedx.git
Now we need to install it in the virtualenv.
cd ../../devstack docker-compose exec lms bash -c 'source /edx/app/edxapp/edxapp_env && cd / →edx/src/edxapp/seb-openedx && pip install -e .'
(continues on next page)
(continued from previous page)
Or more interactively if you prefer
Note: If you already ran the previous instructions you can skip ahead to the second step.
cd ../../devstack make lms-shell cd /edx/src/edxapp/seb-openedx/ pip install -e . exit make lms-restart
Note: It is not required for development but we do recommended to install in studio as well.
make studio-shell cd /edx/src/edxapp/seb-openedx/ pip install -e . exit make studio-restart
Note: We are running the installation in editable mode (-e). When developing or testing, if you make any changes to the code, the server should restart automatically. This will happen if you checkout different tags or branches of the code as well. To see the server restart in action you can see the logs using
docker logs edx.devstack.lms -f
make lms-restart
2. Add the seb_opened middleware to the lms and studio.
So far we have installed the plugin. You can already see if the installation was successful by navigat- ing to http://localhost:18000/seb-openedx/seb-info after login as a superuser. You will see the exact version of the plugin you have installed along with the git commit ID
Now, in order for the plugin to function properly, and be able to control the interactions with the Safe Exam Browser, you need to include the middleware.
We recommend to do that through the EXTRA_MIDDLEWARE_CLASSES configuration setting.
In versions up to the open-release/ironwood of the codebase:
12 Chapter 5. Table of Content
docker-compose exec lms bash -c "sed -i -e 's/\"EXTRA_MIDDLEWARE_ →CLASSES\": \[\]/\"EXTRA_MIDDLEWARE_CLASSES\": \[\"seb_openedx. →middleware.SecureExamBrowserMiddleware\"\]/g' /edx/app/edxapp/ →lms.env.json" docker-compose exec studio bash -c "sed -i -e 's/\"EXTRA_ →MIDDLEWARE_CLASSES\": \[\]/\"EXTRA_MIDDLEWARE_CLASSES\": \[\"seb_ →openedx.middleware.SecureExamBrowserMiddleware\"\]/g' /edx/app/ →edxapp/cms.env.json" make lms-restart && make studio-restart
Or as always, you can do it interactively
For the lms
For studio
make studio-shell vi ../cms.env.json # edit the file by adding "seb_openedx.middleware. →SecureExamBrowserMiddleware" # into the EXTRA_MIDDLEWARE_CLASSES array. exit make studio-restart
Note: In versions starting from to the open-release/juniper of the codebase the lms.env.json or cms.env.json file have been moved to /edx/etc/lms.yml and /edx/etc/studio.yml
3. Run the database migrations
To run the database migration in the devstack environment
make lms-update-db
Running migrations: Applying seb_openedx.0001_initial... OK
Note: The database is shared between lms and studio so you only need to migrate once for both applications.
4. Commit the docker image
Since this is a docker based environment, once you run make down, all your temporary changes will be gone. This includes the installation we just made.
If you want to preserve your changes across installations, then you need to commit your docker image.
5.1. Installation 13
SEB Open edX documentation, Release 1.0
(a) Make lms image work for studio. We will use a single image to start both the lms and studio containers. This means we need to add the seb_openedx middleware to the cms.env.json as well.
docker-compose exec lms bash -c "sed -i -e 's/\"EXTRA_MIDDLEWARE_CLASSES\ →": \[\]/\"EXTRA_MIDDLEWARE_CLASSES\": \[\"seb_openedx.middleware. →SecureExamBrowserMiddleware\"\]/g' /edx/app/edxapp/cms.env.json"
(a) Now we want to commit the current container to an docker image.
docker container ls | grep edx.devstack.lms
The result will be a line describing the current container filtered by the name edx.devstack.lms. Something similar to:
<CONTAINER_ID> edxops/edxapp:master "bash -c 'source /ed..." 5 →minutes ago Up 5 minutes 0.0.0.0:18000->18000/tcp, 0.0.0. →0:19876->19876/tcp, 18010/tcp edx.devstack.lms
Then we use that container ID to commit the container into a named image.
docker commit <CONTAINER_ID> edxops/edxapp_seb
Finally, we need to edit the docker-compose.yml file to use the new image. This is out of the container, so use your favorite editor to modify it.
Where it normally says:
...
(continued from previous page)
...
Note: If you want to go back to a version of the platform that does not have the openedx_seb plugin installed, you only need to remove the changes to docker-compose.yml and restart the environment.
You can also commit the changes into the edxops/edxapp:latest image. This will however affect all your environments.
Upgrading existing code
To upgrade the current running version of the plugin, you need to obtain the correct version of the source code and then restart the lms. This example is done from the outside of the container but you can work from the container shell as well.
1. Use git to pull the version that you want
cd src/edxapp/seb-openedx git fetch origin
# Checkout tag 1.1.0 on branch 'branch_v1_1_0' git checkout -b branch_v1_1_0 tags/v1.1.0
2. Restart the lms
Since we installed it in the editable mode with the -e flag, there is no need to re-install. A simple restart will do.
cd ../../devstack
make lms-restart
5.1.2 Native Installation
The native environment is regarded as a base ubuntu 16.04 server where the ansible playbooks from the configuration repository where run.
Using ansible
If you use ansible to create or update your instance of the Open edX project, then most likely you have a serve-vars.yml directory or you have some form of secure data repository.
To install the SEB Open edX plugin in there you need to change some ansible variables and re-run your installation playbooks.
5.1. Installation 15
EDXAPP_EXTRA_REQUIREMENTS: # SEB Plugin
EDXAPP_EXTRA_MIDDLEWARE_CLASSES: - 'seb_openedx.middleware.SecureExamBrowserMiddleware
If you want to check that your installation was successful you need to verify:
• The /edx/app/edxapp/lms.env.json file must include the seb_openedx middleware in EXTRA_MIDDLEWARE_CLASSES.
• The /edx/app/edxapp/cms.env.json file must include the seb_openedx middleware in EXTRA_MIDDLEWARE_CLASSES.
• /edx/bin/pip.edxapp list| grep seb must return the correct version of seb.
Or you can:
Navigate to https://<yourdomain>/seb-openedx/seb-info as a superuser and you will see the info on your browser.
Note: Some site operators prefer not to run database migration during the playbook runs. If this is you, then please run the migrations manually.
/edx/bin/edxapp-migrate-lms
Installing manually
To run the installation without the help of any script you still need to run the same basic steps.
1. Install the code
2. Activate the middleware
3. Restart the services
16 Chapter 5. Table of Content
/edx/bin/edxapp-migrate-lms
Upgrading existing code
Upgrading the existing code on an already running installation is exactly the same as installing from scratch.
For ansible managed installations this means running the installation scripts again, but make sure you have upgraded the version on the EDXAPP_EXTRA_REQUIREMENTS variable.
EDXAPP_EXTRA_REQUIREMENTS: # SEB Plugin
- name: 'git+https://github.com/edunext/seb-openedx.git@<NEW_VERSION_TAG>#egg=seb- →openedx==<NEW_VERSION>'
For manually managed installations install again with the same steps as before and restart the processes.
1. Install the new code
sudo su edxapp -s /bin/bash /edx/bin/pip.edxapp install git+https://github.com/edunext/seb-openedx. →git@<NEW_VERSION_TAG>#egg=seb-openedx==<NEW_VERSION>
2. Restart the services
/edx/bin/supervisorctl restart all
As before, you can navigate to https://<yourdomain>/seb-openedx/seb-info as a superuser to find the exact version that is running on the platform.
5.1.3 Other Distributions
Being open source, there are a lot of ways of installing the Open edX platform. This document will not pretend to list them all. We do want to give you the information you need to install this plugin in your environment.
1. Install the code
Run pip install git+https://github.com/edunext/seb-openedx.git@v1. 0.0#egg=seb-openedx==1.0.0 in the same virtualenv, or with the same user and permissions you used when installing all the dependencies of the edx-platform repository.
2. Activate the middleware
You can do so by altering the EXTRA_MIDDLEWARE_CLASSES setting.
You can also add it directly into the MIDDLEWARE_CLASSES key in the lms.envs.common.py & cms.envs.common.py module. Whichever method works best for your use case.
3. Restart the services
After installing the SEB Open edX plugin and adding the middleware you always need to restart your processes.
4. Run the database migrations
This is necessary to create the tables that store the user banning. Running the migrations is obligatory. Do so with any available methods from your distribution of Open edX.
5.1. Installation 17
5.2 Usage and configuration
The SEB Open edX plugin is a very flexible plugin and most of its options can be configured.
5.2.1 Plugin Settings
The first thing than can be configured is the plugin itself. For this, the plugin works together with the Open edX platform so that the global settings can be defined in the same way every other property in the platform is.
Both for Native or for Devstack environments there is a set of files lms.env.json, cms.env.json, that allow the instance administrators to change the global settings of the plugin.
If you want to modify any of this settings, you need to add a new key inside of the json files for the lms and cms and restart the server.
Example:
to globally modify the available permissions you would modify the SEB_PERMISSION_COMPONENTS
{ ... "SEB_PERMISSION_COMPONENTS": [
] ...
}
If you are using ansible and the configuration project, then you want to modify the EDXAPP_LMS_ENV_EXTRA and EDXAPP_CMS_ENV_EXTRA variables.
The same change done in ansible:
EDXAPP_LMS_ENV_EXTRA: ... SEB_PERMISSION_COMPONENTS:
Variables
This is the list of variables that you can alter globally
• SEB_PERMISSION_COMPONENTS Default: ['AlwaysAllowStaff', 'CheckSEBHashBrowserExamKeyOrConfigKey']
List of permission classes for the project. If one of the enabled classes grants access, the user will have access to the course. Can be modified on a per-course basis.
• SEB_KEY_SOURCES Default: ['from_global_settings', 'from_other_course_settings', 'from_django_model', 'from_site_configuration']
List of locations where the course settings will be read from.
18 Chapter 5. Table of Content
• SEB_KEY_DESTINATIONS Default: ['to_django_model', 'to_other_course_settings', 'to_site_configuration']
List of locations where the course settings will be stored to.
• SEB_USER_BANNING_BACKEND Default: 'DatabaseBannedUsersBackend'
The user banning backend will determine where the status of banning for a course-user pair is stored. The only available backend in this version is the database backend.
• SEB_USER_BANNING_ENABLED Default: False
Global feature toggle for the user banning feature. Can be modified on a per-course basis.
• SEB_UPDATE_MODULESTORE Default: 'seb_openedx.edxapp_wrapper.backends. get_course_module_h_v1'
This setting controls the backend implementation for the update module wrapper. Defaults to the hawthorn compatible implementation.
• SEB_COURSE_MODULE Default: 'seb_openedx.edxapp_wrapper.backends. get_course_module_h_v1'
This setting controls the backend implementation for the course_module wrapper. Defaults to the hawthorn compatible implementation.
• SEB_COURSEWARE_MODULE Default: 'seb_openedx.edxapp_wrapper.backends. get_courseware_module_h_v1'
• SEB_COURSEWARE_INDEX_VIEW Default: 'seb_openedx.edxapp_wrapper.backends. get_courseware_index_view_h_v1'
• SEB_GET_CHAPTER_FROM_LOCATION Default: 'seb_openedx.edxapp_wrapper. backends.get_chapter_from_location_h_v1
This setting controls the backend implementation for the chapter locator wrapper. Defaults to the hawthorn compatible implementation.
• SEB_CONFIGURATION_HELPERS Default: 'seb_openedx.edxapp_wrapper.backends. get_configuration_helpers_h_v1'
• SEB_EDXMAKO_MODULE Default: 'seb_openedx.edxapp_wrapper.backends. edxmako_module_h_v1'
This setting controls the backend implementation for the mako renderer wrapper. Defaults to the hawthorn compatible implementation.
5.2.2 Key Hashes
One of the properties of the Safe Exam Browser is that it can send a HTTP header with every request, to inform the server of the current configuration for the browser.
This headers are of two distinct types. The Safe Browser Key and the Config Key. The SEB Open edX plugin supports both types of keys.
5.2. Usage and configuration 19
SEB Open edX documentation, Release 1.0
For more advanced information about the keys, you can refer to the official SEB documentation. We will only mention that the keys are viable at the Browser settings under the Exam tab. This exact keys are what you need to copy at the BROWSER_KEYS and CONFIG_KEYS lists on the Access Settings configuration.
5.2.3 Access Settings
The idea with the Safe Exam Browser is to control the access from students in the course to the course itself. To configure this you need to let the Open edX server know what requirements for access you will impose on the course.
This is done on a per-course basis and can be modified in 3 different locations as configured in the SEB_KEY_SOURCES variable.
1. Global settings from_global_setting
As before for the global settings, you can add a key SAFE_EXAM_BROWSER to the lms.env.
20 Chapter 5. Table of Content
SEB Open edX documentation, Release 1.0
json file and inside of it, a dictionary with objects containing the <course_id> and configura- tions.
Here is an example of setting restrictions on two different courses at the same time. The course course-v1:seb-openedx+course_1+2019 uses the simple list notation and the course-v1:seb-openedx+course_2+2019 uses a more advanced notation with more set- tings.
"SAFE_EXAM_BROWSER":{ "course-v1:seb-openedx+course_1+2019":[
2. Advanced studio settings from_other_course_settings
The other course settings is a new field in the Studio Advanced configurations that is available short after the Hawthorn release was cut. It can be backported to Hawthorn easily, but officially it is only available starting at the Ironwood release.
5.2. Usage and configuration 21
SEB Open edX documentation, Release 1.0
In this json field you can add the SAFE_EXAM_BROWSER key and inside of it the configurations for this course.
You could optionally use the course key as well
3. Site Configuration in the admin from_site_configuration
On the site configurations you can add a key SAFE_EXAM_BROWSER to the site values and inside of it, a dictionary with objects containing the <course_id> and configurations. Very similar to the from_global_settings.
Here is an example with the same configuration as before:
22 Chapter 5. Table of Content
SEB Open edX documentation, Release 1.0
Note: The site configuration module uses a cache to improve the read performance for succesive reads. Unlike other caches in the platform that use memcached, this is a local thread cache that is implemented in the django-crud package.
When you change values in the site configuration object, the easiest way to break the cache is to do a process restart.
make lms-restart
Add the settings using a line break between them.
5.2. Usage and configuration 23
SEB Open edX documentation, Release 1.0
Note: It is required to run the migrations.
5.2.4 Advanced usage
The basic usage of the SEB Open edX plugin grants or denies access to a complete course. This means that every page of the course will be blocked for access without the configured Safe Exam Browser.
More advanced users can make use of the Path Whitelisting and Chapter Blacklisting options to provide a more flexible approach.
Path Whitelisting
As we mentioned before, the default of a course requiring a given SEB Key for access is to be completely blocked. Now, some pages of the course might not require such a restriction. For those you can grant access even without the Safe Exam Browser by using the WHITELIST_PATHS list.
24 Chapter 5. Table of Content
SEB Open edX documentation, Release 1.0
"course-v1:seb-openedx+course_1+2019": { "BROWSER_KEYS":[ "cd8827e4555e4eef82........5088a4bd5c9887f32e590" ], "CONFIG_KEYS":[ "9887f32e590cd8827e........5088a4bd5c4555e4eef82" ], "WHITELIST_PATHS": ["wiki", "about"]
}
This will grant access to the course wiki and the external course about page even without the special browser or configurations.
Some important paths that can be whitelisted are:
• "about"
• "course-outline"
• "courseware"
• "discussion"
• "progress"
• "wiki"
Chapter Blacklisting
In the previous section we mentioned that "courseware" can be whitelisted. This would grant a user complete access to the course content thus defeating the purpose of the SEB Open edX plugin. For this the Chapter Blacklisting allows you to mark specific chapters for secure access.
Here it is worth noting that the naming convention is used differently in the user visible pages and in the code.
Code
Both the Code and the OLX or Open Learning XML use a hierarchy composed of course > chapter > sequential > vertical. This is the convention used for development here.
Studio
On Studio, the exact same hierarchy is composed of course > section > subsection > unit.
This means that a chapter is the same a a section and a sequential the same as a subsection.
Example:
}
You will find the ID of the chapter in the URL
5.2. Usage and configuration 25
https://courses.yourdomain.com/courses/course-v1:seb-openedx+course_1+2019/courseware/ →e87b8744ea3949989f8aa113ad428515/10ddf7ff3a0a4e2f80c8838528e8c93e/1
Which means your chapter ID is e87b8744ea3949989f8aa113ad428515.
As always you can use a list of IDs for multiple chapters.
Note: Currently only chapters are supported for blacklisting. Support for sections or verticals might come in the future.
User Banning
The user banning feature allows the administrator of a course to permanently ban a user from access if the user has attempted to access with a different browser of an incorrectly configured SEB.
This feature is by default turned off, but can be turned on either on the global Plugin Settings with the SEB_USER_BANNING_ENABLED key or per course on the Access Settings using the USER_BANNING_ENABLED key.
When a user has been banned, a message will appear on the page saying that the user is banned and that the teacher or systems administrator can assist them.
26 Chapter 5. Table of Content
SEB Open edX documentation, Release 1.0
When this happens, a staff member can unlock the user by navigating to the seb-openedx dashboard.
It is located at: https://courses.yourdomain.com/seb-openedx/dashboard/
5.2. Usage and configuration 27
5.3.1 Summary
The SEB Server is a web application that is external both to the Safe Exam Browser and the Open edX server. It’s purpose is to make operation of courses restricted by the Safe Exam Browser easier.
5.3.2 API
The API for manipulating the Browser Keys (BEK) and Config Keys (CK) is a RESTful API over http. It uses Json as the payload format.
The API has one resource, namely the Course SEB Configuration. This resource is located at:
https://courses.yourdomain.com/seb-openedx/api/v1/course/<COURSE_ID>/ configuration/
Methods
The API has the usual available methods to read, update, create and delete SEB Configurations.
GET
}
If the internal representation of the configuration uses the simple format (list of mixed SEB and CK keys), the API will render the detailed representation.
It the course_id does not have a SEB configuration then a 404 error will be returned.
POST
Issuing a POST request to https://courses.yourdomain.com/seb-openedx/api/v1/course/ <COURSE_ID>/configuration/ will create a new configuration for the give COURSE_ID. If the resource already exists the API will return a 422 ‘unable to process request’ error.
The payload data must be a json object that contains a valid configuration as detailed on the usage section. Otherwise a http 400 error will be returned.
The list of keys for the json object must include either a BEK or CK list, but may also include optionally:
28 Chapter 5. Table of Content
• BROWSER_KEYS: List of valid BEK.
• CONFIG_KEYS: List of valid CK.
• WHITELIST_PATHS: List of whitelisted course paths that do not require SEB for access.
• BLACKLIST_CHAPTERS: List of chapters that do require a valid SEB for access when courseware was whitelisted.
• SEB_PERMISSION_COMPONENTS: Ordered list of permission components.
• USER_BANNING_ENABLED: Boolean that determines the state of the user banning feature for the course.
PUT
Issuing a PUT request is very similar to a POST request, but in this case the object will be updated. If the object does not exist, then it will be created. Calling put is an idempotent operation.
PATCH
The API allows the use of the PATCH request to issue a partial update. This case is similar to a PUT request, but with all the fields being optional
DELETE
Sending a DELETE request to https://courses.yourdomain.com/seb-openedx/api/v1/course/ <COURSE_ID>/configuration/ will delete the SEB configuration for the course in question.
Note: The API can alter the information stored at the django model, site configuration and other_course_settings in studio. However the information stored in the global_settings is out of reach for the python process serving the API and therefore not deletable. Editing is valid since the configuration stored in the other sources will override the global_settings.
Authentication
The API uses the standard mechanisms for authenticating APIs in the Open edX platform. This means that both OAuth2 or Session-based authentication are available. In any mechanism of authentication, the permissions will be given only for global staff users. This means that the session or the user-account linked to the Oauth2 token must have the is_staff flag set.
Storage internals
When available, the API will try to store the configuration in the django model, then in the other_course_settings field that is available in Studio. When this is not possible, then it will defer to use the site_configuration object. The precedence of the storage locations for the API can be configured via the SEB_KEY_DESTINATIONS django setting. See ‘Variables‘_.
5.3. Connection with the SEB Server 29
SEB Open edX documentation, Release 1.0
30 Chapter 5. Table of Content
CHAPTER 6
Project Background
This project was build thanks to the contributions of the ETH Zürich, the Safe Exam Browser Open Source project and the Swiss Mooc Service. It is currently build and maintained by eduNEXT.
32 Chapter 6. Project Background
CHAPTER 7
Implementation notes
• Uses the Open edX plugin architecture
• This plugin can be installed in versions of the project starting at the Hawthorn open release (Released in June 2018) and requires no modifications to the core source code of the edx-platform repository. Support for the Hawthorn version is guaranteed and it should as well work with newer versions.
33
What is Open edX?
What is this plugin?
Summary
API