Workflow Definitions Examples

# Declare your parameters at the beginning
param(
   [string]$AdditionalAttributes
)

# Trim brackets off incoming attribute string
$TrimmedAttributes = $AdditionalAttributes.Substring(1,$AdditionalAttributes.Length-2)

# Replace commas bracketed by quotes in attribute string with a temporary string to facilitate splitting (assumes no incoming values contain temp string)
$TempString = "`"######`""
$CleanAttributes = $TrimmedAttributes -replace "`",`"", $TempString

# Split the incoming attribute string into its component values at the temporary string
$SplitAttributes = $CleanAttributes.Split('######')

# Split the incoming attribute string key/value pairs
foreach($attribute in $SplitAttributes){
   $attributeComponents = $attribute.Trim() -split ":"
   $attributeComponents
   Switch($attributeComponents[0].Trim()){
      '"Department"' {$Department = $attributeComponents[1].Substring(1,$attributeComponents[1].Length-2)}
      '"Code"' {$Code = $attributeComponents[1].Substring(1,$attributeComponents[1].Length-2)}
   }
}

# Initialize a hashtable
$UpdatedAttributes = @{}

# Load original attributes in UpdatedAttributes for the else case
if(![string]::IsNullOrWhiteSpace($Code)) {
   $UpdatedAttributes['Code'] = $Code
}
if(![string]::IsNullOrWhiteSpace($Department)) {
   $UpdatedAttributes['Department'] = $Department
}

# If the value of Department is "Accounting", then the value of Code must be "G5N145"; override submitted value--if any--and use fixed value
if($UpdatedAttributes['Department'] -eq "Accounting") {
   $UpdatedAttributes['Code'] = "G5N145"
}

# Return the updated attributes to the workflow in the original parameter as a hashtable
$result = @{ "AdditionalAttributes" = $UpdatedAttributes }
return $result

# Declare your parameters at the beginning ($Comment, $SDate, and $Edate)
param(
   [string]$Comment,
   [datetime]$SDate,
   [datetime]$EDate
)

# Append your additional text to the existing comment along with the submission and effective dates
$Comment += " - Revocation requested on " + $SDate.ToString("g") + " and effective on " + $EDate.ToString("g")

# Return the updated comment to the workflow in the original parameter as a hashtable
$result = @{ "Comment" = $Comment }
return $result

# Declare your parameters at the beginning
param(
   [string]$ApprovalComment,
   [string]$SignalComment,
   [string]$Metadata
)

# Initialize a hashtable to contain your metadata fields and populate it
$UpdatedMetadata = @{}

$metaObject = $Metadata | ConvertFrom-Json -AsHashtable

foreach ($property in $metaObject.Keys) {
    $UpdatedMetadata[$property] = $metaObject[$property]
}

# Append your signal comment(s) to any existing comment in the ApprovalComments metadata field
if([string]::IsNullOrWhiteSpace($ApprovalComment)) {
   $UpdatedMetadata['ApprovalComments'] = $SignalComment
}else {
   $UpdatedMetadata['ApprovalComments'] = $ApprovalComment + ", " + $SignalComment
}

# Return the updated metadata fields, including ApprovalComments, to the workflow in the original parameter as a hashtable
$result = @{ "ApprovalComment" = $UpdatedMetadata }
return $result

# Declare your parameters at the beginning
param(
   [string]$cn,
   [string]$issuedDate,
   [string]$CA,
   [string]$expireDate,
   [string]$template
)

$LogName = "Application"
$Message = "The certificate in the name $cn issued on $issuedDate from $CA using the $template template will expire on $expireDate."
$Source = "Keyfactor Command"
# EventId 6050 is designated for alert event logging; category 3 is "Monitoring" on the Keyfactor Command server
$EventID = "6050"
$EventType = "Information"
$Category = 3

# Write the event log messages to the Keyfactor Command server
$eventLog = New-Object System.Diagnostics.EventLog
$eventLog.Log = $LogName
$eventLog.Source = $Source
$eventLog.WriteEntry($Message, $EventType, $EventID, $Category)

Expiration Alert: Certificate $(cn) Expiring on $(expdate)

Hello,

The certificate in the name  $(cn) issued on $(issuancedate) from $(CA) using the $(Template) template will expire on $(expdate). The certificate will automatically be renewed as part of this workflow.
The certificate details include:

   <ul>
      <li>Certificate ID: $(certid)</li>   
      <li>CN: $(cn)</li>
      <li>DN: $(dn)</li>
      <li>SANs: $(sans)</li>
      <li>App Owner First Name: $(metadata:AppOwnerFirstName)</li>
      <li>App Owner Last Name: $(metadata:AppOwnerLastName)</li>
   </ul>

Thanks!
Your Certificate Management Tool

Expiration Alert: Certificate $(cn) Successfully Renewed

Hello,

A renewal was requested for the certificate in the name  $(cn) from $(CA) using the $(Template) template with the following result: $(RequestDisposition)

The certificate details include:

   <ul>
      <li>Original Certificate ID: $(certid)</li>
      <li>New Certificate ID: $(RenewedCertId)</li>
      <li>New Thumbprint: $(Thumbprint)</li>
      <li>New Serial Number: $(SerialNumber)</li>      
      <li>CN: $(cn)</li>
      <li>DN: $(dn)</li>
      <li>SANs: $(sans)</li>
      <li>App Owner First Name: $(metadata:AppOwnerFirstName)</li>
      <li>App Owner Last Name: $(metadata:AppOwnerLastName)</li>
   </ul>

Thanks!
Your Certificate Management Tool

# Declare your parameter at the beginning
param(
   [string]$SubjectCN
)

# Initialize a variable for the response
$shouldRun = @()

# Check to see if the requested CN ends with keyexample.com and require approval in the next step if it does not
$Suffix = "keyexample.com"

if ($SubjectCN.EndsWith($Suffix))
{
   $shouldRun = "False"
}else {
   $shouldRun = "True"
}

# Return the true/false value to the workflow as a hashtable
$result = @{ "shouldRun" = $shouldRun; }
return $result

# Declare your parameters at the beginning ($InputCN, $Domain1, $Domain2, and $InputSANs)
param(
   [string]$InputCN,
   [string]$Domain1,
   [string]$Domain2,
   [string]$InputSANs
)

# Load incoming SANs into a hash table
$SANTable = $InputSANs | ConvertFrom-Json -AsHashtable

# Initialize variables for the two types of SANs we're handling
$DnsSans = @()
$IpSans = @()

# Check if SANTable has properties 'dns' and 'ip4' and assign if they exist
if ($SANTable.ContainsKey("dns") -and $SANTable["dns"]) {
    $DnsSans = $SANTable["dns"]
}

if ($SANTable.ContainsKey("ip4") -and $SANTable["ip4"]) {
    $IpSans = $SANTable["ip4"]
}

# Check to see if the incoming CN ends with keyexample.com and, if so, add some SANs.
$Suffix = "keyexample.com"

if ($InputCN.EndsWith($Suffix))
{
   # Load just the portion of the CN without the domain name into a variable.
   $CNName = $InputCN.SubString(0,$InputCN.Length - $Suffix.Length)

   # Do a lookup on the requested CN to find its IPv4 address.
   $IPResult = Resolve-DnsName -Name $InputCN -Type A -ErrorAction SilentlyContinue

   # If an address is found, add that address as a SAN.
   # Also add SANs built with the contents of Domain1, Domain2, and the leading part of the CN
   # (e.g. mycert.my-first-other-domain.com and mycert.my-second-other-domain.com).
   if ($IPResult -ne $null)
   {
      $SAN1 = $IPResult.IPAddress
      $SAN2 = $CNName + $Domain1
      $SAN3 = $CNName + $Domain2
      $DnsSans += $SAN2
      $DnsSans += $SAN3
      $IpSans += $SAN1
   }
   # If an IP address is not found, add only the SANs featuring Domain1 and Domain2.
   else {
      $SAN2 = $CNName + $Domain1
      $SAN3 = $CNName + $Domain2
      $DnsSans += $SAN2
      $DnsSans += $SAN3
   }
}

# Load the resulting IPv4 and DNS SANs into the SANS variable
$UpdatedSANs = @{}

if(![string]::IsNullOrWhiteSpace($DnsSans)) {
   $UpdatedSANs.dns = $DnsSans
}

if(![string]::IsNullOrWhiteSpace($IpSans)) {
   $UpdatedSANs.ip4 = $IpSans
}

# Return the updated SANs to the workflow as a hashtable (case matters in the return value name "SANs" in order
# to reload the results back into the SANs token)
$result = @{ "SANs" = $UpdatedSANs; }
return $result

# Declare your parameters at the beginning
param(
   [string]$Requester
)

#Convert the requester to JSON
$RequesterJSON = ($Requester | ConvertTo-Json)

# Build the query for the REST step
$Query = "Username -eq $RequesterJSON"

# Return the query to the workflow as a hashtable
$result = @{ "Query" = $Query }
return $result

Certificate Enrollment Request for $(request:cn)

Hello,

A certificate using the $(template) template was requested by $(requester:displayname) from $(CA) on $(subdate).

The certificate details include:

   <ul>
      <li>CN: $(request:cn)</li>
      <li>DN: $(request:dn)</li>
      <li>SANs: $(sans)</li>
      <li>App Owner First Name: $(metadata:AppOwnerFirstName)</li>
      <li>App Owner Last Name: $(metadata:AppOwnerLastName)</li>
   </ul>

The requester’s SSH information includes:

   <ul>
      <li>ID: $(MyResponse.Result[0].Key.Id)</li>
      <li>Email: $(MyResponse.Result[0].Key.Email)</li>
      <li>Comments: $(MyResponse.Result[0].Key.Comments.[*])</li>
   </ul>

Thanks!
Your Certificate Management Tool

# Declare your parameters at the beginning ($Comment, $Notes, $RevCode, $Date, and $RevokeBy)
param(
   [string]$Comment,
   [string]$Notes,
   [string]$RevCode,
   [datetime]$Date
   [string]$RevokeBy
)

# Append your additional text to the existing text in the metadata Notes field along with the revoker (removing
# the leading 'DOMAIN\' part), submission date, revocation code, and comment entered at revocation, 
# and beginning the entry with a newline.
$Notes += "`nRevoked on " + $Date.ToString("MMMM d, yyyy") + " by " + $RevokeBy.SubString($RevokeBy.IndexOf('\')+1) + " with revocation option '" + $RevCode + "' and comment '" + $Comment + "'."

