Skip to main content

PowerShell Script

Connector name

agtps

Connector type

Executable with PowerShell script

Type (UI field value)

PowerShell Script

Connector status / support

Bravura Security-Verified

This connector has been tested and is fully supported by Bravura Security.

The following Bravura Security Fabric operations are supported by the connector for PowerShell scripts (agtps):

  • get server information

  • user verify password

  • administrator reset password

  • enable account

  • disable account

  • check account enabled

  • lock account

  • unlock account

  • check account lock

  • expire account

  • check account expiry

  • unexpire account

  • create account

  • delete account

  • add user to group

  • delete user from group

  • add group to group

  • remove group from group

  • create group

  • delete group

  • move contexts

  • rename account

  • update attributes

  • run command

  • list account attributes

  • List:

    • accounts

    • attributes

    • groups

    • members

    • computer objects

    • service accounts

    • resource

  • create resource

  • delete resource

  • update resource

  • move resource

    The network resource operations must be added by a request rewrite plugin.

For a full list and explanation of each connector operation, see Connector operations.

Preparation

Installing required software

Before targeting an application that uses the PowerShell script, ensure that the following are installed on all Bravura Security Fabric servers:

  • PowerShell

  • Any required PowerShell modules

  • Any required PowerShell snap-ins

Writing a script

Account management operations are implemented using a PowerShell script to provide details for interaction between Bravura Security Fabric and the target application. You must write this script and include it in the <Program Files path>\Bravura Security\Bravura Security Fabric\<instance>\ script\ directory on the Bravura Security Fabric server.

PowerShell's execution policy is a safety feature that controls the conditions under which PowerShell loads configuration files and runs scripts. Ensure that your PowerShell execution policy allows you to run your PowerShell scripts for their digital signature state. For more information see https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.2

Some sample scripts are provided in the samples directory. If you cannot find the sample file, try re-running setup to modify your installation. Sample files are automatically installed with complete (typical) installations. You can select them in custom installations.

Caution

Any sample script should be modified to fit your environment and prevent security exploits.

Configuring a target system administrator

In some cases, Bravura Security Fabric uses a designated account (for example, psadmin) on the PowerShell script target system to perform operations.

Ensure that the designated account can log into the application from the Bravura Security Fabric server, and that the account has the necessary privileges to set passwords and manage accounts.

Ensure that you set and note the account’s password. You will be required to enter the login ID and password when you add the target system to Bravura Security Fabric .

Otherwise, when a designated account is not required, the administrator credentials can be left blank.

Targeting an application

For each application that uses a PowerShell script to manage accounts, add a target (Manage the system > Resources > Target systems):

  • The Type is PowerShell Script.

  • The Address in Bravura Security Fabric uses the following settings:

    Script file The name of the PowerShell script file you created earlier . Ensure that the script is located in the <Program Files path>\Bravura Security\Bravura Security Fabric\<instance>\ script\ directory.

    Other settings Enter additional data to be passed into the script in KVGroup format; for example:

    {server=MYSRV;}

    Modules to load Module name; for example

    {psremoteregistry;}

    Snapins to load The name of PowerShell snap-ins; for example

    {Microsoft.Exchange.Management.PowerShell.E2010;}

    Note

    To load multiple modules or PowerShell snap-ins, select List from the drop-down list box, and use More button to add additional input box(es) for each module or snap-in specified.

    There is an option to include all modules or snap-ins in a file if multiple modules or snap-ins need to load. To use a file, select File option from the drop-down list and specify a file name in the field. Ensure the file is located in the <Program Files path>\Bravura Security\Bravura Security Fabric\<instance>\ script\ directory.

    UseSystemPolicy When true, the connector is going to use the execution policy that is already set in the system; so if it's set as Signed, the specified script file must be a signed script. When false, the connector is going to try to change the policy into unrestricted when running and then try to recover it after run.

    The address is entered in KVGroup format:

    {script=agtps-simple.ps1;settings={server=MYSRV;};modules={psremoteregistry;};snapins={Microsoft.Exchange.Management.PowerShell.E2010;};UseSystemPolicy=true;}

  • The Administrator ID and Password are the login ID and password for the target system administrator you configured in configured earlier . If the target does not require administrative credentials, the Administrator ID and Password can be left blank.

