One Identity Safeguard Powershell module and scripting resources.
Check out our samples to get started scripting to Safeguard!
This Powershell module is published to the
PowerShell Gallery
to make it as easy as possible to install using the built-in Import-Module
cmdlet.
It can also be updated using the Update-Module
to get the latest functionality.
By default Powershell modules are installed for all users, and you need to be running Powershell as an Administrator to install for all users.
> Install-Module safeguard-ps
Or, you can install them just for you using the -Scope
parameter which will
never require Administrator permission:
> Install-Module safeguard-ps -Scope CurrentUser
If you want to upgrade from the PowerShell Gallery you should use:
> Update-Module safeguard-ps
Or, for a specific user:
> Update-Module safeguard-ps -Scope CurrentUser
If you run into errors while upgrading make sure that you upgrade for all users
if the module was originally installed for all users. If the module was originally
installed for just the current user, be sure to use the -Scope
parameter to again
specify CurrentUser
when running the Update-Module
cmdlet.
To install a pre-release version of safeguard-ps you need to use the latest version
of PowerShellGet if you aren't already. Windows comes with one installed, but you
want the newest and it requires the -Force
parameter to get it.
If you don't have PowerShellGet, run:
> Install-Module PowerShellGet -Force
Then, you can install a pre-release version of safeguard-ps by running:
> Install-Module -Name safeguard-ps -AllowPrerelease
Once you have loaded the module, you can connect to Safeguard using the
Connect-Safeguard
cmdlet. If you do not have SSL properly configured, you
must use the -Insecure
parameter to avoid SSL trust errors.
Authentication in Safeguard is based on OAuth2. In most cases the
Connect-Safeguard
cmdlet uses the Resource Owner Grant of OAuth2.
> Connect-Safeguard -Insecure 192.168.123.123 local Admin
Password: ********
Login Successful.
The Connect-Safeguard
cmdlet will create a session variable that includes
your access token and connection information. This makes it easier to call
other cmdlets provided by the module.
Client certificate authentication is also available in Connect-Safeguard
.
This can be done either using a PFX certificate file or a SHA-1 thumbprint
of a certificate stored in the Current User personal certificate store.
Two-factor authentication can only be performed using the -Gui
parameter,
so that the built-in secure token service can use the browser agent to
redirect you to multiple authentication providers. This authentication
mechanism uses the Authorization Code Grant of OAuth2.
> Connect-Safeguard -Insecure 192.168.123.123 -Gui
Login Successful.
Once you are logged in, you can call any cmdlet listed below. For example:
> Get-SafeguardUser Admin
If you do not have rights to access a particular portion of the Web API, you will be presented with an error message saying authorization is required.
> Get-SafeguardAsset
Invoke-RestMethod : {"Code":60108,"Message":"Authorization is required for this request.","InnerError":null}
When you are finished, you can close the session or call the
Disconnect-Safeguard
cmdlet to invalidate and remove your access token.
Use the Get-SafeguardCommand
to see what is available from the module.
Since there are so many cmdlets in safeguard-ps you can use filters to find exactly the cmdlet you are looking for.
For example:
> Get-SafeguardCommand Get Account Dir
CommandType Name Version Source
----------- ---- ------- ------
Function Get-SafeguardDirectoryAccount 2.1.0.9... safeguard-ps
The version of safeguard-ps mirrors the version of Safeguard that it was developed and tested against. However, the build numbers (fourth number) should not be expected to match.
For Example:
safeguard-ps 2.2.152 would correspond to Safeguard 2.2.0.6958.
This does not mean that safeguard-ps 2.2.152 won't work at all with Safeguard 2.4.0.7846. For the most part the cmdlets will still work, but you may occasionally come across things that are broken.
For the best results, please try to match the first two version numbers of the safeguard-ps module to the first two numbers of the Safeguard appliance you are communicating with. The most important thing for safeguard-ps is the version of the Safeguard Web API, which will never change between where only the third and fourth numbers differ.
As of version 2.2.x, safeguard-ps began using a three digit version number. It also now supports prerelease builds. This is so the next version of safeguard-ps can be developed in lock step with the Safeguard product.
Dropping the third number is insignificant as the Safeguard Web API never changes in those releases.
Safeguard 2.7 shipped with a new version of the Safeguard API (v3). The safeguard-ps 2.7 module was updated to use the v3 API by default. Safeguard 2.7 serves both the v2 and v3 APIs, but the v3 version of the API is the only one guaranteed to work. Please try to match the first and second version numbers between Safeguard and safeguard-ps as instructed above to avoid any compatibility issues.
Once you have configured your A2A registration in Safeguard, you can get the information to call Safeguard A2A by running the following:
> Get-SafeguardA2aCredentialRetrievalInformation
This will report the certificate thumbprint you need to use as well as the API key required to request a specific account password.
The best practice is to install your user certificate in the Windows User Certificate Store (user the Personal folder). Then, you can reference the certificate securely in safeguard-ps just using the thumbprint.
You can see the thumbprints of certificates currently installed in your Windows User Certificate Store using the following command:
> Get-ChildItem Cert:\CurrentUser\My
To retrieve a password via A2A from PowerShell use Get-SafeguardA2aPassword
.
For example:
> Get-SafeguardA2aPassword 10.5.5.5 -Thumbprint 756766BB590D7FA9CA9E1971A4AE41BB9CEC82F1 -ApiKey JeD9HIgGZM+CYZcVk6YHDNCp4W36DNsjS1TDi+S5HzI=
Safeguard 2.6 added the capability of returning CSV from the API by passing in an Accept header set to 'text/csv'. Several reporting cmdlets were built on this functionality.
Run:
> Get-SafeguardCommand report
to see all of these reporting cmdlets.
The following video shows how the reporting cmdlets work, including parameters for opening the output directly in Excel.
The following cmdlets are currently supported. More will be added to this
list over time. Every cmdlet in the list supports Get-Help
to provide
additional information as to how it can be called.
Please file GitHub Issues for cmdlets that are not working and to request cmdlets for functionality that is missing.
The following list of cmdlets might not be complete. To see everything that safeguard-ps can do run:
> Get-SafeguardCommand
Please report anything you see from the output that is missing, and we will update this list.
- Get-SafeguardCommand
- Get-SafeguardBanner
- Connect-Safeguard
- Disconnect-Safeguard
- Invoke-SafeguardMethod
- Get-SafeguardAccessTokenStatus
- Update-SafeguardAccessToken
- Get-SafeguardLoggedInUser
- Get-SafeguardIdentityProviderType
- Get-SafeguardPlatform
- Find-SafeguardPlatform
- Get-SafeguardTimeZone
- Get-SafeguardTransferProtocol
- Install-SafeguardLicense
- Uninstall-SafeguardLicense
- Get-SafeguardLicense
- Install-SafeguardTrustedCertificate
- Uninstall-SafeguardTrustedCertificate
- Get-SafeguardTrustedCertificate
- Install-SafeguardAuditLogSigningCertificate
- Uninstall-SafeguardAuditLogSigningCertificate
- Get-SafeguardAuditLogSigningCertificate
- Install-SafeguardSslCertificate
- Uninstall-SafeguardSslCertificate
- Get-SafeguardSslCertificate
- Set-SafeguardSslCertificateForAppliance
- Clear-SafeguardSslCertificateForAppliance
- Get-SafeguardSslCertificateForAppliance
- Get-SafeguardCertificateSigningRequest (Get-SafeguardCsr)
- New-SafeguardCertificateSigningRequest (New-SafeguardCsr)
- Remove-SafeguardCertificateSigningRequest (Remove-SafeguardCsr)
- New-SafeguardTestCertificatePki
- Get-SafeguardNetworkInterface
- Set-SafeguardNetworkInterface
- Get-SafeguardDnsSuffix
- Set-SafeguardDnsSuffix
- Install-SafeguardDesktopClient
- Get-SafeguardStatus
- Get-SafeguardApplianceAvailability
- Get-SafeguardApplianceState
- Get-SafeguardVersion
- Get-SafeguardApplianceVerification
- Get-SafeguardTime
- Set-SafeguardTime
- Get-SafeguardApplianceUptime
- Get-SafeguardHealth
- Get-SafeguardApplianceName
- Set-SafeguardApplianceName
- Invoke-SafeguardApplianceShutdown
- Invoke-SafeguardApplianceReboot
- Invoke-SafeguardApplianceFactoryReset
- Get-SafeguardSupportBundle
- Get-SafeguardPatch
- Clear-SafeguardPatch
- Install-SafeguardPatch
- New-SafeguardBackup
- Remove-SafeguardBackup
- Export-SafeguardBackup
- Import-SafeguardBackup
- Restore-SafeguardBackup
- Save-SafeguardBackupToArchive
- Get-SafeguardBackup
- Get-SafeguardBmcConfiguration
- Enable-SafeguardBmcConfiguration
- Disable-SafeguardBmcConfiguration
- Set-SafeguardBmcAdminPassword
- Get-SafeguardTls12OnlyStatus
- Enable-SafeguardTls12Only
- Disable-SafeguardTls12Only
- Add-SafeguardClusterMember
- Remove-SafeguardClusterMember
- Get-SafeguardClusterMember
- Get-SafeguardClusterHealth
- Get-SafeguardClusterPrimary
- Set-SafeguardClusterPrimary
- Enable-SafeguardClusterPrimary
- Get-SafeguardClusterOperationStatus
- Unlock-SafeguardCluster
- Get-SafeguardClusterSummary
- Get-SafeguardClusterPlatformTaskLoadStatus
- Get-SafeguardClusterPlatformTaskQueueStatus
- Invoke-SafeguardPing
- Invoke-SafeguardSessionsPing
- Invoke-SafeguardTelnet
- Invoke-SafeguardSessionsTelnet
- Get-SafeguardSessionContainerStatus
- Get-SafeguardSessionModuleStatus
- Get-SafeguardSessionModuleVersion
- Reset-SafeguardSessionModule
- Repair-SafeguardSessionModule
- Get-SafeguardSessionCertificate
- Install-SafeguardSessionCertificate
- Reset-SafeguardSessionCertificate
- Get-SafeguardSessionSshAlgorithms
- Set-SafeguardSessionSshAlgorithms
- Add-SafeguardSessionSshAlgorithm
- Remove-SafeguardSessionSshAlgorithm
- Get-SafeguardArchiveServer
- New-SafeguardArchiveServer
- Test-SafeguardArchiveServer
- Remove-SafeguardArchiveServer
- Edit-SafeguardArchiveServer
- Get-SafeguardAccessRequest
- Find-SafeguardAccessRequest
- New-SafeguardAccessRequest
- Edit-SafeguardAccessRequest
- Get-SafeguardActionableRequest
- Get-SafeguardMyRequest
- Get-SafeguardMyApproval
- Get-SafeguardMyReview
- Get-SafeguardRequestableAccount (Get-SafeguardMyRequestable)
- Find-SafeguardRequestableAccount (Find-SafeguardMyRequestable)
- Get-SafeguardAccessRequestPassword (Get-SafeguardAccessRequestCheckoutPassword)
- Get-SafeguardAccessRequestRdpFile
- Get-SafeguardAccessRequestRdpUrl
- Get-SafeguardAccessRequestSshUrl
- Start-SafeguardAccessRequestSession
- Copy-SafeguardAccessRequestPassword
- Close-SafeguardAccessRequest
- Approve-SafeguardAccessRequest
- Deny-SafeguardAccessRequest (Revoke-SafeguardAccessRequest)
- Get-SafeguardAccessRequestActionLog
- Assert-SafeguardAccessRequest
- Get-SafeguardIdentityProvider
- New-SafeguardStarling2faAuthentication
- Get-SafeguardUser
- Find-SafeguardUser
- New-SafeguardUser
- Remove-SafeguardUser
- Set-SafeguardUserPassword
- Edit-SafeguardUser
- Enable-SafeguardUser
- Disable-SafeguardUser
- Rename-SafeguardUser
- Get-SafeguardAssetPartition
- New-SafeguardAssetPartition
- Remove-SafeguardAssetPartition
- Edit-SafeguardAssetPartition
- Get-SafeguardAsset
- Find-SafeguardAsset
- New-SafeguardAsset
- Test-SafeguardAsset
- Remove-SafeguardAsset
- Edit-SafeguardAsset
- Sync-SafeguardDirectoryAsset
- Get-SafeguardAssetAccount
- Find-SafeguardAssetAccount
- New-SafeguardAssetAccount
- Edit-SafeguardAssetAccount
- Set-SafeguardAssetAccountPassword
- New-SafeguardAssetAccountRandomPassword
- Test-SafeguardAssetAccountPassword
- Invoke-SafeguardAssetAccountPasswordChange
- Invoke-SafeguardAssetSshHostKeyDiscovery
- Remove-SafeguardAssetAccount
- Get-SafeguardDirectoryIdentityProvider
- New-SafeguardDirectoryIdentityProvider
- Remove-SafeguardDirectoryIdentityProvider
- Edit-SafeguardDirectoryIdentityProvider
- Get-SafeguardDirectoryIdentityProviderDomain
- Get-SafeguardDirectoryIdentityProviderSchemaMapping
- Set-SafeguardDirectoryIdentityProviderSchemaMapping
- Get-SafeguardDirectory
- New-SafeguardDirectory
- Test-SafeguardDirectory
- Remove-SafeguardDirectory
- Edit-SafeguardDirectory
- Sync-SafeguardDirectory
- Get-SafeguardDirectoryMigrationData
- Get-SafeguardDirectoryAccount
- Find-SafeguardDirectoryAccount
- New-SafeguardDirectoryAccount
- Edit-SafeguardDirectoryAccount
- Set-SafeguardDirectoryAccountPassword
- New-SafeguardDirectoryAccountRandomPassword
- Test-SafeguardDirectoryAccountPassword
- Invoke-SafeguardDirectoryAccountPasswordChange
- Remove-SafeguardDirectoryAccount
- Get-SafeguardUserGroup
- New-SafeguardUserGroup
- Remove-SafeguardUserGroup
- Edit-SafeguardUserGroup
- Get-SafeguardAssetGroup
- New-SafeguardAssetGroup
- Remove-SafeguardAssetGroup
- Edit-SafeguardAssetGroup
- Get-SafeguardAccountGroup
- New-SafeguardAccountGroup
- Remove-SafeguardAccountGroup
- Edit-SafeguardAccountGroup
- Get-SafeguardPolicyAsset
- Find-SafeguardPolicyAsset
- Get-SafeguardPolicyAccount
- Find-SafeguardPolicyAccount
- Get-SafeguardAccessPolicy
- Get-SafeguardAccessPolicyScopeItem
- Get-SafeguardAccessPolicyAccessRequestProperty
- Get-SafeguardAccessPolicySessionProperty
- Get-SafeguardEntitlement
- New-SafeguardEntitlement
- Remove-SafeguardEntitlement
- Get-SafeguardUserLinkedAccount
- Add-SafeguardUserLinkedAccount
- Remove-SafeguardUserLinkedAccount
- Get-SafeguardEvent
- Get-SafeguardEventName
- Get-SafeguardEventSubscription
- Find-SafeguardEventSubscription
- New-SafeguardEventSubscription
- Remove-SafeguardEventSubscription
- Edit-SafeguardEventSubscription
- Get-SafeguardA2aServiceStatus
- Enable-SafeguardA2aService
- Disable-SafeguardA2aService
- Get-SafeguardA2a
- New-SafeguardA2a
- Remove-SafeguardA2a
- Edit-SafeguardA2a
- Get-SafeguardA2aCredentialRetrievalInformation
- Get-SafeguardA2aCredentialRetrieval
- Add-SafeguardA2aCredentialRetrieval
- Remove-SafeguardA2aCredentialRetrieval
- Get-SafeguardA2aCredentialRetrievalIpRestriction
- Set-SafeguardA2aCredentialRetrievalIpRestriction
- Clear-SafeguardA2aCredentialRetrievalIpRestriction
- Reset-SafeguardA2aCredentialRetrievalApiKey
- Get-SafeguardA2aCredentialRetrievalApiKey
- Get-SafeguardA2aAccessRequestBroker
- Set-SafeguardA2aAccessRequestBroker
- Clear-SafeguardA2aAccessRequestBroker
- Get-SafeguardA2aAccessRequestBrokerIpRestriction
- Set-SafeguardA2aAccessRequestBrokerIpRestriction
- Clear-SafeguardA2aAccessRequestBrokerIpRestriction
- Reset-SafeguardA2aAccessRequestBrokerApiKey
- Get-SafeguardA2aAccessRequestBrokerApiKey
- Get-SafeguardA2aRetrievableAccounts
- Get-SafeguardA2aPassword
- Get-SafeguardA2aPrivateKey
- New-SafeguardA2aAccessRequest
- Invoke-SafeguardStarlingJoin
- Get-SafeguardStarlingSubscription
- New-SafeguardStarlingSubscription
- Remove-SafeguardStarlingSubscription
- Get-SafeguardStarlingJoinUrl
- Get-SafeguardStarlingSetting
- Set-SafeguardStarlingSetting
- Get-SafeguardAccessCertificationAll
- Get-SafeguardAccessCertificationAccount
- Get-SafeguardAccessCertificationGroup
- Get-SafeguardAccessCertificationEntitlement
- Get-SafeguardAccessCertificationIdentity
- Get-ADAccessCertificationIdentity
- Update-SafeguardAccessCertificationGroupFromAD
- Get-SafeguardReportAccountWithoutPassword
- Get-SafeguardReportDailyAccessRequest
- Get-SafeguardReportDailyPasswordChangeFail
- Get-SafeguardReportDailyPasswordChangeSuccess
- Get-SafeguardReportDailyPasswordCheckFail
- Get-SafeguardReportDailyPasswordCheckSuccess
- Get-SafeguardReportUserEntitlement
- Get-SafeguardReportUserGroupMembership
- Get-SafeguardReportAssetManagementConfiguration
- Get-SafeguardReportA2aEntitlement