# Return the updated metadata Notes value as MyNotes to the workflow as a hashtable
$result = @{ "MyNotes" = $Notes }
return $result

# Declare your parameters at the beginning
param(
   [string]$StoreData,
   [string]$TimeData
)

# Pick one authentication mechanism for the Keyfactor API
# Basic authentication credentials to authenticate to the Keyfactor API
$user = 'KEYEXAMPLE\APIUser'
$pass = 'APIUserSuperSecretPassword'

# Encode Basic authentication credentials
$pair = "$($cred.Username):$($cred.GetNetworkCredential().Password)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

# Token authentication credentials to authenticate to the Keyfactor API (uncomment the below 9 lines and update appropriately to use token authentication)
#$TokenBody = @{
#   grant_type = "client_credentials"
#   client_id = "Keyfactor-API-Workflow-User"
#   client_secret = "WorkflowAPIClientSecret"
#}
#$TokenHeaders = @{
#   'Content-Type' = 'application/x-www-form-urlencoded'
#}
#$TokenURL = "https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token"

# Request token from Keyfactor Identity Provider for token authentication (uncomment the below line to use token authentication)
#$TokenValue = Invoke-RestMethod -Method Post -Uri $TokenURL -Headers $TokenHeaders -Body $TokenBody

# Pick an authentication type for the header
$headerAuth = $basicAuthValue
#$headerAuth = "Bearer " + $TokenValue.access_token

