Upgrade of CERN SSO to Keycloak 24

Keycloak, the software behind CERN SSO service (Single Sign-On, at auth.cern.ch), will be upgraded from version 20 to version 24 on Wednesday January 15th, 2025 at 7:30 PM (link to OTG).

The QA instance of CERN SSO (at keycloak-qa.cern.ch) was upgraded to Keycloak 24 on Monday, November 11th 2024 at 4PM.

If you are impacted by any of the following changes, we strongly encourage you to make sure that the change works for your test application on QA.

Impact to applications

• String matching for client valid redirect URIs now requires case-sensitive matches, so if "https://test.cern.ch/oidc-callback" is registered as a valid redirect URI, queries like "https://test.cern.ch/OIDC-callback" will no longer be recognized.
• Keycloak JS:
  • Keycloak JS adapter must be instantiated with "new":

    const keycloak = new Keycloak({
        url: 'https://auth.cern.ch/auth',
        realm: 'cern',
        clientId: 'sso-example'
    });
    

  • Keycloak JS imports might need to be updated:

    // Before
    import Keycloak from 'keycloak-js/dist/keycloak.js';
    import AuthZ from 'keycloak-js/dist/keycloak-authz.js';
    
    // After
    import Keycloak from 'keycloak-js';
    import AuthZ from 'keycloak-js/authz';
    

  • Use promises (then/catch instead of success/error).
• consider upgrading the version of any Keycloak client adapters that you use (Keycloak Wildfly OpenID Connect Adapter / Keycloak JEE Servlet OpenID Connect Adapter / Keycloak Spring Boot - Spring Security OpenID Connect Adapter / Jetty adapter) (For replacement, look at Keycloak Quickstart GitHub Repository: https://github.com/keycloak/keycloak-quickstarts).
• When validating incorrect OTP with step-up endpoint /stepupotp/otp/username/validate, there is an additional field "error_description" to the {"error":"Invalid","error_description":"For..."}. Be careful with exact matches if you are using this endpoint.

• Added iss parameter to OAuth 2.0/OpenID Connect Authentication Response:

  After submitting proper credentials on the login form (including 2FA), the browser queries /auth/realms/cern/login-actions/authenticate and the response contains a redirection (302 Found) through a location.

  In that location, there is now an additional path parameter iss:

  Location: /#state=5f12fe39&session_state=3d9f64d9&code=bc6acc53

  Location after the upgrade: /#state=1bfa2e0a&session_state=0f58cfd6&iss=https%3A%2F%2Fauth.cern.ch%2Fauth%2Frealms%2Fcern&code=220802af

  Some OpenID Connect/OAuth2 adapters, and especially older Keycloak adapters, may have issues with this new parameter.

  If that breaks your application, please contact us (we can manually override the location URL for an existing SSO registration).

---

In case of major issues, there will be a possibility to roll back the change.