What happened

Full release notes are on https://github.com/sdl/ISHRemote/blob/master/Doc/ReleaseNotes-ISHRemote-8.0.md and https://github.com/RWS/ISHRemote/releases/tag/v8.0

Before I forget, all people with a Github account, could you spare a moment to STAR this repository - see top-right Star icon on https://github.com/RWS/ISHRemote/ Appreciated!

General

This release inherits the v0.1 to v0.14 up to v7.0 development branch and features. Most cmdlets and business logic are fully compatible even around authentication (New-IshSession and Test-IshSession ). In short, we expect it all to work still :)

Remember

• All C# source code of the ISHRemote library is online at master, including handling of the different Connection protocols in a NET 4.8 and NET 6.0+ style.
• All PowerShell-based Pester integration tests are located per cmdlet complying with the *.tests.ps1 file naming convention. See for example AddIshDocumentObj.Tests.ps1 or TestIshValidXml.Tests.ps1

The below text describes the delta compared to fielded release ISHRemote v7.0.

Introducing Session Protocol

Where we used to have only implicit WcfSoapWithWsTrust protocol - same as ISHRemote v7.0 and earlier on Tridion Docs 14SPx/14.0.x and earlier - resulting SOAP Proxy classes on IShSession. We now introduce WcfSoapWithOpenIdConnect for usage on Tridion Docs 15.x/15.x.y which results in SOAP Proxy classes that are authenticated over Modern Authentication.

For ease of use, the target server product version is detected via parameter -WsBaseUrl. So if you don't specifiy an explicit -Protocol parameter, it will get the best matching default. The defaults are listed as below.

• For Tridion Docs 14SP414SPx/14.0.x and earlier, this is WcfSoapWithWsTrust. You can use -PSCredential and –IshUserName/-IshPassword like you were used to.
• For Tridion Docs 15.x/15.x.y and later, this is WcfSoapWithOpenIdConnect. This will lead you to browser-based authentication or you can use a –ClientId/-ClientSecret combination.

You can force the -Protocol parameter, and below list will explain what will happen exactly.

• If protocol on a New-IShSession cmdlet is forced to WcfSoapWithWsTrust, then it behaves the same as ISHRemote v7.0 and earlier or any Tridion Docs 14SPx/14.0.x and earlier system
  • WS-Federation/WS-Trust over –IshUserName/-IshPassword parameters, typical ISHSTS setups
  • WS-Federation/WS-Trust over implicit ActiveDirectory NetworkCredentials , typical ADFS setups
• If protocol is forced to WcfSoapWithOpenIdConnect on Tridion Docs 15.x/15.x.y
  • Modern Authentication like Publication Manager or Organize Space, etc over your favorite Browser
  • Modern Authentication over –ClientId/-ClientSecret coming from Access Management (ISHAM)
  • Note: ISHWS/OWCF web services have feature parity to ISHWS/WCF (and actually also ISHWS/*.ASMX)
• If protocol is forced to OpenApiWithOpenIdConnect on Tridion Docs 15.x/15.x.y
  • You mostly get fully operational WcfSoapWithOpenIdConnect
  • You also get an OpenAPI 3.0 experimental proxy on your IShSession object (experimental, might look different in the future)

OpenIdConnect Authorization Code Flow with PKCE Flow

On Tridion Docs 15.x/15.x.y the below cmdlet with superfluous -Protocol WcfSoapWithOpenIdConnect parameter will create an IshSession for usage in all other cmdlets.

New-IshSession -Protocol WcfSoapWithOpenIdConnect -WsBaseUrl https://ish.example.com/ISHWS/ #over-SystemBrowser

Below animation illustrates how you will authenticate over your (system) browser, potentially reusing your single sign on session. This example federates the authentication from Access Management (ISHAM) to built-in Tridion Docs Identity Provider (ISHID) which could be a different MFA-protected experience in other setups. Do note that ISHID accounts have prepared External Id (FISHEXTERNALID) entries on every Tridion Docs User Profile.

OpenIdConnect Client Credentials Flow

On Tridion Docs 15.x/15.x.y the below cmdlet with superfluous -Protocol WcfSoapWithOpenIdConnect parameter will create an IshSession for usage in all other cmdlets.

New-IshSession -Protocol WcfSoapWithOpenIdConnect -WsBaseUrl https://ish.example.com/ISHWS/ -ClientId "c82..." -ClientSecret "ziK...=="

Below animation illustrates how you need to set up a Service Account resulting in Client Id and Client Secret connected to Tridion Docs User Profile for authorization.

Protocol Overview

User's Last Log On Timestamp Impact

Since Tridion Docs 15/15.0.0, the Tridion Docs User Profile as seen in the Settings > User profile overview (ISHCS/OrganizeSpace) shows the last log on date time (field FISHLASTLOGINON) which is only accurate for authentication over Tridion Docs Identity Provider (ISHID or before ISHSTS). When federating authentication the remote Secure Token Service (STS) is responsible. Do note that Access Management (ISHAM) User Profiles, even when logged in over Tridion Docs Identity Provider (ISHID) or any other federated Secure Token Service (STS) does get updated.

Experimental OpenAPI REST API Proxies

Since Tridion Docs 15/15.0.0 an OpenAPI REST API v3.0 was added on route for a full functional parity successor of the public SOAP v2.5 API on which ISHRemote originated. The outstanding challenge is that over time the internals of ISHRemote cmdlets will be rewired from SOAP to REST - in this ISHRemote release most cmdlets are SOAP as you can derive from protocols WcfSoapWithWsTrust and WcfSoapWithOpenIdConnect.

If there is a new implementation, it can be selected over protocol OpenApiWithOpenIdConnect. If not, it will fall back to WcfSoapWithOpenIdConnect. The first step of side-by-side implementation is having access to authenticated proxies. Hence the introduction of experimental future InfoShareOpenApiWithOpenIdConnectConnection which offers NSwag generated proxies to OpenAPI REST API of Tridion Docs 15.1/15.1.0 and matching Access Management 1.0 API.

$ishSession = New-IshSession -WsBaseUrl "https://example.com/ISHWS/" -Protocol OpenApiWithOpenIdConnect
$json = $ishSession.OpenApiISH30Client.GetApplicationVersionAsync()
$json.Result
$json = $ishSession.OpenApiAM10Client.IdentityProvidersGetAsync()
$json.Result

References

If you don't know what PowerShell or ISHRemote are about. Or don't know how to install it, then have a look at the videos and supporting blogposts on https://community.sdl.com/product-groups/sdl-tridion-dx/tridion-docs/b/weblog/posts/automating-tasks-in-sdl-tridion-docs-using-powershell

Have fun,
Dave