Upgrade to 2027.1+ process¶

Note

If upgrading from a version of Altair SLC Hub prior to 2026.1, make sure to follow the upgrade instructions for 2026.1 first, as there are additional steps required for that version.

Before you start¶

Prerequisites

Administrator access to the Altair SLC Hub server machine.
Completed the Upgrading Guide.
A backup of the Altair SLC Hub database.

What is different in 2027.1¶

In 2027.1, Keycloak replaces the Altair SLC Hub auth service. Keycloak is now the store for users, groups, credentials, and identity provider configuration. Configuration values that were in the Altair SLC Hub configuration move to the Keycloak Admin Console.

Read this section before you start the upgrade. It tells you which manual tasks you must do after the migration.

Authentication and Keycloak configuration¶

Altair SLC Hub uses a dedicated Keycloak realm that is named slchub. The hubctl bootstrap command creates and configures this realm. Bootstrap divides the realm configuration into two kinds:

Required Config, which Altair SLC Hub owns. If a value is different from the expected value, bootstrap reports a conflict and stops.
Default-Only Config, which bootstrap writes only when the realm is created. Your subsequent changes stay in place.

For the full behaviour, see Keycloak bootstrap and configuration behavior.

Configuration values that are no longer used¶

Altair SLC Hub ignores the auth and the serviceAccounts configuration values. Set the equivalent settings in the Keycloak Admin Console, or in the new keycloak configuration values.

Configuration value	Purpose	Where to set it now
`auth.redirectURLs`, `auth.responseTypes`, `auth.grantTypes`, `auth.scopes`, `auth.audience`, `auth.issuer`, `auth.ui`	The OpenID Connect client settings	Clients. Altair SLC Hub owns these settings, and bootstrap sets them from `ingress.url`
`auth.accessTokenLifespan`, `auth.idTokenLifespan`, `auth.authorizeCodeLifespan`	How long a token stays valid	Realm settings > Tokens, or Clients > [client] > Advanced for one client
`auth.refreshTokenLifespan`, `auth.logonSessionLifespan`	How long a session stays valid	Realm settings > Sessions
`auth.clients.[client]`	The lifetimes for one client	Clients > [client] > Advanced
`auth.passwordValidityPolicy`	The password rules, such as the minimum length and the character classes	Authentication > Policies > Password policy
`auth.passwordExpirationPolicy`	How often a user must change the password	Authentication > Policies > Password policy, with the `passwordAge` policy. The warning interval has no equivalent
`auth.passwordHashPolicy`	The password hash algorithm and its cost	The `keycloak.password.hashing` configuration values
`auth.passwordValidityPolicy.blacklist.falsePositiveRate`	The accuracy of the blacklist match	The `keycloak.password.blacklist.falsePositiveProbability` configuration value
`auth.bruteForceDetectionPolicy`	The lockout after failed logins	Realm settings > Security defenses > Brute force detection
`auth.user.allowOsUserModification`	Whether a user can manually change the OS user information	RBAC. See Modification of sensitive user fields
`auth.ldap`	The LDAP connection, the search bases, the queries, and the attribute names	User Federation. See LDAP and Active Directory
`serviceAccounts.keysetFile`	The verification keys for service account tokens	Keycloak manages the realm keys

Roles and groups¶

Item	Change	Replacement
`HubAdministrator` role	Removed	Assign the `Admin` role, or the `UserManager` role
`GeneralConsumers` group	Removed	—
`Admin` role	Added	Full management permission in Altair SLC Hub
`UserManager` role	Added	User and group management, without sensitive attribute changes
`UserManagers` group	Added	Holds the `UserManager` role
`RealmAdmin` Keycloak role	Added	A Keycloak realm role, not an Altair SLC Hub role, can assign it in the Keycloak Admin Console

Role bindings for HubAdministrator are removed

Bootstrap deletes the HubAdministrator role and its role bindings. Users who had this role do not receive a replacement role automatically. After the migration, you must assign the new roles. See Assign the new roles.

The HubAdministrator user is no longer created during installation. Administrator accounts are now created with the hubctl admin create command, see Create and Configure Admin User. For more information, see Roles and Groups.

Modification of sensitive user fields¶

The auth.user.allowOsUserModification configuration option is removed. This option controlled globally whether a user could manually change the Unix username, the Unix home directory, the User Principal Name (UPN).

RBAC now controls these fields and the email address. To change them, a user must have the UpdateSensitive action on the /Users/{userName} object. The Admin role has this permission. The UserManager role does not.

For more information, see Sensitive user fields and permissions and the Access Control Reference.

LDAP and Active Directory¶

You now configure LDAP and Active Directory in Keycloak, with User Federation. See LDAP and Active Directory.

