Skip to content

Latest commit

 

History

History
215 lines (162 loc) · 9.58 KB

README.md

File metadata and controls

215 lines (162 loc) · 9.58 KB

OmadaWeb.PS PowerShell module

PSGallery Version PSGallery Downloads PowerShell PowerShell PSGallery Platform

DESCRIPTION

OmadaWeb.PS is a PowerShell module containing commands to manage data via Omada web and OData endpoints in the cloud or on-prem. This module adds support for additional authentication types like OAuth2 based on client credentials and browser-based login.

This module contains two functions that wraps over the built-in PowerShell commands Invoke-RestMethod and Invoke-WebRequest. It adds authentication handling to be used with Omada.

When using browser based authentication this module is able to sign-in automatically to Entra ID when providing credentials via the -Credential parameter. When using number based MFA it is also capable to copy the required number to you clipboard if you have PhoneLink active. It makes it a little bit easier to past the number directly in the Authenticator app on your phone.

INSTALLATION

To install the module from the PowerShell Gallery, you can use the following command:

Install-Module -Name OmadaWeb.PS

USAGE

Requirements

This module requires:

  • Windows operating system;
  • Windows PowerShell 5.1 or higher (PowerShell 7 is preferred);
  • Windows with Edge Chromium installed (Only for -AuthenticationType "Browser").

Importing the Module

To import the module, use the following command:

Import-Module OmadaWeb.PS

When using -AuthenticationType "Browser", on the first authentication attempt, the module will download the latest versions of Selenium and the Edge Driver. Binaries will be placed in %LOCALAPPDATA%\OmadaWeb.PS. Edge Webdriver updates automatically when a newer Edge version is detected during execution.

SYNTAX

Invoke-OmadaRestMethod

Invoke-OmadaRestMethod -Uri <uri> [-AuthenticationType {OAuth | Integrated | Basic | Browser | Windows}] [-OmadaWebAuthCookieFile <string>]	[-OmadaWebAuthCookieExportLocation <string>] 	[-ForceAuthentication <string>]	[-EdgeProfile <string>]	[-InPrivate <string>] [<Invoke-RestMethod Parameters>]

Invoke-OmadaRestMethod AuthenticationType: OAuth

Invoke-OmadaRestMethod -Uri <uri> [-AuthenticationType {OAuth}] [-OmadaWebAuthCookieFile <string>]	[-OmadaWebAuthCookieExportLocation <string>] 	[-ForceAuthentication <string>]	[-EdgeProfile <string>]	[-InPrivate <string>] [-EntraIdTenantId <string>] [<Invoke-RestMethod Parameters>]

Invoke-OmadaWebRequest

Invoke-OmadaWebRequest -Uri <uri> [-AuthenticationType {OAuth | Integrated | Basic | Browser | Windows}] [-OmadaWebAuthCookieFile <string>]	[-OmadaWebAuthCookieExportLocation <string>] 	[-ForceAuthentication <string>]	[-EdgeProfile <string>]	[-InPrivate <string>] [<Invoke-RestMethod Parameters>]

Invoke-OmadaWebRequest AuthenticationType: OAuth

Invoke-OmadaWebRequest -Uri <uri> [-AuthenticationType {OAuth}] [-OmadaWebAuthCookieFile <string>]	[-OmadaWebAuthCookieExportLocation <string>] 	[-ForceAuthentication <string>]	[-EdgeProfile <string>]	[-InPrivate <string>] [-EntraIdTenantId <string>] [<Invoke-RestMethod Parameters>]

EXAMPLES

Here are some example commands you can use with the OmadaWeb.PS module:

Example 1: Example command to invoke a web request. This uses -AuthenticationType "Browser" by default.

Invoke-OmadaWebRequest -Uri "https://example.omada.cloud"

Example 2: Retrieve an Identity object to the OData endpoint using Browser based authentication.

Invoke-OmadaRestMethod -Uri "https://example.omada.cloud/odata/dataobjects/identity(123456)" -AuthenticationType "Browser"

Example 3: Retrieve Identity object using EntraId OAuth authentication

Invoke-OmadaRestMethod -Uri "https://example.omada.cloud/odata/dataobjects/identity(123456)" -AuthenticationType "OAuth" -EmtraIdTenantId "c1ec94c3-4a7a-4568-9321-79b0a74b8e70" -Credential $Credential

Example 4: Retrieve Identity object using Browser authentication on EntraID with a credential specified

When adding a credential parameter the sign-in process will try to automatically select the correct user when already signed-in or and enters the provided credentials automatically. When PhoneLink is active, you have clipboard sharing configured, number based MFA is used, the required value is copied to the clipboard so you only need to paste it in the authenticator app.

Invoke-OmadaRestMethod -Uri "https://example.omada.cloud/odata/dataobjects/identity(123456)" -AuthenticationType "Browser" -Credential $Credential

PARAMETERS

The built-in are the same for both Invoke-OmadaRestMethod and Invoke-OmadaWebRequest.

-AuthenticationType

The type of authentication to use for the request. Default is Browser. The acceptable values for this parameter are:

  • Basic
  • Browser
  • Integrated
  • OAuth
  • Windows
        Type: System.String
        Required: false
        Position: Named
        Accept pipeline input: false
        Parameter set name: (All)
        Aliases: None
        Dynamic: true
        Accept wildcard characters: false

-EdgeProfile

Use the specified Edge profile for the authentication request. The acceptable values for this parameter is based on the available profiles on your system.

Important

Due the requirements of Selenium the selected Edge profile needs to be closed when using this parameter.

        Type: System.String
        Required: false
        Position: Named
        Accept pipeline input: false
        Parameter set name: (All)
        Aliases: None
        Dynamic: true
        Accept wildcard characters: false

-ForceAuthentication

Force authentication to Omada even when the cookie is still valid.

        Type: System.Switch
        Required: false
        Position: Named
        Accept pipeline input: false
        Parameter set name: (All)
        Aliases: None
        Dynamic: true
        Accept wildcard characters: false

-InPrivate

Use InPrivate mode for the authentication request.

        Type: System.Switch
        Required: false
        Position: Named
        Accept pipeline input: false
        Parameter set name: (All)
        Aliases: None
        Dynamic: true
        Accept wildcard characters: false

-OmadaWebAuthCookieExportLocation

Export the Omada authentication cookie to as a CliXml file.

        Type: System.String
        Required: false
        Position: Named
        Accept pipeline input: false
        Parameter set name: (All)
        Aliases: None
        Dynamic: true
        Accept wildcard characters: false

-OmadaWebAuthCookieFile

Use a previously exported Omada authentication cookie using -OmadaWebAuthCookieExportLocation. This must be to the cookie file.

        Type: System.String
        Required: false
        Position: Named
        Accept pipeline input: false
        Parameter set name: (All)
        Aliases: None
        Dynamic: true
        Accept wildcard characters: false

-EntraIdTenantId

The tenant id or name for -AuthenticationType OAuth.

        Type: System.String
        Required: false
        Position: Named
        Accept pipeline input: false
        Parameter set name: (All)
        Aliases: AzureAdTenantId
        Dynamic: true
        Accept wildcard characters: false

Invoke-RestMethod Parameters / Invoke-WebRequest Parameters

All other parameters, except the exclusion list below, are inherited from the PowerShell built-in functions Invoke-RestMethod for Invoke-OmadaRestMethod and Invoke-WebRequest for Invoke-OmadaWebRequest.

The following native parameters are excluded because they are handled within the module: -Session, -WebSession, -Authentication, -SessionVariable, -UseDefaultCredentials, -UseBasicParsing.

Please see Microsoft documentation for all other available options.

RELATED LINKS

Invoke-RestMethod

Invoke-WebRequest

Omada Documentation

LICENSE

This project is licensed under the MIT License. See the LICENSE file for details.