1E 9.x (on-premises)

Your 1E system requires these certificates for signing requests between internal and external components, including your Identity Provider (IdP). This is a requirement since 8.1.

These certificates can be issued by a PKI but do not have to be, they can be self-signed. Unless specified above, they have no specific requirements other than they must be CNG. Unlike certificates used for web servers, where there is a requirement that there be a trust chain to a root CA certificate, these certificates can be self-signed. This is because the trust relationship is defined either between platform components, or between a platform service and the identity provider, or between integration features and the identity provider. Both parties in each relationship has local access to their certificate and can thus prove their identities using standard cryptography sign/verify procedures.

Creating the certificates

Before installation of a 1E server, you need to have installed certificates in the server's local machine certificate store. You can use the PowerShell cmdlet new-selfsignedcertificate to create self-signed CNG certificates in the local machine certificate store. Although these certificates have no specific requirements other than being CNG, you can apply other certificate attributes, such as the subject, to reflect your corporate policies. For information about this cmdlet, refer to learn.microsoft.com/en-us/powershell/module/pki/new-selfsignedcertificate.

The following PowerShell command creates a self-signed CNG certificate in the local machine certificate store, with your specified subject, RSA (2048) encryption, and default expiry of 1 year, the private key is exportable.

new-selfsignedcertificate -subject CN=<subject>

Note

Refer to AAD Applications for details about the self-signed certificate requirements Azure AD apps need for 1E 9.0, this guidance includes how to create and configure these apps.

Important

1E recommends you do not run this command directly on a 1E server because it is more secure that each of these certificates is stored with its private key not exportable.

Therefore, the above command should be run on a different computer. The certificate is then exported as a PFX file (with a password) before deleting it from the certificate store. The PFX file can then be re-imported onto relevant servers, without marking the private key as exportable.

This PFX process is anyway necessary if you have multiple servers sharing the same Signing certificate for platform tokens certificate.

• The public key of the Signing certificate for IdP requests certificate must be uploaded to the IdP application you have configured for Directory Searches

• The public key of the Signing certificate for integration tokens certificate(s) must be uploaded to the corresponding IdP application(s) you have configured for Non-interactive logins

• The public key of a certificate can be exported for example, as a Base-64 encoded X.509 CER file, without private key

• The Network Service account on each 1E server requires read access permission on each certificate. Permission can be granted manually before, or automatically during installation by using the Add permissions for the private key link in the 1E Server Setup wizard.

Tip

What are CNG certificates?

CNG is the "next generation" of CryptoAPI (CAPI) service providers, that has actually been available for many years.

If you did not use the above method of creating your certificates, you may need to check they are CNG. To check if a certificate is CNG, look to see if its ProviderType and KeySpec values are both 0.

You can check this using the Windows certutil utility, and one of the following commands to make a verbose dump of certificate(s).

certutil -v -store my
certutil -v <path to PFX file>

Microsoft Software Key Storage Provider is one of several CNG providers. Run certutil -csplist to see a list of crypto service providers on your Windows computer.

You need to have a PKI in your environment with at least one Issuing CA.

1E requires each Issuing CA has:

Each server that has 1E server components installed requires its own Web Server certificate (except for a remote SQL Server). This certificate is also used by the Switch and the Coordinator. Therefore, a single-server installation requires only one Web Server certificate. This certificate must be provided on the server prior to installation of 1E.

The Web Server certificate requires the minimum of the following:

Web Server certificates used by a 1E servers must be issued with their fields set as follows. Example DNS Names are discussed in DNS Names.

Fields	Example Option 3 type certificate
Subject Common Name Field (subject:commonName)	Subject (CN) can be any valid name, and is no longer mandatory as required by previous versions of 1E.
Subject Alternative Name Extension (extensions:subjectAltName), type dnsName	The 1E server DNS Name FQDN (DNS Alias) of the server. This is mandatory, same as required by previous versions of 1E. On a Master Stack - example: DNS Name=TACHYON.ACME.LOCAL On a Response Stack - example: DNS Name=TACHYONRS.ACME.LOCAL On a DMZ Server - example: DNS Name=TACHYONEXT.ACME.COM
Subject Alternative Name Extension (extensions:subjectAltName), type dnsName	An Alternate DNS Name FQDN (DNS Alias) of the server. This is usually mandatory, for example if there is more than one server in your 1E system, as discussed in DNS Names. On a Master Stack, example: DNS Name=TACHYONALT.ACME.LOCALorDNS Name=TACHYON.ACME.LOCAL On a Response Stack - example: DNS Name=TACHYONALT.ACME.LOCAL On a DMZ Server - example: DNS Name=TACHYONDMZ.ACME.LOCAL
Example

Examples of old-style certificates:

Fields	Example old Option 2 type certificate
Subject Common Name Field (subject:commonName)	The computername FQDN of the server Example: CN=ACME-TCN01.ACME.LOCAL
Subject Alternative Name Extension (extensions:subjectAltName), type dnsName	The DNS Alias FQDN of the server Example: DNS Name=TACHYON.ACME.LOCAL Tip Add any additional DNS Names here.
Example certificate request	Note Option 2 type certificates required the CN to be the computername FQDN, and the list of Subject Alternate Names (SAN) to contain the DNS Alias. Also, prior to 1E 5.0 the certificate required its private key to be exportable. 1E 5.0 and later is able to use this type of certificate when upgrading from an earlier version of 1E.

Fields	Example of old Option 1 type certificate
Subject Common Name Field (subject:commonName)	The DNS Alias FQDN of the server Example: CN=TACHYON.ACME.LOCAL
Subject Alternative Name Extension (extensions:subjectAltName), type dnsName	The DNS Alias FQDN of the server Example: DNS Name=TACHYON.ACME.LOCAL The computername FQDN of the server Example: DNS Name=ACME-TCN01.ACME.LOCAL
Example certificate request	Note Option 1 type certificates required the CN to be the DNS Alias, and the list of Subject Alternate Names (SAN) to contain the computername FQDN. Also, prior to 1E 5.0 the certificate required its private key to be exportable. 1E 5.0 and later is able to use this type of certificate when upgrading from an earlier version of 1E.

The following need to be considered when requesting this type of certificate.

If you have a Microsoft CA then it is simplest to use the Certificate Enrollment wizard available in the mmc certificates snap-in, to request a Web Server certificate and fill in the details.

When Content Distribution is installed, any server hosting a Background Channel must have a Client Authentication certificate. This can be the same certificate as a Client authentication certificates if you have 1E Client installed, or it can be the same certificate as the Web Server certificate if your organization security policy allows your Web Server certificates to be used for both Server Authentication and Client Authentication.

The Background Channel proxy uses this certificate to be authenticated by the Content Distribution Web API, and must be available on the server so that it can be selected on the 1E Server Setup Content Distribution screen during installation.

Note

The 1E Client requires that the client certificate it presents to the platform has both the Signature and Encryption request handling options. These options are the defaults if provisioning using a Computer Certificate template from a Microsoft Windows Certificate Authority. If you are using a custom template, or an alternative certificate authority, you should confirm that both these options are enabled.

If you have configured 1E to require client certificates (Client certificates) then each device requires a certificate with the following properties, so the 1E Client can be authenticated by the 1E Switch.

The client device's certificate is stored differently depending on the type of OS:

If using a Microsoft Enterprise CA then the following should be considered.

If using a standalone CA, then certificates must be deployed by other means.

You will need your own code signing certificate, and have it registered in your 1E license, if you want to develop your own custom 1E instructions, or modify those of other authors. Instructions that are provided in the 1E platform zip or downloaded from the 1E Exchange have already been code signed using the Platform and 1E Exchange certificates from 1E. Your 1E license controls whether you can use these instructions.

Ideally, all of your 1E instruction developers should share a single code signing certificate between them. Each code signing certificate must be registered in your 1E license and associated with your organization's instruction name prefix. When you have chosen your prefix and have your code signing certificate(s) you then need to send details of these to 1E, who will update your 1E license. This will then automatically activate on your 1E server (assuming it has connection to the Internet).

The following applies to the importing and running of custom 1E instructions:

Custom Instructions must be signed by TIMS using a code-signing certificate present in the Personal certificate store where TIMS is installed (either local user or machine store). The TIMS user signing the Instruction also needs to have access to the certificate's private key.

For a getting started guide to configuring and verifying your 1E system so that you can run customized 1E instructions, refer to Running instructions for the first time.

On Windows computers, the installation MSI files, and binary executable and DLL files of 1E software are digitally signed. The 1E code signing certificate uses a timestamping certificate as its countersignature. 1E occasionally changes its code signing certificate, as shown in the table below, and uses it for new releases and hotfixes for older versions, as shown in the table below.

The signature algorithm of the 1E code signing certificate is SHA256RSA. In most cases, the file digest algorithm of an authenticode signature is SHA256, and the countersignature is a RFC3161 compliant timestamp. The exception is on legacy OS (Windows XP, Vista, Server 2003 and Server 2008) which require the file digest algorithm of an authenticode signature to be SHA1, and a legacy countersignature.

The root CA certificates (for signing and countersigning) must exist in the Third-Party Root Certification Authorities store (which is replicated in the Trusted Root Certification Authorities store). These root CA certificates are normally automatically provided by Microsoft's Update Root Certificates feature, however, this may not be true for legacy OS computers in a lab environment that are not connected to the Internet.

The table below applies to software and hotfixes released in 2020.

1E relies on both client (device) and server side certificates to ensure secure communication. In order for these certificates to work the computers need to trust the PKI implementation (issuing Certification Authority and chain of trust). In a standard on-premises environment, devices can be enrolled with certificates using Directory Group Policy.

It is possible to use a non-Windows based PKI, but it is then left as an exercise for the user as to how to distribute and enrol device certificates to all end-points.

Given the supported Directory configuration above, the PKI requirements described above still apply to a cloud based implementation.