Configure AD bridging

This topic describes how to configure PSM for SSH to integrate with Active Directory.

To learn about how AD bridging works, see AD bridging through PSM for SSH.

Perform the following steps to configure PSM for SSH to integrate with Active Directory:

  1. Configure the Vault

  2. Create a platform for user provisioning

  3. Add a target machine account

  4. Associate the target machine with a user provisioning account

  5. Confirm required permissions

  6. Create logon accounts for the user provisioning account

  7. Synchronize groups with Vault groups

  8. Verify SFTP on the target machine

  9. Set the default shell

  10. Manage users’ UID

  11. Customize AD Bridge scripts

  12. Customize user profiles

Configure the Vault

Configure the Vault to integrate with your enterprise Active Directory. For more information, see Configure transparent user management using LDAP.

Create a platform for user provisioning

Duplicate the Unix via SSH platform to create a new platform for user provisioning.

To create the platform:

  1. In the PVWA, click Administration > Platform Management.

  2. In the Target Platforms tab, select Unix via SSH, click the ellipsis button, and then click Duplicate.

  3. On the Duplicate platform dialog box, enter a platform name: Unix via SSH with Provisioning, and then click Create .

  4. Select the platform that you created, and then click Edit.

  5. In the left pane, open UI & Workflow > Properties > Required, and delete the value from the Username field. The field will no longer appear in the left pane.

  6. Open UI & Workflow > Linked Accounts, and delete the configured linked accounts.

  7. Open UI & Workflow >  Privileged Session Management, and do the following:

    • Set EnablePrivilegedSSO to No.

    • Make sure that UsePersonalPassword is set to No.

  8. Open Privileged Session Management , right-click SSH Proxy, and click Add User Provisioning.
  9. Open User Provisioning, and set Enable User Provisioning to Yes.

  1. Click Apply .

  2. Select the Unix via SSH with Provisioning platform and change its status to Active.

Add a target machine account

Create a target *nix account and associate it with the Unix via SSH with Provisioning platform. For details, see Add Accounts in V10 Interface.

 

To connect to remote machines on IPv6, specify the IPv6 address using the global format, as shown in the following example: 1000:1000:1000:1000:1000:1000:1000:0055

Associate the target machine with a user provisioning account

An additional privileged user account is required to create ad-hoc users on target machines. This account is associated with the target machine account, and is used to create users transparently.

To associate the target machine with a user provisioning account: 

  1. In the Account Details page of the target machine account, click Additional details and actions in classic interface, and then click the User Provisioning tab.

  2. In the User Provisioning tab, click Associate.

    The Associate Account window lists the frequently used accounts. If the account that you require does not appear in this list, search for the required account.

  3. Select the required account, and then click Associate.

    The selected account is linked to the target machine account and its details are listed in the User Provisioning tab.

     

    The user provisioning account can use password or SSH Key to authenticate to target systems.

Confirm required permissions

Before configuring PSM for SSH, make sure that the users used to configure PSM for SSH have the relevant permissions in the safes where the accounts required to access the target machine and the provisioning account are stored.

User

Machine

Permissions

PSM for SSH-ADBridge application user

On the provisioning account
  • List accounts
  • Retrieve accounts

End user

On the target machine account
  • List accounts
  • Use accounts

Users can be allocated permissions for entire safes or for specific accounts. For more information about both options and for details about configuring them, refer to Safes and Safe members, or Use Object Level Access Control in Safes.

Create logon accounts for the user provisioning account

A logon account can be used to enable the Provisioning account to log on to machines that do not permit direct logon  and create ad-hoc users. When a logon account is associated with a Provisioning account, it is used to log on to the remote machine and then elevates itself to the role of the provisioning user.

 

A logon account can be either a regular account or an SSH Key account. However, if a logon account is used, the provisioning account must be a password account.

For more information, refer to Connection Component Configuration.

Synchronize groups with Vault groups

During user provisioning, Vault users are added to all groups on the target machine that have corresponding groups in the Vault to which they belong. Corresponding groups in the Vault must have the same name as the group on the target machine, with ADB_ as a prefix. Groups that do not exist on the target machine will not be created.

For example, a user called David belongs to ADB_Group1 in the Vault. On the target machine there is a group called “Group1” to which David will be added when his user is provisioned. If “Group1” does not exist on the target machine, David’s user will be created but he will not be allocated to a corresponding group.

In the Vault, create user groups that correspond to the user groups in the Active Directory, with an ADB_ prefix. For more information about creating user groups in the Vault, refer to Manage groups.

Verify SFTP on the target machine

SFTP must be enabled on the remote target UNIX machine. It is usually enabled by default. This can be verified in the main sshd configuration file, /etc/ssh/sshd_config, on the remote target UNIX machine.

Set the default shell

When a user logs on to the target machine for the first time, their user is provisioned automatically with a predefined default shell.

To set the default shell:

  1. On the remote target UNIX machine, open the /etc/default/useradd file.
  2. Define the default shell that determines how new users will be provisioned.

Manage users’ UID

You can manage UIDs through Active Directory or through AD Bridge for all users who use AD Bridge to log on to remote UNIX machines.

  • To manage UIDs through Active Directory, set SyncUnixAttributes and ADBridgeManageUID to Yes.

    If a user does not have a UID in Active Directory, AD Bridge will assign a new UID to the user when the user connects for the first time through AD Bridge. If this user already has a UID on the target, AD Bridge will assign this existing UID to the user. The UID assigned by AD Bridge will be used in all subsequent connections by this user through AD Bridge.

  • To manage UIDs through AD Bridge, set SyncUnixAttributes to No and ADBridgeManageUID to Yes.

    AD Bridge will assign a new UID to the user when the user connects for the first time through AD Bridge. If this user already has a UID on the target, AD Bridge will assign this existing UID to the user. The UID assigned by AD Bridge will be used in all subsequent connections by this user through AD Bridge.

  • To let the target machine OS assign UIDs to provisioned users, set ADBridgeManageUID to No.
 

When assigning UIDs to users in the Active Directory, you must give each user a unique UID to avoid UID conflicts.

This is also important when working in an environment with multiple domains.

You can enable or disable UID management by AD Bridge.

1. Click ADMINISTRATION to display the System Configuration page, then click Options. The Web Access Options are displayed.
2. Select ADBridge Settings then, in the Properties list, set the following property:

This parameter determines whether the UID of provisioned users can be managed by AD Bridge.

■ Specify Yes to enable AD Bridge to manage UIDs for provisioned users. This is the default value.
■ Specify No to let the target machine OS assign UIDs to provisioned users.
3. Click Apply to apply the new configurations immediately,

or,

Click OK to save the new configurations and return to the System Configuration page.

You can determine whether to read users' UIDs from Active Directory.

1. Click ADMINISTRATION to display the System Configuration page, then click Options. The Web Access Options are displayed.
2. Select ADBridge Settings then, in the Properties list, set the following property:

This parameter determines whether to read users' UIDs from Active Directory.

■ Specify Yes to read users' UIDs from Active Directory.
■ Specify No to not read users' UIDs from Active Directory. This is the default value.
3. Click Apply to apply the new configurations immediately,

or,

Click OK to save the new configurations and return to the System Configuration page.

You can define a minimum number for the UIDs that AD Bridge will assign to users who do not get a UID from Active Directory. AD Bridge assigns UIDs to users when Ad Bridge is not configured to read UIDs from Active Directory or when the user does not have a UID in the Active Directory.

 

Ensure that the minimum UID number is greater than the range of UIDs that are used in your organization to avoid conflicts between generated UIDs and UIDs that are already assigned to users.
1. Click ADMINISTRATION to display the System Configuration page, then click Options. The Web Access Options are displayed.
2. Select ADBridge Settings then, in the Properties list, set the following property:

This parameter determines the minimum UID number that can be assigned to a user. Specify a number higher than 1000. The default value is 15000.

3. Click Apply to apply the new configurations immediately,

or,

Click OK to save the new configurations and return to the System Configuration page.

Customize AD Bridge scripts

The AD Bridge provisioning and deprovisioning scripts enable you to customize provisioning and deprovisioning processes according to your enterprise standards. You can customize scripts for existing platforms and you can also create new scripts for platforms that PAM - Self-Hosted does not store out of the box.

During installation, the following safes are created to store the provisioning and deprovisioning scripts:

All provisioning scripts that are supported out-of-the-box are stored in the Scripts folder of this safe, and are downloaded to the AD Bridge machine each time the psmpsrv service is restarted.

To retrieve these provisioning scripts during AD Bridge provisioning and deprovisioning, users require the following permissions in this safe:

■ List Files
■ Retrieve Files

A template provisioning script that can be used to customize provisioning scripts is stored in this safe. All customized scripts for specific device types must be stored in this safe.

To edit the provisioning and deprovisioning scripts, users require the following permissions in this safe:

■ List Files
■ Retrieve Files
■ Update Files

By default, Vault administrators have these permissions and can edit these scripts.

By default, users in the PSMP_ADB_AppUsers group have these permissions for both safes and can use all the provisioning scripts.

The following diagram shows the process of customizing provisioning and deprovisioning steps:

In the PrivateArk Client:

  1. Copy a built-in script to use as a template:

    1. Log onto the PrivateArk Client with an administrative user.

    2. Open the PSMPADBridgeCustom safe and, in the Root folder, right-click the Prov-Sample script.

    3. From the pop-up menu, select Retrieve and Save As, then save the script in the same safe with a unique name that describes its purpose.

  2. Customize the copied script:

    1. Open the script and customize it, using the script functions listed in The Custom Provisioning Script.

    2. Save the customized script and return it to the safe.