# Build the headers for the API request
$headers = @{
   "Authorization"=$headerAuth
   "Accept"="application/json"
   "x-keyfactor-requested-with"="APIClient"
}

# Convert incoming data from JSON
$StoreDataInfo = $StoreData | ConvertFrom-Json
$TimeDataInfo = $TimeData | ConvertFrom-Json

# Initialize Variables introduced in script
$JobTime = ""
$JobTimeHuman = ""
$TimeMessage = ""
$StoreMessage = ""
$StoreList = New-Object System.Collections.Generic.List[System.Object]
$CommandServer = 'keyfactor.keyexample.com'

# Evalulate the scheduled delivery time for the certificate store management job, if present, and populate a return message based on the content
if ("Immediate" -in $TimeDataInfo.PSobject.Properties.Name)
{
   $TimeMessage = "The certificate has been scheduled to be delivered at the next orchestrator run."
}
elseif ("ExactlyOnce" -in $TimeDataInfo.PSobject.Properties.Name)
{
   # Convert the certificate store job time to a human readable date/time
   $JobTime = [DateTime]($TimeDataInfo.ExactlyOnce.Time)
   $JobTimeHuman = $JobTime.ToString("M/dd/yyyy h:mm tt")
   $TimeMessage = "The certificate has been scheduled to be delivered at the following time: $JobTimeHuman."
}
else
{
   $TimeMessage = " "
}

