The POST /Users/Migrate operation migrates or updates select settings of a user record in Keyfactor Command to a new or existing user record for the user. This is most commonly used to migrate users from Active Directory to an OAuth identity provider or from one OAuth identity provider to another. On success, the operation returns 204 with no content.
Users are not the same as claims or identities. User records are generated from a number of different sources and used in a variety of ways. When a user logs into the Keyfactor Command Management Portal, a user record is generated for this user. If the user has been granted access to Keyfactor Command via a group security claim, there will not be a security claim for the individual user’s name, but a user record for the individual is required to track user-specific settings and data, including:
- Management Portal dashboard settings for the user, which are unique to each user. Both the legacy and new dashboard are supported.
- The requester field on certificates and certificate requests, which will contain the user’s account name, not the group claim used to grant the user access to Keyfactor Command.
- User names associated with workflow
A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. instances—the user who initiated the workflow instance, the user who restarted the workflow instance, if applicable. - User names associated with providing input signals to workflow instances—for example, users who approve requests that require approval.
The migrate operation updates user data in all the above locations. If the requester field on a certificate or certificate request is updated by the migrate operation, subsequent CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. synchronizations will not overwrite this requester information with the older requester name.
The list of users defined in Keyfactor Command is not visible in the Management Portal or queryable using a Keyfactor API An API is 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. operation.
The user must hold a role containing this permission in the Global Permission Set (see Permission Sets).
Table 1010: POST Users Migrate Input Parameters
Example: Migrate Active Directory User to Keycloak
First, determine the user name of the source record to be migrated. This must be a valid record in the Users database. This operation is not available in the Keyfactor API Reference and Utility, so you will need to use an alternate tool to make your request. The request body to update a single, existing, Active Directory user to a new, not-yet-created, Keycloak user would look like the following:
{
"OriginalUsername": "KEYEXAMPLE\\zadams",
"NewUsername": "zadams",
"OriginalIdentityProvider": "Active Directory",
"NewIdentityProvider": "Command-OIDC",
"NewUniqueClaimType": "sub",
"NewUniqueClaimValue": "a99088ae-fc21-4fd0-ae6b-9f83e7d6eec8"
}Example: Migrate User for the Unknown Identity Provider to Active Directory
Under some circumstances, user records in Keyfactor Command can be created and marked as having an Unknown identity provider. This can occur, for example, on certificate import of certificates from a cloud-based vendor where user records are created for the requesters of the certificates being imported. Since the issuer of the certificate does not include identity provider information along with the requester, this information is not available when creating the user record, so the identity provider is marked as Unknown. You may know who the users are and wish, for example, to map these users accurately to an identity provider so that the requester data can be tracked for users both internally and externally as a single user.
To do this, first determine the user name of the source record to be migrated. This must be a valid record in the Users database. This operation is not available in the Keyfactor API Reference and Utility, so you will need to use an alternate tool to make your request. The request body to update a single, existing, Unknown user to an existing Active Directory user would look like the following:
{
"OriginalUsername": "jsmith",
"NewUsername": "KEYEXAMPLE\\jsmith",
"OriginalIdentityProvider": "Unknown",
"NewIdentityProvider": "Active Directory",
"NewUniqueClaimType": "http://schemas.micrsoft.com/ws/2008/06/identity/claims/primarysid",
"NewUniqueClaimValue": "KEYEXAMPLE\\jsmith"
}Was this page helpful? Provide Feedback