Password Files and Encrypted Deployments - Esri/arcgis-powershell-dsc GitHub Wiki
This workflow guides you through creating Encrypted Password Files and Encrypted Managed Object Format (MOF) files.
Note: Encrypted password files can be used along side encrypted MOF files, or they can be used independently.
At the end of this guide you will have successfully deployed a base ArcGIS Enterprise deployment, on a single node, using Encrypted Password Files and Encrypted MOF files.
- Launch PowerShell as an Administrator
- Run the following command (repeat for each password file needed) this will prompt to enter a password and create the file with an encrypted string:
read-host -assecurestring | convertfrom-securestring | out-file C:\mysecurepasswordfile.txt
There are two methods you can take to create and use the required Encryption Certificate (public-private key pair).
- Create it on the Target Node and export just the public key pair to the Authoring Node, or
- Create it on the Authoring Node and export the entire key pair to the Target Node
Note: Method 1 is recommended because the private key used to decrypt credentials in the MOF stays on the Target Node at all times.
The private key must be kept secret, because it's used to decrypt the MOF on the Target Node. The easiest way to do that is to create the private key certificate on the Target Node, and copy the public key certificate to the computer being used to author the DSC configuration into a MOF file. For example:
- Create a certificate on the Target node
- Export the public key certificate on the Target node.
- Import the public key certificate into the my certificate store on the Authoring node.
Note: For multi-node deployments, repeat steps 1 and 2 on each target node, then the public key certificate for each target node will need to be imported into the the my certificate store on the Authoring node.
# note: These steps need to be performed in an Administrator PowerShell session
$cert = New-SelfSignedCertificate -Type DocumentEncryptionCertLegacyCsp -DnsName 'DscEncryptionCert' -HashAlgorithm SHA256
# export the public key certificate
$cert | Export-Certificate -FilePath "$env:temp\DscPublicKey-TargetNode1.cer" -Force
Note: Once exported, the DscPublicKey-TargetNode1.cer will need to be copied to the Authoring Node and imported into the authoring node's my store
# Import to the my store
Import-Certificate -FilePath "$env:temp\DscPublicKey-TargetNode1.cer" -CertStoreLocation Cert:\LocalMachine\My
# Set the location to the My store
Set-Location Cert:\LocalMachine\My
# Run the following command to obtain the certificate thumbprint
Get-ChildItem | Format-Table Subject, FriendlyName, Thumbprint -AutoSize
Before you run the 'Invoke-ArcGISConfiguration` command to start the module in PowerShell DSC, you’ll need to obtain ArcGIS Enterprise Setups, Authorization files, and SSL Certificates, and add them to your target nodes in the deployment.
Note: We recommend using Windows Management Framework 5.x for the best experience.
Log in to the machine(s) on which you'll be installing. You should have administrative authority on the machine.
Use one of the following options to download the ArcGIS Module:
- Clone this repository to your orchestrating node and all target nodes.
- Add the "ArcGIS" modules folder to your
PsModulePath
, or copy the module into the default PowerShell Modules folder (For example,C:\Program Files\WindowsPowerShell\Modules
) to your orchestrating node and all target nodes.
- Launch PowerShell, as an Administrator, use the command
Install-Module arcgis
to install the ArcGIS module from the PowerShell Gallery. - Download the SampleConfigs files from the GitHub repository.
- Open the BaseDeployment-SingleMachine.json file from the SampleConfigs folder on your orchestrating machine.
- Replace the placeholder variables in brackets with your deployment properties and parameters. Refer to the Variables reference page for a full list.
- To use encrypted password files replace all the
"Password"
variables within the BaseDeployment-SingleMachine.json with"PasswordFilePath": "C:\mysecurepasswordfile.txt",
. For example:
"ConfigData": {
"Version": "10.9",
"Credentials": {
"ServiceAccount": {
"PasswordFilePath": "C:\\mysecurepasswordfile.txt",
"UserName": "domain\\arcgis",
"IsDomainAccount": true
},
"ADServiceUser": {
"PasswordFilePath": "C:\\mysecurepasswordfile.txt",
"UserName": "domain\\arcgis",
"IsDomainAccount": true
}
}
}
- To encrypt the MOF file define the AllNodes.TargetNodeEncyrptionCertificateFilePath and AllNodes.TargetNodeEncyrptionCertificateThumbprint within the BaseDeployment-SingleMachine.json. For example:
"AllNodes": [
{
"NodeName": "TargetNode1",
"DataStoreTypes": [
"Relational"
],
"Role": [
"Server",
"Portal",
"DataStore",
"ServerWebAdaptor",
"PortalWebAdaptor"
],
"TargetNodeEncyrptionCertificateFilePath":"C:\\Users\\<username>\\AppData\\Local\\Temp\\DscPublicKey-TargetNode1.cer",
"TargetNodeEncyrptionCertificateThumbprint":"92C232C78204701BEB3FFB2CDEF24A6D2FAA97DA"
}
],
In PowerShell DSC, run the Invoke-ArcGISConfiguration
cmdlet and provide the path to the configuration file as an input parameter. The -Mode
and -DebugSwitch
are optional arguments.
Invoke-ArcGISConfiguration -ConfigurationParametersFile [[Path to Configuration JSON File]] -Mode [Install | InstallLicense | InstallLicenseConfigure | Uninstall | Upgrade] -Credential [Config RunAs] -DebugSwitch
or
Invoke-ArcGISConfiguration -ConfigurationParametersFile C:\SampleConfigs\BaseDeployment-SingleMachine.json -Mode InstallLicenseConfigure -Credential domain\username