# Pull out the display names of the certificate stores based on the store IDs in the incoming store info
foreach ($Store in $StoreDataInfo){
   $response = Invoke-WebRequest -Uri "https://$($CommandServer)/KeyfactorAPI/CertificateStores/$($store.StoreId)" -Method:Get -Headers $headers `
      -ContentType "application/json" -ErrorAction:Stop -TimeoutSec 60
   $responseContent = $response.Content | ConvertFrom-Json

   #Add the store to the store list
   $StoreList.Add($responseContent.DisplayName)
}

# Evaluate whether any stores were returned and build a message that includes the store list if so, and an alternate message if not
if ($StoreList.Count -gt 0)
{
   $StoreMessage = "If approved, the certificate will be delivered to the following stores:<br /><br />" + ($StoreList -join "<br />")
}
else
{
   $StoreMessage = "If approved, the certificate will be available for download in the Keyfactor Command Management Portal. It has not been scheduled for delivery to any certificate stores."
}

# Return the time message and store message to the workflow as a hashtable
$result = @{ "TimeMessage" = $TimeMessage; "StoreMessage" = $StoreMessage }
return $result

ACTION REQUIRED: Certificate Enrollment Request for $(request:cn)

Hello,

A certificate using the $(template) template was requested by $(requester:displayname) from $(CA) on $(subdate). $(StoreMessage)

$(TimeMessage) 

The certificate details include:

   <ul>
      <li>CN: $(request:cn)</li>
      <li>DN: $(request:dn)</li>
      <li>SANs: $(sans))</li>
      <li>App Owner First Name: $(metadata:AppOwnerFirstName)</li>
      <li>App Owner Last Name: $(metadata:AppOwnerLastName)</li>
   </ul>

Please review this request and issue the certificate as appropriate by going here:

$(reviewlink)

Thanks!
Your Certificate Management Tool

Certificate Enrollment Request Denied for $(request:cn)

Certificate Enrollment Request Approved for $(request:cn)

Hello $(requester:givenname),

The certificate you requested on $(subdate) in the name $(request:cn) has not been issued for the following reason:

$(approvalsignalcmnts)

The certificate details include:

   <ul>
      <li>CN: $(request:cn)</li>
      <li>DN: $(request:dn)</li>
      <li>SANs: $(sans))</li>
      <li>App Owner First Name: $(metadata:AppOwnerFirstName)</li>
      <li>App Owner Last Name: $(metadata:AppOwnerLastName)</li>
   </ul>

For assistance, please contact <a href="mailto:support@keyexample.com">support@keyexample.com</a>.

Thanks!
Your Certificate Management System

Hello $(requester:givenname),

The certificate you requested in the name $(request:cn) on $(subdate) was successfully approved with the following comment:

$(approvalsignalcmnts)

The certificate details include:

   <ul>
      <li>CN: $(request:cn)</li>
      <li>DN: $(request:dn)</li>
      <li>SANs: $(sans))</li>
      <li>App Owner First Name: $(metadata:AppOwnerFirstName)</li>
      <li>App Owner Last Name: $(metadata:AppOwnerLastName)</li>
   </ul>

You will receive an update when it has been issued. For assistance, please contact <a href="mailto:support@keyexample.com">support@keyexample.com</a>.

Thanks!
Your Certificate Management System

# Declare your parameters at the beginning
param(
   [string]$CSRSubject,
   [string]$CSRSANs,
   [string]$OriginalDomain,
   [string]$NewDomain
)

# Load incoming SANs into a hash table
$SANTable = $CSRSANs | ConvertFrom-Json -AsHashtable

# Initialize variable for the dns SANs
$dnsList = @()

# Load original subject in NewSubject for the else case
$NewSubject = $CSRSubject

# Replace escaped commas in the subject temporarily with a string to facilitate splitting
$TempString = "######"
$CleanSubject = $CSRSubject -replace "\\,", $TempString

# Split the incoming Subject string into its component values
$SplitSubject = $CleanSubject.Split(',')

# Initialize variables for the components of the subject
$SubjectCN = @()
$SubjectO = @()
$SubjectOU = @()
$SubjectL = @()
$SubjectST = @()
$SubjectC = @()
$SubjectE = @()

# Load subject values
foreach($element in $SplitSubject){
   $SplitElement = $element.Split('=')
   Switch($SplitElement[0]){
      "CN" {$SubjectCN = $SplitElement[1]}
      "O" {$SubjectO = $SplitElement[1]}
      "OU" {$SubjectOU = $SplitElement[1]}
      "E" {$SubjectE = $SplitElement[1]}
      "L"{$SubjectL = $SplitElement[1]}
      "ST"{$SubjectST = $SplitElement[1]}
      "C"{$SubjectC = $SplitElement[1]}
   }
}

# Check to see if the incoming CN ends with $OriginalDomain and, if so, add it as a SAN with $NewDomain and update the Subject with $NewDomain (assumes non-null CN)
if ($SubjectCN.EndsWith($OriginalDomain))
{
   # Load just the portion of the CN without the domain name into a variable
   $CNName = $SubjectCN.SubString(0,$SubjectCN.Length - ($OriginalDomain.Length + 1)) # +1 to account for the '.'

   # Build new DNS SAN
   $NewSAN = $CNName + "." + $NewDomain

   # Check if SANTable has property 'dns' and assign if so
   if ($SANTable.ContainsKey("dns") -and $SANTable["dns"]) {
       $dnsList = $SANTable["dns"]
   }

   if ($dnsList -notcontains $NewSAN) {
      $dnsList += $NewSAN
   }   
   
   # Load the resulting IPv4 and updated DNS SANs into the updated SANs variable
   $UpdatedSANs = @{}

   if(![string]::IsNullOrWhiteSpace($dnsList)) {
       $UpdatedSANs.dns = $dnsList
   }

   if(![string]::IsNullOrWhiteSpace($SANTable["ip4"])) {
      $UpdatedSANs.ip4 = $SANTable["ip4"]
   }

   # Build new Subject with $NewDomain
   $NewSubject = "";

   if(![string]::IsNullOrWhiteSpace($SubjectCN)){
      $NewSubject += "CN=" + $CNName + "." + $NewDomain + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectO)){
      $NewSubject += "O=" + $SubjectO + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectOU)){
      $NewSubject += "OU=" + $SubjectOU + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectL)){
      $NewSubject += "L=" + $SubjectL + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectST)){
      $NewSubject += "ST=" + $SubjectST + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectC)){
      $NewSubject += "C=" + $SubjectC + ","
   }

   if(![string]::IsNullOrWhiteSpace($SubjectE)){
      $NewSubject += "E=" + $SubjectE + ","
   }

   $NewSubject = $NewSubject.Remove($NewSubject.Length - 1) # remove the last ','

   # Replace temporary string with escaped commas in Subject
   $NewSubject = $NewSubject -replace $TempString, "\,"
}

# Return the updated subject and SANs as NewSubject and NewSANs to the workflow as a hashtable
$result = @{ "Subject" = $NewSubject; "SANs" = $UpdatedSANs }
return $result