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.
To use the Third Party Auth ID Mapping API, follow these steps.
http://localhost/
. The URL is not used for this API.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"}, ] }