The full list of target system parameters is explained in Target System Options.

Note

You can extend the address wizard by adding address line elements using the addressattrs function. See the sample PowerShell scripts for details. This is useful when creating a scripted target system with a scripted platform definition file.

Creating a template account

Consult the documentation included with your specific application to learn how to create an account to use as a template in Bravura Identity . You can then add account attributes to determine how new accounts should be created based on the template account’s parameters.

Bravura Security Fabric still requires a template account, even though attributes may or may not be copied from the template account, for example, if the configured action for all account attributes is Set.

Creating account attributes

The attributes that define accounts are unique to specific applications; you must therefore create your own set of account attributes. You can view the complete list of attributes that Bravura Security Fabric can manage, including native and pseudo-attributes, using in the Manage the system (PSA) module account attributes menu. See Account attributes for more information.

Managing groups

If group management functions are supported by your application, you can configure Bravura Security Fabric’s workflow engine to manage group membership on your targets. You can also map profile attributes to group attributes on the target so that users can select groups when making a request; however, this method is currently incompatible with group management through Bravura Security Fabric ’s workflow configuration. Changes made in one method are not updated in the other.

For more information about account attributes and managed groups, see Groups.

Listing computer objects

In order for scripted connectors to write proper computer object list files for the Bravura Security Fabric server to load, the output file must be properly formatted.

For Bravura Security Fabric 12.0.0 and later, the output is written in SQLite table format to the <target id>.db file in <instance>\psconfig\ and must include the following:

Table 1. agtps discobj table output for computer objects

stableid

type

longid

shortid

displayid

sd

<GUID>

COMP

<GUID>

<computer name>

<computer name>



Table 2. agtps disattr table output for computer objects

stableid

type

attrkey

attrval

seqno

<GUID>

COMP

@disabled

0

0

<GUID>

COMP

@deleted

0

0

<GUID>

COMP

ip

<ip address>

0

<GUID>

COMP

ip

<ip address>

1

<GUID>

COMP

business_unit

<business name>

0

<GUID>

COMP

dNSHostName

<full dns name>

0

<GUID>

COMP

location

<location>

0

<GUID>

COMP

os

<os name>

0



See agtps-*.ps1 sample scripts in the samples\* directory for how listing should be implemented.

Listing iis, dcom, com+, scm, task, and custom accounts

When listing discovered account objects , agtps writes output to in the <instance>\psconfig\ directory

For Bravura Security Fabric 12.0.0 or later, the output must be in SQLite table format. It is written to the <target id>.db file and must include the following:

Table 3. agtps discobj table output for account objects

stableid

type

longid

shortid

displayid

sd

<GUID>

COMP

<GUID>

<computer name>

<computer name>

SID of user

type

SID of user

<description>

<description>



Table 4. agtps discobjattr table output for account objects

stableid

type

attrkey

attrval

seqno

SID of user

type

sid

<SID of user>

0

SID of user

type

domain

<Domain ID>

0

SID of user

type

islocal

<local account 1|0>

0

SID of user

type

ApplicationName

<Scheduled task’s binary>

0

SID of user

type

DisplayName

<Description of object>

0

SID of user

type

Comment <Comment of object>

0



Table 5. agtps discobjrel table output for account objects

parent_stableid

parent_type

reltype

child_stableid

child_type

child_name

child_sd

SID of user

parent_type

SUB

<Full user ID> eg, Domain>\<account ID>

ACCT

<child_name>

<child_sd>



See agtps-*.ps1 sample scripts in the samples\* directory for how listing should be implemented.

In this section: