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
+69-1Lines changed: 69 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -91,6 +91,72 @@ The **InstallAgent Automation Suite** provides the following key features for de
91
91
92
92
* Live Script Status Updates and Timestamps for last actions the Script has taken via Registry
93
93
94
+
# The "Registration Token" - Agent Deployment and Considerations
95
+
96
+
## History
97
+
An information disclosure vulnerability was found in the N-Central platform in certain circumstances, this lead to auto-import being disabled in 12.1 SP1 HF2. As a part of mitigating this vulnerability N-Able introduced registration tokens in 2020.1 to allow automatic import of devices. The patch notes regarding the tokens was as follows:
98
+
99
+
>In order to enhance the security of the agent registration process, and to turn back on the ability to fully autoimport any discovered device, N-central now requires that a new Registration Token be provided during any
100
+
agent install.
101
+
>
102
+
> We've taken care to make this new security requirement as easy as possible for your technicians – the customerspecific installers now come pre-bundled with a registration token, and you can also specify the token as a
103
+
command line parameter for Group Policy or scripted deployments of the agent.
104
+
>
105
+
> From an administrative point of view, you're also going to find this to be a breeze – tokens are automatically
106
+
regenerated by N-central, and you can control how long the tokens last for via the **Administration > Defaults >
107
+
Agent/Probe Settings** page, on the new **Registration Tokens** tab – that's also where you can revoke tokens,
108
+
should the need arise.
109
+
>
110
+
>Please note that because of the new registration token feature, older versions of the agent installer will no
111
+
longer be able to register themselves with N-central.
112
+
Because these changes are in-place, we've also fully re-enabled automatic importation of devices. You're
113
+
welcome!
114
+
115
+
116
+
## Overview
117
+
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.
118
+
119
+
From a practical standpoint getting the token from your N-Central server to an endpoint due to several challenges
120
+
121
+
* By default tokens will expire after a period of time
122
+
****At time of writing*** tokens are *only* generated by human interaction with the N-Central UI interact with one of:
123
+
* 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.
124
+
* Click on an device that supports agent installation, then go to **Settings -> Local Agent** and click **Get Activation Key**
125
+
126
+
I note at time of writing as there is a planned feature to allow it to be refreshed via the N-Central API, otherwise when you first upgrade to a 202x.x platform you will need to manually generate them.
127
+
128
+
These challenges make automation of registration key deployment difficult, with many MSPs simply disabling the token expiration, and some engineers spending their mornings clicking on the same button repeatedly and pasting tokens out to a spreadsheet to then manually update in GPOs.
129
+
130
+
The other challenge is how to deal with deploying at scale to the following kinds of environments:
131
+
* Customers with multiple sites but the same domain
132
+
* Multiple customers/sites on a multi-tenanted domains
133
+
134
+
## Automation of token deployment
135
+
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.
136
+
137
+
Here are some of the main methods of token retrieval that have been developed by the N-Able community:
138
+
* 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
139
+
* Passing the Customer ID to an Agent install script that uses an authenticated Azure function with the JWT hidden in the Configuration
140
+
* 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.
141
+
142
+
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.
143
+
144
+
To update the PartnerConfig file with these values two AMPs have been provided to routinely update the configuration file as needed:
145
+
***Refresh Agent from JWT-API** - This method uses local enumeration of the agent it is run on to gather the Customer ID and Configuration needed, along with a JWT passed to the running agent.
146
+
147
+
***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
148
+
149
+
***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.
150
+
151
+
## Security
152
+
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:
153
+
154
+
***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.
155
+
156
+
***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.
157
+
158
+
***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.
159
+
94
160
# Components
95
161
96
162
The **InstallAgent Automation Suite** is comprised of several Components to aid in the deployment and facilitation of the N-Central Agent, which are listed below:
@@ -116,6 +182,9 @@ The **Deployment Package** is suitable by itself for all deployments, and contai
116
182
***CustomOverrideExample.psm1** - Example function overrides for extended Azure telemetry capability
117
183
***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
118
184
***LibReadme.md** - Brief instruction on usage of above files
185
+
***Custom Service Package** folder
186
+
***CustomService.ps1** Core logic for the custom service AMP file
187
+
***Agent Installer v6.amp** Wrapper for the CustomService to upload into N-Central
119
188
120
189
<sup>1</sup> Download Instructions for these items are included at the designated location in order to reduce overall package size, as they are already freely available on the web
121
190
@@ -490,7 +559,6 @@ That said, due to the complexity of the **Deployment Package,** there are severa
| 10 | 10 | Successful Execution | None - All prerequisite Software is installed and the **Agent Setup Script** was launched successfully |
492
561
| 11 | 11 | Execution Failed | General Failure - The Event Log will contain the details on the failure and resolution. |
493
-
| 12 | 12 | Reboot Required | The system requires a manual reboot for prerequisite Software installation. Run the Launcher again post-boot to continue setup. |
494
562
| 13 | 13 | OS Not Compatible | The Windows Operating System is not compatible with any Legacy or Current Agents (Windows Viata/2008 and older). This **may** also occur on brand new Windows Releases, if Microsoft changes its build scheme again, as it did with Windows 10. |
0 commit comments