Using the 1E PowerShell Toolkit on non-Windows platforms

Only preliminary testing has been conducted, and only on Debian 11.5 and 12.2 at this stage. It is expected that other Linux distributions that allow .NET to be installed should function similarly, for example, Ubuntu.

macOS has not been tested yet.

Authentication using platform-neutral authentication via a JWT and subsequent Tachyon API calls appear to function correctly.

Interactive platform-neutral authentication (where the browser is automatically invoked by the 1E PowerShell Toolkit) also works, but note that you cannot be root when you do this as Debian (and possibly other distributions) won’t allow the browser to be invoked in this situation.

The 1E PowerShell Toolkit will run on PowerShell 6.x onwards as well as legacy PowerShell. The main changes that will affect the toolkit are described below.

NTLM authentication

Attempting to make a connection to a 1E Platform server over SSL with NTLM authentication does not work. This is a known issue with PowerShell Core but it’s not clear if Microsoft have any plans to address it.

Linux files are case-sensitive

If you are unable to load the toolkit module with import-module, check that the two files match in case. The should read the following:

PS1EToolkit.psd1
PS1EToolkit.psm1

Also check that the file reference in PS1EToolkit.psd1 matches the following:

Copy

  RootModule           = 'PS1EToolkit.psm1'

Additionally, check that the reference in PS1EToolkit.psm matches the following:

Copy

$manifestpath = $PSScriptRoot + "\PS1EToolkit.psd1"

On Windows, file names are not case-sensitive, but if the case doesn’t match exactly as shown on Linux, you cannot load the toolkit module.

Certificates

Linux does not have a certificate store that works the way it does on Windows. However, the .NET environment under Linux does emulate the Windows certificate store. It does so by storing certificates in a folder tree whose structure is not specified. You should never interact directly with the files. However, the System.Security.Cryptography.X509Certificates namespace does support certificate storage and retrieval operations that function pretty much as they would in a Windows environment. This includes all the core cryptographic operations that are required by platform-neutral authentication.

However, PowerShell on Linux does not support the certificate store as a virtual drive (that is, prefixed with cert:). This means that you have to call the underlying .NET assemblies to interact with the certificate store. Once you have retrieved an X509Certificate, all remaining operations work the same on that certificate.

Version 1.1.32 and later of the 1E PowerShell Toolkit transparently interact with the certificate store on Linux by detecting the OS that the Toolkit is running on.

Version 1.1.33 and later of the 1E PowerShell Toolkit supports retrieval of certificates from the Azure Key Vault as an alternative to retrieving certificates from the local certificate store. Refer to Accessing Certificates from the Azure Key Vault.

Storing certificates

PowerShell on Linux does not support the new-selfsignedcertificate cmdlet (or the other certificate management cmdlets), but there is a downloadable .NET utility that can be used to import .PFX files into the .NET certificate store on Linux. For more information, refer to this article.

To get this utility installed, you must install the .NET SDK on the Linux target to ensure that the required support components are available. This is separate from installing PowerShell Core, which only bundles the .NET runtime components it relies on.

Certificates are usually stored in the CurrentUser\My certificate store, rather than LocalMachine\My. This is not available on Linux. Consequently, the certificates visible at any time will correspond to the Linux account under which the 1E PowerShell Toolkit is running.

Authenticating

The set-1Eserver cmdlet will operate exactly as it does in Windows environments, but you can only connect to a platform server running platform-neutral authentication.

NTLM authentication is not functional in the Linux environment.

The proxy option to use SSL client certificates is not (yet) supported by the 1E PowerShell Toolkit.

You can authenticate interactively, or by supplying an -AppId and -CertSubject or -CertThumbprint parameter to use a signed JWT, just as you do in the Windows environment.

You can also request an internal platform token using the get-1Eplatformtoken cmdlet. The platform token certificate must be in the cert store to do this.

Enumerating certificates

The tool mentioned earlier has a command line option to do this. Additionally, the get-1Ecertificatethumbprint cmdlet in the Toolkit does operate in the Linux environment. You would normally specify CurrentUser\My as the certificate store rather than LocalMachine\My when using this cmdlet.