PowerShell commands

On this page
Contribute

This topic is about all authentication commands and handles for PSHubContext.

The Devolutions.PowerShell module needs to be installed to use these commands.

Proper permissions are also required to perform some of these commands. Please refer to Application Users.

PSHubContext is an object that specifies your authentication information. You will need a valid PSHubContext to connect to your Devolutions Hub Business. You can have many PSHubContext connected in your PowerShell session, but only one is used when you use Devolutions Hub cmdlets.

In this object, you have the following:

  • Name: Name of the application user
  • URL: Devolutions Hub Business URL
  • Application secret: Application secret given after the application user creation
  • Application key: Application key given after the application user creation
  • To check all available commands:
Get-Command-Module <ModuleName>
  • To check all potential arguments and parameters set for a command:
Show-Command <CommandName>

Connection

Connect-HubAccount

Arguments

  • PSHubContext

or

  • Url
  • ApplicationKey
  • ApplicationSecre

Description

If PSHubContext is provided, tries to connect to Devolutions Hub with it.

or

If PSHubContext is not provided, creates a PSHubContext with information received and tries to connect to Devolutions Hub afterward.

Code example

$PSHubContext = [Devolutions.Hub.PowerShell.Entities.PowerShell.PSHubContext]@{ApplicationKey=“24526a88-7f18-4356-95bd-11690f7bc59b;468ce2d5-ea4b-42ff-bc02-d93c71b4e554“; ApplicationSecret=“U4nmdOjqPAcL0GfbvNC2u8e0FCZjhEJFTnn6YHpIZDY=“; Url=“https<area>://<YourPasswordHubUrl>.devolutions.app“}

Connect-HubAccount -PSHubContext $PSHubContext

or

Connect-HubAccount -Url https<area>://<YourPasswordHubUrl>.devolutions.app -ApplicationKey “24526a88-7f18-4356-95bd-11690f7bc59b;468ce2d5-ea4b-42ff-bc02-d93c71b4e554“ -ApplicationSecret U4nmdOjqPAcL0GfbvNC2u8e0FCZjhEJFTnn6YHpIZDY=

Disconnect-HubAccount

Arguments

  • ApplicationKey

or

  • All

Description

If ApplicationKey is provided, disconnects and removes PSHubContext from the PowerShell session.

or

If All is provided, disconnects and removes all PSHubContext from the PowerShell session.

Context

Get-HubContext

Arguments

  • ListAvailable

Description

If ListAvailable is provided, lists all PSHubContext set the in PowerShell session.

or

If ListAvailable is not provided, retrieves the current PSHubContext which will be used for all other Devolutions Hub commands.

Set-HubContext

Arguments

  • PSHubContext

Description

Sets the current PSHubContext to the one provided.

Select-HubContext

Arguments

  • ApplicationKey

Description

Selects another PSHubContext to change the current PSHubContext which will be used for all Devolutions Hub commands.

Save-HubContext

Arguments

  • PSHubContext

  • Path

  • Force

    • SecurePassword

    or

    • Password

Description

Saves the current PSHubContext to a .json file at the received path.

If PSHubContext is provided, saves it to a .json file.

If Force is provided, overwrites the file if the path already exists.

If SecurePassword is provided, prompts the user to enter a password to encrypt the .json file.

or

If Password is provided, encrypts the .json file with the received password.

Code example

Save a standard PSHubContext.

Save-HubContext -Path “C:\PATH\TO\YOUR\FILE\file.json“

If you want to securely save a PSHubContext with a password, you can do it in 2 ways:

With a password passed by arguments.

Save-HubContext -Path “C:\PATH\TO\YOUR\FILE\file.json“ -Password “password“

or

With a SecurePassword argument that will prompt the secure password input.

Save-HubContext -Path “C:\PATH\TO\YOUR\FILE\file.json“ -SecurePassword

Password: [INSERT YOUR PASSWORD]

Import-HubContext

Arguments

  • Path
  • SecurePassword
  • Password

Description

Imports a PSHubContext from a .json file at the received path.

If SecurePassword is provided, prompts the user to enter a password to decrypt the .json file.

If Password is provided, decrypts the .json file with the received password.

Code example

Import a standard PSHubContext.

Import-HubContext -Path “C:\PATH\TO\YOUR\FILE\file.json“

If you want to import a file protected by a password, you can do it in 2 ways:

With a password passed by arguments.

Import-HubContext -Path “C:\PATH\TO\YOUR\FILE\file.json“ -Password “password“

or

With a SecurePassword argument that will prompt the secure password input.

Import-HubContext -Path “C:\PATH\TO\YOUR\FILE\file.json“ -SecurePassword

Password: [INSERT YOUR PASSWORD]

System Settings

This section is about commands used to handle system settings.

Get-HubSystemSettings

Description

Gets the PSSystemSettings object.

Set-HubSystemSettings

Arguments

  • PSSystemSettings

Description

Sets the provided system settings to Devolutions Hub.

Code example

Change system settings information and save these modifications.

$psSystemSettings = Get-HubSystemSettings

$psSystemSettings.ForceTwoFactorAuthentication = $true

$psSystemSettings.ExtendedSessionLifespan = “SevenDays“

$psSystemSettings.SystemPermissions.Users[“33a0253c-2bbf-43a0-9051-fb6adcb5ac7e“].ManageUsersGroups = $false;

Set-HubSystemSettings -$psSystemSettings $psSystemSettings

New-HubSystemVaultPermission

Arguments

  • UserId
  • PSVaultRole | SystemVaultPermission

or

  • GroupId
  • PSVaultRole | SystemVaultPermission

Description

Adds the provided system vault permission to system settings. If a user or group already exists, the permission will be overwritten.

If UserId is provided, sets a predefined role or a custom system vault permission to this user.

or

If GroupId is provided, sets a predefined role or a custom system vault permission to this group.

Code example

$newSystemVaultPermission = [Devolutions.Hub.Clients.VaultPermission]@{ AddEntries = $true }

New-HubSystemVaultPermission -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4 -SystemVaultPermission $newSystemVaultPermission

Remove-HubSystemVaultPermission

Arguments

  • UserId

or

  • GroupId

Description

If UserId is provided, removes this user's system vault permission from system settings.

or

If GroupId is provided, removes this group's system vault permission from system settings.

Get-HubSystemVaultPermission

Arguments

  • UserId

or

  • GroupId

Description

If UserId is provided, retrieves this user's system permission from system settings.

or

If GroupId is provided, retrieves this group's system permission from system settings.

Code example

Get a systemVaultPermission from a user to create a new systemVaultPermission with the same permissions (values).

$systemVaultPermissionFromUserA = Get-HubSystemVaultPermission -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4

New-HubSystemVaultPermission -UserId 152c06cf-cce6-4116-97e1-34aadeab9984 -SystemVaultPermission $systemVaultPermissionFromUserA

Set-HubSystemVaultPermission

Arguments

  • UserId
  • PSVaultRole | SystemVaultPermissions

or

  • GroupId
  • PSVaultRole | SystemVaultPermissions

Description

Sets a provided system vault permission.

If UserId is provided, sets a predefined PSVaultRole or a custom system vault permission to this user.

or

If GroupId is provided, sets a predefined PSVaultRole or a custom system vault permission to this group.

Code example

$systemVaultPermission = Get-HubSystemVaultPermission -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4

$systemVaultPermission.ExecuteEntries = $false;

Set-HubSystemVaultPermission -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4 -SystemVaultPermission $systemVaultPermission

New-HubSystemPermission

Arguments

  • SystemPermission
    • UserId
      or
    • GroupId

Description

Adds the provided system permission to system settings

If UserId is provided, sets the system permission to this user.

or

If GroupId is provided, sets the system permission to this group.

Code example

$newSystemPermission = [Devolutions.Hub.Clients.SystemPermission]@{ AddVaults = $true }

New-HubSystemPermission -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4 -SystemPermission $newSystemPermission

Remove-HubSystemPermission

Arguments

  • UserId

or

  • GroupId

Description

If UserId is provided, removes this user's system permission from system settings.

or

If GroupId is provided, removes this group's system permission from system settings.

Get-HubSystemPermission

Arguments

  • UserId

or

  • GroupId

Description

If UserId is provided, retrieves this user's system permission from system settings.

or

If GroupId is provided, retrieves this group's system permission from system settings.

Code example

Get a systemPermission from a user to create a new systemPermission with the same permissions (values).

$systemPermissionFromUserA = Get-HubSystemPermission -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4

New-HubSystemPermission -UserId 152c06cf-cce6-4116-97e1-34aadeab9984 -SystemPermission $systemPermissionFromUserA

Set-HubSystemPermission

Arguments

  • UserId
  • SystemPermission

or

  • GroupId
  • SystemPermission

Description

Sets a provided system permission.

If UserId is provided, sets the system permission to this user.

or

If GroupId is provided, sets the system permission to this group.

Code example

$systemPermission = Get-HubSystemPermission -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4

$systemPermission.ForcePromptLogin = $false;

Set-HubSystemPermission -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4 -SystemPermission $systemPermission

Devolutions Gateway

This section is about commands to handle Devolutions Gateway.

New-HubGateway

Arguments

  • PsDecryptedGateway

Description

Adds a new Devolutions Gateway to Devolutions Hub.

Code example

$newDevolutionsGateway = [Devolutions.Hub.CryptoUtils.Models.PSDecryptedGateway]@{ PsMetadata = [Devolutions.Hub.CryptoUtils.Models.PSGatewayMetadata]@{ Name =  'Test Gateway From PS ' }}

New-HubGateway -PSDecryptedGateway $newDevolutionsGateway

Remove-HubGateway

Arguments

  • GatewayId

Description

Removes the Devolutions Gateway with the provided ID.

Set-HubGateway

Arguments

  • PsDecryptedGateway

Description

Sets the provided Devolutions Gateway.

Code example

$psDecrpytedGateway = Get-HubGateway -GatewayId 4c6fb2dc-f7ba-4089-8bc2-b46b3bdcd1d0

$psDecrpytedGateway.PSMetadata.Name = “New Name From PS“

Set-HubGateway -PSDecryptedGateway $psDecrpytedGateway

Get-HubGateway

Arguments

  • GatewayId

Description

Retrieves the Devolutions Gateway with the provided ID.

New-HubGatewaySettings

Description

Creates new Devolutions Gateway settings. If settings already exist, they will be overwritten.

Set-HubGatewaySettings

Description

Sets the provided Devolutions Gateway settings.

Get-HubGatewaySettings

Description

Retrieves the Devolutions Gateway settings.

Vaults

This section is about commands to handle vaults.

New-HubVault

Arguments

  • VaultName
  • VaultDescription

Description

Adds a new vault.

Code example

Have the permission to create vaults and put a name.

Remove-HubVault

Arguments

  • VaultId

Description

Removes this vault from Devolutions Hub.

Get-HubVault

Arguments

  • VaultId

Description

If VaultId is provided, retrieves the vault by ID.

If VaultId is not provided, retrieves all vaults you have access to.

Set-HubVault

Arguments

  • VaultId
  • PSVault

Description

Sets the provided vault to the mentioned VaultId.

Code example

Change information about a vault and save these modifications.

$psVault = Get-HubVault -VaultId 3beb6536-95d2-405b-bc69-70751cc55ca1

$psVault.Name = “New RDP Name“;

$psVault.VaultPermissions.Users[“33a0253c-2bbf-43a0-9051-fb6adcb5ac7e“].ViewPassword = $false;

Set-HubVault -VaultId 3beb6536-95d2-405b-bc69-70751cc55ca1 -PSVault $psVault

New-HubVaultPermission

Arguments

  • VaultID

    • UserId
    • VaultRoleId | VaultPermission

    or

    • GroupId
    • VaultRoleId | VaultPermission

Description

Adds the provided vault permission to a specific vault. If a user or group already exists, the permission will be overwritten. If UserId is provided, sets a predefined PSVaultRole or a custom vault permission to this user. If GroupId is provided, sets a predefined PSVaultRole or a custom vault permission to this group.

Code example

With a custom vaultPermission:

$newVaultPermission = [Devolutions.Hub.Clients.VaultPermission]@{ AddEntries = $true }

New-HubVaultPermission -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4 -VaultPermission $newVaultPermission

or

With a predefined role:

New-HubVaultPermission -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4 -VaultRoleId fde84e48-4662-493b-9de3-e05c708af060

Remove-HubVaultPermission

Arguments

  • VaultID

    • UserId

    or

    • GroupId

Description

If UserId is provided, removes this user's vault permission from the specific vault.

If GroupId is provided, removes this group's vault permission from the specific vault.

Get-HubVaultPermission

Arguments

  • VaultID

    • UserId

    or

    • GroupId

Description

If UserId is provided, retrieves this user's vault permission from the specific vault. If GroupId is provided, retrieves this group's vault permission from the specific vault.

Code example

Get a vaultPermission from a user to create a new vaultPermission with the same permissions (values).

$vaultPermissionFromUserA = Get-HubVaultPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4

New-HubVaultPermission -UserId 152c06cf-cce6-4116-97e1-34aadeab9984 -VaultPermission $vaultPermissionFromUserA

Set-HubVaultPermission

Arguments

  • VaultID

    • UserId
    • VaultRoleId | VaultPermission

    or

    • GroupId
    • VaultRoleId | VaultPermission

Description

Sets a provided vault permission to a specific vault. If UserId is provided, sets a predefined role or a custom vault permission to this user. If GroupId is provided, sets a predefined role or a custom vault permission to this group.

Code example

With a custom vaultPermission:

$vaultPermission = Get-HubVaultPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -UserId 152c06cf-cce6-4116-97e1-34aadeab9984

$vaultPermission.ExecuteEntries = $false;

Set-HubVaultPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -UserId 152c06cf-cce6-4116-97e1-34aadeab9984 -VaultPermission $vaultPermission

or

With a predefined role:

$vaultRole = Get-HubVaultRole -RoleId 1dd2321d-ae0d-41d9-bd2a-ec71cce5b13c

Set-HubVaultPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -GroupId 339d1c22-c01b-47ff-b812-74e34f23991f -PSVaultRole $vaultRole

Get-HubVaultRole

Arguments

  • RoleId

Description

If RoleId is provided, retrieves the vault role by ID.

If RoleId is not provided, retrieves all vault roles.

Users

This section is about commands to handle users.

New-HubUser

Arguments

  • UserEmail
  • UserLocale
  • IsTemporaryPasswordSendByEmail

Description

Adds a new Devolutions user or invites an existing Devolutions user.

If IsTemporaryPasswordSendByEmail is provided, the temporary password for the new Devolutions user will be sent by email. Otherwise, the temporary password is returned.

New-HubOrganizationUser

Arguments

  • Email
  • AllowOfflineInRDM
  • UserSendMessageConfiguration

or

  • PSInvitation

Description

Invites a user from a Devolutions Account Organization set in your hub.

  • If Email, AllowOfflineInRDM and UserSendMessageConfiguration are provided. A single email will be sent.
  • If PSInvitation is provided, you can manually set more than one email and assign groups. This command will only work if Enable SSO with Devolutions Account Organization has been enabled in your hub and a valid Devolutions Account Organization has been selected.

Code example

Add with a PSInvitation.

$psInvitation = [Devolutions.Hub.CryptoUtils.Models.PSInvitation]@{AllowOfflineInRDM = $true; UserSendMessageConfiguration = [Devolutions.Hub.Clients.UserSendMessagePermission]::MessagesWithEntries; Groups = @(“1f017956-1d36-4787-acaa-22b16c73cce5“); Emails = @(“bob@windjammer.co“);}```
```powershell
New-HubOrganizationUser -PSInvitation $psInvitation

Remove-HubUser

Arguments

  • UserId

Description

Removes this user from Devolutions Hub.

Get-HubUser

Arguments

  • UserId

Description

If UserId is provided, retrieves the user by ID.

If UserId is not provided, retrieves all users.

Set-HubUser

Arguments

  • UserId
  • PSUser

Description

Sets the provided user to the mentioned user ID.

Code example

Disable a user and save.

$psUser = Get-HubUser -UserId 321ec891-5674-4be0-aaf1-0c11a62eaf20

$psUser.IsEnabled = $false

Set-HubVault -VaultId 3beb6536-95d2-405b-bc69-70751cc55ca1 -PSVault $psUser

Groups

This section is about commands to handle groups.

New-HubGroup

Arguments

  • GroupName
  • GroupUserIds

Description

Adds a new group to the hub with users, if provided.

Remove-HubGroup

Arguments

  • GroupId

Description

Removes this group from the hub.

Get-HubGroup

Arguments

  • GroupId

Description

If GroupId is provided, retrieves the group by ID.

If GroupId is not provided, retrieves all groups.

Set-HubGroup

Arguments

  • GroupId
  • PSGroup

Description

Sets the provided group to the received group ID.

Code example

Change the name, add a user, and save the group.

$psGroup = Get-HubGroup -GroupId d41b9475-e00a-4f5b-8f25-4d539639dedd

$psGroup.Name = “New Group Name“

$psGroup.UserIds.Add(“321ec891-5674-4be0-aaf1-0c11a62eaf20“)

Set-HubGroup -GroupId d41b9475-e00a-4f5b-8f25-4d539639dedd -$psGroup $psGroup

Add-HubGroupUser

Arguments

  • GroupId
  • UserIds

Description

Adds one or more users to a specific group.

Remove-HubGroupUser

Arguments

  • GroupId
  • UserIds

Description

Removes one or more users from a specific group.

Entries

This section is about commands to handle entries.

New-HubEntry

Arguments

  • VaultId
  • PSDecryptedEntry
  • DocumentPath

Description

Adds a new entry to a specific hub vault with the provided PSDecryptedEntry entry.

Code example

$t = [Devolutions.Hub.CryptoUtils.Models.PSDecryptedEntry]@{ PsMetadata = [Devolutions.Hub.CryptoUtils.Models.PSEntryMetadata]@{ Name = “Test Cred“; ParentId = “9df41856-125a-490a-8589-93afc3059924“; ConnectionType = [Devolutions.Generated.Enums.ConnectionType]::Credential }; Connection = [Devolutions.Generated.Models.Connection]@{ Credentials = [Devolutions.Generated.Models.CredentialsConnection]@{ CredentialType = [Devolutions.Generated.Enums.CredentialResolverConnectionType]::Default; Password = “passworddepowershell“ } } }

New-HubEntry -VaultId d334f44c-fb84-4559-b576-e1e8b68baf65 -Connection $ff

Remove-HubEntry

Arguments

  • VaultId
  • EntryId

Description

Removes this entry from a specific vault.

Get-HubEntry

Arguments

  • VaultId
  • EntryId

Description

If EntryId is provided, retrieves this entry from a specific vault. If EntryId is not provided, retrieves all entries from a specific vault. Entry(ies) will have sensitive passwords if you have the permission.

Set-HubEntry

Arguments

  • VaultId
  • EntryId
  • PSDecryptedEntry

Description

Sets the provided PSDecryptedEntry to the mentioned vault and entry.

Code example

Change information about an entry and save these modifications.

$decryptedEntry = Get-HubEntry -VaultId 3beb6536-95d2-405b-bc69-70751cc55ca1 -EntryId eb3b079e-b763-4657-bfac-ec83998015c1

$decryptedEntry.PsMetadata.Name = “New RDP Name“;

$decryptedEntry.Connection.RDP.Password = “new_password“;

Set-HubEntry -VaultId 3beb6536-95d2-405b-bc69-70751cc55ca1 -EntryId eb3b079e-b763-4657-bfac-ec83998015c1 -PSDecryptedEntry $decryptedEntry

New-HubEntryPermission

Arguments

  • VaultId

  • EntryId

    • UserId
    • PSEntryRole | EntryPermission

    or

    • GroupId
    • PSEntryRole | EntryPermission

Description

Adds a provided entry permission to a specific entry. If a user or group already exists, the permission will be overwritten.

If UserId is provided, sets a predefined role or a custom entry permission to this user.

or

If GroupId is provided, sets a predefined role or a custom entry permission to this group.

Code example

With a custom entryPermission:

$newEntryPermission = [Devolutions.Hub.Clients.EntryPermission]@{ EditEntries = $true }

New-HubEntryPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -EntryId cf73b4ea-c1cd-4f53-9b53-f9277a108c56 -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4 -EntryPermission $newEntryPermission

With a predefined role:

$entryRole = Get-HubEntryRole -RoleId 851f86f6-fe3b-4325-9b22-08c3b797e10c

New-HubEntryPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -EntryId cf73b4ea-c1cd-4f53-9b53-f9277a108c56 -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4 -PSEntryRole $entryRole

Remove-HubEntryPermission

Arguments

  • VaultId

  • EntryId

    • UserId

    or

    • GroupId

Description

If UserId is provided, removes this user's entry permission from a specific entry.

or

If GroupId is provided, removes this group's entry permission from a specific entry.

Get-HubEntryPermission

Arguments

  • VaultId

  • EntryId

    • UserId

    or

    • GroupId

Description

If UserId is provided, retrieves this user's entry permission from a specific entry.

or

If GroupId is provided, retrieves this group's entry permission from a specific entry.

Code example

Get an entryPermission from a user to create a new entryPermission with the same permissions (values).

$entryPermissionFromUserA = Get-HubEntryPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -EntryId cf73b4ea-c1cd-4f53-9b53-f9277a108c56 -UserId 2d9221d6-3cbe-4161-b3aa-387f18a7f8c4

New-HubEntryPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -EntryId cf73b4ea-c1cd-4f53-9b53-f9277a108c56 -UserId 152c06cf-cce6-4116-97e1-34aadeab9984 -EntryPermission $entryPermissionFromUserA

Set-HubEntryPermission

Arguments

  • VaultId

  • EntryId

    • UserId
    • PSEntryRole | EntryPermission

    or

    • GroupId
    • PSEntryRole | EntryPermission

Description

Sets a provided entry permission to a specific entry.

If UserId is provided, sets a predefined role or a custom entry permission to this user.

or

If GroupId is provided, sets a predefined role or a custom entry permission to this group.

Code example

With a custom entryPermission:

$entryPermission = Get-HubEntryPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -EntryId cf73b4ea-c1cd-4f53-9b53-f9277a108c56 -UserId 152c06cf-cce6-4116-97e1-34aadeab9984

$entryPermission.ViewPassword = $false;

Set-HubEntryPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -EntryId cf73b4ea-c1cd-4f53-9b53-f9277a108c56 -UserId 152c06cf-cce6-4116-97e1-34aadeab9984 -EntryPermission $entryPermission

With a predefined role:

$entryRole = Get-HubEntryRole -RoleId 851f86f6-fe3b-4325-9b22-08c3b797e10c

Set-HubEntryPermission -VaultId 12ac66eb-7caa-4866-b5fd-5bd59c7f657e -EntryId cf73b4ea-c1cd-4f53-9b53-f9277a108c56 -GroupId 339d1c22-c01b-47ff-b812-74e34f23991f -PSEntryRole $entryRole

Get-HubEntryRole

Arguments

  • RoleId

Description

If RoleID is provided, retrieves the entry role by ID.

If RoleID is not provided, retrieves all entry roles.

Give us Feedback