Bug 40596 - Migrate CAS and Shibboleth into the identity providers
Summary: Migrate CAS and Shibboleth into the identity providers
Status: In Discussion
Alias: None
Product: Koha
Classification: Unclassified
Component: Architecture, internals, and plumbing (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement
Assignee: Tomás Cohen Arazi (tcohen)
QA Contact: Testopia
URL:
Keywords:
Depends on: 31378
Blocks:
  Show dependency treegraph
 
Reported: 2025-08-05 14:36 UTC by Tomás Cohen Arazi (tcohen)
Modified: 2025-08-14 09:01 UTC (History)
7 users (show)

See Also:
GIT URL:
Change sponsored?: ---
Patch complexity: ---
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:
Circulation function:


Attachments
Bug 40596: Add Shibboleth protocol to identity_providers enum (3.34 KB, patch)
2025-08-06 20:04 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 40596: Add CAS and Shibboleth Identity Provider classes (13.57 KB, patch)
2025-08-06 20:04 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 40596: Add CAS and Shibboleth to protocol class mapping (1.51 KB, patch)
2025-08-06 20:05 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 40596: Add CAS and Shibboleth authentication clients (19.60 KB, patch)
2025-08-06 20:05 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 40596: Add client-level user registration and update methods (4.15 KB, patch)
2025-08-06 20:05 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 40596: Add CAS and Shibboleth compatibility layers (15.72 KB, patch)
2025-08-06 20:05 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 40596: Add authentication provider migration script (7.97 KB, patch)
2025-08-06 20:05 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 40596: Integrate CAS and Shibboleth compatibility layers into C4::Auth (5.42 KB, patch)
2025-08-06 20:05 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 40596: Fix Identity Provider test plan for CAS and Shibboleth protocols (1.49 KB, patch)
2025-08-06 20:05 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 40596: Fix Shibboleth compatibility layer for test scenarios (1.99 KB, patch)
2025-08-06 20:05 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Tomás Cohen Arazi (tcohen) 2025-08-05 14:36:24 UTC
When we envisioned the bug 31378 implementation, it was designed to cover other protocols as well.

I'm filing this report to work on this.
Comment 1 Tomás Cohen Arazi (tcohen) 2025-08-06 20:04:55 UTC
Created attachment 185168 [details] [review]
Bug 40596: Add Shibboleth protocol to identity_providers enum

Adds 'Shibboleth' to the protocol enum in the identity_providers table
to support Shibboleth authentication through the identity provider system.

This extends the existing OAuth, OIDC, LDAP, and CAS protocols to include
Shibboleth, enabling unified authentication management.

Test plan:
1. Apply patch
2. Verify database schema includes Shibboleth in protocol enum
3. Verify existing identity providers continue to work
Comment 2 Tomás Cohen Arazi (tcohen) 2025-08-06 20:04:58 UTC
Created attachment 185169 [details] [review]
Bug 40596: Add CAS and Shibboleth Identity Provider classes

Adds identity provider implementations for CAS and Shibboleth protocols:

* Koha::Auth::Identity::Provider::CAS - Defines mandatory config attributes
  for CAS providers (cas_url)
* Koha::Auth::Identity::Provider::Shibboleth - Defines mandatory config
  attributes for Shibboleth providers (sso_url, slo_url, entity_id)

These classes extend the base identity provider functionality to support
protocol-specific configuration validation.

Test plan:
1. Apply patch
2. Verify classes can be instantiated
3. Verify mandatory_config_attributes returns expected values
4. Test with identity provider upgrade_class() method
Comment 3 Tomás Cohen Arazi (tcohen) 2025-08-06 20:05:01 UTC
Created attachment 185170 [details] [review]
Bug 40596: Add CAS and Shibboleth to protocol class mapping

Updates the protocol_to_class_mapping to include CAS and Shibboleth
protocols, enabling the upgrade_class() method to properly instantiate
the correct provider classes.

Changes:
* Adds CAS => 'Koha::Auth::Identity::Provider::CAS'
* Adds Shibboleth => 'Koha::Auth::Identity::Provider::Shibboleth'

Test plan:
1. Apply patch
2. Create identity providers with CAS and Shibboleth protocols
3. Verify upgrade_class() returns correct specialized classes
4. Run t/db_dependent/Koha/Auth/Identity/Provider.t
Comment 4 Tomás Cohen Arazi (tcohen) 2025-08-06 20:05:04 UTC
Created attachment 185171 [details] [review]
Bug 40596: Add CAS and Shibboleth authentication clients

Implements modern authentication clients for CAS and Shibboleth protocols:

Koha::Auth::Client::CAS:
* Uses Authen::CAS::Client for ticket validation
* Provides get_cas_login_url() and get_cas_logout_url() methods
* Handles CAS service validation and user data extraction

Koha::Auth::Client::Shibboleth:
* Extracts Shibboleth attributes from environment variables
* Maps attributes using provider configuration
* Supports flexible attribute mapping

Both clients extend Koha::Auth::Client and integrate with the modern
identity provider architecture while maintaining compatibility with
existing authentication flows.

Test plan:
1. Apply patch
2. Configure CAS/Shibboleth identity providers
3. Test authentication flows
4. Verify user data extraction and mapping
5. Run t/db_dependent/Koha/Auth/Client.t
Comment 5 Tomás Cohen Arazi (tcohen) 2025-08-06 20:05:07 UTC
Created attachment 185172 [details] [review]
Bug 40596: Add client-level user registration and update methods

Implements client-level authentication with user registration and update
capabilities, moving the logic from controller-level to client-level.

Changes to base Koha::Auth::Client:
* Added register_user() method for creating new patrons
* Added update_user() method for updating existing patrons
* Modified get_user() to automatically handle registration/updates based on domain configuration
* Uses domain settings (auto_register, update_on_auth) to control behavior

This provides the foundation for OAuth to be refactored to use the same
client-level registration/update methods, creating a consistent
authentication architecture across all protocols.

Test plan:
1. Apply patch
2. Configure identity provider domains with auto_register/update_on_auth
3. Test user auto-creation when domain allows it
4. Test user updates when domain allows it
5. Verify CAS and Shibboleth authentication still works
6. Verify OAuth functionality is preserved
Comment 6 Tomás Cohen Arazi (tcohen) 2025-08-06 20:05:10 UTC
Created attachment 185173 [details] [review]
Bug 40596: Add CAS and Shibboleth compatibility layers

Provides compatibility layers between legacy authentication systems and
modern identity provider architecture:

Koha::Auth::CASCompat:
* get_cas_providers() - Returns CAS configuration in legacy format
* authenticate_cas_user() - Bridges legacy checkpw_cas interface to modern clients
* Supports both modern identity providers and legacy system preferences

Koha::Auth::ShibbolethCompat:
* get_shibboleth_provider() - Creates provider from legacy or modern config
* authenticate_shibboleth_user() - Bridges legacy checkpw_shib interface
* get_shibboleth_config() - Returns config in legacy format
* Handles attribute mapping and user auto-creation/updates

These layers allow existing code to continue working unchanged while
using modern authentication internally.

Test plan:
1. Apply patch
2. Test CAS authentication with existing configurations
3. Test Shibboleth authentication with existing configurations
4. Verify user auto-creation and updates work as expected
5. Run t/db_dependent/Auth_with_cas.t
6. Run t/db_dependent/Auth_with_shibboleth.t
Comment 7 Tomás Cohen Arazi (tcohen) 2025-08-06 20:05:13 UTC
Created attachment 185174 [details] [review]
Bug 40596: Add authentication provider migration script

Provides a migration tool to convert legacy CAS and Shibboleth
configurations to modern identity providers.

Features:
* Migrates casServerUrl system preference to CAS identity provider
* Migrates shibboleth configuration to Shibboleth identity provider
* Supports dry-run mode to preview changes
* Verbose output for detailed migration information
* Checks for existing providers to avoid duplicates

Usage:
  perl misc/migration_tools/migrate_authentication_providers.pl [--dry-run] [--verbose]

Test plan:
1. Apply patch
2. Set up legacy CAS/Shibboleth configuration
3. Run script with --dry-run to preview migration
4. Run script to perform actual migration
5. Verify identity providers are created correctly
6. Test authentication with migrated providers
Comment 8 Tomás Cohen Arazi (tcohen) 2025-08-06 20:05:16 UTC
Created attachment 185175 [details] [review]
Bug 40596: Integrate CAS and Shibboleth compatibility layers into C4::Auth

Integrates the modern CAS and Shibboleth compatibility layers into the
legacy authentication system, providing a bridge between old and new
implementations.

Changes to C4::Auth:
* Updated imports to use compatibility layers instead of direct legacy calls
* Added calls to CASCompat::authenticate_cas_user() for CAS authentication
* Added calls to ShibbolethCompat::authenticate_shibboleth_user() for Shibboleth
* Updated CAS provider lookup to use CASCompat::get_cas_providers()
* Added runtime loading of compatibility modules for test scenarios
* Maintains full backward compatibility with existing authentication flows

The compatibility layers use modern client-level architecture internally
while presenting the legacy interface expected by C4::Auth.

Test plan:
1. Apply patch
2. Test CAS authentication with existing configurations
3. Test Shibboleth authentication with existing configurations
4. Test user auto-creation and updates work as expected
5. Run t/db_dependent/Auth.t and verify CAS/Shibboleth tests pass
6. Verify no regressions in OAuth or internal authentication
Comment 9 Tomás Cohen Arazi (tcohen) 2025-08-06 20:05:19 UTC
Created attachment 185176 [details] [review]
Bug 40596: Fix Identity Provider test plan for CAS and Shibboleth protocols

The upgrade_class() test was failing because it planned 5 tests but ran 9.
This happened because we added CAS and Shibboleth protocols to the
protocol_to_class_mapping, increasing the number of protocols from 2 to 4.

The test runs 2 tests per protocol plus 1 test for invalid protocol:
- Original: 2 protocols × 2 tests + 1 = 5 tests
- Current: 4 protocols × 2 tests + 1 = 9 tests

Updated the test plan to reflect the correct number of tests.

Test plan:
1. Apply patch
2. Run prove t/db_dependent/Koha/Auth/Identity/Provider.t
3. Verify all tests pass including upgrade_class() tests
Comment 10 Tomás Cohen Arazi (tcohen) 2025-08-06 20:05:23 UTC
Created attachment 185177 [details] [review]
Bug 40596: Fix Shibboleth compatibility layer for test scenarios

The Shibboleth compatibility layer needed proper test integration.
Instead of bypassing the new code in tests (which would mean tests
don't validate production code), this updates the test to mock the
new authenticate_shibboleth_user function directly.

This ensures:
1. Tests validate the actual production code path
2. The new compatibility layer is properly tested
3. No bypassing of production code in test scenarios
4. Full test coverage of the new authentication architecture

The test now mocks Koha::Auth::ShibbolethCompat::authenticate_shibboleth_user
instead of the legacy C4::Auth_with_shibboleth::checkpw_shib function,
ensuring that the test exercises the same code path as production.

Test plan:
1. Apply patch
2. Run prove t/db_dependent/Auth.t
3. Verify all tests pass including Shibboleth tests
4. Verify tests are actually calling the new compatibility layer
5. Run prove t/db_dependent/Auth_with_shibboleth.t
6. Verify Shibboleth-specific tests still pass
Comment 11 Tomás Cohen Arazi (tcohen) 2025-08-06 20:10:55 UTC
Hi, this is a pet project I've been working on. I share it early to gather some opinions. Mostly about design decisions.

It is not complete:
* no UI changes in IdP config
* haven't checked if the optimistic implementation of the IdP handles login correctly in the UI
* Some methods are still used from the old classes (logout, etc). We probably need to implement them generically and/or the protocol-specific classes. There's a bug for OAuth2 logout somewhere.

I have another patchset in which I wanted to create classes for validating credentials. But then I moved here as I think this protocols could be a PITA in terms of refactoring/moving C4::Auth somewhere else.
Comment 12 David Cook 2025-08-06 23:34:17 UTC
(In reply to Tomás Cohen Arazi (tcohen) from comment #11)
> Hi, this is a pet project I've been working on. I share it early to gather
> some opinions. Mostly about design decisions.
>
> * haven't checked if the optimistic implementation of the IdP handles login
> correctly in the UI

I'm time poor at the moment, but I'd be keen to try out the SAML using Keycloak. 

Added Hugo via CC as I think this is a topic that he's interested in, so hopefully he can provide some useful feedback as well. I think he has Koha instances that use CAS, SAML, and OIDC.

> * Some methods are still used from the old classes (logout, etc). We
> probably need to implement them generically and/or the protocol-specific
> classes. There's a bug for OAuth2 logout somewhere.

I've added the See Also for bug 31900
Comment 13 Oliver Behnke 2025-08-14 09:01:23 UTC
Please note 40650 in this context as well.