Skip to content

SSO Migration from env variable to UI

Enterprise edition

SSO configuration is under the OpenCTI Enterprise Edition license. Please read the information in this page for more information.

Migration process

After upgrade, at platform initialization, the configuration file will be read and migrated: all authentications defined in the configuration file will be stored at database level. They will still exist in the configuration file.

Authentications existing in database will be loaded, initialized and users will be able to use them to authenticate.

Externally managed secrets and migration

In case of externally managed secrets (e.g. environment variables or credentials provider such as Cyberark), special care must be taken to ensure that the secret will still be accessed from external system (via env or via specific provider like Cyberark). In that case the migration is not fully automatic and requires some manual steps to ensure that the migrated provider will be updated to use external secrets after migration. Please read the migration and externally managed secrets section below for more information.

Authentications that will be migrated

Existing LDAP, SAML, OpenID, Certificate & Headers configurations will be migrated to be managed via UI.

Auth0 authentication will be migrated as OpenID.

Migration and externally managed secrets

During migration, secret fields (e.g. OIDC client secret, SAML private key, LDAP bind credentials) are read from your configuration at migration time and stored in the database (encrypted at rest). If you want to keep using external secrets (environment variables or a credentials provider such as Cyberark) instead of storing secrets in the database, follow the procedures below. They ensure you can log in after upgrade and then switch the migrated providers to external secrets.

Using environment variables for secrets (env)

To avoid relying on secrets stored in the database and use environment-based secrets after migration:

  1. Set up the new secrets registry before upgrading. Define each secret via environment variables, e.g. SECRETS__<NAME>__VALUE. The platform will expose these names in the UI under Use external secret. See Secrets management.
  2. Ensure local authentication is enabled so you can log in with username/password after the upgrade.
  3. Upgrade and start the platform. Migration runs; provider configurations are migrated.
  4. Log in via local authentication, then go to Parameters > Authentications.
  5. Edit each migrated provider that should use an env secret: open the provider, and for each secret field, choose Use external secret and select the corresponding secret name (the one you defined with SECRETS__<NAME>__VALUE). Save. From then on, the platform will use the value from the environment at runtime instead of the value stored in the database.
  6. Test each updated provider (log in via SSO) to confirm everything works.
  7. Disable local authentication in the authentication screen if you no longer need it.

Optional: to prevent the secret from ever being stored in the database, remove the secret from your provider configuration (e.g. do not set PROVIDERS__OIC__CONFIG__CLIENT_SECRET or the equivalent) before upgrading. After migration, the provider will be created with a placeholder; then in the UI set the secret field to Use external secret as in step 5.

Using Cyberark

To use Cyberark provider after migration instead of storing secrets in the database:

  1. Set up the secrets registry for your external provider. Define each secret via the appropriate environment variables (e.g. SECRETS__<NAME>__CREDENTIALS_PROVIDER__SELECTOR=cyberark and the related Cyberark variables). See External secret with Cyberark.
  2. Ensure local authentication is enabled so you can log in after the upgrade.
  3. Upgrade and start the platform. Migration runs; provider configurations are migrated.
  4. Log in via local authentication, then go to Parameters > Authentications.
  5. Edit each migrated provider that should use Cyberark: open the provider, and for each secret field, choose Use external secret and select the corresponding secret name (the one you defined in the registry pointing to Cyberark). Save. The platform will then fetch the secret from Cyberark at runtime when the strategy is loaded.
  6. Test each updated provider (log in via SSO) to confirm everything works.
  7. Disable local authentication in the authentication screen if you no longer need it.

Prevent any platform from being locked

To avoid any platform from being locked, the migration will ensure that the Local Authentication strategy is enabled if no other enabled strategy exist prior the migration: this way, any platform that is under community edition & disabled the Local Strategy will have a way to login after the migration.

Troubleshoot any issue post migration

To troubleshoot any issue that might occur during the migration, please refer to this page.

Migrating as a Community Edition

Given authentication via SSO is now an Enterprise Edition feature, a couple of solution exist to help you transition: - login via local authentication: as explained in the above paragraph, local authentication will be forced if no other way to login is detected. - request a trial license: you can request a trial license allowing you to use the power of Enterprise Edition in your platform directly through your Hub instance. More information in this page.

Avoiding having an authentication strategy that keeps appearing in the UI

Assuming you have a configuration defined in your configuration file, when upgrading to version 7, your configuration will be converted to UI (stored in database).

If for whatever reason you delete this configuration from UI, next time you will initialize your platform, you will see the same configuration again.

This is due to the migration process. Once you have confirmed that the migration worked (all your users still able to login as usual), you can safely remove your configuration.