POST Users Migrate

The POST /Users/Migrate method is used to migrate or update 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. This endpoint An endpoint is a URL that enables the API to gain access to resources on a server. returns 204 with no content upon success.

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.
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—e.g. users who approve requests that require approval.

The migrate endpoint updates user data in all of the above locations. If the requester field on a certificate or certificate request is updated by the migrate endpoint, 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. endpoint.

Tip: The following permissions (see Security Roles and Claims) are required to use this feature:

/security/modify/

The user must hold a role containing this permission in the Global Permission Set (see Permission Sets).

Table 854: POST Users Migrate Input Parameters

Name	In	Description
Original Username	Body	Required. A string containing the user name for the source user containing the information to be migrated or updated. For Active Directory users, this will be in the form DOMAIN\\user name. For example: KEYEXAMPLE\\jsmith The source user must exist in the Users database to use this endpoint. User records are unique by username and identity provider combination.
New Username	Body	Required. A string containing the user name for the target user into which the information will to be migrated or updated. If the user already exists, it will be updated. If the user does not already exist, it will be created and populated with the source information.
Original Identity Provider	Body	Required. A string containing the Authentication Scheme of the source user’s identity provider. For example: Active Directory
New Identity Provider	Body	Required. A string containing the Authentication Scheme of the identity provider for the user record into which the data will be migrated or updated. This identity provider must be defined in Keyfactor Command.
New Unique Claim Type	Body	Required. A string containing the unique claim type that will be used for the new user record. This value will vary depending on the target identity provider and the configuration choices made for that identity provider. For example: Active Directory: http://schemas.micrsoft.com/ws/2008/06/identity/claims/primarysid Keyfactor Identity Provider: sub
New Unique Claim Value	Body	Required. A string containing the unique claim type value that will be used for the new user record. The format of this value will vary depending on the target identity provider and the selected unique claim type. For example: Active Directory: KEYEXAMPLE\\mjones Keyfactor Identity Provider: a99088ae-fc21-4fd0-ae6b-9f83e7d6eec8

Note: This endpoint is not exposed in the Keyfactor API Reference and Utility to reduce accidental usage. You may still make use of it by calling it from your own tool.

Example: Migrate Active Directory User to Keyfactor Identity Provider

First, determine the user name of the source record to be migrated. This must be a valid record in the Users database. This endpoint 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, Keyfactor Identity Provider user would look like the following:

Copy

{
  "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 end up 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”. However, you may actually 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 endpoint 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:

Copy

{
  "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

Version v25.1.1

On this page: