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.19.0+

Section titled “v0.19.0+”
Upgrade Details

Keycloak 26.4.0 introduced a breaking change to the ServerInfo endpoint and does not render SystemInfo without additional permissions. This change will cause OpenTofu to fail with a “Malformed version” (see Keycloak Terraform Provider #1342). In oder to resolve the issue, you need to perform the following steps:

  • Navigate to the UDS realm
  • Go to Clients > realm-management > Client Roles > Roles and click Create Role
  • Use view-system as the Role Name and Enables displaying SystemInfo through the ServerInfo endpoint for the Description and click Save
  • Go back to the realm-management Roles by clicking the Client details breadcrumb and find the realm-admin Role. Click on it
  • Go to Associated roles tab and click Assign role > Client Roles
  • Find the view-system role you created earlier, select it and click Assign

v0.17.0

Section titled “v0.17.0”
Upgrade Details

UDS Identity Config introduced the OpenTofu client that can be used for managing Keycloak with OpenTofu. This new client is included in the realm.json, however if unable to re-initialize Keycloak in UDS Core you can find steps here to manually configure the OpenTofu client.

UDS Core v0.51.0 introduced a mechanism to limit the number of concurrent SSO sessions per user in the UDS Realm. To manually configure this:

  • Navigate to the UDS realm
  • Go to Authentication > Flows > UDS Authentication
  • Click Add execution
  • Select User Session Count Limiter :
  • Select the gear icon next to the new User Session Count Limiter to configure the following:
    • Maximum concurrent sessions for each user within this realm: Set to the desired maximum number of concurrent sessions per user. The value should be the same as the SSO_SESSION_MAX_PER_USER value in the realmInitEnv.

v0.14.1+

Section titled “v0.14.1+”
Upgrade Details

UDS Core v0.42.0 switched Keycloak to run in Ambient Mode. In some cases, specifically in AWS environment that uses “Shared Address Space” (see RFC6598), this may result in HTTP 403 errors. In order to resolve this, uds-identity-config v0.14.1 requires setting “Require SSL” option to “None”. To manually configure this:

  • Navigate to the UDS realm
  • Go to Realm Settings > General tab
  • Switch Require SSL to None

v0.14.0+

Section titled “v0.14.0+”
Upgrade Details

In uds-identity-config versions v0.14.0+, the UDS Identity Config has removed Dynamic Client Registration. Part of this means that we need to remove a couple of the Trusted Hosts configured in uds-identity-config. To manually configure this:

  • Navigate to the UDS realm (be aware that in KC v26.2 the UI/UX of navigating realms has changed)
  • Go to Clients > Client Registration > Trusted Hosts
  • Remove the following Trusted Hosts:
    • *.keycloak.svc.cluster.local
    • *.pepr-uds-core-watcher.pepr-system.svc.cluster.local
    • 127.0.0.6
  • Click the Save button
  • Go to Clients > Client Registration
  • Click Create client policy
  • Click the max-clients option
  • Name the max-clients policy max number of clients
  • Set Max Clients Per Realm to 0
  • Click the Save button

UDS Core v0.41.0+ resolves a critical issue with enabling FIPS mode in Keycloak. Previously, due to missing Bouncy Castle FIPS libraries, Keycloak would start in normal mode without FIPS restrictions.

Enabling FIPS mode introduces two significant changes:

  • Passwords must be at least 14 characters long. Keycloak will reject shorter passwords, including database credentials and user passwords.
  • The argon2 hashing algorithm is unavailable in FIPS mode. Existing systems must first migrate to the pbkdf2-sha512 algorithm for hashing user credentials before enabling FIPS mode in the master realm. Failing to do so will lock the administrator password.

To prevent locking the administrator password, follow these steps:

  • Log in to Keycloak with the administrator account (you may need to use uds zarf connect keycloak).
  • In the master Realm, navigate to Authentication > Policies > Password Policy and click Add Policy.
  • Select Hashing Algorithm and enter pbkdf2-sha512.
  • Click Save.
  • Go to Users and select your administrator account.
  • Open the Credentials tab and click Reset Password.
  • Enter a new password of at least 14 characters. You can reuse your existing password if desired.
  • Set Temporary to Off and click Save.
  • Return to your user’s details, open the Credentials tab, and click Show data. Ensure the algorithm is set to pbkdf2-sha512.
  • You are now ready to enable FIPS mode in Keycloak.

For more details on FIPS limitations, refer to the Keycloak FIPS 140-2 support page.

v0.11.0+

Section titled “v0.11.0+”
Upgrade Details

In uds-identity-config versions v0.11.0+, the UDS Operator can automatically switch to Client Credentials Grant from using the Dynamic Client Registration. The new method works faster, is more reliable and doesn’t require storing Registration Tokens in the Pepr Store. It is highly recommended to switch to it, which requires the following steps:

  • Create the uds-operator Client:
    • Go to Clients > Create
      • Client type: openid-connect
      • Client ID: uds-operator
      • Client Name: uds-operator
      • Click Next
      • Client authentication: on
      • Uncheck all Authentications flows except from Service account roles
      • Click Next
      • Click Save
    • Go to Clients > uds-operator > Credentials tab
      • Set Client Authenticator to Client Id and Kubernetes Secret
      • Click Save
    • Go to Clients > uds-operator > Service accounts roles tab
      • Should see the Role default-roles-uds > click the three dots on the right and unassign > Remove
      • Click Assign role
      • Make sure the filter is on Filter by clients
      • Check the box next to realm-management: manage-clients
      • Click Assign
  • Configure the UDS Client Policy
    • Go to Realm Settings > Client Policies > Profiles
      • Click Create Client Profile - Name: uds-client-profile - Description: UDS Client Profile - Click Save
      • Click Add Executor - Select uds-operator-permissions - Click Add
    • Go to Realm Settings > Client Policies > Policies
      • Click Create client policy - Name: uds-client-policy - Description: UDS Client Policy
      • Click Save
      • Click Add condition
      • Select any-client
      • Click Add
      • Click Add client profile
      • Select uds-client-profile
      • Click Add (there is a glitch in the UI where it seems all the profiles are selected, but only the selected one is actually chosen)
  • Configure the Client Credentials Authentication Flow
    • Go to Authentication > Flows
      • Click clients - Click Actions > Duplicate - Name: UDS Client Credentials - Description UDS Client Credentials - Click Duplicate
      • Go to Authentication > UDS Client Credentials - Click Add Step (pre uds-core v0.40.0) or Add Execution (uds-core v0.40.0+) - Select Client Id and Kubernetes Secret - Click Add - Select Requirement and set it to Alternative
      • Go to Authentication, select three dots on the right side of the panel for UDS Client Credentials and select Bind flows - Select Client authentication flow - Click Save
  • Verify that everything is configured correctly
    • Deploy a new uds package or update the existing ones
    • Check UDS Operator logs and verify if there are no errors
      • Use uds zarf tools kubectl logs deploy/pepr-uds-core-watcher -n pepr-system | grep "Client Credentials Keycloak Client is available" command to verify if the UDS Operator uses the Client Credentials flow.

After introducing the changes above, ensure that all packages reconcile correctly and that no errors appear. If the UDS Operator displays the error The client doesn’t have the created-by=uds-operator attribute. Rejecting request, disable UDS Client Policy and give the system a bit more time to process every package. Some users have reported that they needed to disable UDS Client Policy, cycle the Pepr Watcher pod (this will force reconciliation of all Packages), wait for all Package CRs to be ready, and finally enable the UDS Client Policy.

Additional information if you need to add protocol mappers that UDS Core does not include out of the box.

In uds-identity-config version 0.11.0 we incorporated some big changes around MFA.

  • Previous versions didn’t allow for MFA on the X509 Authentication flow. Now that can be configured to required additional factors of authentication. By default this is disabled and will need to be enabled.
  • Additionally, we’ve added support of WebAuthn MFA. This can assume many different forms such as biometrics, passkeys, etc. This also is disabled by default and is only used as an MFA option.

If wanting to configure the MFA everywhere with both OTP and WebAuthn options, the following steps will help to manually configure these options on an upgrade:

  1. There is a new theme for webauthn-authentication that conditionally removes the register button. This is removed because we assume that since you are doing MFA you have already provided enough details to be identified by Keycloak and don’t need to register.
  2. The Authentication Required Actions have a few changes as well:
    • Click Authentication tab from left side menu
    • Click Required Actions tab from Authentication page menu
    • Enable the following Required Actions, only toggle the Enabled DO NOT TOGGLE Set as default action:
      • Configure OTP
      • Webauthn Register
      • Delete Credential
    • Disable the WebAuthn Register Passwordless, make sure this is not the WebAuthn Register option ( this one should be enabled )
  3. The UDS Authentication authentication flow has undergone significant changes.
    • Click Authentication tab from left side menu
    • Click UDS Authentication flow option
    • This can be very dangerous to modify so make sure you know what you’re doing before making changes here
    • In the Authentication top level sub-flow of the UDS Authentication flow
      • Click the + icon and add a sub-flow
        • Name that sub-flow X509 Authentication
      • Drag that new sub-flow up and drop below the Cookie and the IDP Redirector step
      • Set the flow to Alternative
      • in the new X509 Authentication sub-flow select the + icon and add a sub-flow called X509 Conditional OTP
        • Set the X509 Conditional OTP to Required
        • Click the + and add the Condition called Condition - user configured
          • set this to be Required
        • Click the + and add the step called OTP Form
          • set this to be Required
        • Click the + and add the step called WebAuthn Authenticator
      • Drag the existing X509/Validate Username Form step into the X509 Authentication sub-flow, should be above the X509 Conditional OTP
        • May have to drag this twice, make sure this is Required

To add an IDP Redirector option to the UDS Authentication, which enables bypassing the login page and jumping directly to the IDP login when using the kc_idp_hint URL parameter, do the following steps:

  • Click Authentication from the left sidebar under Configure
  • Select the UDS Authentication auth flow
  • Under the Authentication sub-flow in UDS Authentication, click the + and add a new sub-flow
    • Name that sub-flow idp redirector
    • click Add
  • Drag that new idp redirector sub-flow from the bottom of the Authentication sub-flow to be directly below the Cookie step
  • Set the idp redirector sub-flow to be Alternative
  • Click the + on the idp redirector sub-flow and add a new step
  • Select the Identity Provider Redirector
  • Click Add
  • Set that Identity Provider Redirector step to Required

v0.10.0+

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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