Introduction:
ServiceNow provides OOB Microsoft sharepoint spoke which helps to integrate MS sharepoint with servicenow to pull files, folders into ServiceNow.This integration needs certificates to authenticate with sharepoint. These certificates has some expiry dates. When these certs expire, we need to perform bunch of steps in servicenow and azure to keep this integration working.
This article covers these steps.
Updating Sharepoint JWT Credentials
In order to access certain Sharepoint APIs it is necessary to have both client credentials, as well as a valid cert to access the API. The purpose of this document is to outline how to update the credentials and cert in ServiceNow.
Generating the Certificate
The first step to be taken is to generate a new certificate. The certificate can be
generated from a users local machine. Below are instructions for generating the cert on using MaC OS or Windows.
Mac OS:
Mac system can generate the certificate using Terminal and Keytool commands
-
Open Terminal
-
Run the following command. This will generate the IMPORTANT Please note that values will need to be substituted for the keypass and keystore variables. Do not run without changing the values:
Keytool -genkey -alias selfsigned -keyalg RSA -keypass <keypassword> -storepass <keystorepass> -keystore Keystore.pfx -keysize 2048 -validity 1461
3.Running the command will generate a prompt. Enter the relevant information
4. Next run the following command to export the files needed. A prompt will come up asking for the password set earlier in step 1, enter that password.
Keytool -export -keystore keystore.pfx -alias selfsigned -file ketstore.cer
5.When done, there will be a .pfx and .cer file generated that will be needed for this process.
Windows:
In order to generate the certificate on a Windows system it is necessary to run a powershell script.
*Warning, users may get a policy error on their local computer when trying to run powershell scripts as admins.
1. Create a new powershell script using the script below
#Requires -RunAsAdministrator
<#
.SYNOPSIS
Creates a Self Signed Certificate for use in server to server authentication
.DESCRIPTION
.EXAMPLE
PS C:\> .\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21
This will create a new self signed certificate with the common name "CN=MyCert". During creation you will be asked to provide a password to protect the private key.
.EXAMPLE
PS C:\> .\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21 -Password (ConvertTo-SecureString -String "MyPassword" -AsPlainText -Force)
This will create a new self signed certificate with the common name "CN=MyCert". The password as specified in the Password parameter will be used to protect the private key
.EXAMPLE
PS C:\> .\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21 -Force
This will create a new self signed certificate with the common name "CN=MyCert". During creation you will be asked to provide a password to protect the private key. If there is already a certificate with the common name you specified, it will be removed first.
#>
Param(
[Parameter(Mandatory=$true)]
[string]$CommonName,
[Parameter(Mandatory=$true)]
[DateTime]$StartDate,
[Parameter(Mandatory=$true)]
[DateTime]$EndDate,
[Parameter(Mandatory=$false, HelpMessage="Will overwrite existing certificates")]
[Switch]$Force,
[Parameter(Mandatory=$false)]
[SecureString]$Password
)
# DO NOT MODIFY BELOW
function CreateSelfSignedCertificate(){
#Remove and existing certificates with the same common name from personal and root stores
#Need to be very wary of this as could break something
if($CommonName.ToLower().StartsWith("cn="))
{
# Remove CN from common name
$CommonName = $CommonName.Substring(3)
}
$certs = Get-ChildItem -Path Cert:\LocalMachine\my | Where-Object{$_.Subject -eq "CN=$CommonName"}
if($certs -ne $null -and $certs.Length -gt 0)
{
if($Force)
{
foreach($c in $certs)
{
remove-item $c.PSPath
}
} else {
Write-Host -ForegroundColor Red "One or more certificates with the same common name (CN=$CommonName) are already located in the local certificate store. Use -Force to remove them";
return $false
}
}
$name = new-object -com "X509Enrollment.CX500DistinguishedName.1"
$name.Encode("CN=$CommonName", 0)
$key = new-object -com "X509Enrollment.CX509PrivateKey.1"
$key.ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
$key.KeySpec = 1
$key.Length = 2048
$key.SecurityDescriptor = "D:PAI(A;;0xd01f01ff;;;SY)(A;;0xd01f01ff;;;BA)(A;;0x80120089;;;NS)"
$key.MachineContext = 1
$key.ExportPolicy = 1 # This is required to allow the private key to be exported
$key.Create()
$serverauthoid = new-object -com "X509Enrollment.CObjectId.1"
$serverauthoid.InitializeFromValue("1.3.6.1.5.5.7.3.1") # Server Authentication
$ekuoids = new-object -com "X509Enrollment.CObjectIds.1"
$ekuoids.add($serverauthoid)
$ekuext = new-object -com "X509Enrollment.CX509ExtensionEnhancedKeyUsage.1"
$ekuext.InitializeEncode($ekuoids)
$cert = new-object -com "X509Enrollment.CX509CertificateRequestCertificate.1"
$cert.InitializeFromPrivateKey(2, $key, "")
$cert.Subject = $name
$cert.Issuer = $cert.Subject
$cert.NotBefore = $StartDate
$cert.NotAfter = $EndDate
$cert.X509Extensions.Add($ekuext)
$cert.Encode()
$enrollment = new-object -com "X509Enrollment.CX509Enrollment.1"
$enrollment.InitializeFromRequest($cert)
$certdata = $enrollment.CreateRequest(0)
$enrollment.InstallResponse(2, $certdata, 0, "")
return $true
}
function ExportPFXFile()
{
if($CommonName.ToLower().StartsWith("cn="))
{
# Remove CN from common name
$CommonName = $CommonName.Substring(3)
}
if($Password -eq $null)
{
$Password = Read-Host -Prompt "Enter Password to protect private key" -AsSecureString
}
$cert = Get-ChildItem -Path Cert:\LocalMachine\my | where-object{$_.Subject -eq "CN=$CommonName"}
Export-PfxCertificate -Cert $cert -Password $Password -FilePath "$($CommonName).pfx"
Export-Certificate -Cert $cert -Type CERT -FilePath "$CommonName.cer"
}
function RemoveCertsFromStore()
{
# Once the certificates have been been exported we can safely remove them from the store
if($CommonName.ToLower().StartsWith("cn="))
{
# Remove CN from common name
$CommonName = $CommonName.Substring(3)
}
$certs = Get-ChildItem -Path Cert:\LocalMachine\my | Where-Object{$_.Subject -eq "CN=$CommonName"}
foreach($c in $certs)
{
remove-item $c.PSPath
}
}
if(CreateSelfSignedCertificate)
{
ExportPFXFile
RemoveCertsFromStore
}
2. Open the Powershell ISE as Administrator
To open as Administrator, right click on the Icon for Powershell ISE and select Run as Administrator.
3.
Run the command below in the Powershell ISE. Change the values for CommonName, StartDate, and EndDate to valid values
.\Create-SelfSignedCertificate.ps1 -CommonName "MyCompanyName" -StartDate 2017-10-01 -EndDate 2019-10-01
4. The script will generate the two files that are needed and will place them in the folder the script was run from.
Updating Azure
In order to finish updating the credentials, it will be necessary for the Azure/O365 team to generate a new client secret, as well as upload the .cer file we generated and return a thumbprint value.
Converting the Thumbprint value
Before the Thumbprint value can be used by ServiceNow, it needs to be converted from HEX to Base64. This tool from Base64Guru is recommended by ServiceNow for converting the value.
Convert .pfx to .jks
According to ServiceNow’s documentation that is uploaded to ServiceNow can be either a .pfx or .jks file (.PFX - from Washington, till Vancouver we can use .JKS and .CER). If a need arise to convert the .pfx file to a .jks file the following command can be used
keytool -importkeystore -srckeystore mypfxfile.pfx -srcstoretype pkcs12 -destkeystore clientcert.jks -deststoretype JKS
In the command change out the values for mypfxfile.pfx for the the name of the .pfx file and update clientcert.jks to the name we would like to use for the cert. When prompted for the password, enter the password that was used when the .pfx file was generated.
Updating ServiceNow
-
Update the client secret value on the SharePoint Online Spoke 2023 oauth entity record
-
Update the password on the Microsoft SharePoint Online JWT Keys record. The password is the password used when generating the certificate
-
Update the Thumbprint value on the sharepoint http connection record using the value generated previously, after the value has been converted to Base64
-
Remove the current file attached to the Microsoft SharePoint Online Certificate certificate record
-
Attach the .pfx (or .jks) file that was generated previously to the certificate record
-
Update the password on the certificate record to the password used when generating the certificate.
-
Click Stores/Certificates
-
If the test comes back successful, the message Valid key_store will be displayed
-
If the test comes back unsuccessful, make sure the password on the form is the same password used when generating the certificate.
-
Additional Resources
ServiceNow KB1702779 - Knowledge article covering the Sharepoint spoke setup
Granting Access via Azure AD App-Only - Document referred to by ServiceNow for generating the certificate files on a Windows system
Base64Guru - Converting Hex to Base64
Convert .pfx to .jks - How to convert the .pfx file to a .jks file