In the PVWA:

  1. Customize the AD Bridge platform to support the device type for the customized script:

    1. Log onto the PVWA as an administrator user.

    2. Click ADMINISTRATION to display the System Configuration page, then click Platform Management to display a list of supported target account platforms.

    3. Select the platform that you use to connect to the remote machine, eg, Unix via SSH – ADBridge, then click Edit; the platform settings page for this platform appears.

    4. Expand UI & Workflows, then expand Privileged Session Management, and then SSH Proxy.

    5. Expand User Provisioning, then right click Device types and, from the drop-down menu, select Add Device type; a new device type is added to the list of existing supported device types.

    6. In the Properties list of the new device, specify the following:

      Property

      Description

      Display name

      The unique name of the device type. This property is mandatory.

      Device identifier

      The name of the device that is returned from the 'uname' UNIX command. This property is mandatory.

      Provisioning script

      The name of the provisioning script file for the target device type. This property is mandatory.

      Additional files

      The names of additional files needed for provisioning. Separate multiple file names with a comma. The property is optional.

    7. Click Apply to apply the new configurations immediately,

      or,

      Click OK to save the new configurations and return to the System Configuration page.

  2. Associate the target machine account with the customized ADBridge platform. You can either add a new account or associate an existing account.

    1. Display the Account Details page for the account to link to a reconciliation account.

    2. On the toolbar, click Edit; the Edit Account page appears.

    3. In Device Type, specify the type of device on which this account will be used.

    4. In Platform Name, specify the name of the platform that you customized in the previous step.

    5. Click Save; the PVWA associates the account with the customized platform.

  3. Restart the AD Bridge service, using the following command:

    • RHEL7, SUSE11, SUSE12

        
      service psmpsrv restart psmpadb

    • RHEL8

        
      systemctl restart psmpsrv-psmpadbserver

You can now use this account to log onto the target machine, and the associated platform will automatically use the customized provisioning and/or deprovisioning scripts.

The Custom Provisioning Script

Function Description Input
retrieveUID Retrieves the uid of the given username and returns 0. $1 - username
retrieveUsername Retrieves the name of the user who has the specified uid and returns 0. $1 - uid
addUser Creates a new user on the target machine with the specified username and uid, and returns 0. $1 - username
$2 - uid (not mandatory)
removeUser Deletes the user from the target machine and returns 0. $1 - username
resetUserPassword Resets the user’s password to the password specified in the data file and returns 0. $1 – datafile path (format "username:password")
changeUID Resets the uid of the user to the specified uid and returns 0. $1 - username
$2 - uid
retrieveHomeFolder Retrieves the home folder of the specified user and returns 0. $1 - username
retrieveUserGroups Retrieves a list of groups of which the specified user is a member, separated by a comma, and returns 0. $1 - username
addUserToGroup Adds the specified user to the specified group and returns 0. $1 - username
$2 - group name
removeUserFromGroup Removes the  specified user from the  specified group and returns 0. $1 - username
$2 - group name
copyFile Copies the specified source file to the specified destination file path and returns 0. $1 - source file
$2 - destination file path
removeFile Removes the specified file or folder and returns 0. $1 - file or folder path
changeFileOwner Changes the owner on the given file or folder (recursively) to the  specified user and returns 0. $1 - username
$2 - file or folder path
addLineToFile Appends the specified line at the end of the specified file and returns 0. $1 - file path
$2 - line to add
removeLineFromFile Removes the specified line from the specified file and returns 0. $1 - file path
$2 - line to remove

Customize user profiles

You can customize user profiles for users who are automatically provisioned by PSM for SSH-AD Bridge. This enables you to assign a single shell configuration file to customize the user when it is created, such as user profile attributes, environment variables, etc.

You create your own profile configuration files and store them in the PSMPADBUserProfile safe, which is configured for Object Level Access Control. When the PSM for SSH-ADBridge provisions users, it checks this safe for a profile configuration file that is relevant to the user being provisioned and, if it finds one, it provisions the user with the customizations defined in the file.

To customize user profile scripts, users require the following permissions in the PSMPADBUserProfile safe:

■ List Files
■ Rename Files
■ Retrieve Files
■ Delete Files
■ Create Files
■ View Owners
■ Update Files
■ Manage safe Owners
1. Log onto the PrivateArk Client with an administrative user.
2. Open the PSMPADBUserProfile safe, and upload the profile configuration file to the safe.
3. Add the user who will be provisioned on a remote machine using this customized profile script as a safe Owner, without granting them any authorizations.

4. Right-click the profile script that you previously uploaded to the safe and, from the drop-down menu, select Properties; the file’s Properties window appears.
5. In the Security tab, click Add; a list of safe Owners who can be granted retrieve authorization for the profile script appears.

6. Select the user who will be provisioned on a remote machine using this customized profile script, then click OK; the selected user is added to the list of safe owners who can retrieve the profile script in the Security tab.

7. Click OK to close the File Properties window.