Add WebSession auth option and support for background scripts, GlideAjax, sn_cicd and sn_devstudio APIs.

[dimitertodorov]

This pull request covers off a number of features I have been using for a while now. I refactored them to fit the into the PSSnow module. I have included UNIT tests, as well as Integration tests.

Features

• Authentication using WebSessions and the ServiceNow X-UserToken header.
• Support for running background scripts using Invoke-SNOWBackgroundScript
• Support for running GlideAjax requests using Invoke-SNOWGlideAjax and Wait-SNOWGlideAjaxProgress.
• Support for sn_cicd and sn_devstudio API endpoints for managing update sets and VCS applications.

Changed

• Set-SNOWAuth

  • Added -UseWebSession parameter to start a new WebSession and use it for authentication. This works with all authentication methods (Basic, OAuth, OAuthToken).
  • Added OAuthToken ParameterSet with new parameters -AccessToken and -RefreshToken for OAuth authentication using an existing access token and refresh token.

• Assert-SNOWAuth

  • Update OAuth refresh flow. ClientSecret is now optional and will be used if provided. If not, a refresh will be attempted using the existing $script:SNOWAuth.token.refresh_token and $script:SNOWAuth.ClientId only.
  • When a WebSession is used, the function will now check if the cookies are still valid and refreshes it if necessary. This sets the $Script:SNOWAuth.SessionState variable using the new Get-SNOWWebSessionState function.

  Invoke-SNOWWebRequest

  • Update to use the $Script:SNOWAuth.session.WebSession and $script:SNOWAuth.SessionState.SecurityToken variables for authentication and session management when available and valid.

Added

web

• Get-SNOWWebConcourseState - Retrieves the current state of the active ServiceNow session.
• Get-SNOWWebSessionState - Retrieves the current state of a ServiceNow web session.
• Invoke-SNOWBackgroundScript - Executes a background script in the ServiceNow instance.
• Invoke-SNOWGlideAjax - Sends a GlideAjax request to a ServiceNow instance and returns the response synchronously.
• New-SNOWAuthWebSession - Creates an authenticated web session to ServiceNow using credentials from SNOWAuth.
• Set-SNOWWebConcourseState - Sets the current application or update set in a ServiceNow web session.
• Wait-SNOWGlideAjaxProgress - Waits for a ServiceNow background process to complete.

sn_cicd

• Get-SNOWUpdateSet - Get update set from ServiceNow by sys_id. Searches sys_update_set and sys_remote_update_set tables in order.
• Import-SNOWUpdateSet - Imports an update set XML file into ServiceNow using sys_upload.do and a valid WebSession.
• New-SNOWUpdateSet - Creates a new update set in ServiceNow using the CICD API.
• Remove-SNOWUpdateSet - Removes a ServiceNow update set by directly deleting it.
• Search-SNOWUpdateSet - Searches for update sets in ServiceNow.
• Start-SNOWUpdateSetBackOut - Removes (backs out) an update set from ServiceNow.
• Start-SNOWUpdateSetCommit - Starts the commit process for a ServiceNow update set.
• Start-SNOWUpdateSetPreview - Starts the preview process for a ServiceNow update set.
• Start-SNOWVCSApplyChanges - Starts applying changes from a remote source control to a specified local application or application-customization.
• Start-SNOWVCSApplyStash - Starts applying a previously generated "stash" of changes from a remote source control.
• Start-SNOWVCSImport - Imports an application using the specified repository URL and branch name.
• Sync-SNOWVCSApplication - Synchronizes a ServiceNow application with a Git repository using the CICD Source Control API.
• Test-SNOWUpdateSet - Tests an update set XML file to determine if it contains an update set.
• Wait-SNOWCICDProgress - Waits for a ServiceNow CICD operation to complete.

sn_devstudio

• Get-SNOWDevStudioApp - Get all VCS apps from api/sn_devstudio/v1/vcs/apps
• Sync-SNOWDevStudioApp - Imports, syncs and updates a ServiceNow application with a Git repository. Use sn_devstudio API endpoints to manage the repository.
• Wait-SNOWDevStudioTransaction - Wait for a sn_devstudio transaction to complete - api/sn_devstudio/v1/vcs/transactions/{ProgressId}

[dimitertodorov]

@insomniacc - Could you take a look and see if the changes fit with your vision for this Module.

[insomniacc]

@dimitertodorov Hey man! Awesome work, I really appreciate you putting time and effort into improving the module, I've not had a great deal of time myself this past year to add to it. I'll take a look properly at some point this week and go through it all. Will let you know what I think!

[dimitertodorov]

Hey - Thanks you for all the feedback. This was exactly what I was looking for someone to do since I am mostly working solo on this project.

Will fix these up along with some other errors I encountered.

During recent testing I also found that the sn_devstudio endpoint returns 403 for non-admin users. When using Basic auth this is fine since we fallback to traditional login.do session login. This fallback method does not work in an OAuth context - so I will raise a clearer error, along with the required role needed to call that endpoint.

[dimitertodorov]

Need to rethink the web-session handling. Will close this for now while I do a bit of digging. Latest Yokohama release no longer accepts g_ck tokens from the sn_devstudio_/v1/get_publish_info endpoint when running background scripts.