diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d890ef6..47a99974 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,18 @@ ## Planned Updates / Unreleased - Continued development to encompass any new documented features of the CyberArk API. -- psPAS v6.0... +- psPAS v7.0... + +## **6.0.0** + +- Update & Breaking Change + - `New-PASSession` + - **All Privilege Cloud Shared Services Authentication via the CyberArk Identity Platform now depends on the pspete `IdentityCommand` module.** + - Adds Identity User Authentication, using the `IdentityCommand` module to satisfy Identity MFA challenges and obtain required authentication token to use against Privileged Cloud Shared Services. + - Adds logic to determine correct Identity tenant URL based on provided Privileged Cloud Subdomain value. + - Both Privileged Cloud API URL & Identity Portal URL are required to be specified if subdomain value is not provided. + - Service User authentication for Shared Services introduced in recent previous versions requires installation of `IdentityCommand` module and specification of additional attribute. + - See [the docs](https://pspas.pspete.dev/docs/authentication/#shared-services-authentication) & [New-PASSession](https://pspas.pspete.dev/commands/New-PASSession) for full details. ## **5.6.135 (July 31st 2023)** diff --git a/README.md b/README.md index a920a98a..9f56b7bd 100644 --- a/README.md +++ b/README.md @@ -179,6 +179,34 @@ $Cert = "0E199489C57E666115666D6E9990C2ACABDB6EDB" New-PASSession -UseSharedAuthentication -BaseURI https://pvwa.somedomain.com -CertificateThumbprint $Cert ``` +#### Shared Services Authentication + +**Privilege Cloud Shared Services authentication flows require the pspete `IdentityCommand` module, available from the [Powershell Gallery](https://www.powershellgallery.com/packages/IdentityCommand) & [GitHub](https://github.com/pspete/IdentityCommand).** + +##### Identity User + +Provide Identity User credentials and tenant details for authentication to CyberArk Identity for Privilege Cloud Shared Services: + +``` +#using URL +New-PASSession -IdentityTenantURL https://SomeTenantName.id.cyberark.cloud -PrivilegeCloudURL https://SomeTenant.privilegecloud.cyberark.cloud -Credential $Cred -IdentityUser +``` + +``` +#using subdomain +New-PASSession -TenantSubdomain SomeTenantName -Credential $Cred -IdentityUser +``` + +##### Service User + +Provide tenant ID and non-interactive API User credentials for authentication via CyberArk Identity for Privilege Cloud Shared Services: + +``` +New-PASSession -TenantSubdomain YourPrivilegeCloudTenantID -Credential $ServiceUserCreds -ServiceUser +``` + +Consult the vendor documentation for guidance on setting up a dedicated API Service user for non-interactive API use. + ### Basic Operations ![Logo][Logo] @@ -946,18 +974,18 @@ Click the below dropdown to view the current list of psPAS functions and their m [`Get-PASPTARiskSummary`][Get-PASPTARiskSummary] |**13.2** |Get PTA Risk Summary [`New-PASRequestObject`][New-PASRequestObject] |**---** |Format an object to include in an request list -[New-PASRequestObject]:/psPAS/Functions/Requests/New-PASRequestObject -[Get-PASUserTypeInfo]:/psPAS/Functions/User/Get-PASUserTypeInfo -[Get-PASPTARiskEvent]:/psPAS/Functions/EventSecurity/Get-PASPTARiskEvent -[Set-PASPTARiskEvent]:/psPAS/Functions/EventSecurity/Set-PASPTARiskEvent -[Get-PASPTARiskSummary]:/psPAS/Functions/EventSecurity/Get-PASPTARiskSummary -[Get-PASPTAGlobalCatalog]:/psPAS/Functions/EventSecurity/Get-PASPTAGlobalCatalog -[Add-PASPTAGlobalCatalog]:/psPAS/Functions/EventSecurity/Add-PASPTAGlobalCatalog -[Disable-PASUser]:/psPAS/Functions/User/Disable-PASUser -[Enable-PASUser]:/psPAS/Functions/User/Enable-PASUser -[Get-PASLinkedAccount]:/psPAS/Functions/Accounts/Get-PASLinkedAccount -[Add-PASPersonalAdminAccount]:/psPAS/Functions/Accounts/Add-PASPersonalAdminAccount -[Publish-PASDiscoveredAccount]:/psPAS/Functions/Accounts/Publish-PASDiscoveredAccount +[New-PASRequestObject]:/psPAS/Functions/Requests/New-PASRequestObject.ps1 +[Get-PASUserTypeInfo]:/psPAS/Functions/User/Get-PASUserTypeInfo.ps1 +[Get-PASPTARiskEvent]:/psPAS/Functions/EventSecurity/Get-PASPTARiskEvent.ps1 +[Set-PASPTARiskEvent]:/psPAS/Functions/EventSecurity/Set-PASPTARiskEvent.ps1 +[Get-PASPTARiskSummary]:/psPAS/Functions/EventSecurity/Get-PASPTARiskSummary.ps1 +[Get-PASPTAGlobalCatalog]:/psPAS/Functions/EventSecurity/Get-PASPTAGlobalCatalog.ps1 +[Add-PASPTAGlobalCatalog]:/psPAS/Functions/EventSecurity/Add-PASPTAGlobalCatalog.ps1 +[Disable-PASUser]:/psPAS/Functions/User/Disable-PASUser.ps1 +[Enable-PASUser]:/psPAS/Functions/User/Enable-PASUser.ps1 +[Get-PASLinkedAccount]:/psPAS/Functions/Accounts/Get-PASLinkedAccount.ps1 +[Add-PASPersonalAdminAccount]:/psPAS/Functions/Accounts/Add-PASPersonalAdminAccount.ps1 +[Publish-PASDiscoveredAccount]:/psPAS/Functions/Accounts/Publish-PASDiscoveredAccount.ps1 [Get-PASPlatformSummary]:/psPAS/Functions/Platforms/Get-PASPlatformSummary.ps1 [Add-PASOpenIDConnectProvider]:/psPAS/Functions/Authentication/Add-PASOpenIDConnectProvider.ps1 [Get-PASOpenIDConnectProvider]:/psPAS/Functions/Authentication/Get-PASOpenIDConnectProvider.ps1 @@ -1241,6 +1269,9 @@ Priority support could be considered for ] -BaseURI [-newPassword ] [-SkipCertificateCheck] [-WhatIf] [-Confirm] [] ``` -### SharedServices-URL +### ISPSS-URL-ServiceUser ``` New-PASSession -Credential -IdentityTenantURL -PrivilegeCloudURL - [-PVWAAppName ] [-SkipVersionCheck] [-Certificate ] [-CertificateThumbprint ] - [-SkipCertificateCheck] [-WhatIf] [-Confirm] [] + [-ServiceUser] [-PVWAAppName ] [-SkipVersionCheck] [-Certificate ] + [-CertificateThumbprint ] [-SkipCertificateCheck] [-WhatIf] [-Confirm] [] ``` -### SharedServices-Subdomain +### ISPSS-Subdomain-ServiceUser ``` -New-PASSession -Credential -TenantSubdomain [-IdentitySubdomain ] - [-PVWAAppName ] [-SkipVersionCheck] [-Certificate ] [-CertificateThumbprint ] - [-SkipCertificateCheck] [-WhatIf] [-Confirm] [] +New-PASSession -Credential -TenantSubdomain [-ServiceUser] [-PVWAAppName ] + [-SkipVersionCheck] [-Certificate ] [-CertificateThumbprint ] [-SkipCertificateCheck] + [-WhatIf] [-Confirm] [] +``` + +### ISPSS-URL-IdentityUser +``` +New-PASSession -Credential -IdentityTenantURL -PrivilegeCloudURL + [-IdentityUser] [-PVWAAppName ] [-SkipVersionCheck] [-Certificate ] + [-CertificateThumbprint ] [-SkipCertificateCheck] [-WhatIf] [-Confirm] [] +``` + +### ISPSS-Subdomain-IdentityUser +``` +New-PASSession -Credential -TenantSubdomain [-IdentityUser] [-PVWAAppName ] + [-SkipVersionCheck] [-Certificate ] [-CertificateThumbprint ] [-SkipCertificateCheck] + [-WhatIf] [-Confirm] [] ``` ### Gen1Radius @@ -292,7 +306,9 @@ Authenticates to a CyberArk Vault using SAML authentication & Gen1 API. New-PASSession -TenantSubdomain PCloudTenantID -Credential $cred ``` -Authenticates to Privilege Cloud Shared Services, where 'PCloudTenantID' is a Subdomain configured for both Identity & Privilege Cloud portals. +Authenticates to Privilege Cloud Shared Services, where 'PCloudTenantID' is the Subdomain configured for the Privilege Cloud portal. + +The subdomain value provided will be used to discover the identity portal URL. ### EXAMPLE 24 ``` @@ -321,17 +337,52 @@ Logon with PKIPN auth, using a selected certificate stored on smart card. ### EXAMPLE 26 ``` -New-PASSession -TenantSubdomain PCloudTenantID -IdentitySubdomain IdentityTenantID -Credential $cred +New-PASSession -TenantSubdomain PCloudTenantID -Credential $cred -ServiceUser ``` -Authenticates to Privilege Cloud Shared Services, where subdomains for Identity & Privilege Cloud portals have not been configured to share the same value. +Authenticates to Privilege Cloud Shared Services using an API Service User. ### EXAMPLE 27 ``` -New-PASSession -IdentityTenantURL 'https://ABC123.id.cyberark.cloud' -PrivilegeCloudURL 'https://XYZ789.privilegecloud.cyberark.cloud' -Credential $cred +New-PASSession -IdentityTenantURL 'https://ABC123.id.cyberark.cloud' -PrivilegeCloudURL 'https://XYZ789.privilegecloud.cyberark.cloud' -Credential $cred -ServiceUser ``` -Authenticates to Privilege Cloud Shared Services, specifying individual URL values for Identity & Privilege Cloud tenants. +Authenticates to Privilege Cloud Shared Services using an API Service User, specifying individual URL values for Identity & Privilege Cloud tenants. + +### Example 28 +``` +New-PASSession -IdentityTenantURL https://SomeTenantName.id.cyberark.cloud -PrivilegeCloudURL 'https://XYZ789.privilegecloud.cyberark.cloud' -Credential $Cred -IdentityUser +``` + +Authenticates to Identity Shared Services using an Identity User and provides authenticated session to associated Privileged Cloud environment. + +Requires IdentityCommand module to be installed for authentication flow to complete. + +See: Get-Help IdentityCommand + +### Example 29 +``` +New-PASSession -TenantSubdomain YourTenantName -Credential $Cred -IdentityUser +``` + +Authenticates to Identity Shared Services using an Identity User and provides authenticated session to associated Privileged Cloud environment. + +Assumes a Shared Services URL of https://YourTenantName.id.cyberark.cloud + +Requires IdentityCommand module to be installed for authentication flow to complete. + +See: Get-Help IdentityCommand + +### Example 30 +``` +New-PASSession -IdentityTenantURL https://SomeTenantName.id.cyberark.cloud -Credential $Cred -PrivilegeCloudURL https://SomeName.privilegecloud.cyberark.cloud -IdentityUser +``` + +Authenticates to Identity Shared Services using an Identity User and provides authenticated session to specified Privileged Cloud environment. + +Requires IdentityCommand module to be installed for authentication flow to complete. + +See: Get-Help IdentityCommand ## PARAMETERS @@ -352,7 +403,7 @@ Accept wildcard characters: False ```yaml Type: PSCredential -Parameter Sets: SharedServices-URL, SharedServices-Subdomain, Gen2Radius +Parameter Sets: ISPSS-URL-ServiceUser, ISPSS-Subdomain-ServiceUser, ISPSS-URL-IdentityUser, ISPSS-Subdomain-IdentityUser, Gen2Radius Aliases: Required: True @@ -764,16 +815,16 @@ Accept wildcard characters: False ``` ### -TenantSubdomain -The subdomain name value of the Identity Shared Services / Privilege Cloud Tenant. +The subdomain name value of the Shared Services Privilege Cloud Tenant. -Where the Shared Services tenants for both Identity and Privilege Cloud have been configured to share identical subdomain names, use this parameter to specify the subdomain name. +The value provided for the subdomain parameter will be used to discover the identity tenant api URL. - API operations will target URL: https://.privilegecloud.cyberark.cloud -- Authentication will be performed against https://.id.cyberark.cloud +- Authentication will be performed against https://.id.cyberark.cloud ```yaml Type: String -Parameter Sets: SharedServices-Subdomain +Parameter Sets: ISPSS-Subdomain-ServiceUser, ISPSS-Subdomain-IdentityUser Aliases: Required: True @@ -783,36 +834,34 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -IdentitySubdomain -A subdomain name value for the Identity Tenant used for authentication into Privilege Cloud. - -Where the Shared Services tenants for Identity and Privilege Cloud have not been configured with identical subdomain names, use this parameter to specify the subdomain name for the Identity tenant. +### -IdentityTenantURL +Specify the URL value of the CyberArk Identity Portal to authenticate against. -- Authentication will be performed against https://.id.cyberark.cloud -- API operations will target URL: https://.privilegecloud.cyberark.cloud +E.G.: +- https://.id.cyberark.cloud +- https://.my.idaptive.app ```yaml Type: String -Parameter Sets: SharedServices-Subdomain +Parameter Sets: ISPSS-URL-ServiceUser, ISPSS-URL-IdentityUser Aliases: -Required: False +Required: True Position: Named Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -IdentityTenantURL -Specify the URL value of the CyberArk Identity Portal to authenticate against. +### -PrivilegeCloudURL +Specify the URL value used to access the CyberArk Privilege Cloud API. E.G.: -- https://.id.cyberark.cloud -- https://.my.idaptive.app +- https://.privilegecloud.cyberark.cloud ```yaml Type: String -Parameter Sets: SharedServices-URL +Parameter Sets: ISPSS-URL-ServiceUser, ISPSS-URL-IdentityUser Aliases: Required: True @@ -822,15 +871,31 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -PrivilegeCloudURL -Specify the URL value used to access the CyberArk Privilege Cloud API. +### -IdentityUser +Specify switch parameter to authenticate with standard Interactive Identity User. -E.G.: -- https://.privilegecloud.cyberark.cloud +Authentication process will require use of the IdentityCommand module. + +See: Get-Help IdentityCommand. ```yaml -Type: String -Parameter Sets: SharedServices-URL +Type: SwitchParameter +Parameter Sets: ISPSS-URL-IdentityUser, ISPSS-Subdomain-IdentityUser +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ServiceUser +Specify switch parameter to authenticate with Identity API Oauth Service User + +```yaml +Type: SwitchParameter +Parameter Sets: ISPSS-URL-ServiceUser, ISPSS-Subdomain-ServiceUser Aliases: Required: True @@ -862,3 +927,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable [https://docs.cyberark.com/Product-Doc/OnlineHelp/PAS/Latest/en/Content/SDK/Shared%20Logon%20Authentication%20-%20Logon.htm#Sharedlogonauthentication](https://docs.cyberark.com/Product-Doc/OnlineHelp/PAS/Latest/en/Content/SDK/Shared%20Logon%20Authentication%20-%20Logon.htm#Sharedlogonauthentication) [https://github.com/allynl93/PS-SAML-Interactive](https://github.com/allynl93/PS-SAML-Interactive) + +[https://github.com/pspete/IdentityCommand](https://github.com/pspete/IdentityCommand) diff --git a/docs/collections/_docs/01-authentication.md b/docs/collections/_docs/01-authentication.md index f68527ff..1882c6c7 100644 --- a/docs/collections/_docs/01-authentication.md +++ b/docs/collections/_docs/01-authentication.md @@ -2,7 +2,7 @@ title: "Authentication" permalink: /docs/authentication/ excerpt: "psPAS Authentication" -last_modified_at: 2023-07-31T01:23:45-00:00 +last_modified_at: 2023-08-20T01:23:45-00:00 --- _Everything begins with a **Logon**:_ @@ -136,24 +136,35 @@ New-PASSession -UseSharedAuthentication -BaseURI https://pvwa.somedomain.com -Ce ## Shared Services Authentication -Provide tenant ID and non-interactive API User credentials for authentication via CyberArk Identity for Privilege Cloud Shared Services: +**Privilege Cloud Shared Services authentication flows require use of the pspete `IdentityCommand` module, available from the Powershell Gallery & GitHub.** + +### Identity User + +Provide Identity User credentials and tenant details for authentication to CyberArk Identity for Privilege Cloud Shared Services: ``` -New-PASSession -TenantSubdomain YourPrivilegeCloudTenantID -Credential $PCloudCreds +New-PASSession -IdentityTenantURL https://SomeTenantName.id.cyberark.cloud -PrivilegeCloudURL https://SomeTenant.privilegecloud.cyberark.cloud -Credential $Cred -IdentityUser ``` -Most Shared Services implementations will be configured so that Identity and Privileged Cloud portal addresses share a common subdomain. +### Service User -Where this is not the case, and Identity and Privilege Cloud portals do not share an identical subdomain, these can be specified independently: +Provide tenant ID and non-interactive API User credentials for authentication via CyberArk Identity for Privilege Cloud Shared Services: ``` -New-PASSession -TenantSubdomain PCloudTenantID -IdentitySubdomain IdentityTenantID -Credential $cred +New-PASSession -TenantSubdomain YourPrivilegeCloudTenantID -Credential $ServiceUserCreds -ServiceUser ``` -For scenarios where Identity and Privilege Cloud portals are accessed using different URLs (i.e. 1st generation systems), the URLs can be specified instead on subdomain values: +Consult the vendor documentation for guidance on setting up a dedicated API Service user for non-interactive API use. + +### Tenant Subdomains & Portal URLs +When providing a value for a privilege cloud tenant subdomain, this value is used to discover the identity tenant with which to authenticate: ``` -New-PASSession -IdentityTenantURL 'https://ABC123.id.cyberark.cloud' -PrivilegeCloudURL 'https://XYZ789.privilegecloud.cyberark.cloud' -Credential $cred +New-PASSession -TenantSubdomain PCloudTenantID -Credential $cred -ServiceUser ``` -Consult the vendor documentation for guidance on setting up a dedicated API Service user for non-interactive API use. \ No newline at end of file +If you encounter any issue authenticating with the module when providing a subdomain value, you can alternatively specify URL values for both your Identity portal, and Privilege Cloud API: + +``` +New-PASSession -IdentityTenantURL 'https://ABC123.id.cyberark.cloud' -PrivilegeCloudURL 'https://XYZ789.privilegecloud.cyberark.cloud' -Credential $cred -ServiceUser +``` diff --git a/psPAS/Functions/Authentication/New-PASSession.ps1 b/psPAS/Functions/Authentication/New-PASSession.ps1 index 02451856..f3894e41 100644 --- a/psPAS/Functions/Authentication/New-PASSession.ps1 +++ b/psPAS/Functions/Authentication/New-PASSession.ps1 @@ -28,13 +28,25 @@ function New-PASSession { Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelinebyPropertyName = $true, - ParameterSetName = 'SharedServices-Subdomain' + ParameterSetName = 'ISPSS-Subdomain-IdentityUser' )] [Parameter( Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelinebyPropertyName = $true, - ParameterSetName = 'SharedServices-URL' + ParameterSetName = 'ISPSS-URL-IdentityUser' + )] + [Parameter( + Mandatory = $true, + ValueFromPipeline = $true, + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'ISPSS-Subdomain-ServiceUser' + )] + [Parameter( + Mandatory = $true, + ValueFromPipeline = $true, + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'ISPSS-URL-ServiceUser' )] [ValidateNotNullOrEmpty()] [PSCredential]$Credential, @@ -43,7 +55,13 @@ function New-PASSession { Mandatory = $true, ValueFromPipeline = $false, ValueFromPipelinebyPropertyName = $true, - ParameterSetName = 'SharedServices-Subdomain' + ParameterSetName = 'ISPSS-Subdomain-IdentityUser' + )] + [Parameter( + Mandatory = $true, + ValueFromPipeline = $false, + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'ISPSS-Subdomain-ServiceUser' )] [string]$TenantSubdomain, @@ -98,18 +116,16 @@ function New-PASSession { [string]$BaseURI, [Parameter( - Mandatory = $false, + Mandatory = $true, ValueFromPipeline = $false, ValueFromPipelinebyPropertyName = $true, - ParameterSetName = 'SharedServices-Subdomain' + ParameterSetName = 'ISPSS-URL-IdentityUser' )] - [string]$IdentitySubdomain, - [Parameter( Mandatory = $true, ValueFromPipeline = $false, ValueFromPipelinebyPropertyName = $true, - ParameterSetName = 'SharedServices-URL' + ParameterSetName = 'ISPSS-URL-ServiceUser' )] [string]$IdentityTenantURL, @@ -117,10 +133,44 @@ function New-PASSession { Mandatory = $true, ValueFromPipeline = $false, ValueFromPipelinebyPropertyName = $true, - ParameterSetName = 'SharedServices-URL' + ParameterSetName = 'ISPSS-URL-IdentityUser' + )] + [Parameter( + Mandatory = $true, + ValueFromPipeline = $false, + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'ISPSS-URL-ServiceUser' )] [string]$PrivilegeCloudURL, + [Parameter( + Mandatory = $true, + ValueFromPipeline = $false, + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'ISPSS-Subdomain-IdentityUser' + )] + [Parameter( + Mandatory = $true, + ValueFromPipeline = $false, + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'ISPSS-URL-IdentityUser' + )] + [switch]$IdentityUser, + + [Parameter( + Mandatory = $true, + ValueFromPipeline = $false, + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'ISPSS-Subdomain-ServiceUser' + )] + [Parameter( + Mandatory = $true, + ValueFromPipeline = $false, + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'ISPSS-URL-ServiceUser' + )] + [switch]$ServiceUser, + [parameter( Mandatory = $true, ValueFromPipelinebyPropertyName = $true, @@ -398,7 +448,7 @@ function New-PASSession { Switch ($PSCmdlet.ParameterSetName) { - 'SharedServices-URL' { + ( { $PSItem -match '^ISPSS-URL' } ) { #Ensure URLs are in expected format #Remove trailing space and PasswordVault (if provided in PrivilegeCloudURL) @@ -406,45 +456,27 @@ function New-PASSession { $PrivilegeCloudURL = $PrivilegeCloudURL -replace '/$', '' $PrivilegeCloudURL = $PrivilegeCloudURL -replace '/PasswordVault$', '' - #Set Required URL Values for Request - $LogonRequest['Uri'] = "$IdentityTenantURL/oauth2/platformtoken" - $Uri = "$PrivilegeCloudURL/$PVWAAppName" - } - 'SharedServices-Subdomain' { - - #Most Shared Services subdomains for Identity & Privilege Cloud tenants will be identical - If ($PSBoundParameters.Keys -notcontains 'IdentitySubdomain') { - $IDSubdomain = $TenantSubdomain - } Else { - #If different, use specified subdomain for Identity - $IDSubdomain = $IdentitySubdomain - } + ( { $PSItem -match '^ISPSS-SubDomain' } ) { - $LogonRequest['Uri'] = "https://${IDSubdomain}.id.cyberark.cloud/oauth2/platformtoken" #hardcode Shared Services auth + $SharedServicesURLs = Find-SharedServicesURL -subdomain $TenantSubdomain - #Build URL - $Uri = "https://${TenantSubdomain}.privilegecloud.cyberark.cloud/$PVWAAppName" + $IdentityTenantURL = $SharedServicesURLs | Select-Object -ExpandProperty identity_user_portal | Select-Object -ExpandProperty api + $PrivilegeCloudURL = $SharedServicesURLs | Select-Object -ExpandProperty pcloud | Select-Object -ExpandProperty api } - ( { $PSItem -match '^SharedServices-' } ) { + ( { $PSItem -match '^ISPSS-.*-.*User$' } ) { - $Body = @{ + #IdentityUser/ServiceUser LogonRequest for New-IDSession/New-IDPlatformToken + $LogonRequest['Uri'] = $IdentityTenantURL + $LogonRequest['Credential'] = $Credential - grant_type = 'client_credentials' - #Add user name from credential object - client_id = $($Credential.UserName) - #Add decoded password value from credential object - client_secret = $($Credential.GetNetworkCredential().Password) + #URL for P Cloud API Operations + $Uri = "${PrivilegeCloudURL}/$PVWAAppName" - } - - $LogonRequest['Body'] = $Body - $LogonRequest['ContentType'] = 'application/x-www-form-urlencoded' break - } 'integrated' { @@ -597,8 +629,30 @@ function New-PASSession { try { - #Send Logon Request - $PASSession = Invoke-PASRestMethod @LogonRequest + switch ($PSCmdlet.ParameterSetName) { + ( { $PSItem -match '^ISPSS' } ) { + #Check IdentityCommand module available + if (-not (Get-Module IdentityCommand)) { + try { Import-Module IdentityCommand -ErrorAction Stop } + catch { throw 'Failed to import IdentityCommand: Install the IdentityCommand Module and try again.' } + } + } + ( { $PSItem -match '^ISPSS-.*-IdentityUser$' } ) { + #Perform Identity User Authentication using IdentityCommand module + $PASSession = New-IDSession -tenant_url $LogonRequest['Uri'] -Credential $LogonRequest['Credential'] + break + } + ( { $PSItem -match '^ISPSS-.*-ServiceUser$' } ) { + #Perform Identity User Authentication using IdentityCommand module + $PASSession = New-IDPlatformToken -tenant_url $LogonRequest['Uri'] -Credential $LogonRequest['Credential'] + break + } + default { + #Send Logon Request + $PASSession = Invoke-PASRestMethod @LogonRequest + break + } + } If ($null -ne $PASSession.UserName) { @@ -686,6 +740,19 @@ function New-PASSession { #Shared Service access_token. $CyberArkLogonResult = "$($PASSession.token_type) $($PASSession.access_token)" + #Make the IdentityCommand WebSession available in the psPAS module scope + Set-Variable -Name WebSession -Value $($PSItem.GetWebSession()) -Scope Script + + } + + ( { $null -ne $PSItem.Token } ) { + + #Shared Services Identity User Bearer Token + $CyberArkLogonResult = "Bearer $($PASSession.Token)" + + #Make the IdentityCommand WebSession available in the psPAS module scope + Set-Variable -Name WebSession -Value $($PSItem.GetWebSession()) -Scope Script + } ( { $null -ne $PSItem.LogonResult } ) { diff --git a/psPAS/Private/Find-SharedServicesURL.ps1 b/psPAS/Private/Find-SharedServicesURL.ps1 new file mode 100644 index 00000000..ebf435bf --- /dev/null +++ b/psPAS/Private/Find-SharedServicesURL.ps1 @@ -0,0 +1,116 @@ +function Find-SharedServicesURL { + <# + .SYNOPSIS + Find URL details for ISPSS shared services + + .DESCRIPTION + Given a shared services subdomain or URL value, returns details of URLs for available Shared Services. + + .PARAMETER subdomain + The Shared Services subdomain to return service URL values of. + + .PARAMETER url + The Shared Services URL to return service URL values of. + + .PARAMETER service + Specify to return the API URL of a particular service. + + .EXAMPLE + Find-SharedServicesURL -subdomain somedomain + + .EXAMPLE + Find-SharedServicesURL -url https://someotherdomain.cyberark.cloud + + .EXAMPLE + Find-SharedServicesURL -subdomain somedomain -service pcloud + + .NOTES + Pete Maan 2023 + #> + [CmdletBinding()] + Param( + [Parameter( + Mandatory = $true, + ValueFromPipeline = $true, + ParameterSetName = 'Subdomain' + )] + [string]$subdomain, + + [Parameter( + Mandatory = $true, + ValueFromPipeline = $true, + ParameterSetName = 'URL' + )] + [string]$url, + + [Parameter( + Mandatory = $false, + ValueFromPipeline = $true + )] + [ValidateSet( + 'analytics', + 'audit', + 'cem', + 'cloud_onboarding', + 'component_manager', + 'flows', + 'idaptive_risk_analytics', + 'identity_administration', + 'identity_compliance', + 'identity_user_portal', + 'jit', + 'pcloud', + 'sca', + 'secrets_hub', + 'secrets_manager', + 'session_monitoring' + )] + [string]$service + ) + + Begin { + $PlatformDiscoveryURL = 'https://platform-discovery.cyberark.cloud/api/v2/services/subdomain/' + } + + Process { + + if ($PSCmdlet.ParameterSetName -eq 'URL') { + $URIObject = [System.UriBuilder]::new($url) + $subdomain = $URIObject.host.Split('.') | Select-Object -First 1 + } + + $PlatformDiscoveryURL = $PlatformDiscoveryURL + $subdomain + + $Result = Invoke-PASRestMethod -URI $PlatformDiscoveryURL -Method GET + + If ($null -ne $Result) { + + If ($PSBoundParameters.ContainsKey('service')) { + + $Services = $Result | Get-Member -MemberType NoteProperty | Select-Object -ExpandProperty Name + + If ($Services -notcontains $Service) { + + throw "URL for $service API not found" + + } + + Else { + + $Result | Select-Object -ExpandProperty $service | Select-Object -ExpandProperty api + + } + + } Else { + + $Result + + } + + } + + } + + End {} + +} \ No newline at end of file diff --git a/psPAS/Private/Get-PASResponse.ps1 b/psPAS/Private/Get-PASResponse.ps1 index c7d06dd6..e4f4f03f 100644 --- a/psPAS/Private/Get-PASResponse.ps1 +++ b/psPAS/Private/Get-PASResponse.ps1 @@ -68,7 +68,7 @@ function Get-PASResponse { } - 'application/json; charset=utf-8' { + ({ $PSItem -match 'application/json' }) { #application/json content expected for most responses. diff --git a/psPAS/Private/Invoke-PASRestMethod.ps1 b/psPAS/Private/Invoke-PASRestMethod.ps1 index 499d0541..5adf004f 100644 --- a/psPAS/Private/Invoke-PASRestMethod.ps1 +++ b/psPAS/Private/Invoke-PASRestMethod.ps1 @@ -242,9 +242,9 @@ try { - $ResponseException = $ResponseException | ConvertFrom-Json - $ErrorMessage = $ResponseException | Select-Object -ExpandProperty error_description - $ErrorID = $($ResponseException | Select-Object -ExpandProperty error) + $ThisException = $ResponseException | ConvertFrom-Json -ErrorAction Stop + $ErrorMessage = $ThisException | Select-Object -ExpandProperty error_description -ErrorAction Stop + $ErrorID = $($ThisException | Select-Object -ExpandProperty error -ErrorAction Stop) } catch { diff --git a/psPAS/en-US/psPAS-help.xml b/psPAS/en-US/psPAS-help.xml index 9ffae87b..f3f9e9d3 100644 --- a/psPAS/en-US/psPAS-help.xml +++ b/psPAS/en-US/psPAS-help.xml @@ -24471,6 +24471,17 @@ Invoke-RestMethod -Method GET -Uri "$session.BaseURI/SomePath" -WebSession $sess None + + ServiceUser + + Specify switch parameter to authenticate with Identity API Oauth Service User + + + SwitchParameter + + + False + New-PASSession @@ -24577,10 +24588,88 @@ Invoke-RestMethod -Method GET -Uri "$session.BaseURI/SomePath" -WebSession $sess TenantSubdomain - The subdomain name value of the Identity Shared Services / Privilege Cloud Tenant. - Where the Shared Services tenants for both Identity and Privilege Cloud have been configured to share identical subdomain names, use this parameter to specify the subdomain name. + The subdomain name value of the Shared Services Privilege Cloud Tenant. + The value provided for the subdomain parameter will be used to discover the identity tenant api URL. - API operations will target URL: https://<TenantSubdomain>.privilegecloud.cyberark.cloud - - Authentication will be performed against https://<TenantSubdomain>.id.cyberark.cloud + - Authentication will be performed against https://<DiscoveredIdentitySubdomain>.id.cyberark.cloud + + String + + String + + + None + + + ServiceUser + + Specify switch parameter to authenticate with Identity API Oauth Service User + + + SwitchParameter + + + False + + + + New-PASSession + + Credential + + A Valid PSCredential object. + + PSCredential + + PSCredential + + + None + + + PVWAAppName + + The name of the CyberArk PVWA Virtual Directory. + Defaults to PasswordVault + + String + + String + + + PasswordVault + + + SkipVersionCheck + + If the SkipVersionCheck switch is specified, Get-PASServer will not be called after successfully authenticating. + Get-PASServer is not supported before version 9.7. + + + SwitchParameter + + + False + + + Certificate + + See Invoke-WebRequest + Specifies the client certificate that is used for a secure web request. + Enter a variable that contains a certificate or a command or expression that gets the certificate. + + X509Certificate + + X509Certificate + + + None + + + CertificateThumbprint + + See Invoke-WebRequest + The thumbprint of the certificate to use for client certificate authentication. String @@ -24590,12 +24679,191 @@ Invoke-RestMethod -Method GET -Uri "$session.BaseURI/SomePath" -WebSession $sess None - IdentitySubdomain + SkipCertificateCheck + + Skips certificate validation checks. + Using this parameter is not secure and is not recommended. + This switch is only intended to be used against known hosts using a self-signed certificate for testing purposes. + Use at your own risk. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm - A subdomain name value for the Identity Tenant used for authentication into Privilege Cloud. - Where the Shared Services tenants for Identity and Privilege Cloud have not been configured with identical subdomain names, use this parameter to specify the subdomain name for the Identity tenant. - - Authentication will be performed against https://<IdentitySubdomain>.id.cyberark.cloud + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + IdentityTenantURL + + Specify the URL value of the CyberArk Identity Portal to authenticate against. + E.G.: - https://<identity-tenant-id>.id.cyberark.cloud + - https://<identity-tenant-id>.my.idaptive.app + + String + + String + + + None + + + PrivilegeCloudURL + + Specify the URL value used to access the CyberArk Privilege Cloud API. + E.G.: - https://<subdomain>.privilegecloud.cyberark.cloud + + String + + String + + + None + + + IdentityUser + + Specify switch parameter to authenticate with standard Interactive Identity User. + Authentication process will require use of the IdentityCommand module. + See: Get-Help IdentityCommand. + + + SwitchParameter + + + False + + + + New-PASSession + + Credential + + A Valid PSCredential object. + + PSCredential + + PSCredential + + + None + + + PVWAAppName + + The name of the CyberArk PVWA Virtual Directory. + Defaults to PasswordVault + + String + + String + + + PasswordVault + + + SkipVersionCheck + + If the SkipVersionCheck switch is specified, Get-PASServer will not be called after successfully authenticating. + Get-PASServer is not supported before version 9.7. + + + SwitchParameter + + + False + + + Certificate + + See Invoke-WebRequest + Specifies the client certificate that is used for a secure web request. + Enter a variable that contains a certificate or a command or expression that gets the certificate. + + X509Certificate + + X509Certificate + + + None + + + CertificateThumbprint + + See Invoke-WebRequest + The thumbprint of the certificate to use for client certificate authentication. + + String + + String + + + None + + + SkipCertificateCheck + + Skips certificate validation checks. + Using this parameter is not secure and is not recommended. + This switch is only intended to be used against known hosts using a self-signed certificate for testing purposes. + Use at your own risk. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + TenantSubdomain + + The subdomain name value of the Shared Services Privilege Cloud Tenant. + The value provided for the subdomain parameter will be used to discover the identity tenant api URL. - API operations will target URL: https://<TenantSubdomain>.privilegecloud.cyberark.cloud + - Authentication will be performed against https://<DiscoveredIdentitySubdomain>.id.cyberark.cloud String @@ -24604,6 +24872,19 @@ Invoke-RestMethod -Method GET -Uri "$session.BaseURI/SomePath" -WebSession $sess None + + IdentityUser + + Specify switch parameter to authenticate with standard Interactive Identity User. + Authentication process will require use of the IdentityCommand module. + See: Get-Help IdentityCommand. + + + SwitchParameter + + + False + New-PASSession @@ -25988,25 +26269,10 @@ Invoke-RestMethod -Method GET -Uri "$session.BaseURI/SomePath" -WebSession $sess TenantSubdomain - The subdomain name value of the Identity Shared Services / Privilege Cloud Tenant. - Where the Shared Services tenants for both Identity and Privilege Cloud have been configured to share identical subdomain names, use this parameter to specify the subdomain name. - - API operations will target URL: https://<TenantSubdomain>.privilegecloud.cyberark.cloud - - Authentication will be performed against https://<TenantSubdomain>.id.cyberark.cloud - - String - - String - - - None - - - IdentitySubdomain - - A subdomain name value for the Identity Tenant used for authentication into Privilege Cloud. - Where the Shared Services tenants for Identity and Privilege Cloud have not been configured with identical subdomain names, use this parameter to specify the subdomain name for the Identity tenant. - - Authentication will be performed against https://<IdentitySubdomain>.id.cyberark.cloud + The subdomain name value of the Shared Services Privilege Cloud Tenant. + The value provided for the subdomain parameter will be used to discover the identity tenant api URL. - API operations will target URL: https://<TenantSubdomain>.privilegecloud.cyberark.cloud + - Authentication will be performed against https://<DiscoveredIdentitySubdomain>.id.cyberark.cloud String @@ -26042,6 +26308,32 @@ Invoke-RestMethod -Method GET -Uri "$session.BaseURI/SomePath" -WebSession $sess None + + IdentityUser + + Specify switch parameter to authenticate with standard Interactive Identity User. + Authentication process will require use of the IdentityCommand module. + See: Get-Help IdentityCommand. + + SwitchParameter + + SwitchParameter + + + False + + + ServiceUser + + Specify switch parameter to authenticate with Identity API Oauth Service User + + SwitchParameter + + SwitchParameter + + + False + @@ -26232,7 +26524,8 @@ New-PASSession -SAMLAuth -concurrentSession $true -BaseURI $baseURL -SAMLRespons -------------------------- EXAMPLE 23 -------------------------- New-PASSession -TenantSubdomain PCloudTenantID -Credential $cred - Authenticates to Privilege Cloud Shared Services, where 'PCloudTenantID' is a Subdomain configured for both Identity & Privilege Cloud portals. + Authenticates to Privilege Cloud Shared Services, where 'PCloudTenantID' is the Subdomain configured for the Privilege Cloud portal. + The subdomain value provided will be used to discover the identity portal URL. @@ -26262,16 +26555,44 @@ New-PASSession -BaseURI $url -type PKIPN -Certificate $Cert -------------------------- EXAMPLE 26 -------------------------- - New-PASSession -TenantSubdomain PCloudTenantID -IdentitySubdomain IdentityTenantID -Credential $cred + New-PASSession -TenantSubdomain PCloudTenantID -Credential $cred -ServiceUser - Authenticates to Privilege Cloud Shared Services, where subdomains for Identity & Privilege Cloud portals have not been configured to share the same value. + Authenticates to Privilege Cloud Shared Services using an API Service User. -------------------------- EXAMPLE 27 -------------------------- - New-PASSession -IdentityTenantURL 'https://ABC123.id.cyberark.cloud' -PrivilegeCloudURL 'https://XYZ789.privilegecloud.cyberark.cloud' -Credential $cred + New-PASSession -IdentityTenantURL 'https://ABC123.id.cyberark.cloud' -PrivilegeCloudURL 'https://XYZ789.privilegecloud.cyberark.cloud' -Credential $cred -ServiceUser - Authenticates to Privilege Cloud Shared Services, specifying individual URL values for Identity & Privilege Cloud tenants. + Authenticates to Privilege Cloud Shared Services using an API Service User, specifying individual URL values for Identity & Privilege Cloud tenants. + + + + -------------------------- Example 28 -------------------------- + New-PASSession -IdentityTenantURL https://SomeTenantName.id.cyberark.cloud -PrivilegeCloudURL 'https://XYZ789.privilegecloud.cyberark.cloud' -Credential $Cred -IdentityUser + + Authenticates to Identity Shared Services using an Identity User and provides authenticated session to associated Privileged Cloud environment. + Requires IdentityCommand module to be installed for authentication flow to complete. + See: Get-Help IdentityCommand + + + + -------------------------- Example 29 -------------------------- + New-PASSession -TenantSubdomain YourTenantName -Credential $Cred -IdentityUser + + Authenticates to Identity Shared Services using an Identity User and provides authenticated session to associated Privileged Cloud environment. + Assumes a Shared Services URL of https://YourTenantName.id.cyberark.cloud + Requires IdentityCommand module to be installed for authentication flow to complete. + See: Get-Help IdentityCommand + + + + -------------------------- Example 30 -------------------------- + New-PASSession -IdentityTenantURL https://SomeTenantName.id.cyberark.cloud -Credential $Cred -PrivilegeCloudURL https://SomeName.privilegecloud.cyberark.cloud -IdentityUser + + Authenticates to Identity Shared Services using an Identity User and provides authenticated session to specified Privileged Cloud environment. + Requires IdentityCommand module to be installed for authentication flow to complete. + See: Get-Help IdentityCommand @@ -26300,6 +26621,10 @@ New-PASSession -BaseURI $url -type PKIPN -Certificate $Cert https://github.com/allynl93/PS-SAML-Interactive https://github.com/allynl93/PS-SAML-Interactive + + https://github.com/pspete/IdentityCommand + https://github.com/pspete/IdentityCommand +