SAML SSO User Creation Causes Keycloak External ID and Sunbird User ID Mismatch Leading to Enrollment and Certificate Failures

[suraj-tekdi]

Issue: SAML SSO User Creation Causes Keycloak External ID and Sunbird User ID Mismatch Leading to Enrollment and Certificate Failures

Environment

• NULP Deployment
• Keycloak 7
• Cassandra User Storage Provider enabled
• SAML Identity Federation configured in Keycloak
• User creation through /api/user/v1/sso/create

Problem Statement

When a user logs in through SAML SSO, Keycloak generates an external identity (available in JWT sub claim).

Example:

JWT sub (External ID):
e78c30c5-0ad9-4afe-a99d-406051fb4c69

We create the corresponding Sunbird user using:

POST /api/user/v1/sso/create

Request:

{
  "params": {
    "signupType": "sso"
  },
  "request": {
    "firstName": "User Name",
    "channel": "nulp-mainorg",
    "externalIds": [
      {
        "id": "e78c30c5-0ad9-4afe-a99d-406051fb4c69",
        "provider": "nulp-mainorg",
        "idType": "nulp-mainorg"
      }
    ],
    "email": "user@example.com",
    "emailVerified": true
  }
}

Response:

{
  "result": {
    "userId": "6121eabc-7a56-4108-8e74-72bc8e936119"
  }
}

This creates the expected mapping:

External ID (Keycloak/SAML)
e78c30c5-0ad9-4afe-a99d-406051fb4c69

↓

Sunbird User ID
6121eabc-7a56-4108-8e74-72bc8e936119

Verified in Cassandra:

SELECT * FROM usr_external_identity
WHERE externalid='e78c30c5-0ad9-4afe-a99d-406051fb4c69';

Result:

userid     = 6121eabc-7a56-4108-8e74-72bc8e936119
externalid = e78c30c5-0ad9-4afe-a99d-406051fb4c69

Issue Observed

While the SSO mapping is created correctly, course enrollment is getting stored against the external identity instead of the actual Sunbird user ID.

Enrollment request:

POST /learner/course/v1/enrol

Payload:

{
  "request": {
    "courseId": "do_114582226199396352116",
    "userId": "6121eabc-7a56-4108-8e74-72bc8e936119",
    "batchId": "0145848852057456642"
  }
}

However, Cassandra stores:

userid = e78c30c5-0ad9-4afe-a99d-406051fb4c69

instead of:

userid = 6121eabc-7a56-4108-8e74-72bc8e936119

Verified in:

SELECT * FROM sunbird_courses.user_enrolments
WHERE userid='e78c30c5-0ad9-4afe-a99d-406051fb4c69';

Multiple enrollments exist against the external ID.

No enrollments exist for:

SELECT * FROM sunbird_courses.user_enrolments
WHERE userid='6121eabc-7a56-4108-8e74-72bc8e936119';

Impact

Certificate generation fails because the certificate processor expects Sunbird user IDs.

Observed error:

Error from get API:
/learner/private/user/v1/read/e78c30c5-0ad9-4afe-a99d-406051fb4c69

UOS_USRRED0013
Requested user resource not found

Certificate job payload contains:

userIds -> List(e78c30c5-0ad9-4afe-a99d-406051fb4c69)

The processor attempts:

GET /private/user/v1/read/e78c30c5-0ad9-4afe-a99d-406051fb4c69

which fails because the API expects a Sunbird user ID, not an external identity.

Expected Behaviour

After SSO login:

JWT sub (externalId)
        ↓
Lookup through usr_external_identity
        ↓
Resolve Sunbird userId
        ↓
Enrollments, progress, certificates and telemetry should use Sunbird userId

Expected enrollment record:

userid = 6121eabc-7a56-4108-8e74-72bc8e936119

Actual enrollment record:

userid = e78c30c5-0ad9-4afe-a99d-406051fb4c69

Request

Please clarify:

1. Whether /learner/course/v1/enrol is expected to use the authenticated actor ID instead of request.userId.
2. Whether SSO users created through /api/user/v1/sso/create require additional user resolution before enrollment.
3. The recommended approach for ensuring enrollments, progress tracking, and certificate generation use the mapped Sunbird user ID rather than the external SSO identity.

[chethann007]

Hi @suraj-tekdi , two quick things we need to confirm:

1. JWT sub during enrollment
When the enrollment API is called, decode the X-Authenticated-User-Token header (you can use jwt.io) and share the exact sub claim value. Is it plain e78c30c5-0ad9-4afe-a99d-406051fb4c69 or does it have a prefix like f:<something>:e78c30c5-...?

2. Keycloak user check
In Keycloak Admin Console → Realm: sunbird → Users — search for 6121eabc-7a56-4108-8e74-72bc8e936119. Does a user with that ID exist?