Configuring Azure for Process Director Integration

Note A PDF file for end-to-end Azure OAuth configuration can be found here: Configuring Azure OAuth (PDF Download)

Microsoft Modern Authentication (an OAuth-based authentication system) provides much more secure access to SharePoint, SMTP email, and other Azure services from Process Director, but does require a complex setup process. To set up Modern Authentication between Azure and Process Director, you must complete the following steps.

  1. Create a certificate to authenticate Process Director with Azure.
    1. Using Microsoft’s certreq.exe, installed on all modern Windows OS versions.
    2. Using PowerShell, also included with all modern Windows OS versions.
  2. Add Process Director as a Registered Active Directory application in the Azure Active Directory portal.
    1. Add the public key certificate to the Process Director application in Azure.
    2. Configure the appropriate Azure settings.

In this topic, we'll address each of these required steps in detail. Additional information about this topic can also be obtained from Microsoft's online documentation.

Important You cannot configure any OAuth settings for SharePoint Datasources or SMTP Email in Process Director until you have created and registered an Azure Active Directory Application in Azure by completing the steps described in this topic.

Create a certificate to authenticate Process Director with Azure #

Microsoft prefers the use of certificates for authentication. Each certificate includes both the public and private keys used to encrypt data. The public key (in a CER file) is used by SharePoint Online to authenticate Process Director. The private key is packaged in a password-protected PFX file and is used by Process Director to authenticate with Azure Services. There are two methods that can be used on Windows-based systems to create a proper certificate.

  • Using Microsoft’s certreq.exe, installed on all modern Windows OS versions.
  • Using PowerShell, also included with all modern Windows OS versions.

Important Keep in mind that certificates expire after a set period of time. Most organizations specify the maximum length of time certificates should be used. By default, the instructions that follow will generate certificates valid for one year. You should, therefore, generate and install new certificates well before existing certificates expire. This implies that your organization also has a mechanism in place to be reminded when expiration is approaching, to ensure that service interruptions don't occur.

Creating a Certificate with certreq.exe

This method of certificate creation might be preferred if you’re less comfortable with command-line operations and don’t intend to automate the generation of certificates. Microsoft's online documentation has additional information about certreq.exe.

First, using a text editor like Notepad, copy and paste the following text into a new document:

[Version]
Signature = "$Windows NT$"

[Strings]
szOID_ENHANCED_KEY_USAGE = "2.5.29.37"
szOID_KEY_ENCIPHERMENT = "1.3.6.1.5.5.7.3.1"

[NewRequest]
Subject = "cn=BP Logix Process Director"
MachineKeySet = false
KeyLength = 2048
HashAlgorithm = Sha1
Exportable = true
RequestType = Cert

KeyUsage = "CERT_KEY_ENCIPHERMENT_KEY_USAGE"
; The following values can be changed to generate certificates that expire
; sooner or later depending on your organizations needs. The default is 1 year.
ValidityPeriod = "Years"
ValidityPeriodUnits = "1"

[Extensions]
%szOID_ENHANCED_KEY_USAGE% = "{text}%szOID_KEY_ENCIPHERMENT%"

Once you've done so, save the document as an INF file in a folder on your system, e.g., c:\Users\Some.User\Documents\PD Certificate\CertReq.inf.

Open the Windows Command Prompt. You can press the [WINDOWS] key, type "cmd", then select the "Command Prompt" application.

In the Command Prompt, open the directory in which you installed the INF by using the cd command, and the folder path to the INF file, then pressing the [ENTER] key. Using the example above, you'd need to type:

cd c:\Users\Some.User\Documents\PD Certificate\

Once the directory changes, type the following and press the [ENTER] key to run the certreq application.

certreq -new certreq.inf PublicKey.cer

Running the certreq application will create the certificate, and add it to the Windows Certificate Manager. To continue, you'll need to open the Certificate Manager to access the new certificate. To open the Certificate Manager, you can press the [WINDOWS] key, type "certmgr", then select the "Manage computer certificates" option. When the Certificate Manager opens, you'll need to navigate to the Personal\Certificates folder, where you should see the certificate issued to and by BP Logix Process Director.

Right-click that certificate and then select All Tasks > Export.

