Testing SAML Authentication Locally with MockSAML

Testing SAML Authentication Locally with MockSAML#

This guide walks through setting up and testing SAML authentication in a local Open edX devstack environment using MockSAML.com as a test Identity Provider (IdP).

Overview#

SAML (Security Assertion Markup Language) authentication in Open edX requires three configuration objects to work together:

  1. SAMLConfiguration: Configures the Service Provider (SP) metadata - entity ID, keys, and organization info

  2. SAMLProviderConfig: Configures a specific Identity Provider (IdP) connection with metadata URL and attribute mappings

  3. SAMLProviderData: Stores the IdP’s metadata (SSO URL, public key) fetched from the IdP’s metadata endpoint

Critical Requirement: The SAMLConfiguration object MUST have the slug “default” because this value is hardcoded in the authentication execution path at common/djangoapps/third_party_auth/models.py:906.

Prerequisites#

Step 1: Configure SAMLConfiguration#

The SAMLConfiguration defines your Open edX instance as a SAML Service Provider (SP).

  1. Navigate to Django Admin → Third Party Auth → SAML Configurations

  2. Click “Add SAML Configuration”

  3. Configure with these required values:

    Field

    Value

    Site

    localhost:18000

    Slug

    default (MUST be “default” - hardcoded in code)

    Entity ID

    https://saml.example.com/entityid

    Enabled

    ✓ (checked)

  4. For local testing with MockSAML, you can leave the keys blank.

  5. Optionally configure Organization Info (use default or customize):

    {
  "en-US": {
    "url": "http://localhost:18000",
    "displayname": "Local Open edX",
    "name": "localhost"
  }
}

  6. Click “Save”

Step 2: Configure SAMLProviderConfig#

The SAMLProviderConfig connects to a specific SAML Identity Provider (MockSAML in this case).

  1. Navigate to Django Admin → Third Party Auth → Provider Configuration (SAML IdPs)

  2. Click “Add Provider Configuration (SAML IdP)”

  3. Configure with these values:

  4. Leave all attribute mappings (User ID, Email, Full Name, etc.) blank to use defaults

  5. Click “Save”

Important: The Entity ID in SAMLProviderConfig MUST match the Entity ID in SAMLConfiguration.

Step 3: Set IdP Data#

The SAMLProviderData stores metadata from the Identity Provider (MockSAML), create a record with

Step 4: Test SAML Authentication#

  1. Navigate to: http://localhost:18000/auth/idp_redirect/saml-default

  2. You should be redirected to MockSAML.com

  3. Complete the authentication on MockSAML - just click “Sign In” with whatever is in the form.

  4. You should be redirected back to Open edX

  5. If this is a new user, you’ll see the registration form

  6. After registration, you should be logged in

Expected Behavior#

  1. Initial redirect to MockSAML (https://mocksaml.com/api/saml/sso)

  2. MockSAML displays the login page

  3. After authentication, MockSAML POSTs the SAML assertion back to Open edX

  4. Open edX validates the assertion and creates/logs in the user

  5. User is redirected to the dashboard or registration form (if new user)

Reference Configuration#

Here’s a summary of a working test configuration:

SAMLConfiguration (id=6):

SAMLProviderConfig (id=11):

SAMLProviderData (id=3):

MockSAML Configuration: