Share via

How to update OutboundCertificate in Workflow Manager (and SharePoint)

  • Article

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!!

Comments

  • Anonymous
    August 05, 2015
    Thank you Felipe you made my day. I was facing this issue after removing workflow Manager and re-install it again, and your article made it clear to me that there was new WorkflowBound registered for second installation and it was used to communicated with SharePoint that still using the old certificate. Finally I could update the new certificate and the security token issue on SharePoint. Thanks for made this clear here.

  • Anonymous
    May 20, 2016
    Great post, I was searching around on how to update the outbound certificate, and glad you blogged it. Thanks Felipe!!

  • Anonymous
    June 29, 2016
    Hi! Thanks a lot for your article. Please, could you explain, why Get-WFFarm shows old Thumbprint OutboundCertificate. We have some problems, because we used PKI certificates for in WF OutboundCertificateSslCertificateEncryptionCertificateThe last two of them we changed, but OutboundCertificate - we can't. Is it possible ? Because it's will expired soon...and we have a panic. Thanks for any help!

    • Anonymous
      September 23, 2016
      Hi Jonh,Currently there is a cosmetic issue (not affecting engine runtime) in WFM 1.0 CU3 where Get-WFFarm shows the old certificate after you update outbound certificate. Please, use Get-WFOutboundCertificate instead, since it will return the correct certificate thumbprint.This issue will be solved in next WFM 1.0 CU4.Kind Regards,Felipe.