How to update OutboundCertificate in Workflow Manager (and SharePoint)

Outbound certificate is used to sign the security token portion of a HTTP activity, which includes the claims of the user that instantiates the workflow. This is used for securing communications between workflows and external REST services such as SharePoint, WCF, etc.

There are certain situations where you might need to update the Outbound certificate in Workflow Manager, for example when the certificate is about to expire. When this is the case, follow below instructions:

1. Add the new certificate to thelist of available outbound certificates:

Set-WFNextOutboundCertificateReference -Thumbprint <Your New thumbprint> -ServiceUri  <Workflow Management URI>

2. Set the new certificate as the Outgoing one,  so that all outbound messages going forward will be signed with this new current certificate:

Set-WFNextOutboundCertificateAsCurrent -ServiceUri  <Workflow Management URI>

3. Verify that the new certificate has been defined as OutboundCertificate.

Get-WFOutboundCertificate -ServiceUri  <Workflow Management URI>

 

Additionally, and just in case you are using Workflow Manager to execute SharePoint Workflows, you need to execute below steps to update OutboundCertificate into SharePoint. Otherwise, you might receive below error when executing a SharePoint Workflow because Workflow response was signed with a certificate that SharePoint does not reconize:

System.ApplicationException: HTTP 401{              
"error_description": "Invalid JWT token. Could not resolve issuer token."
"x-ms-diagnostics": ["3000006;reason="Tokencontainsinvalidsignature.";category="invalid_client"],...               
at Microsoft.Activities.Hosting.Runtime.Subroutine.SubroutineChild.Execute(CodeActivityContext context) at System.Activities.CodeActivity.InternalExecute(ActivityInstance instance, ActivityExecutor executor, BookmarkManager bookmarkManager) at
System.Activities.Runtime.ActivityExecutor.ExecuteActivityWorkItem.ExecuteBody(ActivityExecutor executor, BookmarkManager bookmarkManager, Location resultLocation)

  1. Update Outbound certificate in SharePoint

When you register SharePoint against Workflow Manager Farm, Workflow Manager outbound certificate is stored in SharePoint database. So, if the outbound certificate changes in Workflow Manager, you should also update it in SharePoint side by executing below steps:

a) At SharePoint Central Admin portal, under Security => Manage Trust, open “Trust RelationShip” for 00000005-0000-0000-c000-000000000000*. Note: below picture is just shown for illustration purpose.

b) Click Browse Button, select the new outbound certificate, and then click Ok.

c) After that, verify that the all Certificate information (Thumbprint,  Issued to, etc) has been changed properly to the new certificate one.

 

2. Create the corresponding Security Token Issuer in SharePoint for the new Workflow Manager Outbound Certificate

Check whether the thumbprint for the new certificate has been already updated according for SPTrustedSecurityTokenIssuer whose RegisteredIssuerName = "00000005-0000-0000-c000-000000000000@*".

Get-SPTrustedSecurityTokenIssuer| ft -autosize name,@{expression={$_.signingcertificate.thumbprint};label="Thumbprint"},RegisteredIssuerName,Id

If it is still pointing to the old certificate thumbprint, you need to execute below cmdlets to create the corresponding Security Token Issuer in SharePoint for the new Workflow ManagerOutbound Certificate

a) Load new certificate into $cert :

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("<Your new certification Path>.cer")

b) Create a new TrustedSecurityTokenIssuer in SharePoint based on $cert:

$tokenIssuer = New-SPTrustedSecurityTokenIssuer -Certificate $cert -Name <FriendlyName> -RegisteredIssuerName "00000005-0000-0000-c000-000000000000@*"

$tokenIssuer.IsSelfIssuer = < $true if you are using Auto-generated WFM certificate (Wildcard), or $false if you are using your own custom certificate >
$tokenIssuer.Update()

Note: <FriedlyName> is a placeholder to specify the name you want for this SPTrusterSecurityTokenIssuer. By default when registering WFM in SharePoint (Register-SPWorkflowService) it is created in SharePoint a SPTrustedSecurityTokenIssuer named "00000005-0000-0000-c000-000000000000", you can keep it though it is recommended to delete to avoid future confusions.

 

Hope it helps!!