Skip to content

Latest commit

 

History

History
227 lines (157 loc) · 12.7 KB

README.md

File metadata and controls

227 lines (157 loc) · 12.7 KB
Raw

NinjaOne - A PowerShell module for NinjaOne software

Azure DevOps Pipeline Status Azure DevOps Code Coverage PowerShell Gallery License GitHub Sponsors Stable Release Preview Release

Who am I?

I am Mikey O'Toole (@homotechsual) the founder and director for a UK-based managed IT services provider with a passion for automation and good quality MSP software tools.

What is this?

This is the code for a PowerShell module for the NinjaOne platform.

The module is written for PowerShell 7. It is not compatible with Windows PowerShell 5.1 and never will be.. This module is licensed under the MIT license.

What does it do?

NinjaOne provides a PowerShell wrapper around the NinjaOne API. The module can retrieve and send information to the NinjaOne API.

Thanks & Credits

This module would not work nearly as well without the support of the NinjaOne team in particular:

  • Robert K
  • Peter B
  • Jonathan C

Installing

This module is published to the PowerShell Gallery and can be installed from within PowerShell with Install-Module

Install-Module NinjaOne -AllowPrerelease

Current Status

The following API endpoints have not yet been implemented or have been implemented but not tested. They will be added/tested before the first stable release unless otherwise indicated. This list does not contain any GET actions - all information can be retrieved - only outstanding commands are POST, PUT, PATCH and DELETE actions (Set-, New- and Remove- commands.)

Endpoint Status Notes
/v2/webhook Not Planned This endpoint is not useful in the context of the PS module.
/v2/devices/approval/$mode Not Tested Will be tested before 1.0.0.
/v2/alert/$uid Not Added Will be added before 1.0.0. Waiting on clarity from NinjaOne.
/v2/ticketing/ticket/$ticketId Not Added Will be added before 1.0.0.
/v2/ticketing/ticket Not Added Will be added before 1.0.0.
/v2/device/$id/windows-service/$serviceId/configure Not Added Will be added before 1.0.0.
/v2/device/$id/reboot/$mode Not Added Will be added before 1.0.0.
/v2/device/$id Not Added Will be added before 1.0.0.
/v2/device/$id/windows-service/$serviceId/control Not Added Will be added before 1.0.0.
/v2/device/$id/maintenance Not Added Will be added before 1.0.0.
/v2/device/$id/script/run Not Added Will be added before 1.0.0.
/v2/organization/$id/locations Not Added Will be added before 1.0.0.
/v2/organization/$id Not Added Will be added before 1.0.0.
/v2/organization/$id/locations/$locationId Not Added Will be added before 1.0.0.
/v2/organization/$id/policies Not Added Will be added before 1.0.0.

Getting Started

The first and probably most important requirement for this module is getting it connected to NinjaOne instance.

Using Client Credentials (Non-Interactive/Unattended Auth)

Creating an API application in NinjaOne

  1. In your NinjaOne tenant head to Configuration > Integrations > API.

  2. Click on Client App IDs
    All going well you should be at configuration/integrations/api/client.

  3. Click on Add to add a new API application.

  4. Set the Application Platform to API Services (machine-to-machine)

  5. Enter the Name.
    For example NinjaOne API PS Module.

  6. In the Redirect URIs box enter https://localhost/ This isn't actually used so just set it to plain old localhost as above.

  7. Set the Scopes appropriately. If you want to be able to do anything using the API select all three scopes. Otherwise select them as appropriate for your needs:

    • Monitoring - This provides access to most of the Get-* commands.
    • Management - This provides access to most of the management functionality like agent installer generation.
    • Control - This provides access to control settings and make changes to the configuration of your Ninja tenant.

  8. Set the Allowed Grant Types to Client Credentials and Refresh Token. Authorization code is used for the initial login, the refresh token is used to maintain access on subsequent logins.

  9. Click on Save and Complete the MFA challenge.

  10. Store the Client Secret securely and close the small popup window.

  11. Click on Close and on the Client App IDs screen copy the Client ID for your application. Store this with your Client Secret.

Important: You cannot currently use Client Credentials authentication to access any of the ticketing API endpoints (Tickets/Boards/Contacts) due to a bug on Ninja's side.

Connecting the PowerShell module to the API

  1. Connect to the NinjaOne API with Connect-NinjaOne

    # Splat the parameters - easier to read!
$ConnectionParameters = @{
    Instance = 'eu'
    ClientID = 'ABCDEfGH-IjKLmnopqrstUV1w23x45yz'
    ClientSecret = 'abc123abc123def456def456ghi789ghi789lmn012lmn012'
    UseClientAuth = $True
}

Connect-NinjaOne @ConnectionParameters
    • Let's disect that last parameter:
      • UseClientAuth tells the module that we have we want to use Client Credentials to authenticate and get an access token the module can use to authenticate to NinjaOne.
    # Pass the parameters individually - more familiar!
