When the K2 Server is installed, a high-trust certificate is generated and stored in the K2 database. This certificate is unique to that K2 environment. When the K2 for SharePoint App is installed, the SharePoint environment reads this certificate from the K2 environment. When there are multiple K2 environments (for example a Production environment and a Development environment) which connect to the same SharePoint server, only the most recently registered K2 for SharePoint App will work because of the unique certificate that was read from that K2 environment's database. This article describes how to use tooling to copy the high-trust certificate between K2 environments so that both K2 environments can work against the same SharePoint server.
This topic applies to SharePoint 2013/2016/2019
- Contact K2 Support to obtain the Certificate Manager tool that is used to copy the High-trust certificate from one K2 environment to another K2 environment. The Certificate Manager tool is a command line tool that needs to be run as Administrator with a user account that has rights to access the K2 database, preferably the installation account. The tool can be run on any machine that can access the K2 database for that environment.
The syntax of the command is as follows:
CertificateManager.exe ["connection string"] [PARAMETER] [file name]
"connection string": a sql connection string that points to the K2 database
PARAMETER: EXTRACT or INSERT
file name: the name of the file to create (EXTRACT), or the file that should be imported (INSERT)
- On a machine that can connect to the K2 environment that was last configured with the K2 App (in other words the working environment; we will use "Development" in this sample) run the following command to extract the certificate to a text file:
CertificateManager.exe "Data Source=devsql;Initial Catalog=K2;integrated security=sspi;Pooling=True" EXTRACT data.txt
This will decrypt the environment's encrypted variables, and save them to the file 'data.txt'.
- Copy the text file that was created to a machine that can connect to the second (non-working) K2 environment. On this second machine, run the following command to import the certificate data from the text file into the second K2 environment ("Production" in this sample):
CertificateManager.exe "Data Source=prodsql;Initial Catalog=K2;integrated security=sspi;Pooling=True" INSERT data.txt
This will re-encrypt the decrypted data in the file ('data.txt' in this sample) and import the certificate into the second K2 environment. It is important that the database connection string is changed to point to the correct database when you EXTRACT or INSERT the file, otherwise the same set of variables will be updated each time. After you have imported the file into the second K2 environment, you can run the EXTRACT command on the second machine to compare the values in the text file to the values obtained from the first machine, and confirm that they are the same.
- If you are using K2 4.7 or later, you will also need to update the [SHAREPOINT_HIGHTRUST_ISSUER_ID] value in the [K2].[HostServer].[Configuration] table as follows:
- In either of the K2 environments, back up the K2 database, or at least back up the [K2].[HostServer].[Configuration], [K2].[Authorization].[OAuthAppOnlyToken] and [K2].[Authorization].[OAuthIdentity] tables.
- Open the SharePoint management shell, and run the command Get-SPTrustedSecurityTokenIssuer. Take note of the value for the RegisteredIssuerName for the K2 High trust certificate. The RegisteredIssuerName will be in the format <GUID1>@<GUID2>. Make a note of the value of GUID1 (in other words the value before the @ sign), this is the value you will need to insert into your K2 database using the SQL command in the next step
- Open a SQL query to your K2 environment's database, and execute the following command, replacing the value in blue with the value you obtained in step 4.2:
UPDATE [K2].[HostServer].[Configuration] SET VariableValue = '<GUID>' where VariableToken = '[SHAREPOINT_HIGHTRUST_ISSUER_ID]'
- Clear the cached tokens by deletin the contents of the [K2].[Authorization].[OAuthAppOnlyToken] and [K2].[Authorization].[OAuthIdentity] tables
- Repeat steps 4.1 to 4.4 for the other K2 environment.
- Now both environments should be using the same value for the [SHAREPOINT_HIGHTRUST_ISSUER_ID] value in the [K2].[HostServer].[Configuration] table