Item	Change
`auth.ldap.*` configuration	Replaced by a Keycloak user federation provider
`hubctl ldap` and `hubctl ldapsync` commands	No longer operate. They print a deprecation notice
`hubctl verify ldap` commands	Removed
Attribute templates	Replaced by a mapper that uses a FreeMarker template. See Attribute value templates
`auth.ldap.bindVaultSecret`	Not supported. Keycloak has no integration with HashiCorp Vault

HashiCorp Vault

Keycloak cannot read secrets from HashiCorp Vault. If the LDAP bind credential or the database credentials come from Vault, you must supply the credentials directly. For the database, see Planning.

Password policy and brute force detection¶

Keycloak now enforces the password policy and the brute force detection. You configure them in the Keycloak Admin Console:

Setting	Location in Keycloak
Password policy	Authentication > Policies > Password policy
Brute force detection	Realm settings > Security defenses > Brute force detection

See Password policies and Brute force detection.

The migration maps the legacy auth.passwordValidityPolicy settings to the equivalent Keycloak policy. The following legacy settings have no Keycloak equivalent, and the migration does not apply them:

notContainsEmailParts. Keycloak notEmail only finds an exact match.
notContainsDisplayNameParts
haveibeenpwnedCheck and haveibeenpwnedService
minimumZxcvbnScore
The blacklist falsePositiveRate. Use the keycloak.password.blacklist.falsePositiveProbability configuration value instead

Keycloak supports one password blacklist file only. If you use more than one blacklist file, merge the files into one file. Put the file in the Keycloak blacklist directory, [installation root]/libexec/keycloak/data/password-blacklists, and set the policy to that file name. If the file is not in that directory, the migration skips the blacklist policy.

Keycloak does not support all the legacy password hash algorithms. No user passwords will be migrated, all Altair SLC Hub users must set a new password.

The migration does not transfer the legacy auth.bruteForceDetectionPolicy settings. Bootstrap applies the Altair SLC Hub defaults. Check the values in the Keycloak Admin Console after the upgrade.

Auth REST API and hubcli¶

The auth REST API changes because Keycloak now holds the user data. If you have scripts or applications that use the auth API, or hubcli, you must update them.

The following endpoints are removed:

Endpoint	Alternative
`/impersonate`	—
`/tokeninfo`	—
`/me/validatePassword`	Keycloak enforces the policy at the point of change
`/passwords/validate`	Keycloak enforces the policy at the point of change
`/users/{userId}/validatePassword`	Keycloak enforces the policy at the point of change
`/passwords/changeByUsername`	`/me/changePassword`
`/passwords/validateResetToken`	Keycloak account management
`/passwords/complete`	Keycloak account management
`/registration/validateInvitationToken`	Keycloak account management
`/registration/complete`	Keycloak account management
`/registration/usernameAvailability`	—
`/users/{userId}/osinfo`	`/users/{userId}`
`/users/{userId}/clearLogonFailures`	Users > Sessions in the Keycloak Admin Console

The endpoint /usernames/policyDescription is added.

The query filters on /users and /groups have all changed, because Keycloak does the search. Keycloak has one search filter that matches several fields, in place of the separate filter for each field. The sort, fields, and excludeFields parameters are removed from both endpoints.

Endpoint	New filters
`/users`	`filter[search][EQ]`, `filter[search][CO]`, `filter[search][SW]`, `filter[enabled][EQ]`
`/groups`	`filter[search][EQ]`, `filter[search][CO]`, `filter[search][SW]`

The filter[search] parameter matches the username, the first name, the last name, and the email address for a user, and the name for a group. The filter[_id][IN] filter stays on both endpoints. The filter[userName][EQ] and filter[invitationPending][EQ] filters stay on /users, and filter[externalId][PR] stays on /groups.

The user object changes:

The active field is renamed to enabled.
The fields firstName and lastName are added.
The field userName is now required, and displayName is no longer required.
The fields inactiveReason, invitationExpiry, deleted, and temporarilyLocked are removed.
The field _modified was removed.

The hubcli commands change:

Command	Change
`hubcli user create`	Added `--firstName` and `--lastName`
`hubcli user modify`	Removed `--userName`. To rename a user, use the Keycloak Admin Console
`hubcli user list`	Removed the name, email, date, sort, and deletion filters. Added `--enabled`
`hubcli user get`	Shows `Enabled`. Removed the inactive reason, deletion, and invitation fields
`hubcli group list`	Removed the name, date, and sort filters, and the `Created` and `Modified` columns
`hubcli group get`	Removed the `Created` and `Modified` rows

The hubctl commands change:

Command	Change
`hubctl admin create`, `hubctl admin delete`	New. Manage Altair SLC Hub administrator accounts
`hubctl keycloak apply`	New. Applies the Altair SLC Hub Keycloak configuration
`hubctl migrate`	New. Migrates the data to Keycloak
`hubctl ldap`, `hubctl ldapsync`	Deprecated. They no longer operate
`hubctl generate externalssc`	Replaced by `hubctl generate externalcert`

Upgrade¶

For the upgrade, follow the usual upgrade process for Altair SLC Hub defined in the server upgrade guide.

1. Install and bootstrap¶

During the bootstrap stage of the upgrade, Altair SLC Hub creates the Keycloak slchub realm and applies the configuration that it requires. Bootstrap also removes the roles that 2027.1 no longer uses, and their role bindings.

If the realm already exists, and a Required Config value is different from the expected value, bootstrap reports the conflict and stops. Correct the conflict, then run hubctl bootstrap again. See Resolving conflicts.

2. Migrate the users and groups¶

When the upgrade is successful, migrate the users, the groups, and the remaining auth configuration to Keycloak.

Run this command on the server node:

hubctl migrate

The command copies the users, the groups, the password policy, and the LDAP configuration into Keycloak. It then updates the Altair SLC Hub records that refer to a user or a group, so that they refer to the new Keycloak identity.

The command is safe to run more than once. It skips the items that it already migrated.

Read the output before you continue. The command gives a warning for each configuration item that it cannot migrate automatically. Configure these items manually in Keycloak.

Users that Keycloak rejects

Keycloak does not accept all the characters that Altair SLC Hub accepted in a username or a name. The command lists the users that it does not migrate for this reason. These users cannot log in. Correct the data in Altair SLC Hub and run hubctl migrate again, or create the users in Keycloak manually.

3. Migrate the external users¶

If you use an external LDAP server, do the steps in External LDAP before you continue.

4. Assign the new roles¶

The HubAdministrator role no longer exists, so no user has full administrator permission after the migration. Create an administrator account on the server node:

hubctl admin create

The command creates a Keycloak user, gives the user the Keycloak RealmAdmin realm role, and binds the Altair SLC Hub Admin role. By default the account uses multi-factor authentication (MFA). For the full procedure, see Create and Configure Admin User.

Log in to the portal with this account. Then assign the Admin role, the UserManager role, or the applicable groups to the users that had the HubAdministrator role.

Do not bind the Admin role to a group

Bind the Admin role to individual users only. See Security considerations for group bindings.

5. Tell the users to set a password¶

The migration does not copy the passwords of internal users. Keycloak sends each migrated user an email with a link to set a new password. Until the user sets a password, the user cannot log in.

The command lists the users that have no email address. Keycloak cannot send an email to these users. For each user, add and verify an email address in the Keycloak Admin Console, then send the required actions email again.

External LDAP¶

If you use an external LDAP server for authentication, hubctl migrate moves the LDAP configuration to Keycloak. The migration creates a user federation provider that is named SLC Hub Migrated. It also creates most of the mappers, from the attribute names in the previous configuration: the group mapper, the UPN mapper, the Unix home directory mapper, and the Unix username mapper.

The migration cannot move all the settings. Check the LDAP configuration in Keycloak, and complete it.

Do these steps:

In the Keycloak Admin Console, go to User Federation > SLC Hub Migrated.
If the LDAP bind credential came from HashiCorp Vault, enter the credential in the Bind Credential field, then click Save. Keycloak has no integration with HashiCorp Vault, so the migration cannot copy this credential.
On the Mappers tab, check the mappers that the migration created. Keycloak also adds its own default mappers, and some of them do not match what Altair SLC Hub requires. See Required attribute mappers.
If an attribute used a template in the previous configuration, add a mapper for it. The migration does not move the transformation. See Attribute value templates.
On the Mappers tab, select the groups mapper, then click Action > Sync LDAP groups to Keycloak. The migration does not import the groups. You must do this sync manually.
Go back to the provider, then click Action > Sync all users. The migration does not import the external users. You must do this full sync manually.
Run hubctl migrate again on the server node. The external users and groups now exist in Keycloak, so the command can map them to their Altair SLC Hub records. Without this second run, the external users lose their group memberships, their role bindings, and the ownership of their objects.

Important

Sync the groups and the users before you run hubctl migrate again. The command can only map a user or a group that exists in Keycloak.

Troubleshooting¶

If an error occurs, enable debug logging and show the full progress messages:

hubctl migrate --debug --progress=plain

With --debug, the command keeps the temporary identifier map file in [var directory]/tmp. Attach this file, and the command output, to a support request.

A user has no group memberships after the migration¶

The command can only map a user or a group that exists in Keycloak. For an external user, do a full sync in Keycloak, then run hubctl migrate again. See External LDAP.

`hubctl bootstrap` fails with `invalid_grant: Invalid user credentials`¶

The HubServiceAdmin password in Keycloak does not match the stored password. See the recovery procedure.