Connect-NinjaOne -Instance 'eu' -ClientID 'ABCDEfGH-IjKLmnopqrstUV1w23x45yz' -ClientSecret 'abc123abc123def456def456ghi789ghi789lmn012lmn012' -UseClientAuth

Using Authorisation Code (Interactive/Attended Auth)

Creating an API application in NinjaOne

  1. In your NinjaOne tenant head to Configuration > Integrations > API.

  2. Click on Client App IDs
    All going well you should be at configuration/integrations/api/client.

  3. Click on Add to add a new API application.

  4. Set the Application Platform to Web (PHP, Java, .Net Core, etc.)

  5. Enter the Name.
    For example NinjaOne API PS Module.

  6. In the Redirect URIs box enter http://localhost:9090/ **Make sure the redirect URI ends with a /. You can use any port number here just make sure you remember it and adjust the Connect-NinjaOne command below appropriately.

  7. Set the Scopes appropriately. If you want to be able to do anything using the API select all three scopes. Otherwise select them as appropriate for your needs:

    • Monitoring - This provides access to most of the Get-* commands.
    • Management - This provides access to most of the management functionality like agent installer generation.
    • Control - This provides access to control settings and make changes to the configuration of your Ninja tenant.

  8. Set the Allowed Grant Types to Authorization Code and Refresh Token. Authorization code is used for the initial login, the refresh token is used to maintain access on subsequent logins.

  9. Click on Save and Complete the MFA challenge.

  10. Store the Client Secret securely and close the small popup window.

  11. Click on Close and on the Client App IDs screen copy the Client ID for your application. Store this with your Client Secret.

Connecting the PowerShell module to the API (first time / authorisation code flow)

  1. Install the NinjaOne PowerShell module on PowerShell 7.0 or above.

    Install-Module NinjaOne -AllowPrerelease

  2. Make sure you have all the information you need to connect:

    • Your NinjaOne instance this could be:
      • EU https://eu.ninjarmm.com
      • OC https://oc.ninjarmm.com
      • US https://app.ninjarmm.com
    • Your client ID and client secret.
    • The port you chose for your redirect URI.

  3. Connect to the NinjaOne API with Connect-NinjaOne

    # Splat the parameters - easier to read!
$ConnectionParameters = @{
    Instance = 'eu'
    ClientID = 'ABCDEfGH-IjKLmnopqrstUV1w23x45yz'
    ClientSecret = 'abc123abc123def456def456ghi789ghi789lmn012lmn012'
    Port = 9090
    UseWebAuth = $True
    ShowTokens = $True
}

Connect-NinjaOne @ConnectionParameters
    • Let's disect those last two parameters:
      • UseWebAuth tells the module that we need to login to NinjaOne to get an authorisation code. This uses a local .NET Kestrel based webserver that listens on the port you pass and handles the reponse that Ninja sends to http://localhost:9090 - the Redirect URI we configured earlier.
      • ShowTokens tells the module that you want to see the generated refresh token - so that when you next authenticate you can use that refresh token instead of logging in again and generating a new set of tokens.
    # Pass the parameters individually - more familiar!
Connect-NinjaOne -Instance 'eu' -ClientID 'ABCDEfGH-IjKLmnopqrstUV1w23x45yz' -ClientSecret 'abc123abc123def456def456ghi789ghi789lmn012lmn012' -Port 9090 -UseWebAuth -ShowTokens

Connecting the PowerShell module to the API (subsequent times / refresh token flow)

  1. Connect to the NinjaOne API with Connect-NinjaOne

    # Splat the parameters - easier to read!
$ReconnectionParameters = @{
    Instance = 'eu'
    ClientID = 'ABCDEfGH-IjKLmnopqrstUV1w23x45yz'
    ClientSecret = 'abc123abc123def456def456ghi789ghi789lmn012lmn012'
    RefreshToken = 'abc123abc123defABCDEfGH-IjKLmnopqrstUV1w-23x45yz456def456ghi789ghi7-89lmn012lmn012'
    UseTokenAuth = $True
}

Connect-NinjaOne @ReconnectionParameters
    • Let's disect those last two parameters:
      • RefreshToken this is the token we get from the initial authorisation code flow login.
      • UseTokenAuth tells the module that we have a refresh token so we want to bypass the authorisation code steps and just exchange it inside the module for an access token the module can use to authenticate to NinjaOne.
    # Pass the parameters individually - more familiar!
Connect-NinjaOne -Instance 'eu' -ClientID 'ABCDEfGH-IjKLmnopqrstUV1w23x45yz' -ClientSecret 'abc123abc123def456def456ghi789ghi789lmn012lmn012' -RefreshToken 'abc123abc123defABCDEfGH-IjKLmnopqrstUV1w-23x45yz456def456ghi789ghi7-89lmn012lmn012' -UseTokenAuth