The following sections provide information about Open edX Platform
configuration options.
Configuring Open edX Sites
By default, an Open edX installation has one site for users to interact with.
You can configure multiple sites within your Open edX installation. A site
presents Open edX courses and content in an individual way. If you set up
multiple sites, you can configure them independently of each other. For
example, you can assign a different theme to each site and specify which
courses are available on each site.
You host each site on a separate domain or subdomain from your Open edX
installation. You configure the domain name for a site in the Django admin site
when you create it. For example, you might configure one site
with the domain name university.edu and another site with the domain
name advancedplacement.edu. Or you might configure one site with the domain
name arts.myuniversity.edu and another site with the domain name
sciences.myuniversity.edu.
Create an Open edX Site
To create an Open edX site, follow these steps.
Sign in to the Django administration console for your base URL. For example,
http://{your_URL}/admin.
Select Sites to open the http://{your_URL}/admin/sites/site page.
Enter the domain name for the site. This is the domain name in the URL for
the site. For example, myuniversity.edu.
To make a site available on a non-default port that is entered as part of
the URL, the domain name must include the port number. For example, if an
LMS site is available at my-site.localhost:8000, the domain name for
the site must be my-site.localhost:8000.
Select Save.
Configuring Sites Independently
You can set configuration properties independently for individual sites. The
values that you define for individual sites override the default values that
are present in the studio.yml or lms.yml files. For example, you
can set the PLATFORM_NAME property to a different value for each of your
sites to indicate that the sites present courses for different organizations or
audiences.
Configuring a Site
To set configuration properties for a site, follow these steps.
Sign in to the Django administration console for your base URL. For example,
http://{your_URL}/admin.
Select Site Configurations .
Select Add site configuration.
From the Site menu, select the site you want to configure.
Enter configuration properties in the Values field. Structure all
properties in valid JavaScript Object Notation (JSON) format.
The following example shows a set of configuration properties for a site.
{
"course_email_from_addr":"courses@onlineu.edu",
"university":"Online University",
"PLATFORM_NAME":"Online University",
"email_from_address":"courses@onlineu.edu",
"payment_support_email":"payments@onlineu.edu",
"SITE_NAME":"onlineu.edu",
"site_domain":"onlineu.edu",
"SESSION_COOKIE_DOMAIN":"onlineu.edu"
}
Note
To make courses site-specific, you set the course_org_filter
property to an organization identifier. Only that organization’s courses
are available from the site.
When you are ready for the configuration settings to take effect,
select Enabled.
The configuration properties that you set do not affect the site
until you select Enabled. If needed, you can return to the Site
configurations screen for this site to enable the configuration properties
later.
Select Save.
Site Configuration Reference
An example of the properties that you define to configure a site follows.
{
"ECOMMERCE_API_URL":"https://my-site.sandbox.edx.org/api/v2",
"ECOMMERCE_PUBLIC_URL_ROOT":"https://my-site.sandbox.edx.org",
"ECOMMERCE_API_SIGNING_KEY":"ecommerce-secret",
"COURSE_CATALOG_VISIBILITY_PERMISSION":"see_in_catalog",
"COURSE_ABOUT_VISIBILITY_PERMISSION":"see_about_page",
"ENABLE_COMBINED_LOGIN_REGISTRATION":true,
"ENABLE_PAID_COURSE_REGISTRATION":true,
"course_email_template_name":"my-site",
"course_email_from_addr":"my-site@example.com",
"ALLOW_AUTOMATED_SIGNUPS":true,
"domain_prefix":"my-site",
"university":"Education Programs",
"PLATFORM_NAME":"Education Programs",
"platform_name":"Education Programs",
"show_only_org_on_student_dashboard":true,
"email_from_address":"my-site@example.com",
"payment_support_email":"payments@example.com",
"SITE_NAME":"my-site.sandbox.edx.org",
"site_domain":"my-site.sandbox.edx.org",
"SESSION_COOKIE_DOMAIN":"my-site.sandbox.edx.org",
"course_org_filter":"MyOrgX",
"course_index_overlay_text":"<img src='/static/my-site/images/400x103.png' width='400' height='103' />",
"homepage_overlay_html":"<img src='/static/my-site/images/400x103.png' width='400' height='103' />",
"payment_email_signature":"Education Programs<br>The Digital Programs Team<br>my-site@example.com<br>101 Example Street<br>Example State"
}
For more information about themes, see Changing Themes for an Open edX Site.
Changing the Appearance of Open edX Sites
This section describes how you can customize your Open edX sites to change the
way they look.
Changing Themes for an Open edX Site
The theme for a website defines the appearance of its user interface (UI): the
logo, the color scheme, and the links in the page headers and footers are
examples of different aspects of an Open edX site that are defined by its
theme.
Open edX provides a default theme that is defined by page templates, CSS
styling, and assets such as images that are provided in the Open edX code. You
can change the appearance of the following parts of an Open edX site.
The Studio UI, which is used by course teams.
The learning management system (LMS) UI, which is used by learners and course
teams.
The UI of the E-commerce service, which is used by course offering and order
managers.
The topics in this section describe how you can change the way an Open edX
site looks, without changing how it works.
Themes Overview
After you configure one or more sites for your Open edX installation, including
their domain and platform names, you can set up a theme to use for each site.
To override the files that constitute the default Open edX theme, you create
replacements for one or more of those files, place them in file paths that are
constructed and named in parallel to the default file locations,
configure your Open edX instance to use the files in your theme’s directories
instead of the default locations, and then compile the theme.
EdX first looks for files in your theme directories, and uses any file that
matches the exact file path and file name of a default UI file. If matching
files are not found, then Open edX looks in the default location.
For more information about Open edX sites, see Configuring Open edX Sites.
Root Directories for Theme Files
Themes are located outside of the Open edX source directories, in any location
you like. For example, you might make a directory called
/my-open-edx-themes.
Within that directory, you create a separate directory for each Open edX
repository that you want to create a theme for, such as edx-platform
and ecommerce.
Within each of those directories, you create another directory and name it for
your theme, such as my-theme. You can create a number of themes, each with
their own name. Within each theme directory, you create directories and files
to parallel the structure in the corresponding Open edX repository.
After you create these directories, you might have a structure like this one.
my-open-edx-themes
├── ecommerce
│ └── my-theme
└── edx-platform
└── my-theme
├── cms
└── lms
You must give the files that you create for a theme the same relative file
paths and file names as the default files that they override. Different root
directories for the relative paths apply to Studio, the LMS, and the E-commerce
service.
For Studio and the LMS, relative file paths are from the root directory of
the local clone of the edx/edx-platform repository in your installation
directory.
For the E-commerce service, relative file paths are from the ecommerce
directory of the local clone of the edx/ecommerce repository in your
installation directory.
For example, the root directory for the relative file paths of your theme files
might be at one of the following file paths.
For the LMS UI or Studio UI, /edx/app/edxapp/edx-platform.
For the UI of the E-commerce service,
/edx/app/ecommerce/ecommerce/ecommerce.
The following subdirectories hold the UI files that you can override.
static holds media files such as images and styling resources such as
Syntactically Awesome Style Sheet (Sass) files that produce Cascading Style
Sheet (CSS) files.
templates holds Python web application page templates that produce the
HTML for UI pages.
Creating a Theme
To create a theme, you add a theme directory to the installation-wide themes
directory that you added when you enabled theming for your Open edX
installation. Then, you copy default UI files into your theme directory and
update them to change the appearance of the Open edX site or sites that will
use that theme.
For more information about the themes directory, see
Enabling and Applying Themes.
You can customize the default images, Sass files, and web application template
files for the Open edX components in your installation.
To replace an image, you can override any of the images in the
static/images directories for the components you are theming.
For the LMS and Studio, you can customize any of the Sass files in the
static/sass directories.
For the E-commerce service, you can customize any of the Sass files in the
static/sass/partials directory.
Note
Do not customize Sass files in the static/sass/base directory.
You can override any of the HTML templates in the lms/templates or
cms/templates directories for the components that you want to apply a
theme to.
UI files for the LMS are stored in the directories shown in the following
example theme directory. You can examine the default UI files in the source
repository of the component that you want to apply the theme to.
/my-open-edx-themes/edx-platform/my-theme/lms/static/images
/my-open-edx-themes/edx-platform/my-theme/lms/static/sass
/my-open-edx-themes/edx-platform/my-theme/lms/templates
The default Open edX theme includes an image file named logo.png that
appears in the header of most LMS pages. The file path of that image in the
edx-platform repository is lms/static/images/logo.png.
The following example shows an absolute file path of the LMS logo image in a
theme directory. The file path after
/my-open-edx-themes/edx-platform/my-theme/ matches
the relative file path of that image in the default directory for the LMS UI.
/my-open-edx-themes/edx-platform/my-theme/lms/static/images/logo.png
The name of the directory that you create to hold your versions of the image,
theme, and Sass styling files identifies the theme. As a result, if you want to
create a theme named my-theme, the name of the directory within your
installation-wide themes directory must be my-theme.
Note
If you add more than one site-specific theme directory, make sure that each
of the directory names is unique. The Open edX installation looks for a
theme with a certain name, and selects the first one that matches.
Because the UI files for the LMS and Studio are located together in the
edx-platform repository, you can create one theme that applies to both the LMS
and Studio. If you want to create a theme for the E-commerce service, you must
add a separate theme directory for its files.
The theme directory holds the UI files that override the corresponding
default files.
For example, if the themes directory for your site is /my-open-edx-themes,
the files in the following example create a theme named my-theme.
/my-open-edx-themes/edx-platform/my-theme/lms/static/images/logo.png
/my-open-edx-themes/edx-platform/my-theme/lms/static/sass/partials/base/_variables.scss
/my-open-edx-themes/edx-platform/my-theme/lms/templates/navigation.html
/my-open-edx-themes/edx-platform/my-theme/cms/static/images/studio-logo.png
/my-open-edx-themes/edx-platform/my-theme/cms/static/images/logo.png
/my-open-edx-themes/edx-platform/my-theme/cms/templates/login.html
Because the theme directory includes UI files in both the lms and cms
subdirectories, you can apply the theme to both the LMS and Studio.
Note
After you create or make changes to a theme, you must update the theme.
Updating a theme compiles Sass files to create the CSS files that style
your UI. For more information, see Compiling a Theme.
Enabling and Applying Themes
You must enable the use of themes for your Open edX installation before you can
apply themes to your Open edX sites. If your installation has only one site,
you apply a theme to that default site.
For more information about Open edX sites, see Configuring Open edX Sites.
To enable the use of themes for your Open edX installation, follow these steps.
Create an installation-wide themes directory to hold the customized UI files
for all of the themes that you create. This directory will hold
subdirectories for each theme. Your Open edX installation will look in the
directory to find the themes you apply to sites.
You can create this directory at any location on a file system that is
accessible to your Open edX installation. For example, you might place it at
the root of the file system in a directory named /my-open-edx-themes.
Set the file permissions on the themes directory, and all of its
subdirectories, to enable read+write permissions for the Ubuntu user.
For example, to allow the devstack edxapp user for the LMS and Studio to
read and write files in the themes directory, you might use the following
commands.
sudo chown -R edxapp:edxapp /my-open-edx-themes
sudo chmod -R u+rw /my-open-edx-themes
On fullstack and native installations the Ubuntu user is www-data.
For each Open edX component that you want to theme, set the
ENABLE_COMPREHENSIVE_THEMING configuration property to true.
The specific method that you use to configure Open edX components depends on
the type of environment you are using. For example, you can set the
configuration property in the following files.
For the LMS, you edit /edx/app/edxapp/lms.yml to set
"ENABLE_COMPREHENSIVE_THEMING": true.
For Studio, you edit /edx/app/edxapp/studio.yml to set
"ENABLE_COMPREHENSIVE_THEMING": true.
For the E-commerce service, you edit /edx/etc/ecommerce.yml to set
ENABLE_COMPREHENSIVE_THEMING: true.
If any of these files do not exist, you can add them to define this
configuration setting.
For each Open edX component that you want to apply a theme to, add the
absolute path of the themes directory to the COMPREHENSIVE_THEME_DIRS
configuration property.
The specific method that you use to configure Open edX components depends on
the type of environment you are using. For example, you can set the
configuration property in the following files.
For Studio, add the path to COMPREHENSIVE_THEME_DIRS in
/edx/app/edxapp/studio.yml.
"COMPREHENSIVE_THEME_DIRS": [
"/my-open-edx-themes/edx-platform"
],
For the LMS, add the path to COMPREHENSIVE_THEME_DIRS in
/edx/app/edxapp/lms.yml.
"COMPREHENSIVE_THEME_DIRS": [
"/my-open-edx-themes/edx-platform"
],
For the E-commerce service, add the path to COMPREHENSIVE_THEME_DIRS
in /edx/etc/ecommerce.yml.
COMPREHENSIVE_THEME_DIRS: ["/my-open-edx-themes/ecommerce"]
Restart all servers.
Note
You can create more than one themes directory for your Open edX
installation. To use multiple themes directories, include the path to each
directory in the COMPREHENSIVE_THEME_DIRS configuration property. The
following example shows the configuration for multiple themes directories.
"COMPREHENSIVE_THEME_DIRS": [
"/my-open-edx-themes/edx-platform",
"/my-other-open-edx-themes/edx-platform"
],
For the following file structure:
edx
└── my-themes
└── my-theme-red
├── cms
└── lms
└── static
└── templates
set these in lms.yml and studio.yml:
"COMPREHENSIVE_THEME_DIRS": [
"/edx/my-themes",
],
"THEME_NAME": "my-theme-red"
To apply a theme to an Open edX site, follow these steps.
Make sure that you have enabled theming for your Open edX installation and
that you have configured an installation-wide themes directory. For more
information, see Enabling and Applying Themes.
Make sure that you have created a theme and that you know the identifier of
the theme. The identifier of a theme is the name of the directory for that
theme, within your installation-wide themes directory. For more information,
see Creating a Theme.
Sign in to the Django administration console for your base URL. For example,
http://{your_URL}/admin.
Select Site themes.
Select Add site theme.
From the Site menu, select the site you want to apply a theme to.
In the Theme dir name field, enter the identifier of the theme.
Select Save.
Compiling a Theme
To update a theme, you compile the Sass files to create the CSS files that
style your UI when you apply the theme.
To update a theme for Studio or the LMS, follow these steps.
Log in to the Open edX machine as the edxapp user.
Change to the /edx/app/edxapp/edx-platform directory.
Execute the paver update_assets command to update all themes.
If you want to update specific themes, use the arguments described in the
following table.
Argument |
Description |
|---|
--theme-dirs
|
Provide a space-separated list of the theme directories that you want
to update. Only files in the theme directories that you include
are updated. |
--themes
|
Provide a space-separated list of the themes that you want to update.
Only the themes that you include are updated. |
For the E-commerce service, commands are available for you to update
all themes at once, or to update only the themes you specify.
To update a theme for the E-commerce service, follow these steps.
Log in to the server for the E-commerce service as the ecommerce user.
Change to the /edx/app/ecommerce/ecommerce directory.
To update all themes, execute one of these commands.
To specify a theme or set of themes to update, or to include optional
arguments, execute python manage.py update_assets with the options
described in the following table.
Argument |
Description |
|---|
--settings
|
Provide the name of a Django settings module
in Python package syntax. For example,
--settings=ecommerce.settings.production. |
--themes
|
Provide a space-separated list of the themes that you want to update.
Only the themes that you include are updated. |
--output-style
|
Defines the coding style for the compiled CSS files. Possible values
are nested, expanded, compact, and compressed. The
default value is nested. |
--skip-system
|
Disables Sass file compilation for the default Sass files provided in
the Open edX software. Use this option if you have only updated the
Sass files in your theme. |
--skip-collect
|
Only compile the Sass files and do not deploy the resulting CSS files. |
--enable-source-comments
|
Include the location of the source file as comments in the resulting
CSS files. Enabling this argument can be useful when you are testing a
theme. |
In addition, an example theme is
available for review.
Styling Drag and Drop Problems
You can customize the appearance of drag and drop problems in your Open edX
site using custom Cascading Style Sheet (CSS) files. The style that you
configure applies to all drag and drop problems in all courses. For more
information about drag and drop problems, see
Drag and Drop Problem.
The following two methods apply CSS styling to drag and drop problems.
You can apply CSS styles to drag and drop problems by creating a theme for
your site and updating the Syntactically Awesome Style Sheet (Sass) files
that produce the CSS files. For more information, see Creating a Theme.
You can apply CSS styles to drag and drop problems by adding a Python
programming language module that includes a CSS file to your Open edX site.
For more information, see the instructions in this section.
Note
This section provides information about styling the drag and drop
problem type that was added to the edX platform in 2016. This drag and drop
problem type replaced an earlier drag and drop problem type. You should use
the latest drag and drop problem type for all new course problems.
Note
Course teams can also style the background and text colors of the draggable
items in an individual drag and drop problem, without adding CSS files or
configuring a Python module. For more information, see
Changing the Visual Style of a Drag and Drop Problem.
To customize the style of drag and drop problems by adding a CSS file in a
Python module, follow these steps.
Create a custom CSS style sheet that applies styles to the drag and drop
problem user interface. You can base your style sheet on the example CSS
file for drag and drop problems that is included in the drag and drop
problem module.
Create a Python module that includes your custom CSS style sheet. For
example, the following Python module files include a CSS style sheet.
./my_drag_and_drop_style
./my_drag_and_drop_style/css
./my_drag_and_drop_style/css/my_drag_and_drop_style.css
./my_drag_and_drop_style/__init__.py
./setup.py
For more information about creating and installing Python modules, see the
documentation for the Python programming language.
Install your Python module on the LMS server as the edxapp user.
pip install /path/to/my/module
Edit the lms.yml file for your LMS server. Add the drag-and-
drop-v2 object to the XBLOCK_SETTINGS object. Include the content
shown in the following example.
"XBLOCK_SETTINGS":{
"drag-and-drop-v2": {
"theme": {
"package": "my_drag_and_drop_style",
"locations": ["css/my_drag_and_drop_style.css"]
}
}
Enter the name of your Python module in the value of the package object. The value in the example above is my_drag_and_drop_style.
Enter the path to your CSS style sheet file in the value of the
locations object. The value in the example above is
css/my_drag_and_drop_style.css. The path must be relative to your Python
module installation directory. You can include more than one path in the
locations array, separated by commas.
Restart the LMS.
Adding Custom Fields to the Registration Page
This topic describes how to add custom fields to the registration page for your
instance of Open edX.
By default, the registration page for each instance of Open edX has fields that
ask for information such as a user’s name, country, and highest level of
education completed. You can add custom fields to the registration page for
your own Open edX instance. These fields can be different types, including
text entry fields and drop-down lists.
Before you add a custom field to the registration page, you must make sure that
the combined sign-in and registration form is enabled for your Open edX
instance. To do this, open the lms.yml and studio.yml files, and
set the ENABLE_COMBINED_LOGIN_REGISTRATION feature flag to True. These
files are located one level above the edx- platform directory.
To add custom fields to the registration page, follow these steps.
Start and sign in to your instance of Open edX.
Use Python to create a Django form that contains the fields that you want to
add to the page, and then create a Django model to store the information
from the form.
For more information about how to create Django forms, see Django Forms
on the Django website.
In the lms.yml file, add the app for your model to the
ADDL_INSTALLED_APPS array.
In the lms.yml file, set the REGISTRATION_EXTENSION_FORM
setting to the path of the Django form that you just created, as a dot-
separated Python string.
For example, if your form is named “ExampleExtensionForm” and is located at
“path/to/the_form.py”, the value of the setting is
path.to.the_form.ExampleExtensionForm.
Run database migrations.
Restart the LMS and verify that the new fields appear on your registration
form.
Specifying Allowed Registration Email Patterns
This topic describes how to restrict registration on your site by specifying
which email address patterns are allowed in registration emails.
By default, all email addresses are accepted when learners register for an
account on your Open edX site. You have the option of restricting registrations
to learners who use an allowed email address pattern. Doing so can be useful in
cases where you want to allow only learners who are members of a school,
organization, or corporation to register and access your courses.
Note
Configuring your site using the procedure below only restricts
registration to learners whose email addresses match the specified patterns.
It does not hide courses from any learners, or prevent access to pages on
your site that can be accessed without registration.
DEPRECATED: This Is Unavailable in Lilac onwards
Enabling Open edX Search
You can add a search feature to your Open edX site so that prospective learners
can find courses more easily. When a learner searches for a key word or words,
the search feature returns a list of the courses that are currently open for
enrollment and that match the entered key words.
This section describes how to enable search in your instance of Open edX.
EdX Search is a Django application that provides access to search services
from within edX Platform applications. Searching is accomplished by creating an
index of documents, and then searching within that index for matching
information.
When you install the Open edX devstack, edX search is enabled by
default. You must enable this feature to use it with Open edX fullstack.
By default, edX Search uses MockSearchEngine for testing and ElasticSearch
Engine for production. You can configure edX Search to use a different search
engine.
MockSearchEngine
MockSearchEngine is a simple implementation using a JSON file for index
storage. It has no specific requirements, but it does not scale well and should
only be used for testing.
ElasticSearchEngine
ElasticSearchEngine is a ElasticSearch back-end implementation. It uses same
ElasticSearch version that is already part of Open edX Platform. The current
version is v1.5.2. The ElasticSearch Python client is the latest 1.x version.
EdX Search requires the following applications.
Django (edX Platform version)
pyMongo (edX Platform version)
pytz
Django elasticsearch (0.4.5)
EdX Search is included in Open edX Platform GitHub requirements and is
installed automatically when you install the Open edX Platform.
You enable course indexing by setting the ENABLE_COURSEWARE_INDEX flag.
You enable library indexing by setting the ENABLE_LIBRARY_INDEX flag.
Indexing is done from Studio as a Celery task. Every publish event triggers the
reindex procedure.
You can also reindex the course manually through the Reindex button in the
Course Overview page.
Note
The search feature only returns results for courses that are
currently open for enrollment. Course teams can set the enrollment start and
end dates for their courses in Studio. For more information, see
Guidelines for Start and End Dates in the Building
and Running an Open edX Course guide.
Which Data Gets Indexed
Which data gets indexed is determined by the module index_dictionary()
function implementation. Modules supporting this method are Sequence,
Vertical, Video, and HTML Block. You can add support to any module
type.
Course metadata, including the name, description, and start and end dates are
also indexed.
The following flags are supported in the CMS and LMS applications.
CMS
ENABLE_COURSEWARE_INDEX: Enables and disables courseware content and
course info indexing.
ENABLE_LIBRARY_INDEX: Enables and disables library content indexing.
SEARCH_ENGINE: Sets the search engine to use. There are two predefined
values.
ELASTIC_FIELD_MAPPINGS: Sets any additional field mappings that elastic
search should be aware of. For example, the following code includes the
course start date.
ELASTIC_FIELD_MAPPINGS = {
"start_date": {
"type": "date"
}
}
LMS
ENABLE_COURSEWARE_SEARCH: Enables and disables Courseware Search feature
(in course searching).
ENABLE_DASHBOARD_SEARCH: Enables and disables Dashboard Search feature
(in enrolled courses searching).
ENABLE_COURSE_DISCOVERY: Enables and disables Course Discovery feature
(over courses searching and facet filtering).
COURSE_DISCOVERY_FILTERS: If provided, overrides the list of facets that
are used in the Course Discovery feature to filter the results. By default,
all facets will be displayed. The list of available facets includes:
SEARCH_ENGINE: Sets the search engine to use. The following values are
predefined.
SEARCH_INITIALIZER: Used to set custom SearchInitializer.
SearchInitializer provides an extension to achieve masquerade and other
presearch environmental settings.
SEARCH_RESULT_PROCESSOR: Used to set custom SearchResultProcessor.
SearchResultProcessor does post processing and data manipulation on a result
set returned by SearchEngine.
SEARCH_FILTER_GENERATOR: Used to set custom SearchFilterGenerator.
SearchFilterGenerator sets filters defined by current active user. Basic
implementation sets only course start date filter.
Enabling Badging
This topic describes how to enable and configure badging in your instance of
Open edX.
Badges provide a way for learners to share their course achievements. For
courses that have course completion badges enabled, learners receive a badge at
the same time that they receive a course certificate, and have the option of
sharing their badges to a badging site such as Mozilla Backpack. For more
information, see Course Completion Badges.
In addition to badges that are awarded for completing single courses, you can
also issue badges for various cross-course events. For example, you can create
badges to be awarded when any of the following events occur.
A learner enrolls in a certain number of courses.
A learner receives a completion certificate for a certain number of courses.
A learner receives a completion certificate for every course in a specified
list of courses.
For more information, see Course Event Badges.
By default, Open edX supports Open Badges (http://openbadges.org/), an open
standard originally developed by the Mozilla Foundation. Open Badges provides a
badge generator called Badgr Server, which is used by default in Open edX.
You can use a badge generator other than Badgr Server. For information, see
Specify a Badge Generator Other Than Badgr Server.
For information about creating custom badges, see Create New Badges for Your Open edX Instance.
Setting up the badges feature on your instance of Open edX involves performing
the set up and configuration tasks that are described in the topics below.
Badge generation depends on certificate generation. Badges for course
completion are automatically generated when a course certificate is generated
for a learner. Make sure certificates are enabled on your Open edX instance.
For information, see Enabling Course Certificates.
By default, Open edX uses Badgr Server as the badge generator. If you do not use
Badgr Server, you can configure a different badge generator.
Install Badgr Server
Badgr Server provides an API for issuing Open Badges. Follow the instructions
at https://github.com/concentricsky/badgr-server to install and run Badgr
Server.
Important
You must install Badgr Server at a publicly accessible IP
address, to allow the Open edX LMS and services such as Mozilla Backpack to
contact Badgr Server.
If you do not use Badgr Server, you can configure a different badge generator.
See Specify a Badge Generator Other Than Badgr Server.
Specify a Badge Issuer for Your Organization
Note
This step is required only if you use Badgr Server for your badge
generator.
If you are using Badgr Server, log in to your installation of Badgr
Server and add an issuer of Open Badges for your organization.
For more information about issuing Open Badges, see the Issuing Badges topic
on the Mozilla wiki.
Specify a Badge Generator Other Than Badgr Server
By default, Open edX uses Badgr Server as the badge generator. To use Badgr
Server, see Install Badgr Server and Specify a Badge Issuer for Your Organization.
To specify a different badge generator, follow these steps.
Note
Because the services and software used for badge generation can differ
significantly, the steps described in this topic are intended as guidelines
and not as exact procedures.
Add the BadgingBackend object as a subclass to
lms/djangoapps/badges/backends/base.py.
A BadgingBackend object must include the award function
award(badge_class, user_id, evidence_url=None)
where
badge_class is the definition of the badge class for which the
BadgeAssertion is created,
user_id is an ID for the user that the BadgeAssertion is to be created
for, and
evidence_url is an optional URL for the location where the badge
evidence can be viewed.
The award function is responsible for the server awarding a badge to a
learner. It is also responsible for all checks leading up to the awarding of
the badge, including making sure the badge specification does not already
exist on the target before creating a new badge specification.
The award function should either return a BadgeAssertion object or raise
an exception if the award cannot be given. By default, a base badge
generation object called BadgeBackend exists, and contains a dummy
version of the award function.
class BadgeBackend(object):
"""
Defines the interface for badge generators.
"""
__metaclass__ = ABCMeta
@abstractmethod
def award(self, badge_class, user, evidence_url=None):
"""
Create a badge assertion for the user using this badge generator.
"""
In the BadgeAssertion object that is generated by the award function, make
sure the backend value is the name of the BadgingBackend subclass.
class BadgeAssertion(models.Model):
"""
Tracks badges on our side of the badge baking transaction
"""
user = models.ForeignKey(User)
badge_class = models.ForeignKey(BadgeClass)
data = JSONField()
backend = models.CharField(max_length=50)
image_url = models.URLField()
assertion_url = models.URLField(
In the lms.yml and studio.yml files, set the value of
BADGING_BACKEND as a dot-separated python path specification to the
object that you use to create and assign badges.
When you have finished modifying your configuration files for the badge
generator, restart the Studio and Learning Management System processes so
that the updated environment configurations are loaded.
To enable badges, you modify the lms.yml and studio.yml files,
which are located one level above the edx-platform directory.
In the lms.yml and studio.yml files, in the FEATURES
section, set the value of ENABLE_OPENBADGES to True.
# Enable OpenBadge support.
'ENABLE_OPENBADGES': True,
In lms.yml, set the values for the following parameters.
BADGR_USERNAME: The username connected to your Issuer App in Badgr.org
or in your installation of Badgr Server. This will be used to create OAuth2 tokens.
BADGR_PASSWORD: The password connected to your Issuer App in Badgr.org
or in your installation of Badgr Server. This will be used to create OAuth2 tokens.
BADGR_TOKENS_CACHE_KEY: The cache key for Badgr API tokens. Once created,
the tokens will be stored in cache and can be retrieved using this key.
BADGR_BASE_URL: A string containing the base URL for Badgr Server.
If you are running your own installation, the Badgr Server must be installed
at a publicly accessible IP address. If you have registered an Issuer App
with Badgr.org, this will be provided for you.
BADGR_ISSUER_SLUG: A string that is the slug for the Badgr issuer.
The slug can be obtained from the URL of the Badgr Server page that
displays the issuer. For example, in the URL
http://exampleserver.com/issuer/test-issuer, the issuer slug is
test-issuer.
BADGR_ENABLE_NOTIFICATIONS: Optional boolean setting for enabling
email notifications. When set to “True”, learners will be notified by email
when they earn a badge. Default is “False”.
############## Badgr OpenBadges generation ##############
BADGR_USERNAME = "example@example.com"
BADGR_PASSWORD = "password"
BADGR_TOKENS_CACHE_KEY = "secret-test-cache-key"
# Do not add the trailing slash here.
BADGR_BASE_URL = "http://localhost:8005"
BADGR_ISSUER_SLUG = "test-issuer"
BADGR_ENABLE_NOTIFICATIONS = True
Save the lms.yml and studio.yml files.
Run database migrations.
Restart the Studio and Learning Management System processes so that the
updated environment configurations are loaded.
The ability to issue course completion badges is enabled by default for all
courses, but can be turned off or on again using an advanced setting in
Studio. For information, see Enable or Disable Badges for Your Course in
Building and Running an Open edX Course.
Note
The course-level setting to enable badges does not affect badges that
are issued for completing or enrolling in multiple courses.
Important
Default images are supplied in Open edX for course completion
badges. Be sure to replace these default badge images with your
organization’s own badge images before any badges are issued. When the first
badge is issued for a given course, badge images are uploaded to Badgr
Server. All badges issued in future for this course will use this uploaded
original badge image, even if you subsequently change badge images in the
Django Administration badge image configuration.
Access the Django Administration website for your instance of Open edX. To
do this, go to https://<host name of your Open edX instance>/admin. For
example, this might be https://YourOrganization.org/admin.
Select Site Administration > Badges > Course complete image
configurations, and then define a course complete image configuration for
each course mode on your platform for which you want to issue badges upon
course completion. Examples of course modes are “professional” or “advanced”
or “basic”.
For each course complete badge image configuration, set these parameters.
Important
Be sure to replace the default badge images with your
organization’s own badge images before any badges are issued.
Optionally, you can define a badge image that will be used as the default
badge image for any course modes that do not have an explicitly specified
badge image.
To do so, in the course complete image configuration that references the
image you want to use as a default, select the Default checkbox. After
you save the configuration, this badge image is used for any course
completion badge configurations that do not have a badge image explicitly
specified.
Note
You can specify only one default badge image.
Save each configuration parameter and exit the Django Administration
website.
Open edX provides several customizable course event badges that can be awarded
when any of the following events occur.
A learner enrolls in a certain number of courses.
A learner receives a completion certificate for a certain number of courses.
A learner receives a completion certificate for every course in a specified
list of courses.
Before course event badges can be awarded, you must customize them with your
parameters and badge images. To customize any of the course event badges, follow
these steps.
Access the Django Administration website for your instance of Open edX. To
do this, go to https://<host name of your Open edX instance>/admin. For
example, this might be https://YourOrganization.org/admin
Select Site Administration > Badges > Badge Classes.
Add a badge class for each course event for which you want to issue badges.
Examples of course events might be enrolling in five courses, or completing
three required courses.
For each badge class, set the following parameters.
Slug: A unique identifier that you choose to identify the badge class. This
identifier can contain only numbers, lowercase letters, underscores, or
hyphens. The slug, combined with the Issuing Component value, uniquely
identifies a badge.
Issuing Component: Identifies the part of the platform that is issuing the
badge. This identifier can contain only numbers, lowercase
letters,underscores, or hyphens. For the three customizable course event
badges that are included in the Open edX platform, the value for Issuing
Component must be openedx__course (with two underscores). For
course completion badges that are included
in the Open edX platform, the issuing component value should be empty.
For new badge types that you create, specify an
Issuing Component value that identifies the software component
responsible for issuing the badge. For example, if badges are issued by the
course management component, you might define Issuing Component as
platform__course; if badges are issued based on activity in course
discussions, you might define Issuing Component as
platform__discussions.
Display name: The human readable badge name that is used when badges are
shown to learners, for example, in the Accomplishments view of learners’
profiles.
Course ID: This value should be blank for course event type badges, as
they are not associated with a single course.
Description: A description of this badge.
Criteria: A description of the criteria for awarding this badge.
Mode: The course mode for the course associated with this badge, if
applicable.
Image: The badge image to use for this badge. Badge images should be
square .png files less than 250KB in size.
An example of a badge class configuration might have the following values.
slug: enrolled_three
issuing_component: openedx__course
display_name: Enroll in Three Courses
description: Enrolled in three courses
criteria: A learner must enroll in three courses to receive this badge
image: triple_enrollment_badge_image.png
When you have finished defining the badge class, select Save.
Next, you create a new course event badge configuration that defines all of
the course event badges that you want to issue. Select Site
Administration > Badges > Course event badges configurations >
Add course event badges configuration.
Important
You can create more than one course event badge configuration,
but you can only mark one configuration as Enabled. Only the most
recently activated course event badge configuration is used.
Within the new course event badge configuration, set the following
parameters.
Courses completed: Define badges to be awarded for completing a certain
number of courses, or completion of specific courses. Define one badge
per line. On each line, enter the number of courses that must be completed,
followed by a comma and then the slug of the badge class to associate
with this badge.
For example, to configure two badges, one that is awarded when a learner
completes 3 courses, and another that is awarded when a learner completes
8 courses, you add two lines to the Courses completed field.
3,completed_three
8,completed_eight
where completed_three and completed_eight are badge slugs that
you previously defined in badge classes.
Courses enrolled: Define badges to be awarded for enrolling in a certain
number of courses, or enrolling in specific courses. Define one badge per
line. On each line, enter the number of courses that must be enrolled in,
followed by a comma and then the slug of the badge class to associate
with this badge.
For example, to configure a badge that is awarded when a learner enrolls in
5 courses, you add this definition.
5,enrolled_five
where enrolled_five is a badge slug that you previously defined in a
badge class.
Course groups: Define badges to be awarded for completing a list of
specific courses. Define one badge per line. On each line, enter the slug
of the badge class, a comma, then the list of course keys.
For example, to configure a badge that is awarded when a learner completes
the 3 prerequisite courses in a series, you add this definition.
prereq_computerscience_badge_slug,course1_identifier,course2_identifier,course_3_identifier
where prereq_computerscience_badge_slug is a badge slug that you
previously defined in a badge class, and course1_identifier,
course2_identifier, and course3_identifier are the Course IDs for
the three courses that must be completed for this badge.
When you have finished defining badges in the configuration, select Save.
To activate this configuration, select Enabled at the top of the
configuration page.
Important
You can create more than one course event badge configuration,
but you can only mark one configuration as Enabled. Only the most
recently activated course event badge configuration is used.
In addition to using the default customizable badges that are provided with the
Open edX platform, you can design new badges that are generated when a
particular XBlock-related or course-related action occurs.
Before you create new badges, you should understand the following concepts.
Badge Class - The specification of the badge that is to be awarded.
Parameters for badge classes are described in Step 4 of the Create Course Event Badges for Your Open edX Instance topic.
Slug - This field in the BadgeClass model uniquely identifies the badge
class.
Issuing Component - This field in the BadgeClass model identifies the part
of the software that is issuing the badge. For example, the name of the
XBlock where the occurrence of some event triggers the awarding of a badge.
For the customizable course event badges that are
included with the Open edX platform, the value for issuing_component must
be openedx__course (with two underscores). For course completion
badges that are included in the Open edX platform,
the issuing component value should be empty.
For new badge types that you create, specify an Issuing Component value
that identifies the software component responsible for issuing the badge. For
example, if badges are issued by the course management component, you might
define Issuing Component as platform__course; if badges are issued
based on activity in course discussions, you might define Issuing
Component as platform__discussions.
The combination of badge slug, issuing component, and optionally, course ID
uniquely identifies an awarded badge.
Award method - The award function on the Badge Class instantiates the
badge generator and calls the badge generator’s award function, which is
responsible for awarding a badge to a learner, as well as for performing all
checks leading up to the awarding of the badge. On the Badge Class, the
award function either returns a BadgeAssertion object or raises an
exception if the award cannot be given.
Badge Assertion - A specific generated instance of a badge that a
learner has been awarded. Badge assertions contain data about the learner
who earned the badge, and the date and time that the badge was awarded.
Multiple badge assertions can be awarded for a specific BadgeClass,
including to the same learner. You can get all assertions for a particular
learner for a specific BadgeClass using the get_for_user method, using
user as an argument.
For instructions for creating new badges, see Create New Badges for Your Open edX Instance.
Create New Badges for Your Open edX Instance
To create new badges for use within your Open edX platform, follow these steps.
Create a Badge Class specifying the details of the badge you want to award.
You can do this using the get_badge_class method from the badges
app, or create a badge class in Django Admin. For Django Admin
instructions, see steps 1-5 in Create Course Event Badges for Your Open edX Instance.
BadgeClass.get_badge_class creates the requested badge class if one does
not already exist that has the same combination of slug and
issuing_component. Badge classes are uniquely identified by a
combination of their slug and issuing_component fields, and
optionally also the course_id field if a badge is associated with an
individual course.
If a badge class already exists with the same combination of slug and
issuing_component that is in the request, the existing badge is returned.
No new badge class is created, and no changes are made to the values of the
existing badge class.
In the XBlock or component where badges are to be awarded based on some
event occurring, add declarations to the badging and user services.
The following example illustrates creating a badge class and awarding it
from an XBlock.
from xblock import XBlock
from xblock.fragment import Fragment
import pkg_resources
@XBlock.wants('badging')
@XBlock.wants('user')
class AwardBlock(XBlock):
"""
A Block that awards a badge when a learner visits it.
"""
def award_badge(self, user_service, badge_service):
user = user_service.get_current_user()
badge_class = badge_service.get_badge_class(
slug='general_award', issuing_component='my_org__award_block',
description="A shiny badge, given to anyone who finds it!",
criteria="Visit a page with an award block.",
# This attribute not available in all runtimes,
# but if we have both of these services, it's a safe bet we're in the LMS.
course_id=self.runtime.course_id,
# The path to this file should be somewhere relative to your XBlock's package.
image_file_handle=pkg_resources.get_resource_stream(__name__, 'badge_images/award.png')
# Badge image should be a square PNG file less than 250KB in size.
)
# Award the badge.
if not badge_class.get_for_user(user):
badge_class.award(user)
def student_view(self, context=None):
"""
Displayed to the learner when they visit.
"""
# If the user and badge services are not present, we cannot award the badge.
# If they are, we are ready to award one.
user_service = self.runtime.service(self, 'user')
badge_service = self.runtime.service(self, 'badging')
if user_service and badge_service:
self.award_badge(user_service, badge_service)
return Fragment(u"<div><p>You just earned a badge!</p></div>")
Supported Badges API Endpoint
The Badges API supports the endpoint
GET /api/badges/v1/assertions/user/{username}/. You can use the following
query parameters with this endpoint.
Note
All of these query parameters are optional.
Parameters |
Description |
|---|
slug |
If used, filters by the badge class identified by this slug. Unless
issuing component is also specified, assumes a null/empty issuing
component. |
issuing component |
If used, also requires slug to be specified. Filters by the badge
class. |
courseid |
If used, returns only badge assertions that were awarded as part of the
specific course. |
For example, to get a list of badge assertions issued for a badge with an
issuing_component value of openedx__course and a slug value of
enroll_in_three_courses, the query would be
{openedx domain}/api/badges/v1/assertions/user/?issuing_component=openedx__course&slug=enroll_in_three_courses
where <openedx_instance> is the site URL for your Open edX instance.
Possible query results are as follows.
200 on success, with a list of badge assertions.
403 if a user who does not have permission to masquerade as another user
specifies a username other than their own.
404 if the specified user, badge class, or course does not exist.
Enabling Course Certificates
This topic describes how to enable and configure course certificates in your
instance of Open edX.
For information about configuring program certificates, refer to documentation
in the edx/credentials GitHub repository.
Organizations and course teams can choose to generate certificates for learners
who pass a course. Learners can view, print, or share their certificates.
For additional information about certificates, see
Setting Up Certificates in Studio in the Building and Running an
Open edX Course guide or Print a Web Certificate in the
Open edX Learner’s Guide.
To enable course certificates on your instance of Open edX, you must enable a
feature flag in both Studio and the Learning Management System and complete the
configuration tasks described in this topic.
To enable certificates, modify the lms.yml and studio.yml
files, which are located one level above the edx-platform directory.
In the lms.yml and studio.yml files, set the value of
CERTIFICATES_HTML_VIEW within the FEATURES object to true.
"FEATURES": {
...
'CERTIFICATES_HTML_VIEW': true,
...
}
Save the lms.yml and studio.yml files.
If it does not exist already, create the folder /tmp/certificates owned
by the user and group www-data. Depending on your configuration, this
folder might not survive reboots, and so might need to be created by a
script.
Run database migrations.
Within Studio, course team members with the Admin role can create and edit a
certificate configuration that is used to generate certificates for their
course, including adding signatories and images for organization logo and
signature images for signatories. For details, Setting Up Certificates in Studio in Building and Running an Open edX Course.
Set up the templates for certificates that your organization will issue. Base
templates are included, but you must ensure that they are customized for your
organization. For example, you can change the images that appear on
certificates for each course mode that your organization supports, as well as
fonts and colors that are used on certificates.
To issue certificates in more than one language, see Enable Certificates in Additional Languages.
To display hours of effort on certificates, see Display Hours of Effort on Course Certificates.
Assets for HTML certificates exist in the following locations.
lms/templates/certificates - this folder contains .html files for
certificates. The file valid.html is an example of a certificate file.
Files with names that start with an underscore, such as
_certificate_footer.html, are partial files that can be referenced in the
main certificate .html files.
lms/static/certificates - subfolders of this folder contain assets used
in creating certificates, such as images, fonts, and sass/css files.
You can configure course certificates to render in a specific language.
To display hours of effort for a course run on a course certificate, follow
these steps.
Log in to the Discovery service Django Administration site for your instance
of Open edX. To do this, go to https://<discovery.host name of your Open
edX instance>/admin. For example, this might be
https://discovery.YourOrganization.com/admin.
Under Course Metadata > Course Runs, locate the course run, and make
sure there are values for the following attributes.
Max effort
Weeks to complete
Log in to the LMS Django Administration site for your instance of Open edX.
To do this, go to https://<courses.host name of your Open edX
instance>/admin. For example, this might be
https://courses.YourOrganization.com/admin.
Under Site Administration > Certificates, add or edit a
certificate generation course setting.
Select Yes for Include hours of effort and save the configuration.
Under Site Administration > Certificates, add or edit a certificate
template.
In the certificate template, ensure that a div element exists that
includes the context variable hours_of_effort.
Save your edits to the certificate template.
It is suggested that automatic certificate generation
be enabled in order to provide the best experience for learners.
Particularly in self-paced courses (see Enabling Self-Paced Courses), your learners might not want to wait until an instructor
initiates certificate generation; instead, they would typically expect
to be able to download their certificates as soon as they achieve a
passing grade. This can be achieved by enabling auto_certificate_generation
as described below.
To globally enable this functionality, you must set a Waffle switch:
In the LMS Django Administration site for your instance of Open
edX, under Django-Waffle > Switches, select Add Switch.
Name the switch certificates.auto_certificate_generation.
Tick the Active checkbox.
Optionally, add a Note describing that the switch enables
certificate auto-generation for self-paced courses, or any other
information you consider necessary. The Note contents are never
shown to learners.
Click Save to activate the switch.
Open edX caches the value of this Waffle switch, thus the changed
setting may take several minutes to propagate in a large installation.
In addition to this Waffle switch, automatic certificate generation
requires certain settings to be defined for the course, by a member of
the course staff. For more details, see Allow Learners to Receive Early Certificates and
Allow Learners to Download Early Certificates in
Building and Running an Open edX Course.
To manually generate certificates for a course, run the manage.py script
with the following settings. When the script finishes running, course certificates
will have been generated for eligible learners.
Obtain the course ID for the course for which you are generating
certificates. When you view course content in your browser, the course ID
appears as part of the URL. For example, in the URL
http://www.edx.org/course/course-v1:edX+demoX_Demo_2015, the course ID
is course-v1:edX+demoX_Demo_2015. For some courses, the course ID
contains slashes, however it will not contain beginning or trailing slashes.
For example, a course id look like edX/Demox/Demo_2014.
Obtain the user IDs for any learners for whom you’d like to generate course
certificates. These can be found in the auth_user database table.
Run manage.py with the following settings, replacing {UserID} with a user id
and {CourseID} with the course ID. Do not include beginning or trailing slashes.
./manage.py lms --settings=production cert_generation -u {UserID} {UserID} -c {CourseID}
For example,
./manage.py lms --settings=production cert_generation -u 123 456 -c course-v1:edX+DemoX+Demo_Course
You can then view the certificates in the certificates_generatedcertificate database table.
Enabling Self-Paced Courses
This topic describes how to enable the self-paced courses feature in your
instance of Open edX.
By default, courses are instructor-paced. These courses run on a schedule,
typically four to eight weeks, with new content released each week and set
assignment due dates. You can configure your instance of Open edX so that it
enables self-paced courses. A self-paced course releases content all at once
and is available to complete for three to twelve months after the start date.
In a self-paced course, there are no due dates other than the course end date.
To enable self-paced courses on your instance of Open edX, you must enable the
self-paced course feature in the Learning Management System. Then, course
teams are able to set up a course as either instructor-paced or self-paced in
Studio.
For information about how course teams set course pacing, see the
Set the Course Run Schedule and Pacing in Studio topic in the
Building and Running an Open edX Course guide.
To enable self-paced courses, follow these steps to edit the configurations,
using the Django administration console for your Open edX LMS.
Log in to the Django administration console for the LMS.
In the Self_Paced section, locate Self paced configurations, and
then select Add.
Select the Enabled and Enable course home page improvements
checkboxes.
Select Save.
Enabling Public Course Content
By default, learners must create an Open edX account, be signed in to the LMS,
and enroll in a course before they can see the course content. The Public
Course Content feature gives you the option to make either a course outline
or course content available to anyone, regardless of whether they have registered
for an Open edX account or enrolled in the course. You can decide which courses,
and which parts of those courses, that you want to make public. For example,
you can:
Make just the course outline public. The LMS displays the course outline
without any links to internal course pages, giving potential learners an
overview of what they will see when they enroll.
Make the entire course public. Anyone visiting your course outline can
follow links to visit internal course pages, and freely navigate HTML and
Video course content and handouts.
Show different content blocks to public learners vs. enrolled learners.
You can create content tailored to the public view, while still supporting
the needs of your enrolled audit and paid learners.
Public Course Content and Search Engines
In addition to making your course content visible to people who already use your
site, the public course content feature also allows Google and other search
crawlers to index your public course contents. People who are searching for
information about the topics you teach can then find your course through their
normal search behaviors. This can increase the visibility of your organization’s
courses and boost enrollments for genuinely interested learners.
Enable Public Course Content in the Admin
The public course content feature is enabled in the Django LMS Admin with the
seo.enable_anonymous_courseware_access waffle flag. You can use this flag
in two different ways:
Create a normal waffle flag to enable this flag for all courses. For more
information, see the Waffle documentation.
Create a Waffle flag course override with the ID of a course to enable
this flag for just that course.
Set Visibility for a Course in Studio
After you set the waffle flag to enable public course content in the Django
LMS Admin, you set the visibility for the course content and its About page
in Studio Advanced Settings.
Set Course Content Visibility
View your course in Studio, and navigate to the Advanced Settings page.
Locate the Course Visibility For Unenrolled Learners setting.
By default, this is set to "private", which ensures that only enrolled
learners can access your course content.
If you change this to "public_outline", then your course outline, but not
the other course content, will be visible to everyone.
If you change this to "public", then all of your course content, including
the course outline, will be visible to everyone.
Set Course About Page Visibility
If you want your course to be crawled by Google and other search engines, you
should also ensure that your course’s About page is visible, and that it is
shown in the course catalog. Without these settings, only people with a link
to your course outline or specific content blocks will be able to find your
course.
View your course in Studio, and navigate to the Advanced Settings page.
Locate the Course Visibility in Catalog setting and set it to "both".
Feature Limitations
The public course content feature is currently subject to some limitations,
including the following.
Anonymous or unenrolled learners are not members of any cohort, and so they
only see course blocks that are not assigned to a content group. If you want
to restrict public access to selected course blocks, you need create content
groups for your private content, and ensure that your enrolled learners are
members of a cohort that can see this content group.
Only Text components, Video components, and course handouts have a “public”
view. Unenrolled learners will see a message requesting that they enroll to
see more complex content types, such as discussion forums, problem blocks,
randomized content blocks, exams, Open Response Assessment, and other XBlocks.
Unenrolled learners will not see course completion or progress updates as
they proceed through the course, and Open edX doesn’t remember where they
left off if they leave the course and come back.
The edX mobile apps do not support public course content.
Enabling Custom Courses
To enable designated users to create custom courses (CCX) on your instance of
Open edX, you must configure the server-vars.yml file in the edX platform.
Stop the LMS server.
Create or update the file /edx/app/edx_ansible/server-vars.yml to
include the CCX feature flag.
EDXAPP_FEATURES:
CUSTOM_COURSES_EDX: true
Run the command /edx/bin/update.
sudo /edx/bin/update edx-platform <your-branch-name>
Restart the LMS server.
Enabling Custom Course Settings
To enable course developers to add custom fields to a course on your instance
of Open edX, you must configure the studio.yml file in the edX platform.
Stop the LMS server.
Create or update the file studio.yml to include the custom course
settings feature flag.
'ENABLE_OTHER_COURSE_SETTINGS': true,
Restart the LMS server.
Enabling Discussion Notifications
You can set up notifications that learners receive the first time that anyone
adds a response to a discussion post that they have made.
For more information, including the text of the discussion notification
message, see Automatic Email Messages from the Open edX Platform and
Receiving Notifications.
To create discussion notifications for your instance of the Open edX platform,
you need the following items.
edX Automated Communication Engine (ACE). For more information about how to
install and configure ACE, see edX Automated Communication Engine.
A third party email client, such as Sailthru. For information about how to
configure your email client, see the documentation for the client.
After you have set up ACE and the third party email client, you enable
discussion notifications in the Django administration console for your instance
of Open edX.
Sign in to the LMS Django administration console for your base URL. For
example, http://{your_URL}/admin.
On the Site Administration page, locate Site_Configuration.
In the Site_Configuration section, next to Site configurations,
select Change.
On the Change site configuration page, locate the Values field, and
then add the following value.
{
"enable_forum_notifications":true
}
Select Save.
Enabling Entrance Exams
This topic describes how to enable entrance exams in your instance of Open
edX.
Course teams can create an entrance exam for the course. Learners must pass the
entrance exam before participating in the course.
To enable this feature on your instance of Open edX, you must enable
entrance exams in Studio and the Learning Management System.
For information about entrance exams, see the Building and Running an
Open edX Course and Open edX Learner’s guides.
To enable entrance exams, you modify the lms.yml and studio.yml
files, which are located one level above the edx-platform directory.
Set the value of ENTRANCE_EXAMS in the lms.yml and
studio.yml files to True.
# Entrance exams feature flag
'ENTRANCE_EXAMS': True,
Save the lms.yml and studio.yml files.
Configuring Open Response Assessments
You can change the default configuration for the Open Response Assessment
(ORA2) application. You can change the default file storage system or change
the default set of files that learners are prohibited from submitting.
Configuring ORA2 to Upload Files to Alternative Storage Systems
By default, the Open Response Assessment (ORA2) application stores files that
learners upload in an Amazon S3 bucket.
You can configure ORA2 to store files in an alternate system. To have learners’
files stored in a system other than Amazon S3, follow these steps.
In the ORA-2 repository, implement the BaseBackend class defined in the
base.py file.
For example, the S3.py file in the same directory is an implementation of
BaseBackend for Amazon S3. You must implement the equivalent class for
the storage system you intend to use.
Configure ORA2 to use your alternative storage system by modifying the value
of backend_setting in init file to point to your implementation of
BaseBackend.
Add code to instantiate the new implementation to the get_backend()
function in the init.py file.
Configure ORA2 to use the alternative storage system by modifying the value
of ORA2_FILEUPLOAD_BACKEND in the Django settings to point to your
implementation of BaseBackend.
Prohibiting Submission of Specified File Types
Course teams can configure open response assessments so that learners can
upload files along with their text responses. During the peer review stage of
the assessment, other learners download the submitted file and read the
response.
To protect learners from exposure to files with malicious content, the ORA2
application uses a “blacklist” to identify a set of file types that learners
are not permitted to upload.
To add or remove file types from the blacklist, follow these steps.
In the ORA-2 repository, use an editor to open the submission_mixin.py
file.
Locate the FILE_EXT_BLACK_LIST parameter in the file. By default, this
parameter lists the following file types.
FILE_EXT_BLACK_LIST = [
'exe', 'msi', 'app', 'dmg', 'com', 'pif', 'application', 'gadget',
'msp', 'scr', 'hta', 'cpl', 'msc', 'jar', 'bat', 'cmd', 'vb', 'vbs',
'jse', 'ws', 'wsf', 'wsc', 'wsh', 'scf', 'lnk', 'inf', 'reg', 'ps1',
'ps1xml', 'ps2', 'ps2xml', 'psc1', 'psc2', 'msh', 'msh1', 'msh2', 'mshxml',
'msh1xml', 'msh2xml', 'action', 'apk', 'app', 'bin', 'command', 'csh',
'ins', 'inx', 'ipa', 'isu', 'job', 'mst', 'osx', 'out', 'paf', 'prg',
'rgs', 'run', 'sct', 'shb', 'shs', 'u3p', 'vbscript', 'vbe', 'workflow',
'htm', 'html',
]
Add or remove values from this list.
Save your changes to submission_mixin.py.
Restart the Studio (CMS) and Learning Management System (LMS) processes so
that your updates are loaded.
For more information and examples of how course teams might set up an open
response assessment, see Introduction to Open Response Assessments
in the Building and Running an Open edX Course guide.
Enabling Course Prerequisites
This topic describes how to enable course prerequisites in your instance of
Open edX.
Course teams can set prerequisites for a course. Learners must complete the
prerequisite courses before participating in the course.
To use this feature on your instance of Open edX, you must configure the
Milestones application, then enable prerequisites in Studio and the Learning
Management System.
For information about prerequisites, see the Building and Running an
Open edX Course and Open edX Learner’s guides.
To enable prerequisite courses, you modify the lms.yml and
studio.yml files, which are located one level above the edx-platform
directory.
Set the value of ENABLE_PREREQUISITE_COURSES in the
lms.yml and studio.yml files to true.
# Prerequisite courses feature flag
'ENABLE_PREREQUISITE_COURSES': true,
Save the lms.yml and studio.yml files.
Enabling Course and Video Licensing
This topic describes how to enable licensing in your instance of Open edX.
Course teams can specify licensing options for course content as well as for
each video in a course.
Course teams can select one of the following license options.
All Rights Reserved
Creative Commons
By specifying the license, course teams communicate to learners whether and how
they can reuse course content.
To enable this feature on your instance of Open edX, you must enable licensing
in both Studio and the Learning Management System.
To enable licensing, you modify the lms.yml and studio.yml
files, which are located one level above the edx-platform directory.
In the lms.yml and studio.yml files, in the FEATURES
dictionary, add 'LICENSING':True:
FEATURES = {
'LICENSING': True,
. . .
Save the lms.yml and studio.yml files.
Configuring Transcript Behavior
As a best practice, transcripts should always be provided, so that course
videos meet accessibility requirements. Video transcripts are displayed in the
language selected by the learner in the video player if they are available in
that language. Otherwise, by default video transcripts fall back to an English
language transcript. In cases where no transcript is available, you can
configure Open edX so that the video player does not display the caption and
transcript buttons.
You can configure the default transcript behavior using the
FALLBACK_TO_ENGLISH_TRANSCRIPTS feature flag. By default, this feature
flag is set to TRUE. If you set it to FALSE, then the video transcript
will not fall back to an English language transcript and if no transcript is
available, the caption and transcript buttons are not displayed in the video
player.
Configuring the Transcript Feature Flag
To set the FALLBACK_TO_ENGLISH_TRANSCRIPTS feature flag, you modify the
lms.yml and studio.yml files, which are located one level above
the edx-platform directory.
In the lms.yml and studio.yml files, in the FEATURES
dictionary, change the value of FALLBACK_TO_ENGLISH_TRANSCRIPTS to
FALSE.
Save the lms.yml and studio.yml files.
Enabling Social Sharing of Courses and Certificates
This section describes how to configure Open edX so that learners can share
their certificates, and so course teams can enable learners to share their
courses on social media.
You can enable learners to share courses and certificates that they earn on
social media sites such as Facebook and Twitter.
To use this feature on your instance of Open edX, you must configure social
sharing settings.
Optionally, you can also enable course teams to set custom URLs for social
sharing. If a course team sets a custom course URL, posts to the social sharing
site can include a link back to that URL. If you do not enable custom course
URLS, a link to the course About page in the LMS is used.
In addition to enabling the social sharing icons, you can allow course
teams to provide a custom URL for social sharing sites to link back to.
You must set the CUSTOM_COURSE_URLS parameter to True in both the
lms.yml and studio.yml files. In the studio.yml file, this
parameter is the only social sharing setting.
SOCIAL_SHARING_SETTINGS = {
'CUSTOM_COURSE_URLS': True
}
When finished, save the lms.yml and studio.yml files.
Set a Custom URL for a Course
When you enable custom course URLs in your instance of Open edX, course teams
can then set custom URLs for their courses.
In Studio Advanced Settings, the course team specifies the custom course
URL in the Social Media Sharing URL setting.
This URL is provided to the social sharing site for linking back to a course
location. This URL is used only if you have enabled custom URLs in your
instance of Open edX.
Configuring a Password Policy
This topic describes how to configure a password policy in your
instance of Open edX.
By default, Open edX imposes a minimal password complexity policy for all
users who log in to the LMS or Studio. Under the default password complexity
policy, passwords must contain 2 to 75 characters and cannot be similar to the
user’s username or email address.
Note
Open edX does not store plain-text passwords, only
hashes. Since the length of a hash is independent of the length of
the original password, passwords can effectively be of unlimited
length. The 75-character default limit is rather arbitrary. Open
edX does impose an upper limit of 5,000 characters on a password,
but this should be well beyond the practical limit of password
length.
This password policy is defined in the lms.yml configuration file,
under the AUTH_PASSWORD_VALIDATORS setting:
AUTH_PASSWORD_VALIDATORS:
- NAME: django.contrib.auth.password_validation.UserAttributeSimilarityValidator
- NAME: common.djangoapps.util.password_policy_validators.MinimumLengthValidator
OPTIONS:
min_length: 2
- NAME: common.djangoapps.util.password_policy_validators.MaximumLengthValidator
OPTIONS:
max_length: 75
You can override these settings by modifying one of the existing
OPTIONS. For example, if you want to enforce a minimum password
length of 16 characters, and a maximum length of 256,
you would set:
AUTH_PASSWORD_VALIDATORS:
- NAME: django.contrib.auth.password_validation.UserAttributeSimilarityValidator
- NAME: common.djangoapps.util.password_policy_validators.MinimumLengthValidator
OPTIONS:
min_length: 16
- NAME: common.djangoapps.util.password_policy_validators.MaximumLengthValidator
OPTIONS:
max_length: 256
You can also substitute your own password policy for the default
policy. To configure a password policy in replacement of the default
password policy, follow these steps.
Create or import a new password validator. This is a Python class that defines how a
password is validated. For details about writing a password validator class,
see Creating a Password Validator.
Add your password validator to the list in the AUTH_PASSWORD_VALIDATORS
configuration key in the lms.yml configuration file. For details,
see Configuring a Password Validator.
An Open edX password validator is a Python class that specifies how user
passwords are validated. You can use whatever criteria you choose to establish
a password policy for your Open edX instance. You can create your own custom
password validator, or import one or more password validators from
password_policy_validators in the edx-platform repository on GitHub.
Those password validators include minimum length, maximum length, user
attribute similarity, minimum alphabetic, minimum numeric, minimum uppercase,
minimum lowercase, minimum punctuation, and minimum symbols. For more
information, see also the Django password validation documentation.
To configure your Open edX instance to use a particular password validator,
add your password validator to the list in the AUTH_PASSWORD_VALIDATORS
configuration key in the lms.yml configuration file. For example, to
add a password validator named MyPasswordValidator, add a line like this
to the lms.yml configuration file.
AUTH_PASSWORD_VALIDATORS:
- NAME: path.to.module.MyPasswordValidatorClass
Enabling Third Party Authentication
To enhance sign in options for your users, you can enable third party
authentication, sometimes also called “third party auth”, “single sign on”, or
“SSO”, between organizational authentication systems and the sites you define
for your implementation of the edX platform. After you enable third party
authentication, users can register and sign in to your Open edX site with their
campus or organizational credentials.
Supported Identity Providers
In an exchange of authentication and authorization data, an identity provider
securely asserts the identity and access rights of a set of users. Your Open
edX site is the service provider that allows the users access on the basis of credentials sent by an identity provider.
For example, your Open edX site hosts the courses of three different
organizations. When you configure the Open edX site to be a service provider,
and configure each of the three organizations to be identity providers, you
permit learners who have valid user credentials at any of those organizations
to access the Open edX site.
You can enable third party authentication between your Open edX site and many
types of identity providers. The Open edX platform provides support for
three types of identity providers.
Supported Identity Providers
The Open edX platform has integrated support for the following providers.
OAuth based providers (OAuth2 and the older OAuth v1). Google, Facebook,
LinkedIn, and Azure Active Directory are available by default. Any other
OAuth backends supported by python-social-auth v0.2.12 can be enabled by
changing a configuration setting. People in the Open edX community sometimes
use “third party auth” to refer to Google or Facebook integration. Single
sign on, or “SSO”, and “third party auth” are largely interchangeable terms
for the purposes of this document.
Security Assertion Markup Language (SAML) version 2.0, or Shibboleth.
SAML is an SSO standard mostly used by universities and corporations.
Shibboleth is the name of a particular implementation of SAML, commonly used
by higher education institutions. People in the Open edX community sometimes
use “SSO” to refer to SAML or Shibboleth. “SSO” and “Third Party Auth” are
largely interchangeable terms for the purposes of this doc. For more
information, see Integrating with a SAML Identity Provider.
LTI. Users can use Learning Tools Interoperability® (LTI®) to
authenticate.
Provisionally Supported Identity Providers
The Open edX platform also includes limited support for the following SSO
providers.
These providers are part of the external_auth app, tend to be older and less
robustly tested, and have a much more limited feature set. These providers are
included in the source code but are not officially supported.
Integrating Identity Providers
Regardless of the standard that the identity provider you want to integrate
with uses, you begin by enabling the third party authentication
feature for your site.
For example, your Open edX site hosts the courses of three different
organizations. When you configure the Open edX site to be a service provider,
and configure each of the three organizations to be identity providers, you
permit learners who have valid user credentials at any of those organizations
to access the Open edX site.
If you are using edX as an LTI tool provider to a external learning management system
or application, you can set up an authentication workflow between your Open
edX site and the system that is the LTI tool consumer. For more information,
see Options for LTI Authentication and User Provisioning and
Configuring Open edX User Authentication for LTI.
SSO Behavior
The following behavior applies to all three types of provider (OAuth, SAML, and LTI).
New Learner Registration
When a user signs in by using single sign on (SSO) for the first time, their
account is not normally created automatically. Instead, the user information
sent by the provider is used to pre-fill the registration form. The user can
then edit any of the information before finalizing the creation of their
account. The user could also cancel the registration process at this point,
and no account would be created for them.
The user information that is passed from the external authentication provider
to Open edX varies depending on the provider. For example, Google, Facebook,
a university’s SAML provider, and a corporate SAML provider may all provide
different user information. Some providers may pass the user’s full name,
first name, last name, username, email address, external user ID, and more.
Other providers may pass only an opaque “user token” that can be used to
permanently and consistently identify that user, but which is not considered
personal information and does not correspond to any other public identifier.
After a user submits the registration form, their user account is created and
is automatically “linked” to the external provider. For more information, see
Linking Accounts.
When a user creates an account by using SSO, the password field on the
registration form is hidden. User accounts created by using SSO will have a
random and highly secure password assigned to their account. The user will
not know (or need to know) this password. However, the user can always use
the “reset password” feature to change their password, if they would also
like to be able to use a traditional password-based sign in method.
Important
No matter which type of sign in method is used, a full and independent Open
edX user account is always created for the new user, with a copy of the
user’s information. As a result, if the external provider updates the user’s
information (such as name or email address), that information will not be
automatically updated in the user’s Open edX account. In other words, the use
of the external account as a reference that provides user details is a one-
time event, not an ongoing connection.
Linking Accounts
To be able to sign in by using an external provider such as Google, the
user’s Open edX account must be “linked” to that provider. For example, if a
user’s account is linked to Google, the user can click the Login with
Google button, and will be automatically signed in to their Open edX
account.
User accounts can be linked to zero, one, or many external providers.
Any provider can be linked or unlinked from an account at any time.
If an external provider is used to register a new account, the newly created
account will automatically be linked to that provider.
If a user tries to sign in by using an external provider that is not yet
linked to any Open edX account, the user will be given the following options.
Integrating Third Party Authentication in Open edX
For the Open edX platform, you complete two steps to integrate third party
authentication.
Enable the third party authentication feature.
Set up a provider.
Enable the Third Party Authentication Feature
By default, third party authentication is not enabled on Open edX
installations. To enable this feature, follow these steps.
In the edx/app/edxapp/lms.yml file, edit the file so that it
includes the following line in the features section.
"FEATURES" : {
...
"ENABLE_COMBINED_LOGIN_REGISTRATION": true,
"ENABLE_THIRD_PARTY_AUTH": true
}
Save the edx/app/edxapp/lms.yml file.
Set Up a Third Party Authentication Provider
You can set up an OAuth or SAML provider. For information about the differences
between the two providers, see Supported Identity Providers.
Integrating with an OAuth2 Identity Provider
Open edX has specific instructions for Google, Facebook, LinkedIn, and Azure
Active Directory. For more information about how to set up one or more of these
integrations, see Common OAuth2 Providers.
The system also supports integrations with alternative OAuth2 providers. For
more information, see Additional OAuth2 Providers (Advanced).
Common OAuth2 Providers
Integrating with the most common OAuth2 IdPs has several steps.
Register the Open edX instance with the provider.
Configure Open edX.
Add the provider configuration.
Register the Open edX Instance
The most common OAuth2 providers are Google, Facebook, LinkedIn, and Azure
Active Directory.
Register the Open edX Instance with Google
The following instructions describe how to configure Google as a third party
authentication provider so that users can use Google accounts (which includes
Google Apps accounts) to sign in. These are based on the official Google
instructions.
Obtain credentials to access the Google API. To do this, follow the
official Google instructions to go to the Google Developers Console,
create a new project, and enable the Google+ API service.
In the Google Developers Console, select API Manager, and then select
OAuth Consent Screen.
For Product name shown to users enter the name of your Open edX instance
(for example, “Example Academy Online”).
Select Save.
Select the Credentials tab, select Create credentials, and then
select OAuth client ID.
For Application type, select Web application.
Leave the Authorized JavaScript origins field blank.
For Authorized redirect URIs, enter <Open edX instance
domain>/auth/complete/google-oauth2/. For example, for devstack, enter
http://localhost:8000/auth/complete/google-oauth2/.
Select Create to finish creating the credentials.
After you obtain the credentials, note the client ID and the client secret.
Register the Open edX Instance with Facebook
To create the app in the Facebook developer portal, follow these steps.
Sign in to Facebook, then go to the Facebook for Developers page.
Select Add a New App, and then select Website.
Enter a name for the app, and then select Create New Facebook App ID.
Enter your information in the rest of the fields in the app creation
process.
Under Quick Start for Website, select Skip Quick Start.
You are now at the developer console page for the new Facebook app.
Select Settings, and note the App ID and App Secret.
On the Settings page, select Add Platform, and then select
Website.
For Site URL, enter the URL of your Open edX instance (for example,
<http://localhost:8000/> for devstack).
In the App Domains field, enter the domain name from this URL (for
example, localhost).
Select Save Changes.
Under Products -> Facebook Login -> Settings ->
Authorized redirect URIs, enter <Open edX instance
domain>/auth/complete/facebook/. For example, for devstack, enter
http://localhost:8000/auth/complete/facebook/.
Select Save Changes.
Register the Open edX Instance with LinkedIn
To create the LinkedIn app, follow these steps.
Go to the LinkedIn Developers page.
Click Create Application, enter your information in the form, and then
submit the form.
On the page that opens with information about the app, note the Client
ID and Client Secret.
In the OAuth 2.0 section, for Authorized Redirect URL, enter <Open
edX instance domain>/auth/complete/linkedin-oauth2/. For example, for
devstack, enter http://localhost:8000/auth/complete/linkedin-oauth2/.
Select Update to save your information.
Register the Open edX Instance with Azure Active Directory
You can use Azure Active Directory to allow users with Microsoft Office 365
Business accounts to sign in to Open edX. Note that this feature currently does
not work with other types of Microsoft accounts (such as “@live.com” or
“@hotmail.com” accounts).
If you do not have a Microsoft account, create one on the Microsoft sign in page.
If you do not have an Azure subscription, create one on the Azure account
creation page.
Note
You must enter a credit card on this page, but if you do not create any
virtual machines or other services besides Azure AD, you will not be
charged.
Go to the Azure sign in page.
Click New, locate Active Directory, and then select Create.
Enter a name, domain name, and country.
Create a new application.
Find the new Active Directory in the portal, select Applications,
select Add, and then select Add an application my organization is
developing.
Enter a name for the app, and then select Web Application.
For Sign-on URL, enter <LMS URI>/auth/complete/azuread-oauth2/.
For example, you might enter
http://localhost:8000/auth/complete/azuread-oauth2/.
For App ID URL, enter <LMS URI>/sign in. For example, you might
enter http://localhost:8000/sign in.
Finish creating the new app.
In the portal, locate your Azure AD application, click Configure, and
then locate and make a note of the client ID. For example, the client ID may
be fe3c3868-0faa-44ee-a1bf-1110aeab1a65.
In the Keys section, select a two-year duration, and then select
Save to create a secret key. Note the value of the key. For example, the
key-value may be abcdef12341yHlmOrR8D3vlV1cD2VtL7k9xk9DSB8vw=.
In the Permissions to other applications section, locate the Delegated
Permissions option for Windows Azure Active Directory, and then select
Sign in and read user profile.
Verify the Azure AD domain name. To do this, follow these steps.
In the portal, locate the new Active Directory.
Select Domains, select Add, and then add the root domain you want
to use (for example, edx.org). Make sure that you add the root domain
first, and then follow the TXT record verification process.
(optional) After the domain has been verified, add subdomains (for
example, courses.edx.org). Subdomains also request verification, but
do not need it.
In the Active Directory, select Applications, and then select the
application that you created.
Enable multi-tenant support.
Add the Provider Configuration
Go to <LMS URI>/admin/third_party_auth/oauth2providerconfig/. For
example, on devstack, go to
http://localhost:8000/admin/third_party_auth/oauth2providerconfig/.
Select Add Provider Configuration (OAuth).
Make sure that Enabled is selected.
Make sure that Visible is selected.
For Icon Class, enter the appropriate value.
For Google, enter fa-google-plus.
For Facebook, enter fa-facebook.
For LinkedIn, enter fa-linkedin.
For Azure, leave the field blank.
For Name, enter the appropriate value.
For Google, enter Google.
For Facebook, enter Facebook.
For LinkedIn, enter LinkedIn.
For Azure, enter Microsoft.
For Backend Name, select the appropriate value.
For Google, select google-oauth2.
For Facebook, select facebook.
For LinkedIn, select linkedin-oauth2.
For Azure, select azuread-oauth2.
Note
If the value does not appear in the list, either the
ENABLE_THIRD_PARTY_AUTH setting or the THIRD_PARTY_AUTH_BACKENDS
setting is not configured correctly.
For Client ID, enter the client ID that you noted earlier.
Leave Client Secret blank. Open edX sets the secret through
lms.yml, which is more secure.
(Optional) If you want Facebook or LinkedIn to provide the user’s email
address during registration, enter the following code into Other
settings.
For Facebook, use this code.
{
"SCOPE": ["email"],
"PROFILE_EXTRA_PARAMS": {
"fields": "id, name, email"
}
}
For LinkedIn, use this code.
{ "SCOPE": ["r_basicprofile", "r_emailaddress"], "FIELD_SELECTORS":
["email-address"] }
Select Save.
Users who have an account with the IdP that you have configured can now sign
in.
Note
For Google only, if you see the following error message, the
SOCIAL_AUTH_OAUTH_SECRETS setting is not correct.
'unicode' object has no attribute 'get'
To resolve this problem, make sure that this setting does not appear multiple
times in the lms.yml file.
Additional OAuth2 Providers (Advanced)
You can add any other third party authentication provider that supports the
OAuth2 standard to the Open edX platform. To do this, follow these steps.
Note
OAuth1 providers are also supported and can be configured using these same
steps. However, OAuth2 is preferred over OAuth1 wherever possible.
In lms.yml, change the value of FEATURES >
ENABLE_THIRD_PARTY_AUTH to true (it is false by default).
Install the python-social-auth authentication backend specific to
that provider, and determine the python module path of the backend.
If the provider is a python-social-auth supported backend, the backend
is already installed.
To determine the python module path of the backend, locate the backend in
the list of python-social-auth backends, open the file for the backend,
and locate the name of the class. The python module path is of the format
social_core.backends.<file name>.<class name>.
For example, for GitHub, the file is github.py and the class in that
file is GithubOAuth2. The backend module path is therefore
social_core.backends.github.GithubOAuth2.
If the provider is not a python-social-auth supported backend, you must
create a new Python package that includes the code required to implement
the backend. Your python package must contain a module with a class that
subclasses social_core.backends.oauth.BaseOAuth2. For more information, see
the python-social-auth documentation, or see the code of the fully
supported backends (such as Google or Facebook) for examples.
Enable the python-social-auth authentication backend specific to that
provider:
In the THIRD_PARTY_AUTH_BACKENDS setting in lms.yml, add the
full path of the module to the list.
(optional) Set the value of THIRD_PARTY_AUTH_BACKENDS to match the
default value in the aws.py file, and then add any additional backends
you need.
Obtain a client ID and client secret from the provider.
Add the client secret to lms.yml. To do this, create a new key
called SOCIAL_AUTH_OAUTH_SECRETS if it doesn’t already exist, and then
add the backend name to that key as follows.
"SOCIAL_AUTH_OAUTH_SECRETS": { "backend-name": "secret" }
If you are using Ansible, the variable to set is called
EDXAPP_SOCIAL_AUTH_OAUTH_SECRETS.
Restart the LMS server so that it will use the new settings.
Go to <LMS URI>/admin/third_party_auth/oauth2providerconfig/. For
example, on devstack, go to
http://localhost:8000/admin/third_party_auth/oauth2providerconfig/.
Select Add Provider Configuration (OAuth).
Make sure that Enabled is selected.
Make sure that Visible is selected.
For Icon Class, select one of the following options.
Use a generic icon by entering fa-sign-in.
Use a relevant Font Awesome icon.
Upload an SVG icon using the Icon Image field.
For Name, enter the name of the provider.
For Site, choose the site which you want to apply the provider config to,
if there are multiple site configurations.
For Backend Name, select the backend name from the list. (If it does not
appear in the list, either the ENABLE_THIRD_PARTY_AUTH setting or the
THIRD_PARTY_AUTH_BACKENDS setting is not configured correctly.)
For Client ID, enter the client ID that you noted earlier.
Leave Client Secret blank. Open edX sets the secret through
lms.yml, which is more secure.
Select Save.
Users can now sign in using this OAuth2 provider.
Integrating with a SAML Identity Provider
You can integrate your Open edX site with federated identity solutions
that use the Security Assertion Markup Language, version 2.0 (SAML 2.0)
standard. An example is Shibboleth, a single sign on system that is used by
many educational institutions.
Add and Enable a SAML Identity Provider
To add and enable a SAML 2.0 identity provider, follow these steps.
Log in to the Django administration console for your base URL. For example,
http://{your_URL}/admin.
In the Third_Party_Auth section, next to Provider Configuration
(SAML IdPs) select Add.
Note
If you want to change the configuration of an existing provider,
next to Provider Configuration (SAML IdPs) select Change, and then
select Update for the provider that you want to configure.
Enter the following information for the provider.
Icon class: Specifies a Font Awesome image for the button that
users will select to access the sign in page for this IdP. The fa-sign-
in icon is used by default. For university or institutional providers, a
suggested alternative is fa-university.
Name: The name of the IdP as you want it to appear on the sign in
page.
Secondary: Select this option to include the IdP in an intermediary
list of providers that users access from a Use my institution/campus
credentials button on the sign in page.
Backend name: The default, tpa-saml, is optimized for use with
Open edX and works with most SAML providers. Select a different option
only if you have added a custom backend that provides additional
functionality.
Site: Select the site that you are configuring to use this IdP. Each
IdP can only belong to one site at a time. For more information about
sites in Open edX, see Configuring Open edX Sites.
IdP slug: A short, unique name to identify this IdP in the URL. The
slug becomes part of a URL, so the value that you enter cannot include
spaces.
Entity ID: The URI that identifies the IdP. This ID must match the
value specified in the metadata XML file.
Metadata source: The URL of the XML file that contains this provider’s
metadata.
Specify your selections for any of the other, optional configuration
options. For more information about these options, see Configure the SAML Identity Provider.
When you are ready to enable the provider, select Enabled at the top of
the page. Alternatively, save your configuration settings and enable the
provider at another time.
Select Save or one of the other save options at the bottom of the page.
Next, you can test an enabled provider.
Test an Enabled SAML Provider
To verify the sign in process for an IdP that you have enabled, follow these
steps.
On the Django administration console, in the Third_Party_Auth section,
select Provider Configuration (SAML IdPs).
Check the icon in the Metadata ready column for the IdP. After the
provider’s metadata is fetched successfully from the URL that you provided
as the metadata source, a check mark in a green circle appears and the
provider is ready for use immediately.
You might need to wait 30-60 seconds for the task to complete, and then
refresh this page.
If the check mark does not appear, make sure that celery is configured
correctly and is running. You can also manually trigger an update by running
the management command ./manage.py lms saml --pull --settings=production on
fullstack or ./manage.py lms saml --pull --settings=devstack on
devstack.
For additional information about the data fetched from the IdP, on the
Django administration console select SAML Provider Data, and then select
the provider. The page that opens reports data fetched from the metadata
source URL and the date and time it was fetched.
To verify that users can use the IdP for sign in, go to the sign in page for
your LMS. The page should include the institutional sign in button.
Select Use my institutional/campus credentials. The list of providers
that appears should include the IdP that you enabled.
Configuring your Open edX Site as a SAML Service Provider
The first step in configuring your Open edX site to act as a SAML SP is
to create a credential key pair to ensure secure data transfers with identity
providers. To complete the configuration procedure, you configure your Open edX
site as a SAML SP, which creates your metadata XML file.
After you complete this configuration, you can share your metadata file with
SAML identity providers, and configure them to assert identity and access
rights for users to your installation. For more information, see
Integrating with a SAML Identity Provider.
To generate the keys for your Open edX installation, follow these steps.
On your local computer or on the server, open Terminal or a Command Prompt
and run the following command.
openssl req -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.key
Provide information at each prompt.
Two files, saml.crt and saml.key, are created in the directory where
you ran the command.
Note
Configuration settings added to the lms.yml file are reset
to their default values when you use Ansible to update edx-platform.
To configure an Open edX site with your public and private SAML keys, follow
these steps.
Open the edx/app/edxapp/lms.yml file in your text editor.
In the root of the JSON, add the SOCIAL_AUTH_SAML_SP_PUBLIC_CERT key
followed by a colon (:), a space, and an empty string where you’ll paste the
escaped certificate.
"SOCIAL_AUTH_SAML_SP_PUBLIC_CERT": "",
Open the saml.crt file, copy its entire contents, and then paste them
inside the quotes after the SOCIAL_AUTH_SAML_SP_PUBLIC_CERT parameter.
Replace all newlines with n.
"SOCIAL_AUTH_SAML_SP_PUBLIC_CERT": "-----BEGIN CERTIFICATE-----\nSWP6P/C1ypaYkmS...j9+hjvbBf3szk=\n-----END CERTIFICATE-----\n"
Add the SOCIAL_AUTH_SAML_SP_PRIVATE_KEY key followed by a colon
(:), a space, and an empty string where you’ll paste the escaped key.
"SOCIAL_AUTH_SAML_SP_PUBLIC_CERT": "-----BEGIN CERTIFICATE-----\nSWP6P/C1ypaYkmS...j9+hjvbBf3szk=\n-----END CERTIFICATE-----\n"
"SOCIAL_AUTH_SAML_SP_PRIVATE_KEY": ""
Open the saml.key file, copy its entire contents, and then paste them
inside the quotes after the SOCIAL_AUTH_SAML_SP_PRIVATE_KEY key.
Replace all newlines with n.
"SOCIAL_AUTH_SAML_SP_PUBLIC_CERT": "-----BEGIN CERTIFICATE-----\nSWP6P/C1ypaYkmS...j9+hjvbBf3szk=\n-----END CERTIFICATE-----\n"
"SOCIAL_AUTH_SAML_SP_PRIVATE_KEY": "-----BEGIN RSA PRIVATE KEY-----\nW1icmlkZN+FtM5h...s/psgLDn38Q==\n-----END RSA PRIVATE KEY-----\n"
Save and close the lms.yml file.
By default, SAML is included as an approved data format for identity providers.
The default configuration of the /edx/app/edxapp/lms.yml file does not
explicitly include the THIRD_PARTY_AUTH_BACKENDS setting.
If you have customized this file and added the THIRD_PARTY_AUTH_BACKENDS
setting to it, you might need to verify that the
common.djangoapps.third_party_auth.saml.SAMLAuthBackend python-social-auth backend class is
specified for it. That backend is required before you can add SAML IdPs.
To verify that the SAML authentication backend is loaded on a devstack or
fullstack installation, review the /edx/app/edxapp/lms.yml file.
Advanced Third Party Authentication Features
The Open edX Third Party Authentication feature offers many advanced
configuration options and integration points that can be used to customize the
sign in experience for learners using specific third party providers. None of
the following features are required for a typical installation, but they may be useful.
Skip Email Verification
When you configure an OAuth2 or SAML provider in the Django admin, there is a
boolean Skip email verification for that provider. Normally, all users are
required to verify their email address by clicking a link in the verification
email that gets automatically sent to the user upon registration. When this
option is selected, Open edX trusts that the email address provided by the
external authentication provider is correct.
If a user registering with a provider that has this option enabled, and the
user’s email address matches the email address that was sent to Open edX by the
external provider, the user’s email address will be marked as verified, and no
verification email will be required. (However, the email address sent by the
external provider is only used to pre-fill the registration form, and the user
has a chance to edit the email address on the registration form before creating
their account. If they edit their email address so that it no longer matches
the email address sent by the external provider, the user will still be
required to verify their email address as usual.)
Hinted Sign In
When you link to Open edX, you can create “hinted links” that prompt the user
to sign in using a specific provider. For example, the following link
represents a typical link to an example course.
https://courses.example.com/courses/course-v1:OrganizationX+Course101x+1T2016/courseware/3eddbb5919544c229d34b3175debc6d6/f9900289d2d0474096d20d23a1eeed81/
The following link represents a hinted link to the same course. At the end of
the URL, ?tpa_hint=oa2-google-oauth2 has been added.
https://courses.example.com/courses/course-v1:OrganizationX+Course101x+1T2016/courseware/3eddbb5919544c229d34b3175debc6d6/f9900289d2d0474096d20d23a1eeed81/?tpa_hint=oa2-google-oauth2
When users select the typical link, they go to the sign in page. When they
select the hinted link, they receive a “Would you like to sign in using your
Google credentials?” prompt that includes a large button to use Google to sign
in, as well as a small button to use other sign in options.
The intended use case of this feature is for organizations that wish to provide
a link from an on-premise system (or a course in another LMS like Canvas) to a
course in Open edX. In that case, the organizations will want students to sign
in using the organizations’ SAML providers. By using hinted links, the sign in
and/or registration process will be simpler for students, as they won’t have to
select a sign in provider or enter a password.
To create a hinted link for an OAuth2 provider, append
?tpa_hint=oa2-providername to any Open edX URL, where providername is
the “Backend Name” value from the “Provider Configuration (OAuth)” section of
the Open edX Django admin.
To create a hinted link for a SAML provider, append ?tpa_hint=saml-idpslug
to any Open edX URL, where idpslug is the “Idp slug” value from the
“Provider Configuration (SAML IdP)” section of the Open edX Django admin.
Auto-enrollment
Open edX has a feature that allows instructors, marketing teams, and others to
create links that automatically enroll students who click the link into a
specific course.
If you send users to {LMS base URL}/account/finish_auth and include
course_id, enrollment_action, and optional course_mode and
email_opt_in parameters, the system auto-enrolls the user in the
specified course.
For example, the following URL would auto-enroll the user who clicks this link
into the edX Demo course (that course’s ID,
course-v1:edX+DemoX+Demo_Course, has been url-encoded as the value of the
course_id parameter). If the user is not signed in, they are auto-enrolled
after they sign in or register.
https://courses.example.com/account/finish_auth?course_id=course-v1%3AedX%2BDemoX%2BDemo_Course&enrollment_action=enroll&email_opt_in=false
You can include the following parameters.
enrollment_action: This is required so that the auto-enrollment behavior
is triggered. It must be set to either enroll (for free courses) or
add_to_cart (for paid courses). If add_to_cart is used, learners
are directed to the e-commerce basket page rather than being instantly
enrolled.
course_id: This is required. The ID of the course to enroll the user in,
or add to cart, etc. The value must be URL-encoded.
course_mode: One of audit, honor, verified, etc. This
parameter applies only if enrollment_action is enroll. If
course_mode is not specified, and the course has more than one mode,
learners are sent to the track selection page, where they can choose which
track of the course to enroll in. If honor or audit is specified,
learners are instantly enrolled. If any other mode is specified, learners
are sent to the payment/verification flow.
email_opt_in: Can be true or false. If true, this indicates that
the user has consented to receiving marketing emails from Open edX and the
course partner.
The auto-enrollment feature can be combined with hinted sign in, if you create a URL such as the following example.
https://courses.example.com/account/finish_auth?course_id=course-v1%3AedX%2BDemoX%2BDemo_Course&enrollment_action=enroll&email_opt_in=false&tpa_hint=oa2-facebook
Secondary Providers
When you configure an OAuth2 or SAML provider in the Django admin, there is a
boolean option to mark the provider as a Secondary provider. Normally,
third party sign in providers are displayed on the Open edX sign in and
register pages. However, secondary providers are not displayed directly on the
sign in or register pages. Instead, users see a button that says “Use my
institution/campus credentials”. Clicking that will bring up a separate menu
that lists all the secondary providers.
The intended use case of this feature is to keep the sign in/register page from
being cluttered with too many buttons.
SAML Attribute Requirements
When you integrate Open edX with a SAML provider, you can allow only some users
to sign in based on some criteria. For example, organizations may not want
alumni or guest users to be able to sign in to Open edX using their SAML
provider, even though those users have valid sign in credentials for the
organization.
Users can be filtered based on eduPersonEntitlement attributes (supported
out of the box), or other attributes (requires custom code). For details on how
this can be set up, refer to this edx-code mailing list post.
Eliminating PII From Third-Party Authentication
Open edX sites and Open edX Edge do not require any personally identifiable
information (PII) about learners during third-party authentication. PII is
information that can be used to reveal an individual’s identity, such as a
name. Your identity provider (IdP) service can send only non-personal
identifiers to create Open edX site accounts for learners. If you configure
third-party authentication in this way, the Open edX site never receives PII
from your organization.
Note
The types of information that constitute PII and requirements for handling it
depend on the laws and regulations that apply to your organization. The
information in this documentation is intended to explain how Open edX sites
can be configured to handle learner data. You cannot rely on this
documentation as a source of legal guidance.
After you have configured a third-party authentication profile for an Open edX
site, the site’s sign-in page will display a button for users to access your
IdP service. Learners will access your IdP service and authenticate using their
organization credentials. Your IdP service will direct learners back to the
Open edX site’s sign-in screen with an authentication token.
The IdP authentication token includes an identifying string for a learner. This
identifier serves as a link between the identifying information that your
organization maintains for a learner and the Open edX account for that learner.
The identifying string does not need to include any PII for the learner. The
identifying string is sometimes referred to as an opaque identifier because it
does not make the identity of the learner visible.
When a learner uses third-party authentication to sign in to an Open edX site
for the first time, the Open edX site creates a learner account. The new Open
edX learner account is permanently associated with the identifying string
included in the IdP authentication token. Learners will be prompted to create
profiles by entering Open edX usernames, email addresses, and other information
in their accounts. Learners can take steps to minimize the PII in their
profiles. For more information, see
Minimizing PII in Account Profiles.
The following diagram shows how an IdP can direct a learner to an Open edX site to
create a learner account, without transmitting any PII.
You can download a report containing grades for all learners in the Open edX
courses that you run. The report includes the Open edX username for each
learner enrolled in the course, but the usernames may not correspond to learner
records that your organization maintains. If you need to match the scores for
Open edX site learners to the learner records that your organization maintains,
you can use the third- party authentication ID mapping REST API to retrieve the
user ID SAML attribute and matching Open edX username for a learner. For more
information about grade reports for Open edX courses that you run, see
Generate a Grade Report for All Learners in a Course.
The following diagram shows how an organization that uses third-party
authentication can match non-personally identifying Open edX learner usernames
with the records that the organization holds for those learners.
When your IdP directs a learner to an Open edX site for the first time, the
learner enters information to create an Open edX site account. The basic
information required for an Open edX site account is an email address, full
name, public username, password, and country. Learners may also provide
additional personal details such as gender, year of birth, and educational
background. While course teams have access to full registration information
for learners enrolled in their courses, only public usernames are used to
identify learners in course discussions and other public-facing course
interactions.
To minimize PII stored on an Open edX site, learners can limit the information
in their Open edX account profiles to the basic information required for an
Open edX site account. Additionally, learners may use random or nondescript
public usernames and create non-identifying email addresses to receive course
updates.
If you want to avoid transmitting PII for the Open edX learner accounts that
use third-party authentication, you should not include personally identifying
information in the authentication token. The only piece of information that is
required in the authentication token is the user ID, which should not be
personally identifying.
For more information about configuring the information in a third-party
authentication token, see Configure the SAML Identity Provider.
Organizations that use SAML to integrate their IdPs with Open edX need to
understand what personal information is provided to Open edX when users sign in
using SAML.
When a user uses SAML or Shibboleth to sign in to Open edX, the IdP
authoritatively asserts pieces of information about the user.
Each piece of information is called a SAML attribute. Each attribute has a
name and a formal identifier that is called an object identifier (OID)
uniform resource name (URN).
The following table lists some common attributes.
Name |
OID URN |
Example Value |
User ID |
urn:oid:0.9.2342.19200300.100.1.1
|
123456789 |
Full Name |
urn:oid:2.5.4.3
|
Donna Noble |
First Name |
urn:oid:2.5.4.42
|
Donna |
Last Name |
urn:oid:2.5.4.4
|
Noble |
Email |
urn:oid:0.9.2342.19200300.100.1.3
|
dnoble@school.edu |
eduPersonPrincipalName |
urn:oid:1.3.6.1.4.1.5923.1.1.1.6
|
dnoble@school.edu |
eduPersonEntitlement |
urn:oid:1.3.6.1.4.1.5923.1.1.1.7
|
urn:mace:school.edu:confocalMicroscope |
For more information about eduPersonPrincipalName and
eduPersonEntitlement, see eduPersonPrincipalName and
eduPersonEntitlement on the eduPerson Object Class Specification page.
When a new user uses SAML to sign in to Open edX, the IdP sends information
about the user to Open edX in the form of these attributes. These attributes
can be used to pre-fill the registration form.
For example, when a user signs in, their server may provide the following
information.
"urn:oid:0.9.2342.19200300.100.1.1: 123, urn:oid:2.5.4.3: John Smith,
urn:oid:0.9.2342.19200300.100.1.3: jsmith@school.edu"
Open edX saves the user ID because it is required to match future sign-in
attempts to the correct user account. The full name (John Smith) and email
(jsmith@school.edu) is pre-filled on the registration form, but if the user
edits those, Open edX saves only the new changed version. (For example, if the
user changes the email to jsmith@example.com, Open edX would record the
user’s email as jsmith@example.com and would not have any record of the
jsmith@school.edu address.)
By default, Open edX expects the standard User ID field
(urn:oid:0.9.2342.19200300.100.1.1) and uses that as the unique external
ID. Open edX can accept any set of attributes that a SAML IdP sends, as long as
one of the attributes is a unique, permanent identifier for the user being
authenticated. The URN or OID of the unique identifier must be specified in the
Open edX “Provider Configuration (SAML IdPs)” profile for the organization
(part of the Django administration console) in the User ID Attribute
field.
If you want to configure Open edX to always store all of the attributes that
the external IdP sends for each user, you can enable that with a
setting, as follows.
Sign in to the Django administration console for your base URL. For example,
http://{your_URL}/admin.
Go to the SAML Configuration page, and then select Add SAML
Configuration. (Do not go to the SAML Provider Configuration page.)
In the Other Config Str section, add the following code.
"EXTRA_DATA": [ "attributes" ]
This setting causes all the attributes to be saved in the
social_auth_usersocialauth table’s extra_data column for every new SAML
user. This data is only accessible by accessing the database directly or by
going to the User social auths page of the Open edX LMS Django
administration console.
For organizations that want to avoid sending any personally identifiable
information to Open edX during the SAML sign in or registration process, we
recommend that the organization configure their SAML IdP to only send a single
attribute: a unique, permanent, opaque user identifier. This should be a
value that uniquely identifies any learner or staff member, but is different
from their organization ID or any other identifier they may have.
For reporting and analytics purposes when using an opaque user identifier, the
organization can use the Third Party Auth ID Mapping API to convert Open
edX user IDs found in reports or analytics back to these opaque organization
user identifiers. Organization partners can then convert each opaque user
identifier back to the official learner ID.
Third Party Auth ID Mapping API
Open edX has an API that can be used to retrieve the association between Open
edX user IDs and the unique user identifiers sent by the external platform.
When an Open edX course is used in an on-premise environment, and SAML, LTI, or
other SSO is enabled to allow learners to authenticate to edX using their on-premise credentials, normally an on-premise identity provider (IdP) sends an
identifier. This identifier is stored in edX and linked to the edX account.
Later, when learners return from an on-premise IdP, edX can authenticate the
learner using their edX account.
Because learners may create Open edX accounts using an alternative identity,
instructors may have difficulty identifying Open edX learners in their courses.
Grade records obtained from Open edX will only contain Open edX learner IDs,
which would be unknown to the on-premise system.
This API can be used for mapping between the edX user ID and the ID provided by
the IdP. This API provides information that allows instructors or course
support staff to figure out the identity of the on-premise learners who are
using the edX course. It also allows grade information coming from Open edX to
be appropriately associated to on-premise learners for uploading to an
on-premise learning management system (LMS) or learner information
system (SIS).
This API is intended to be consumed by on-premise middleware, which combines
the information from an on-premise system. The middleware communicates with the
premise system to get information about the course and enrollment, then uses
that information to control instructor access. The instructor can then perform
tasks such as obtaining the edX learner’s on-premise identity, uploading grades
back to their LMS or SIS, and making groups based on on-premise activities.
This API also helps with the issue where learners enter incorrect email
addresses and cannot activate their accounts, and then cannot authenticate with
Open edX through SSO because of the inactive accounts. With this API,
on-premise course support staff or instructors can provide the Open edX
operator with the learner’s real edX username instead of the ID that the
IdP passed over to Open edX, so that the Open edX operator does not have
to manually query the tables to figure out the mapping between the source
system ID and the Open edX username.
Using the Third Party Auth ID Mapping API
To use the Third Party Auth ID Mapping API, follow these steps.
Have one or more third party auth providers enabled, and have learners who
have link their accounts to one or more of those providers.
Set up an OAuth2 client. To do this, open the Django administration panel,
select OAuth2, select Client, select Add Client, and then enter
the following information.
For User, create a dedicated user for this API.
For URL, Redirect URL, enter a dummy value such as
http://localhost/. The URL is not used for this API.
For Client Type, specify Confidential.
Leave other fields with the default values.
Give the new client permission to this API. To do this, go to
Third_Party_Auth, select Provider API Permissions, and then select
Add Provider API Permission.
Select the OAuth2 client that you just created, and select an external
authentication provider. This will give the new client access to query that
provider mapping.
The API is now available at {LMS base
URL}/api/third_party_auth/v0/providers/{provider_id}/users. The API client
must use OAuth2 to authenticate before that endpoint will work. The
{provider_id} value uses the same format as described in Hinted Sign In.
To test the API, follow these steps.
Use client credentials (from the django admin) to get the access token, as
follows.
curl --data "client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=client_credentials" http://localhost:8000/oauth2/access_token
Returns: {"access_token": "c1efde84445b2f256e1c80886b3f6d46339b84ee", "token_type": "Bearer", "expires_in": 31535999, "scope": ""}
Use the access token to issue requests to the API, as in the following
examples.
curl --header "Authorization: Bearer ACCESS_TOKEN" http://localhost:8000/api/third_party_auth/v0/providers/{provider_id}/users
curl --header "Authorization: Bearer ACCESS_TOKEN" http://localhost:8000/api/third_party_auth/v0/providers/{provider_id}/users?username=USERNAME1,USERNAME2
curl --header "Authorization: Bearer ACCESS_TOKEN" http://localhost:8000/api/third_party_auth/v0/providers/{provider_id}/users?username=USERNAME1&username=USERNAME2
curl --header "Authorization: Bearer ACCESS_TOKEN" http://localhost:8000/api/third_party_auth/v0/providers/{provider_id}/users?remote_id=REMOTE_ID1,REMOTE_ID2
curl --header "Authorization: Bearer ACCESS_TOKEN" http://localhost:8000/api/third_party_auth/v0/providers/{provider_id}/users?remote_id=REMOTE_ID1&remote_id=REMOTE_ID2
The following example shows a return value from the API.
{
"page": 1,
"page_size": 200,
"count": 8,
"results": [
{"username": "USERNAME1", "remote_id": "REMOTE_ID1"},
{"username": "USERNAME2", "remote_id": "REMOTE_ID2"},
]
}
This section includes information for teams involved in identity management at
Open edX installations, including development operations (DevOps) and
information technology (IT).
Enabling Timed Exams
This topic describes how to enable the timed exams feature in your instance of
Open edX.
Course teams can configure course subsections to limit the amount of time that
learners have to complete problems in that subsection.
To use this feature on your instance of Open edX, you must enable the timed
exams feature in Studio and the Learning Management System.
For information about how course teams set up timed exams, see the
Offering Timed Exams topic in Building and Running an Open edX
Course. For information about the learner experience, see
Taking a Timed Exam in the Open edX Learner’s Guide.
To enable timed exams, you modify the lms.yml and
studio.yml files, which are located one level above the edx-platform
directory.
Set the value of ENABLE_SPECIAL_EXAMS in the
lms.yml and studio.yml files to true.
# Timed exams feature flag
'ENABLE_SPECIAL_EXAMS': true,
Save the lms.yml and studio.yml files.
Restart the Studio (CMS) and Learning Management System (LMS) processes so
that your updates are loaded.
Enabling the User Retirement Feature
There have been many changes to privacy laws (for example, GDPR or the
European Union General Data Protection Regulation) intended to change the way
that businesses think about and handle Personally Identifiable Information
(PII).
As a step toward enabling Open edX to support some of the key updates in privacy
laws, edX has implemented APIs and tooling that enable Open edX instances to
retire registered users. When you implement this user retirement feature, your
Open edX instance can automatically erase PII for a given user from systems that
are internal to Open edX (for example, the LMS, forums, credentials, and other
independently deployable applications (IDAs)), as well as external systems, such
as third-party marketing services.
This section is intended not only for instructing Open edX admins to perform
the basic setup, but also to offer some insight into the implementation of the
user retirement feature in order to help the Open edX community build
additional APIs and states that meet their special needs. Custom code,
plugins, packages, or XBlocks in your Open edX instance might store PII, but
this feature will not magically find and clean up that PII. You may need to
create your own custom code to include PII that is not covered by the user
retirement feature.
Implementation Overview
In the Open edX platform, the user experience is enabled by several
services, such as LMS, Studio, ecommerce, credentials, discovery, and more.
Personally Identifiable Identification (PII) about a user can exist in many of
these services. As a consequence, to remove a user’s PII, you must be able
to request each service containing PII to remove, delete, or unlink the
data for that user in that service.
In the user retirement feature, a centralized process (the driver scripts)
orchestrates all of these requests. For information about how to configure the
driver scripts, see Setting Up the User Retirement Driver Scripts.
The User Retirement Workflow
The user retirement workflow is a configurable pipeline of building-block
APIs. These APIs are used to:
“Forget” a retired user’s PII
Prevent a retired user from logging back in
Prevent re-use of the username or email address of a retired user
Depending on which third parties a given Open edX instance integrates with,
the user retirement process may need to call out to external services or to
generate reports for later processing. Any such reports must subsequently be
destroyed.
Configurability and adaptability were design goals from the beginning, so this
user retirement tooling should be able to accommodate a wide range of Open edX
sites and custom use cases.
The workflow is designed to be linear and rerunnable, allowing recovery and
continuation in cases where a particular stage fails. Each user who has
requested retirement will be individually processed through this workflow, so
multiple users could be in the same state simultaneously. The LMS is the
authoritative source of information about the state of each user in the
retirement process, and the arbiter of state progressions, using the
UserRetirementStatus model and associated APIs. The LMS also holds a
table of the states themselves (the RetirementState model), rather than
hard-coding the states. This was done because we cannot predict all the
possible states required by all members of the Open edX community.
This example state diagram outlines the pathways users follow throughout the
workflow:
Unless an error occurs internal to the user retirement tooling, a user’s
retirement state should always land in one of the terminal states. At that
point, either their entry should be cleaned up from the
UserRetirementStatus table or, if the state is ERRORED, the
administrator needs to examine the error and resolve it. For more information,
see Recovering from ERRORED.
The User Experience
From the learner’s perspective, the vast majority of this process is obscured.
The Account page contains a new section titled Delete My Account. In this
section, a learner may click the Delete My Account button and enter
their password to confirm their request. Subsequently, all of the learner’s
browser sessions are logged off, and they become locked out of their account.
An informational email is immediately sent to the learner to confirm the
deletion of their account. After this email is sent, the learner has a limited
amount of time (defined by the --cool_off_days argument described in
Setting Up the User Retirement Driver Scripts) to contact the site administrators and rescind their
request.
At this point, the learner’s account has been deactivated, but not retired.
An entry in the UserRetirementStatus table is added, and their state set to
PENDING.
By default, the Delete My Account section is visible and the button is
enabled, allowing account deletions to queue up. The
ENABLE_ACCOUNT_DELETION feature in django settings toggles the visibility
of this section. See Django Settings.
Third Party Auth
Learners who registered using social authentication must first unlink their
LMS account from their third-party account. For those learners, the Delete
My Account button will be disabled until they do so; meanwhile, they will be
instructed to follow the procedure in this help center article: How do I link
or unlink my edX account to a social media
account?.
Setting Up User Retirement in the LMS
This section describes how to set up and configure the user retirement feature
in the Open edX LMS.
Django Settings
The following Django settings control the behavior of the user retirement
feature. Note that some of these settings values are lambda functions rather
than standard string literals. This is intentional; it is a pattern for
defining derived settings specific to Open edX. Read more about it in
openedx/core/lib/derived.py.
Setting Name |
Default |
Description |
|---|
RETIRED_USERNAME_PREFIX |
'retired__user_'
|
The prefix part of hashed usernames. Used in RETIRED_USERNAME_FMT. |
RETIRED_EMAIL_PREFIX |
'retired__user_'
|
The prefix part of hashed emails. Used in RETIRED_EMAIL_FMT. |
RETIRED_EMAIL_DOMAIN |
'retired.invalid'
|
The domain part of hashed emails. Used in RETIRED_EMAIL_FMT. |
RETIRED_USERNAME_FMT |
lambda settings:
settings.RETIRED_USERNAME_PREFIX + '{}'
|
The username field for a retired user gets transformed into this format,
where {} is replaced with the hash of their username. |
RETIRED_EMAIL_FMT |
lambda settings:
settings.RETIRED_EMAIL_PREFIX + '{}@' +
settings.RETIRED_EMAIL_DOMAIN
|
The email field for a retired user gets transformed into this format, where
{} is replaced with the hash of their email. |
RETIRED_USER_SALTS |
None |
A list of salts used for hashing usernames and emails. Only the last item in this list is used as a salt for all new retirements, but historical salts are preserved in order to guarantee that all hashed usernames and emails can still be checked. The default value MUST be overridden! |
RETIREMENT_SERVICE_WORKER_USERNAME |
'RETIREMENT_SERVICE_USER'
|
The username of the retirement service worker. |
RETIREMENT_STATES |
See lms/envs/common.py
in the RETIREMENT_STATES setting |
A list that defines the name and order of states for the retirement
workflow. See Retirement States for details. |
FEATURES[‘ENABLE_ACCOUNT_DELETION’] |
True |
Whether to display the “Delete My Account” section the account settings page. |
Retirement States
The state of each user’s retirement is stored in the LMS database, and the
state list itself is also separately stored in the database. We expect the
list of states will be variable over time and across different Open edX
installations, so it is the responsibility of the administrator to populate
the state list.
The default states are defined in lms/envs/common.py
in the RETIREMENT_STATES setting. There must be, at minimum, a PENDING
state at the beginning, and COMPLETED, ERRORED, and ABORTED states
at the end of the list. Also, for every RETIRING_foo state, there must be
a corresponding foo_COMPLETE state.
Override these states if you need to add any states. Typically, these
settings are set in lms.yml.
After you have defined any custom states, populate the states table with the
following management command:
$ ./manage.py lms --settings=<your-settings> populate_retirement_states
All states removed and new states added. Differences:
Added: set([u'RETIRING_ENROLLMENTS', u'RETIRING_LMS', u'LMS_MISC_COMPLETE', u'RETIRING_LMS_MISC', u'ENROLLMENTS_COMPLETE', u'LMS_COMPLETE'])
Removed: set([])
Remaining: set([u'ERRORED', u'PENDING', u'ABORTED', u'COMPLETE'])
States updated successfully. Current states:
PENDING (step 1)
RETIRING_ENROLLMENTS (step 11)
ENROLLMENTS_COMPLETE (step 21)
RETIRING_LMS_MISC (step 31)
LMS_MISC_COMPLETE (step 41)
RETIRING_LMS (step 51)
LMS_COMPLETE (step 61)
ERRORED (step 71)
ABORTED (step 81)
COMPLETE (step 91)
In this example, some states specified in settings were already present, so
they were listed under Remaining and were not re-added. The command output
also prints the Current states; this represents all the states in the
states table. The populate_retirement_states command is idempotent, and
always attempts to make the states table reflect the RETIREMENT_STATES
list in settings.
Retirement Service User
The user retirement driver scripts authenticate with the LMS and IDAs as the
retirement service user with oauth client credentials. Therefore, to use the
driver scripts, you must create a retirement service user, and generate a DOT
application and client credentials, as in the following command.
app_name=retirement
user_name=retirement_service_worker
./manage.py lms --settings=<your-settings> manage_user $user_name $user_name@example.com --staff --superuser
./manage.py lms --settings=<your-settings> create_dot_application $app_name $user_name
Note
The client credentials (client ID and client secret) will be printed to the
terminal, so take this opportunity to copy them for future reference. You
will use these credentials to configure the driver scripts. For more
information, see Setting Up the User Retirement Driver Scripts.
The retirement service user needs permission to perform retirement tasks, and
that is done by specifying the RETIREMENT_SERVICE_WORKER_USERNAME variable
in Django settings:
RETIREMENT_SERVICE_WORKER_USERNAME = 'retirement_service_worker'
Django Admin
The Django admin interface contains the following models under USER_API
that relate to user retirement.
Name |
URI |
Description |
|---|
Retirement States |
/admin/user_api/retirementstate/
|
Represents the table of states defined in RETIREMENT_STATES and
populated with populate_retirement_states. |
User Retirement Requests |
/admin/user_api/userretirementrequest/
|
Represents the table that tracks the user IDs of every learner who
has ever requested account deletion. This table is primarily used for
internal bookkeeping, and normally isn’t useful for administrators. |
User Retirement Statuses |
/admin/user_api/userretirementstatus/
|
Model for managing the retirement state for each individual learner. |
In special cases where you may need to manually intervene with the pipeline,
you can use the User Retirement Statuses management page to change the
state for an individual user. For more information about how to handle these
cases, see Handling Special Cases.
Setting Up the User Retirement Driver Scripts
Tubular (edx/tubular on github) is a
repository of Python 3 scripts designed to plug into various automation
tooling. Included in Tubular are two scripts intended to drive the user
retirement workflow.
scripts/get_learners_to_retire.pyGenerates a list of users that are ready for immediate retirement. Users
are “ready” after a certain number of days spent in the PENDING state,
specified by the --cool_off_days argument. Produces an output intended
for consumption by Jenkins in order to spawn separate downstream builds for
each user.
scripts/retire_one_learner.pyRetires the user specified by the --username argument.
These two scripts share a required --config_file argument, which specifies
the driver configuration file for your environment (for example, production).
This configuration file is a YAML file that contains LMS auth secrets, API URLs,
and retirement pipeline stages specific to that environment. Here is an example
of a driver configuration file.
client_id: <client ID for the retirement service user>
client_secret: <client secret for the retirement service user>
base_urls:
lms: https://courses.example.com/
ecommerce: https://ecommerce.example.com/
credentials: https://credentials.example.com/
retirement_pipeline:
- ['RETIRING_EMAIL_LISTS', 'EMAIL_LISTS_COMPLETE', 'LMS', 'retirement_retire_mailings']
- ['RETIRING_ENROLLMENTS', 'ENROLLMENTS_COMPLETE', 'LMS', 'retirement_unenroll']
- ['RETIRING_LMS_MISC', 'LMS_MISC_COMPLETE', 'LMS', 'retirement_lms_retire_misc']
- ['RETIRING_LMS', 'LMS_COMPLETE', 'LMS', 'retirement_lms_retire']
The client_id and client_secret keys contain the oauth credentials.
These credentials are simply copied from the output of the
create_dot_application management command described in
Retirement Service User.
The base_urls section in the configuration file defines the mappings of
IDA to base URLs used by the scripts to construct API URLs. Only the LMS is
mandatory here, but if any of your pipeline states contain API calls to other
services, those services must also be present in the base_urls section.
The retirement_pipeline section defines the steps, state names, and order
of execution for each environment. Each item is a list in the form of:
Start state name
End state name
IDA to call against (LMS, ECOMMERCE, or CREDENTIALS currently)
Method name to call in Tubular’s
edx_api.py
For example: ['RETIRING_CREDENTIALS', 'CREDENTIALS_COMPLETE', 'CREDENTIALS',
'retire_learner'] will set the user’s state to RETIRING_CREDENTIALS, call
a pre-instantiated retire_learner method in the CredentialsApi, then set
the user’s state to CREDENTIALS_COMPLETE.
Examples
The following are some examples of how to use the driver scripts.
Set Up Environment
Set up your execution environment.
git clone https://github.com/edx/tubular.git
cd tubular
virtualenv --python=`which python3` venv
source venv/bin/activate
List of Targeted Learners
Generate a list of learners that are ready for retirement (those learners who
have selected and confirmed account deletion and have been in the PENDING
state for the time specified cool_off_days).
mkdir learners_to_retire
scripts/get_learners_to_retire.py \
--config_file=path/to/config.yml \
--output_dir=learners_to_retire \
--cool_off_days=5
Run Retirement Script
After running these commands, the learners_to_retire directory contains
several INI files, each containing a single line in the form of USERNAME
=<username-of-learner>. Iterate over these files while executing the
retire_one_learner.py script on each learner with a command like the following.
scripts/retire_one_learner.py \
--config_file=path/to/config.yml \
--username=<username-of-learner-to-retire>
Using the Driver Scripts in an Automated Framework
At edX, we call the user retirement scripts from
Jenkins jobs on one of our internal Jenkins
services. The user retirement driver scripts are intended to be agnostic
about which automation framework you use, but they were only fully tested
from Jenkins.
For more information about how we execute these scripts at edX, see the
following wiki articles:
And check out the Groovy DSL files we use to seed these jobs:
Handling Special Cases
Recovering from ERRORED
If a retirement API indicates failure (4xx or 5xx status code), the driver
immediately sets the user’s state to ERRORED. To debug this error state,
check the responses field in the user’s row in
user_api_userretirementstatus (User Retirement Status) for any relevant
logging. Once the issue is resolved, you need to manually set the user’s
current_state to the state immediately prior to the state which should be
re-tried. You can do this using the Django admin. In this example, a user
retirement errored during forums retirement, so we manually reset their state
from ERRORED to ENROLLMENTS_COMPLETE.
Now, the user retirement driver scripts will automatically resume this user’s
retirement the next time they are executed.
Rerunning some or all states
If you decide you want to rerun all retirements from the beginning, set
current_state to PENDING for all retirements with current_state ==
COMPLETE. This would be useful in the case where a new stage in the user
retirement workflow is added after running all retirements (but before the
retirement queue is cleaned up), and you want to run all the retirements
through the new stage. Or, perhaps you were developing a stage/API that
didn’t work correctly but still indicated success, so the pipeline progressed
all users into COMPLETED. Retirement APIs are designed to be idempotent,
so this should be a no-op for stages already run for a given user.
Cancelling a retirement
Users who have recently requested account deletion but are still in the
PENDING retirement state may request to rescind their account deletion by
emailing or otherwise contacting the administrators directly. edx-platform
offers a Django management command that administrators can invoke manually to
cancel a retirement, given the user’s email address. It restores a given
user’s login capabilities and removes them from all retirement queues. The
syntax is as follows:
$ ./manage.py lms --settings=<your-settings> cancel_user_retirement_request <email-of-user-to-cancel-retirement>
Keep in mind, this will only work for users which have not had their retirement
states advance beyond PENDING. Additionally, the user will need to reset
their password in order to restore access to their account.
Setting Up the YouTube API Key
This topic describes how to set the YouTube API key for your instance of
Open edX.
If you intend for courses on your Open edX instance to include videos that are
hosted on YouTube, you must get a YouTube API key and set the key in the
Open edX Platform.
The Open edX Platform uses the YouTube Data API v3, which requires that
the application uses an API key.
After you obtain a YouTube API key, you must install that key into your
Open edX installation. There are two different ways you can do this.
Ansible is the automation system used for installing and updating Open edX.
If you set your YouTube API key in Ansible’s configuration file, then Ansible
will make sure that the YouTube API key remains in place when you update Open
edX.
To set your YouTube API key in Ansible’s configuration file, follow these
steps.
Find the configuration repository on your Open edX server. If you are
running devstack or fullstack, the directory is
/edx/app/edx_ansible/edx_ansible.
In that repository, open the playbooks/roles/edxapp/defaults/main.yml
file in a text editor.
Find the line for the YouTube API key.
EDXAPP_YOUTUBE_API_KEY: "PUT_YOUR_API_KEY_HERE"
Replace PUT_YOUR_API_KEY_HERE with your YouTube API key. Ensure
that the YouTube API key is within by quotation marks.
Save and close the file.
Run Ansible so that it applies your YouTube API key to your Open edX
installation.
For example, if you are running the Open edX Cypress release, run the
following command.
/edx/bin/update edx-platform named-release/cypress
Ansible outputs information to several JSON files used by Open edX. If you
prefer not to edit the Ansible configuration, you can edit these files
directly.
However, every time you update Open edX, your edits will be overwritten by
Ansible. As a result, we recommend setting your YouTube API key in Ansible’s
configuration instead.
To set your YouTube API key by editing JSON files, complete the following
steps.
Find the edx-platform repository on your Open edX server. If you are
running devstack or fullstack, the directory is
/edx/app/edxapp/edx-platform.
In the directory above your repository, there should be several JSON
files, including lms.yml and studio.yml. If you are running
devstack or fullstack, the directory is /edx/app/edxapp.
Open the lms.yml file in your text editor.
Find the line for the YouTube API key.
"YOUTUBE_API_KEY": "PUT_YOUR_API_KEY_HERE",
Replace PUT_YOUR_API_KEY_HERE with your YouTube API key. Verify
that the YouTube API key is between the quotation marks.
Save and close the file.
Open the studio.yml file and make the same change. If that line does
not exist in this file, create it.
Save and close the file.
Installing an XBlock
The XBlock framework allows developers to expand the Open edX platform by
building different learning experiences and deploying them as XBlocks. Before
course teams can use an XBlock in courses running on an instance of the
Open edX platform, both of the following tasks must be completed.
To install an XBlock, follow these steps.
Obtain the GitHub location and commit, or PyPi package name and version,
for the XBlock.
Run pip along with either the GitHub link to the XBlock or the PyPi
package name.
An example of the GitHub link that installs the Oppia XBlock follows.
pip install git+https://github.com/oppia/xblock.git@9f6b95b7eb7dbabb96b77198a3202604f96adf65#egg=oppia-xblock==0.0.0
An example of the PyPi package name that installs the Peer Instruction
XBlock follows.
pip install ubcpi-xblock==0.4.4
The course teams that want to include components that use the XBlock can then
enable the XBlock for their courses. To do so, they add the name specified in
the XBlock’s setup.py file to each course’s advanced module list. For more
information, see Enabling Additional Exercises and Tools.
Enabling a CDN for Course Assets
By default, all course assets are served directly from your Open edX instance.
For courses with large enrollments, or courses with large assets, such as high-
quality images, PDFs, or video files, this can increase not only the load on
the instance but also the time it takes for learners to load the courses on
their computers and mobile devices.
You can configure your Open edX instance to serve assets from a content
delivery network (CDN) instead. Using a CDN offloads the work required to
deliver assets from your Open edX instance.
Note
Whether you need a CDN depends on the type, and amount, of content
in your courses. Not all installations need a CDN for their course assets.
A CDN, or content delivery network, is a service that places servers all around
the world, and keeps copies of content on those servers. Instead of serving
files from one location, a CDN serves them from whichever server is closest to
the end user. This results in faster download speeds and, ultimately, faster
page loads.
When you configure a CDN for use with your Open edX instance, you should
identify your Open edX instance as the origin server.
Choose the cache expiration carefully: you want content to be cached long
enough to keep the load on your Open edX instance low, but not so long that
changes made to course assets are not realized within a reasonable amount of
time. As a starting point, edX recommends a cache expiration period of one
hour.
After you configure your CDN, follow these steps.
Sign in to the Django administration console for your base URL. For example,
http://{your_URL}/admin.
In the Static_Replace section, next to Asset base url configs,
select Add.
Select Enabled.
Enter the hostname for your CDN provider.
For example, if you were using CloudFront, this would look something like
d37djvu3ytnwxt.cloudfront.net.
Be sure not to include the scheme (http:// or https://) when you
specify the hostname.
Select Save.
Enabling the Weekly Learning Goals Feature
The feature adds a new Weekly Learning Goal widget to the course home page.
To use it, learners select a weekly learning goal and are automatically subscribed to goal reminder emails. The weekly reminders continue until the learner completes their course and/or their audit access ends. Learners can modify/cancel their goal and reminder settings at any time from the widget or via links in the email.
For more details on this feature or screenshots see this blog post.
Note
This feature is only available on the new learning micro frontend. If that is not already enabled for you, you can view instructions here.
The following waffle flag needs to be enabled:
course_experience.enable_course_goals
To send goal reminder emails, you need to regularly run the following management command.
edx.org runs this command at the following cron schedule H */3 * * *
The script does a number of checks before sending emails. There are five main conditions that must be met in order for an email to be sent, otherwise an email will not be sent:
The script will check the number of days left for a learner to successfully hit their goal compared to the learning goal selected by the learner (i.e. if the learner has chosen to learn once per week, three times per week, or five times per week)
If you’re not actively enrolled in the course or your enrollment was this week
If an audit user’s access expires this week, exclude them from the email since they may not be able to hit their goal anyway
If a user has a downloadable certificate, we will consider them as having completed the course and opt them out of receiving emails
We want to email users during the morning of their timezone
![digraph retirement_states_example {
ranksep = "0.3";
node[fontname=Courier,fontsize=12,shape=box,group=main]
{ rank = same INIT[style=invis] PENDING }
INIT -> PENDING;
"..."[shape=none]
PENDING -> RETIRING_ENROLLMENTS -> ENROLLMENTS_COMPLETE -> RETIRING_FORUMS -> FORUMS_COMPLETE -> "..." -> COMPLETE;
node[group=""];
RETIRING_ENROLLMENTS -> ERRORED;
RETIRING_FORUMS -> ERRORED;
PENDING -> ABORTED;
subgraph cluster_terminal_states {
label = "Terminal States";
labelloc = b // put label at bottom
{rank = same ERRORED COMPLETE ABORTED}
}
}](_images/graphviz-d9748f4808f97b9345d79587d10ca38fbc8fb31b.png)
![digraph retirement_states_example {
//rankdir=LR; // Rank Direction Left to Right
ranksep = "0.3";
edge[color=grey]
node[fontname=Courier,fontsize=12,shape=box,group=main]
{ rank = same INIT[style=invis] PENDING }
{
edge[style=bold,color=black]
INIT -> PENDING;
"..."[shape=none]
PENDING -> RETIRING_ENROLLMENTS -> ENROLLMENTS_COMPLETE -> RETIRING_FORUMS;
}
RETIRING_FORUMS -> FORUMS_COMPLETE -> "..." -> COMPLETE
node[group=""];
RETIRING_ENROLLMENTS -> ERRORED;
RETIRING_FORUMS -> ERRORED[style=bold,color=black];
PENDING -> ABORTED;
subgraph cluster_terminal_states {
label = "Terminal States";
labelloc = b // put label at bottom
{rank = same ERRORED COMPLETE ABORTED}
}
ERRORED -> ENROLLMENTS_COMPLETE[style="bold,dashed",color=black,label=" via django\nadmin"]
}](_images/graphviz-93479794f498b69c155679964c3bdb4b14c8678c.png)