The Certificate Export Wizard will open. On the first screen, click the Next button. On the Export Private Key screen, select Yes, export the private key, then click the Next button.

On the Export File Format screen of the Wizard, Ensure that you select the following options:

  • Personal Information Exchange - PKCS #12 (.PFX)
  • Include all certificates in the certification path, if possible
  • Enable certificate privacy

On the Security screen, check Password as the security protocol and enter a password twice.

Note Be sure to store this password securely, you'll need it in future steps.

Important Be sure to use a long, sufficiently complex password in line with your organization’s cryptographic standards.

On the File to Export screen, store the resulting PFX file in the same folder as you stored the CertReq.Inf and PublicKey.Cer files, then click the Next button.

Click the Finish button on the next Wizard screen, then OK to finish the Wizard and close it.

BP Logix recommends that you remove the certificate installed in the Certificate Manager by right-clicking it and then selecting Delete followed by Yes to delete it in the confirmation dialog.

Keep both the PublicKey.cer and PrivatePublicKeys.pfx files handy for subsequent steps in this setup process. You should also archive them in a secure, backed up location as well.

Creating a Certificate with PowerShell

PowerShell is a command line application that's included with all modern versions of Windows. You can choose this method if you’re comfortable with PowerShell and might want to automate certificate generation on a recurring basis.

Open PowerShell by pressing the [WINDOWS] key, typing "PowerShell" then selecting the Run as Administrator option to open Windows PowerShell.

In PowerShell, create or navigate to the directory you'd like to use to store the certificate files. Once you're in the desired directory, run the following command:

$cert = New-SelfSignedCertificate -CertStoreLocation Cert:\LocalMachine\ -KeyUsage KeyEncipherment
    -KeyAlgorithm rsa -KeyLength 2048 -subject "BP Logix Process Director"
    -DnsName "BP Logix Process Director" -Type SSLServerAuthentication
    -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.1")

Next, run these commands in PowerShell, replacing <password> with a password of your choosing. Ensure the passowrd is cryptographically secure, in accordance with your organization’s standards. Be sure to also store this password securely, as you'll need it in future steps.

$pwd = ConvertTo-SecureString -String '<password>' -Force -AsPlainText
$path = 'cert:\LocalMachine\My\' + $cert.Thumbprint

Finally, run these commands to create the .PFX and .CER files. Modify the <path> value to store the file in a location of your choosing.

Export-PfxCertificate -cert $path -FilePath <path>\PrivatePublicKeys.pfx -Password $pwd
Export-Certificate -cert $path -FilePath <path>\PublicKey.cer

Keep both the PublicKey.cer and PrivatePublicKeys.pfx files handy for subsequent steps in this setup process. You should also archive them in a secure backup location as well.

Add Process Director to Azure #

To add Process Director as an application in your Azure Active Directory portal at the Tenant level, complete the steps below after signing into your Azure portal (portal.azure.com):

  1. If you have access to multiple tenants, use the Directories + subscriptions filter in the top menu to switch to the tenant in which you want to register the application.
  2. Search for and select Azure Active Directory.
  3. Under Manage, select App registrations > New registration.
  4. Enter a display Name for your application, e.g., “Process Director”. This name can be changed later, if needed.
  5. Specify who can use the application. Typically, only accounts in this organizational directory should be used. See the Microsoft documentation titled Quickstart: Register an application with the Microsoft identity platform for more information.
  6. Add the Redirect URI, which is the URI for your Process Director installation, e.g., https://myorg.bplogix.net.
  7. Click the Register button to register the application.

To add your public key certificate to the Process Director application in Azure, complete the steps below.

  1. In the Azure portal, in App registrations, select the Process Director application you created previously, e.g., “Process Director”, as in step 1D, above.
  2. Select Certificates & secrets > Certificates > Upload certificate.
  3. Select the PublicKey.cer file you created earlier.
  4. Upload the certificate file to Azure.

Your AAD Application should now be properly registered and secured with a certificate.

Conclusion

Congratulations! Assuming that you've correctly followed the instructions above, you've now configured an Azure Integration with Process Director. To complete the integration, you'll need to perform some additional, specialized configuration in Azure, depending on whether you're trying to: