Index
+ +
+
+
+
+
+
+ ' + + '' + + _("Hide Search Matches") + + "
" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/genindex.html b/genindex.html new file mode 100644 index 00000000..5833f7c4 --- /dev/null +++ b/genindex.html @@ -0,0 +1,83 @@ + + + + + + +This application provides a central system to handle ecommerce activities across the Open Learning web applications.
+The goal of the Unified Ecommerce system is to:
+Provide a single interface that can be used across applications and brands to unify the checkout experience for end users
Provide a single interface for managing products, discounts, and financial assistance
Provide a clearinghouse for post-sale events and data
Reduce the load of implementing new features and responding to new requirements
+ Searching for multiple words only shows matches that contain + all words. +
+ + + + + + + + + +The Unified Ecommerce application expects to be run behind the APISIX API gateway. APISIX’s main job is to coordinate the integration between the application and SSO.
+The Unified Ecommerce application doesn’t have (or need) its own login UI. It’s intended to be used in conjunction with other systems, so it needs to share authentication and accounts with those systems. In addition, these accounts all need to be in sync with each other.
+We’ve chosen Keycloak as the authentication system for Open Learning applications. It is the source of truth for user information and authentication, and other Open Learning applications are configured to use it for authentication. They redirect the user to Keycloak, and then Keycloak verifies the user and sends them back to the application (via OAuth2/OIDC).
+For UE, APISIX handles this integration with Keycloak. For certain API endpoints, APISIX itself checks for a session and redirects the user through Keycloak. It then passes the user on to UE and attaches a payload of the user data in the headers. UE can then set up the Django session, create or update the local user account, and check permissions as it needs.
+UE doesn’t have to coordinate with Keycloak or use OIDC at all in this scenario. APISIX controls that. Additionally, the APISIX configuration can be shared across services, so ideally everything routes through it, and users can seamlessly transition between individual applications after authenticating once.
+Unified Ecommerce API endpoints generally fall into one of three categories:
+Anonymous access: a number of APIs are accessible anonymously. (Product information falls into this category.)
Authenticated access: other APIs require a session to be established within Unified Ecommerce. (Basket and order information APIs are in this category.)
Transitional access: specific APIs that handle transition between anonymous and authenticated access. (Essentially, login.)
For anonymous access APIs, APISIX is configured to pass these along without change or processing. Any existing Django session will be used.
+For authenticated access APIs, APISIX is configured in the same way, and passes these along as well. The user will receive an error if the Django session isn’t established beforehand.
+Transitional access APIs involve the APISIX OIDC integration.
++ --- +title: Session Establishment +--- +flowchart LR + accessEndpoint["User hits the endpoint"] + hasApisixSession["User has an APISIX session"] + redirectSso["Redirected to Keycloak SSO"] + ssoAuth["Log in via SSO"] + ssoAuthOk["SSO Auth OK"] + ssoAuthBad["SSO Auth Fail"] + apisixAuth["Session setup in APISIX"] + intoDjango["Redirect into Django"] + fail["Auth failed"] + + accessEndpoint --> hasApisixSession + hasApisixSession --> intoDjango + hasApisixSession --> redirectSso + redirectSso --> ssoAuth + ssoAuth --> ssoAuthBad + ssoAuth --> ssoAuthOk + ssoAuthOk --> apisixAuth + ssoAuthBad --> fail + apisixAuth --> intoDjango +
Since APISIX sits before the Django app, it will first check to see if the user has a session established in APISIX. If it does, then the user is passed along to the Django app. If not, the user is redirected into Keycloak to log in. Assuming that succeeds, APISIX receives the user back, sets up its own session, and then sends the user to the Django app with the APISIX payload attached. (If the user can’t get past Keycloak, the process stops.)
+APISIX attaches user information in a special X-UserInfo header. A middleware within the Django app processes this header, either updates or creates a user account, and establishes a Django session for the account with the data contained within.
This workflow is used by the /establish_session endpoint. The frontend calls an endpoint to retrieve the current user data, and redirects the user to /establish_session if the user’s not logged in. This endpoint then logs the user in with the processed APISIX data, starts a Django session, and sends the user back to the frontend. The user can then use the rest of the API as an authenticated user.
When configured to use authentication via OIDC Connect, APISIX returns the user data back to the application by injecting it into the HTTP headers sent to the app. A custom middleware in the application decodes this data, and takes action based on it.
+APISIX sends user data retrieved via OIDC in the X-UserInfo header. The data is sent as a base64-encoded JSON object, and its contents may vary but include:
The user’s email address (email)
The UUID associated with the user in the SSO system (preferred_username)
The user’s first and last name (given_name, family_name)
The middleware creates or updates the user account based on this data and sets the session user appropriately.
+Note
+Regular forward authentication doesn’t include the user data. If we used that, the app would have to perform a round-trip to Keycloak to retrieve it.
+Having the app configured in this way means that it must sit behind APISIX. At time of writing, the APISIX middleware also blindly trusts the payload that APISIX sends along. So, the Django app must not be exposed directly to the Internet when it is deployed.
+Certain operations within Unified Ecommerce trigger events, and those events can send data to the relevant configured integrated systems.
+The integrated system model has a field for a webhook URL. Data for all events are sent to this URL. The integrated system itself decides whether or not to take action on the data.
+These are the events that are triggered:
+Event (in UE) |
+Type |
+Description |
+
|---|---|---|
|
+
|
+Triggered when an item is added to the basket. |
+
|
+
|
+Triggered when an order has been completed successfully. |
+
|
+
|
+Triggered when an item has been refunded from a completed order. |
+
Note
+The Event tracks the plugin hook spec that is called to generate the event.
+The event data is wrapped in a standard container (implemented in payments/serializers/v0 as the WebhookBase dataclass):
system_slug: the system slug for the data being sent
system_key: the shared key for the system
user: nested object containing user information
type: the event type (see table above)
data: event-specific data
Each system will only get the data that is relevant to itself, which will be indicated by the system_slug attribute. The system should verify the slug and key sent are valid, and emit a 401 error if they aren’t.
User data includes:
+id: the ID of the purchaser (this is Unified Ecommerce’s ID)
username: the username of the purchaser (this will be a UUID corresponding to a Keycloak user)
email: the email address of the purchaser
first_name: the purchaser’s first name
last_name: the purchaser’s last name
The data attribute differs depending on what event is being sent.
For presale:
action: either “add” or “remove”
product: the product added or removed to the basket
For postsale:
reference_number: the reference number of the order. (Despite this saying “number” this is generally a string.)
total_price_paid: the total amount paid for the order, inclusive of any discounts and taxes assessed.
state: the state of the order. This should always be fulfilled.
lines: array of line items for the order
Line data includes:
id: an ID for the line item
quantity: quantity on order
item_description: description of the item
unit_price: the unit price (before tax/discounts) of the item
total_price: the amount charged for the item
product: the product
Product data includes (just relevant fields):
id: an ID for the product
sku: the product’s SKU. By convention, this should be the readable ID of the resource in the integrated system.
name: the product’s name
description: the product’s description
system_data: JSON; system-specific data. This is defined by the integrated system.
price: the base price of the product
The event system is built using Pluggy, REST framework serializers, and Celery tasks. The hookspecs listed in the table in Events have a hook implementation that queues a task to send the data to the target URL(s) without blocking the user.
+