You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: ReadMe.md
+18-16Lines changed: 18 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -54,8 +54,8 @@ All scripts in the suite have been run and tested as functional. It is currently
54
54
Feel free to provide feedback and lodge issues and they will be reviewed.
55
55
56
56
## New and improved Features in AgentDeploymentPackage 6.0.1 (Beta)
57
-
=======
58
-
This script is a fork of Ryan Crowther Jr's AgentDeploymentPackage on GitHub[](https://github.com/N-able/AgentDeploymentPackage/)
57
+
58
+
This script is a fork of [Ryan Crowther Jr's AgentDeploymentPackage on GitHub](https://github.com/N-able/AgentDeploymentPackage/) and will soon be the future branch going forward as they have moved on to other projects.
59
59
60
60
If you discover a problem with any component of the Automation Suite or have ideas on how it could be improved, [post an issue on GitHub](https://github.com/AngryProgrammerInside/InstallAgent/issues). Alternatively, post on the N-Central Slack Community chat.
61
61
@@ -137,12 +137,12 @@ welcome!
137
137
138
138
139
139
## Overview
140
-
The registration token is a simple random GUID that in combination with the customer Id acts as a password for installation. With 2^122 possible tokens values there is no practical method for brute forcing, ensuring that only those with tokens generated for a customer/site can do so.
140
+
The registration token is a simple random GUID that in combination with the customer Id acts as a password for installation. With 2^122 possible tokens values there is no practical method for brute forcing, ensuring that only those with tokens generated for a customer/site can install an agent.
141
141
142
-
From a practical standpoint getting the token from your N-Central server to an endpoint due to several challenges
142
+
From a practical standpoint getting the token from your N-Central server to an endpoint poses several challenges
143
143
144
144
* By default tokens will expire after a period of time
145
-
****At time of writing*** tokens are *only* generated by human interaction with the N-Central UI interact with one of:
145
+
****At time of writing*** tokens are *only* generated by human interaction with the N-Central UI with one of:
146
146
* Under **Actions -> Download Agent/Probe** and click on either **Get Registration Token** or download a Customer/Site Specific Agent/Probe that has the token pre-baked in.
147
147
* Click on an device that supports agent installation, then go to **Settings -> Local Agent** and click **Get Activation Key**
148
148
@@ -158,9 +158,9 @@ The other challenge is how to deal with deploying at scale to the following kind
158
158
To tackle the challenges of Agent deployment the community has produced several solutions that involve the N-Central API in some way. To utilise the N-Central API requires what is know as JSON Web Token (**JWT**). A JWT effectively allows anyone with that token to be able to access your N-Central server with all of the permissions associated with the user account it was generated from, so security consideration needs to be taken in where it is stored and how it is used.
159
159
160
160
Here are some of the main methods of token retrieval that have been developed by the N-Able community:
161
-
* Direct passing of Customer, Token and JWT held in a GPO through to a script that pulls the token from N-Central API then installs
162
-
* Passing the Customer ID to an Agent install script that uses an authenticated Azure function with the JWT hidden in the Configuration
163
-
* Retrieving the token values from the N-Central API then re-injecting them to Custom Properties (CPs), then then injecting those values into installation configuration files.
161
+
* Direct passing of Customer, Token and JWT held in a GPO through to a script that pulls the token from N-Central API then installs
162
+
* Passing the Customer ID to an Agent install script that uses an authenticated Azure function with the JWT hidden in the Configuration
163
+
* Retrieving the token values from the N-Central API then re-injecting them to Custom Properties (CPs), then then injecting those values into installation configuration files.
164
164
165
165
The updates to the InstallAgent are intended to take advantage of the PartnerConfig configuration file by containing the Customer ID and registration token needed for new or upgrade installations, as well as configuration of the URI and AuthCode needed for an Azure based proxy token if desired.
166
166
@@ -169,16 +169,18 @@ To update the PartnerConfig file with these values two AMPs have been provided t
169
169
170
170
***Refresh Agent Token from CP** - This method uses some local enumeration for the N-Central server address, but otherwise it is intended to pass through the Customer ID and token from Custom Properties of the Customer/Site
171
171
172
-
***RequestAzWebProxyToken() function** - Built into the script is a function that takes the Uri and Authcode and pulls the relevant registration token. The AzNableProxy is simple to deploy to your own company subscription, with a few clicks and a coffee break this token retrieval method can be adapted to many scenarios with just a CustomerID provided.
172
+
***RequestAzWebProxyToken() function** - Built into the script is a function that takes the Uri and Authcode and pulls the relevant registration token. The AzNableProxy is simple to deploy to your own company Azure subscription, with a few clicks and a coffee break this token retrieval method can be adapted to many scenarios with just a CustomerID provided.
173
173
174
174
## Security
175
-
Security is at the forefront of everyone's mind when looking at automated deployment, MSPs are continually targetted by bad faith actors, and given current events some further detail on security of tokens and JWT will be explored for each method here:
175
+
Security is at the forefront of everyone's mind when looking at automated deployment, MSPs are continually targetted by bad faith actors, given this some further detail on security of tokens and JWT will be explored for each method here:
176
+
177
+
***Refresh Agent from JWT-API** - This method passes the JWT through the local agent securely over HTTPS before being passed into the AMP parameters. The JWT is never written to the disk but is resident in the Agent process and AMP for several seconds. An attacker would need a compromised device, which for GPO deployments is a Domain Controller, with escalated priveleges to have a chance at obtaining the JWT for the few random seconds it is in memory; given this the method is considered to have very low risk of exposure.
176
178
177
-
***Refresh Agent from JWT-API** - This method passes the JWT through the local agent securely over HTTPS before being passed into the AMP parameters. The JWT is never written to the disk but is resident in the Agent process and AMP for several seconds. An attacker would need a compromised device, for GPO deployments is a Domain Controller, with escalated priveleges to have a chance at obtaining the JWT for the few random seconds it is in memory; given this the method is considered to have very low risk of exposure.
179
+
***Refresh Agent Token from CP** - In this method you would likely populate Custom Properties with a custom script from a device that is located inside the perimeter network that is secured with 2FA. Treat the JWT as you would any username/password with the principal of least privelage.
178
180
179
-
***Refresh Agent Token from CP** - In this method you populate would likely populate Custom Properties with a custom script from a device that is located inside the perimeter network that is secured with 2FA. Treat the JWT as you would any username/password with the principal of least privelage.
181
+
***RequestAzWebProxyToken() function** - This method's JWT is secured inside of a function configuration file `local.settings.json` in an Azure subscription, accessed by accounts that should be secured by 2FA. Microsoft's Azure functions are secure by design, and their security meets many international standards. If you have compliance requirements, store the token in a [Key Vault](https://docs.microsoft.com/en-us/azure/app-service/app-service-key-vault-references).
180
182
181
-
***RequestAzWebProxyToken() function** - This method's JWT is secured inside of a function configuration file `local.settings.json` in an Azure subscription, accessed by accounts that should be secured by 2FA. Microsoft's Azure function are secure by design, and their security meets many international standards. If you have compliance requirements, store the token in a [Key Vault](https://docs.microsoft.com/en-us/azure/app-service/app-service-key-vault-references).
183
+
Another component of the automation suite to consider in terms of security is the Refresh Agent Token.amp automation. This AMP directly takes a username and password of an account where MFA must be disabled, as well as a JWT of an account that can retrieve tokens. While these will be passed as variables and should only exist in memory while it executes, it is recommended to only run this automation item on a trusted device inside your perimeter network.
182
184
183
185
# Components
184
186
@@ -202,7 +204,7 @@ The **Deployment Package** is suitable by itself for all deployments, and contai
202
204
***Update PartnerConfig from JWT-API.amp** - **AMP wrapper**, for below ps1 file that uses local agent information and a JWT token to automatically populate a PartnerConfig.xml
203
205
***Update PartnerConfig from JWT-API.ps1** - **PS Code** for populating PartnerConfig
204
206
***Update PartnerConfig from CP.amp** - **AMP wrapper**, for below ps1 file that populates the PartnerConfig from your N-Central Customer Property
205
-
***Update PartnerConfig from CP.ps1** - **PS Code** for populating PartnerConfig from CP
207
+
***Update PartnerConfig from CP.ps1** - **PS Code** for populating PartnerConfig from a Custom Organization Property
206
208
***Custom Library** folder
207
209
***CustomOverrideExample.psm1** - Example function overrides for extended Azure telemetry capability
208
210
***GetCustomInstallMethodExamples.psm1** - Example function to override or change your install method data. This function is called by default at the approriate time just prior to validation checks
@@ -247,7 +249,7 @@ The methods that have been implemented by the community include:
247
249
* Token lookup by the more secure [AzNableProxy method by Kelvin Tegelaar](https://github.com/KelvinTegelaar/AzNableProxy) that hides the JWT
248
250
* Update of the Customer ID/Token in PartnerConfig via N-Central AMP
249
251
250
-
The updates to the deployment package uses all the above methods in some manner to achieve a rate of installation success. Here is the list of installation methods available by default for upgrading or installing new agents in order:
252
+
The updates to the deployment package uses all the above methods in some manner to a achieve high a rate of installation success. Here is the list of installation methods available by default for upgrading or installing new agents in order:
0 commit comments