In this guide, we use PowerShell to demonstrate calling Cerberus SOAP API. PowerShell’s inclusion in Windows and relatively simple syntax make it a natural starting point for experimentation and prototyping.
PowerShell expertise isn’t required to follow this guide. Nor is any experience with SOAP or XML. However, previous experience writing script in some shell language is recommended. Review Microsoft’s PowerShell documentation or a beginner’s guide if necessary.
Note: The example code has been tested with PowerShell version 5.1 and it may not run correctly on older versions.
Quick Start - HelloCerberus.ps1
The example script HelloCerberus.ps1 calls ServerInformation, which requests basic information from Cerberus FTP Server. While the results are very simple, the code and concepts introduced are relevant to all Cerberus SOAP API operations.
Open a PowerShell console on the same system hosting Cerberus FTP Server
Copy HelloCerberus.ps1 to the local hard drive of the same system
Paste the command below into the PowerShell console, hit Enter, and confirm by typing ‘Y’ and hitting Enter.
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
See Execution Policy for more information on this command
Type the ampersand character (&) into the console, then drag and drop HelloCerberus.ps1 from File Explorer the PowerShell console.
Hit Enter in the PowerShell console to execute the script.
Provide the username and password of the Cerberus primary administrator account when requested.
If successful, the console will contain basic information about the running Cerberus FTP Server. Hostname, status, and version information will be displayed:
PS C:\> Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process Execution Policy Change The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose you to the security risks described in the about_Execution_Policies help topic at https:/go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy? [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): Y PS C:\> &C:\Cerberus\Scripts\HelloCerberus.ps1 version : CerberusFtp.Version hostname : DESKTOP-QFAOC1H isStarted : True isSuccess : True isSuccessSpecified : True message : maj : 10 min : 0 maint : 10 build : 0
Stepping Through the Code
What took place in HelloCerberus.ps1 can be summarized in five parts. Let’s examine the most important lines of code in detail.
1: Get Credentials
Every Cerberus SOAP operation requires credentials to authenticate the request. Since it is bad practice to store credentials directly within a script, HelloCerberus.ps1 either takes the credentials from the command-line or requests them interactively from the user.
The lines above check if credentials were provided on the command-line. If not, the Get-Credential command is called to request them from the user. Depending on the shell environment, the user may be presented with a pop-up window or a text input prompt. The result is stored in a variable named $CerberusCredentials to be used authenticate later requests to Cerberus FTP Server.
PowerShell offers many options for storing credentials securely when authentication is required but user interaction is not possible. More complicated automation scenarios will need to use some of these techniques.
2: Create a SOAP Proxy
New-WebServiceProxy is used to read the SOAP API definition provided by Cerberus. It returns an object used by the script to make subsequent requests of Cerberus FTP Server.
This seemingly simple command triggers a cascade of activity. The Cerberus SOAP API definition is retrieved from your Cerberus FTP Server. The definition is translated into dependent types which are placed in the CerberusFtp namespace of the current shell environment.
The $CerberusSvc variable stores a newly-created object with methods representing every API operation supported by Cerberus FTP Server. $CerberusSvc object is later used to issue requests to your running Cerberus FTP Server.
3: Prepare the Request
All Cerberus SOAP API operations follow the same pattern: a request object is sent to the server and a response object is received in reply. All operations require credentials, so all request objects will contain at least a username and password.
Most operations require additional information, like the name of a user or group when retrieving such objects, or a complete user or group object when making modifications.
The lines above prepare a request object to call ServerInformation. Technically, this syntax creates a hash table. Because the hash table’s names and values are consistent with a ServerInformationRequest object, the conversion is made automatically when we call ServerInformation.
The inner hash table, named credentials, is populated with the primary administrator account username and password. At this time, only the primary administrator account is allowed to make SOAP requests.
4: Send the Request
The $CerberusSvc object contains every operation available in Cerberus SOAP API, so making requests of Cerberus FTP Server is just a matter of calling methods on the object.
In the above line, we call ServerInformation, passing the $request object to the method. We store the result in a variable named $infoResponse.
5: Interpret the Response
Response objects vary from one operation to another, but generally, they contain a “result” value indicating success or failure of the operation and a “message” value containing details of the success or failure. If successful, additional data will be contained in the response.
In these lines, PowerShell emits the content our response object’s “result” member and the “version” information contained within the result.
The main logic of the script is complete. In relatively few lines of code, we’ve opened a connection to, authenticated with, and retrieved information from Cerberus FTP Server. The bulk of the work was handled by the .NET SOAP tools. See Understanding Cerberus SOAP API for greater detail on how SOAP definitions relate to PowerShell code.
A shrewd reader will note that many lines in HelloCerberus.ps1 were not detailed in the previous section. This code is used to ensure a successful experience when running this script against a new Cerberus FTP Server installation. This section and the comments throughout HelloCerberus.ps1 outline the reasons for this code.
PowerShell Execution Policy
Execution Policy is a Windows security feature that restricts PowerShell code based on its origin. The default settings restrict all script execution, so a change must be made before HelloCerberus.ps1 is allowed to run. The Quickstart instructions achieved this by running this line before executing the script:
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
This command disables execution policy checking for the duration of the PowerShell process, but leaves existing local machine and user policies unmodified. See Microsoft’s Set-ExecutionPolicy documentation for greater detail.
NOTE: In Windows Domain environments, Execution Policy may be controlled by system administrators via Group Policy. Consult with your domain administrators if Set-ExecutionPolicy is ineffective.
Ensuring the integrity of executable code is critical to system security. Scripted code is no different. Administrative scripts may run with elevated privileges, utilize sensitive credentials, and access critical resources. If the content of a script is compromised, then any credentials and resources used by the script are also compromised.
Bare minimum, use NTFS permissions to restrict write-access to scripts. Write-access should be as restricted as possible in production.
Ideally, a system to cryptographically sign scripts should be employed, but this is a significant undertaking. This may require coordination with your IT department to issue, deploy, and trust code-signing certificates. Implementing such a system is outside the scope of this guide.
PowerShell’s default settings reject self-signed, expired, or otherwise misconfigured certificates when establishing an HTTPS connection. HelloCerberus.ps1 includes a function Disable-CertificateValidation to work-around this restriction.
In production, however, this must not be used. Cerberus FTP Server should be configured with a legitimate certificate issued by a trusted certificate authority. Once in place, default certificate validation will succeed, eliminating the need for the workaround.
Securing Cerberus SOAP API Service Endpoint
Cerberus FTP Server configuration may be used to restrict or relax access to the SOAP service endpoint, according to needs. The configuration options are found under Configure, Remote tab, SOAP Administration Settings.
Use Secure HTTPS
Determines whether SOAP requests are accepted on HTTP or HTTPS.
Recommended: HTTPS should be used whenever possible.
Allow Remote SOAP Access
When unchecked, SOAP requests must originate from the localhost (thus PowerShell requests must be run locally); Remote connections are refused.
Recommended: Unchecked unless remote SOAP clients are a business requirement.
SOAP TLS Protocols
TLS 1.2 is the most secure option. Others are provided for compatibility with SOAP clients incapable of 1.2.
Recommended: TLS v1.2 enabled, others disabled.
The Cerberus SOAP API offers great potential for automating Cerberus FTP Server administration to those who need it. In the next installment, we’ll perform operations more interesting than ServerInformation. Look forward to example code that adds, removes, and modifies Cerberus users.