Migrating to a New Identity Provider

If you decide you want to switch from one identity provider to another, you need to do some planning to assure a smooth transition. If you’re currently using Active Directory and want to switch to using OAuth or currently using OAuth and want to switch to using Active Directory, Keyfactor recommends standing up a second instance of Keyfactor Command using the alternate identity provider on a separate URL but communicating with the same backend database and then slowly migrating users over from one URL and IdP to the other, decommissioning the initial instance of Keyfactor Command once all users are migrated. If you would prefer instead to update the authentication mechanism of your existing Keyfactor Command instance, below is an outline of the steps to follow.

Things to consider before you make the switch include what and how authentication is happening to your Keyfactor Command instance currently. For example:

  • Do you have any agents or orchestrators deployed and connected to Keyfactor Command? What authentication mechanism are these agents/orchestrators using? These will need to be updated to the new authentication mechanism. Older agents and orchestrators may not support token authentication (assuming a migration from Active Directory to OAuth) and will need to be upgraded.

  • Do you have any Keyfactor APIClosed A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. applications? What authentication mechanism are these applications using? These will need to be updated to the new authentication mechanism.

  • Do you have any workflows with embedded authentication (for Keyfactor API requests)? These will need to be updated to the new authentication mechanism.

  • Do you have any other implementations in your environment that integrate with Keyfactor Command (e.g. custom applications, gateways, ACME)? These will need to be updated to the new authentication mechanism. Some implementations and implementation versions may not support token authentication.

  • Are any of your users using the Keyfactor API Reference and Utility (Swagger)? These users will need training on how to authenticate to the Keyfactor API Reference and Utility under the new identity provider (see Authenticating to the Keyfactor API).

To migrate an existing Keyfactor Command instance from Active Directory to OAuth (or vice versa):

  1. Consider whether the name of each virtual directory in IIS is significant to you. For example, the default virtual directory for the Keyfactor API is KeyfactorAPI. If you have Keyfactor API applications relying on this name, this is significant. The default virtual directory name for the agent and orchestratorClosed Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. requests is KeyfactorAgents. If you have agents and/or orchestrators deployed in your environment, this is significant. The default virtual directory name for the Management Portal is KeyfactorPortal. If you have users already trained to use this or you have links in place to this, it’s significant. When you modify the identity provider for an existing Keyfactor Command implementation from Active Directory to OAuth or vice versa, new virtual directories will be created with the new authentication settings appropriate to the new identity provider. Since these can’t have the same name as the existing virtual directories, these will change without some advanced planning.

  2. If you’ve decided you want to retain the same virtual directory names, BEFORE making any identity provider changes, on the Keyfactor Command server, open the Keyfactor Command Configuration Wizard, connecting to your SQL server and selecting your Keyfactor Command database name. In the configuration wizard on the Keyfactor Portal tab, change the Virtual Directory name to something other than the existing value (e.g. KeyfactorPortal-AD). Repeat this step for the Virtual Directory names on the Dashboard and Reports, Orchestrators, and API tabs. The KeyfactorProxy virtual directory is used only by OAuth identity providers and does not need to be modified on a switch to or from Active Directory. Apply the changes and close the configuration wizard. You will now have two sets of virtual directories in IIS.

    Figure 418: Change the Virtual Directory Name

  3. Open the Keyfactor Command Configuration Wizard again, connecting to your SQL server and selecting your Keyfactor Command database name.

  4. On the Authentication tab of the configuration wizard, make your configuration changes as per the regular installation instructions (see Authentication Tab).

  5. On the Administrative Users tab, add at least one administrative user for the new identity provider (see Administrative Users Tab).

  6. Update the Virtual Directory names on the Keyfactor Portal, Dashboard and Reports, Orchestrators, and API tabs to the names you wish to use going forward.

  7. Apply the changes and close the configuration wizard.