Skip to content
Unicorn Delivery Service Unicorn Delivery Service

Upgrading Versions

This doc contains important information for upgrading uds-identity-config versions. It is not meant to be an exhaustive list of changes between versions, rather information and steps required to manually upgrade versions without a full redeploy of keycloak.

v0.10.0+

Upgrade Details

In uds-identity-config versions 0.10.0+, the version of Keycloak was upgraded to Keycloak 26.1.0. In this release of Keycloak an unmentioned breaking change that added case sensitivity to the Client SAML Mappers. This resulted in breaking SAML Auth flows due to users IDP data not being correctly mapped into applications ( ex. Sonarqube, Gitlab, etc ). Manual steps to fix this issue:

  • Click Client scopes
  • For each of the following mappers:
    • mapper-saml-email-email
    • mapper-saml-firstname-first_name
    • mapper-saml-lastname-last_name
    • mapper-saml-username-login
    • mapper-saml-username-name
  • Select the mapper, should now be on the Client scope details page
  • Select the Mappers tab
  • Select the available mapper
  • Manually change the Property field dropdown to match the designated mapper property
    • mapper-saml-email-email had a value of Email, that needs to be changed to select the email option from the drop down.
    • mapper-saml-firstname-first_name had a value of FirstName, that needs to be changed to select the firstName option from the drop down.
    • mapper-saml-lastname-last_name had a value of LastName, that needs to be changed to select the lastName option from the drop down.
    • mapper-saml-username-login had a value of Username, that needs to be changed to select the username option from the drop down.
    • mapper-saml-username-name had a value of Username, that needs to be changed to select the username option from the drop down.
  • Make sure and click Save after updating the property field

v0.9.1 to v0.10.0

Upgrade Details
  • For running Istio with Ambient Mesh, it is required to add two new entries to the trusted hosts list: *.pepr-uds-core-watcher.pepr-system.svc.cluster.local and *.keycloak.svc.cluster.local. This is done automatically for new deployments but when upgrading it is required to perform these extra steps:
    • Click Clients > Client registration > Client details
    • Add *.pepr-uds-core-watcher.pepr-system.svc.cluster.local and *.keycloak.svc.cluster.local to the Trusted Hosts list
    • Click Save
  • Keycloak 26.1.1 introduces a new option to force re-login after resetting credentials (Keycloak Release Notes). This option has been enabled for new deployments but the existing ones, it needs to be turned on manually:
    • Click Authentication > UDS Reset Credentials and find Send Reset Email Step of the Authentication Flow.
    • Click Settings, enter a new alias name, for example reset-credentials-email and turn the Force login after reset option on.
    • Click Save

v0.5.1 to v0.5.2

Upgrade Details
  • An custom Keycloak event logger that replaces the default event logger is included in this release, if you wish to enable manually as part of an upgrade do the following (in the Unicorn Delivery Service realm):
    • Click on the Realm Settings > Events and add jsonlog-event-listener.
    • Remove the built in jboss-logging event listener.
    • Click Save
  • The custom registration event listener was renamed from custom-registration-listener to registration-event-listener. To manually update this event listener (in the Unicorn Delivery Service realm):
    • Click on the Realm Settings > Events and add registration-event-listener.
    • Remove custom-registration-listener.
    • Click Save
  • An additional scope (bare-groups) was included in the uds realm.json. To add this scope manually do the following (in the Unicorn Delivery Service realm):
    • Click on Client Scopes > Create client scope.
    • Name the scope bare-groups, and configure it to be
      • Type: Optional
      • Include in token scope: On
    • Click Save
    • Click Mappers > Create a new mapper
    • Select Custom Group Path Mapper and name it bare groups
    • To enable this scope to be added as a defaultClientScope for your clients, navigate to the top level Clients > Client registration tab.
      • Click Allowed Client Scopes
      • Add bare-groups to the list of Allowed Client Scopes
      • Click Save

v0.5.0 to v0.5.1

Upgrade Details

This version upgrade utilizes built in Keycloak functionality for User Managed Attributes.

If upgrading without a full redeploy of keycloak the following changes will be needed:

  1. The realm.json will need to be updated to contain the correct User Managed Attributes definition, User Managed Attributes Configuration. The following steps can be used to do this with clickops:
    1. In Realm Settings tab and on the General page
      1. toggle off User-managed access
      2. Unmanaged Attributes set to Only administrators can write
    2. On User profile page
      1. select the JSON Editor tab
      2. Copy and Paste the value of the User Attribute Definition from the realm.json
      3. Save
  2. Incorporate STIG password rules, in accordance with these two hardening guides:

v0.4.5 to v0.5.0

Upgrade Details This version upgrade brings in a new Authentication Flow for group authorization.

If upgrading without a full redeploy of keycloak the following steps will be necessary to create and use group authorization:

  1. In keycloak admin portal, in UDS realm, navigate to Authentication sidebar tab
  2. In Authentication tab add the Authorization flow to UDS Authentication, UDS Registration, UDS Reset Credentials
    1. In each Authentication flow
      1. Add step -> UDS Operator Group Authentication Validation
      • Make sure that the step is at the base level and bottom of the Authentication flow
  3. Finally if using SAML IDP
    1. In the Authentication tab
      1. Create Flow
      2. Name -> Authorization
      3. Description -> UDS Operator Group Authentication Validation
      4. Basic Flow
      5. Create
      6. Add execution
      7. Add the UDS Operator Group Authentication Validation
    2. In the Identity Providers tab, select the SAML Provider
      1. Add the Authorization flow to the Post login flow in the Advanced settings section
Cookie Settings Privacy Policy