Skip to content

Commit

Permalink
psPAS 6.0 (#485)
Browse files Browse the repository at this point in the history
* ✨➕ ADD Identity User Authentication

- Privilege Cloud Shared Services Authentication is via the CyberArk Identity Platform
- Update adds ability to use the pspete `IdentityCommand` module to satisfy Identity MFA challenges and obtain required authentication token to use against Privileged Cloud Shared Services.
- `New-PASSession` invokes the `New-IDSession` command from the  `IdentityCommand` module to progress authentication to privilege cloud systems.

* 🤡💚UPDATE New-PASSession.Tests

Correctly mock the WebRequestSession returned from the GetWebRequest method of the of the New-IDSession object.

* Update README.md

Fix issue with links

* 🚸⚡️⚗️ADD Find-SharedServicesURL

Adds helper function which finds related shared services URLs using a privileged cloud tenant subdomain name.
Updates logic in `New-PASSession` to make use of new helper function.
- Removes `IdentitySubdomain` parameter as this is now automatically discovered.
- Makes `PrivilegeCloudURL` mandatory for 'ISPSS-URL-IdentityUser'  parameterset; if not specifying a subdomain, both identity & p cloud api urls must be provided (no discovery or assumptions will be made).

Attempt at tidy up of p cloud/shaed services error handling (to be revisited no doubt)
Update of tests and docs related to updates.

* 👽️ ♻️ UPDATE New-PASSession

Abstracts service user authentication flow to utilise `New-IDPlatformToken` from `IdentityCommand` module.

---------
  • Loading branch information
pspete authored Aug 22, 2023
1 parent bcf2bcb commit 918f95d
Show file tree
Hide file tree
Showing 14 changed files with 1,089 additions and 221 deletions.
13 changes: 12 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)**

Expand Down
58 changes: 43 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1241,6 +1269,9 @@ Priority support could be considered for <a href="https://github.com/sponsors/ps

Hat Tips:

**Joe Garcia** ([infamousjoeg](https://github.com/infamousjoeg))
for the unofficial API documentation, general API wizardry & knowledge sharing.

**Jesse McWilliams**
([JesseMcWilliamss](https://github.com/JesseMcWilliams))
For the infomration needed to add PKIPN authentication into `New-PASSession`
Expand All @@ -1260,9 +1291,6 @@ For the JSON formatting assistance.
**Warren Frame**
([RamblingCookieMonster](https://github.com/RamblingCookieMonster)) for [Add-ObjectDetail.ps1](https://github.com/RamblingCookieMonster/PowerShell/blob/master/Add-ObjectDetail.ps1).

**Joe Garcia** ([infamousjoeg](https://github.com/infamousjoeg))
for the unofficial API documentation.

Chapeau!

![Logo][Logo]
80 changes: 80 additions & 0 deletions Tests/Find-SharedServicesURL.Tests.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
Describe $($PSCommandPath -Replace '.Tests.ps1') {

BeforeAll {
#Get Current Directory
$Here = Split-Path -Parent $PSCommandPath

#Assume ModuleName from Repository Root folder
$ModuleName = Split-Path (Split-Path $Here -Parent) -Leaf

#Resolve Path to Module Directory
$ModulePath = Resolve-Path "$Here\..\$ModuleName"

#Define Path to Module Manifest
$ManifestPath = Join-Path "$ModulePath" "$ModuleName.psd1"

if ( -not (Get-Module -Name $ModuleName -All)) {

Import-Module -Name "$ManifestPath" -ArgumentList $true -Force -ErrorAction Stop

}

}

InModuleScope $(Split-Path (Split-Path (Split-Path -Parent $PSCommandPath) -Parent) -Leaf ) {

Context 'General Operations' {

BeforeEach {

Mock Invoke-PASRestMethod -MockWith {

[pscustomobject]@{
identity_user_portal = [pscustomobject]@{api = 'https://SubDomainABC.id.cyberark.cloud' }
pcloud = [pscustomobject]@{api = 'https://SomeSubDomain.privilegecloud.cyberark.cloud' }
}

}

}

It 'sends request to expected endpoint when subdomain provided' {
Find-SharedServicesURL -subdomain somedomain
Assert-MockCalled -CommandName Invoke-PASRestMethod -Times 1 -ParameterFilter {
$URI -eq 'https://platform-discovery.cyberark.cloud/api/v2/services/subdomain/somedomain'
} -Scope It -Exactly
}

It 'sends request to expected endpoint when url provided' {
Find-SharedServicesURL -url https://someotherdomain.cyberark.cloud
Assert-MockCalled -CommandName Invoke-PASRestMethod -Times 1 -ParameterFilter {
$URI -eq 'https://platform-discovery.cyberark.cloud/api/v2/services/subdomain/someotherdomain'
} -Scope It -Exactly
}

It 'uses expected method' {
Find-SharedServicesURL -url https://someotherdomain.cyberark.cloud
Assert-MockCalled -CommandName Invoke-PASRestMethod -Times 1 -ParameterFilter {
$Method -eq 'GET'
} -Scope It -Exactly
}

It 'outputs expected results' {
$results = Find-SharedServicesURL -url https://someotherdomain.cyberark.cloud
$results.pcloud.api | Should -Be 'https://SomeSubDomain.privilegecloud.cyberark.cloud'
$results.identity_user_portal.api | Should -Be 'https://SubDomainABC.id.cyberark.cloud'
}

It 'outputs filtered results when service is specified' {
Find-SharedServicesURL -subdomain somedomain -service pcloud | Should -Be 'https://SomeSubDomain.privilegecloud.cyberark.cloud'
}

It 'throws if specifed service detail is not included in results' {
{ Find-SharedServicesURL -subdomain somedomain -service flows } | Should -Throw -ExpectedMessage 'URL for flows API not found'
}

}

}

}
Loading

0 comments on commit 918f95d

Please sign in to comment.