Integration for Microcredentials

[richard015ar]

As a

Network Administrator

I want

the SAML SSO plugin to work seamlessly with pressbooks-microcredentials for single sign-on authentication

So that

users from institutions with SAML/Shibboleth identity providers can authenticate once and access microcredential content without separate login credentials, maintaining the same SSO experience they have with Pressbooks

Context

Current Analysis:
Based on initial investigation, the SAML SSO plugin should work with minimal or no changes for Microcredentials because:

• It's site-wide authentication (doesn't depend on post types or content)
• Simply authenticates users at WordPress login level
• Creates accounts with pressbooks_saml_identity user meta
• Microcredentials on same multisite network should inherit SSO
  In fact, we did a quick PoC and it worked locally, see demo here.
  We also need to review points mentioned here: https://docs.google.com/document/d/1K-pQf1shTyCqCI4MlLUf1v3hU8xIXgWbTK_nmioY--E/edit?tab=t.0#heading=h.7dntw8cumy21

What Needs Verification:

1. Confirm SAML works on MC sites without Pressbooks core
2. Remove/replace any Pressbooks\Container dependencies
3. Test end-to-end authentication flow
4. Define role mapping for MC context
5. Document configuration for MC networks

SAML Plugin Architecture:

Component	Purpose
SAML class	Core authentication flow using OneLogin PHP SAML Toolkit
Admin class	Network admin settings page for IdP configuration
User matching	Match by pressbooks_saml_identity user meta → fallback to email
Provisioning	refuse (deny new users) or create (auto-register)

Authentication Flow:

1. User clicks "Connect via SAML2" on wp-login.php
   └── Redirect to IdP with AuthnRequest

2. IdP authenticates user, returns SAML assertion
   └── POST to /wp-login.php?action=pb_shibboleth_acs

3. Plugin parses assertion, extracts attributes:
   └── uid (urn:oid:0.9.2342.19200300.100.1.1)
   └── mail (urn:oid:0.9.2342.19200300.100.1.3)
   └── eduPersonPrincipalName (optional fallback)

4. Match user:
   └── Check user_meta `pressbooks_saml_identity` = "{net_id}|timestamp"
   └── If not found, try email match
   └── If not found, create or refuse based on config

5. Login user via programmatic_login()
   └── Redirect to original page (tracked in $_SESSION)

Acceptance Criteria

Compatibility Verification

• SAML plugin activates on MC network without errors and works in PB and MC
• Confirm possible design changes with Michelle
• No fatal errors from Pressbooks\Container dependencies
• Admin settings page loads and saves correctly
• IdP configuration can be saved and retrieved

Authentication Flow

• "Connect via SAML2" button appears on login page
• Clicking initiates redirect to IdP
• Successful IdP auth returns to MC site
• User is logged into WordPress
• Session redirect works (returns to original page)
• Logout works correctly (SP-initiated logout if configured)

User Provisioning

• Existing users matched by pressbooks_saml_identity meta
• Existing users matched by email (fallback)
• New user creation works (when provisioning=create)
• New user denial works (when provisioning=refuse)
• pressbooks_saml_identity meta set on new users

Role Mapping

• Define appropriate default role for MC sites
• Role mapping from SAML attributes (if applicable)
• Super admin role protection
• Role assignment on specific MC sites

Multi-site Behavior

• SSO works across all MC sites in network
• User can access MC sites they have access to
• Access to new MC sites doesn't require re-auth
• Site-specific role assignment works

Code Changes (if needed)

• Replace Pressbooks\Container with app() helper
• Replace any PB-specific function calls such as programmatic_login() for example
• Maintain backward compatibility with Pressbooks networks
• No breaking changes to existing SAML config

Documentation

• Update README for MC context
• Document IdP configuration for MC
• Document role mapping configuration
• Troubleshooting guide

Out of Scope

• LTI-initiated SAML authentication (separate consideration)
• Multiple IdP support per network
• Custom attribute mapping UI
• SAML-based authorization (beyond authentication)
• IdP-initiated SSO (if not currently supported)

Technical Notes

Key Config Options:

Option	Values	Description
idp_entity_id	URL	Identity Provider Entity ID
idp_sso_login_url	URL	IdP SSO endpoint
idp_x509_cert	PEM cert	IdP signing certificate
provision	refuse / create	New user handling
bypass	bool	Skip WordPress signup validation
forced_redirection	bool	All logins go through SAML

Key Hooks/Filters:

Hook	Location	Purpose
pb_saml_auth_settings	SAML class	Modify OneLogin settings array
pb_integrations_multidomain_email	SAML class	Transform email before matching
authenticate	WordPress	Main entry point for SAML auth

Potential Code Changes:

// Before (if using Pressbooks Container)
$service = \Pressbooks\Container::get('SomeService');

// After (using app() helper)
$service = app('SomeService');
// Or if service doesn't exist in MC container, handle gracefully

Role Mapping Considerations:

// MC-specific roles to consider
// - mc_author: Can create/edit own MC content
// - mc_editor: Can edit any MC content
// - subscriber: Can view/complete MCs (learner)
// - administrator: Full site access

// Possible SAML attribute mapping
$role_map = [
    'faculty' => 'mc_author',
    'staff' => 'mc_editor', 
    'student' => 'subscriber',
];

Test IdP Setup:

• Auth0 SAML configuration (pending access)
• Local SimpleSAMLphp for development testing
• Test assertions with various attribute formats

Design/Mockups

No UI changes expected - using existing SAML plugin admin interface

If role mapping UI is needed:

• Mockup for role mapping settings
• Admin page integration with MC settings

Dependencies

• Auth0 test environment access (for testing)
• pressbooks-microcredentials Container/app() helper stable
• Test IdP configured with test users
• MC roles defined (if custom roles needed)

Testing Notes

Test Environment Setup

1. Configure test IdP (Auth0 or SimpleSAMLphp)
2. Configure SAML plugin with test IdP
3. Create test users in IdP
4. Test on MC network (not Pressbooks network)

Manual Testing Scenarios

Authentication:

1. Access MC site while logged out
2. Click "Connect via SAML2"
3. Authenticate at IdP
4. Verify redirect back and logged in
5. Verify user meta set correctly

User Matching:

1. Login with user that has pressbooks_saml_identity meta
2. Login with user matched by email only
3. Login with new user (provisioning=create)
4. Login with new user (provisioning=refuse)

Definition of Done

• SAML plugin works on MC network without Pressbooks core
• Full authentication flow tested and working
• User provisioning tested (create and refuse modes)
• Role mapping defined and documented
• No regressions on Pressbooks networks (if changes made)
• Documentation updated
• Code reviewed
• Tested with real IdP (Auth0)

Risk Assessment

Risk	Likelihood	Impact	Mitigation
Hidden PB dependencies	Low	Medium	Thorough code review
OneLogin library compatibility	Low	High	Test early
Role mapping complexity	Medium	Medium	Start simple, iterate
IdP configuration variance	Medium	Low	Good documentation