PIAM Admin Guide

Once you have successfully logged in:

• You will be taken to either the CIPAM home screen, where all available connections are listed,

• or directly to a connection, if you only have access to one connection.

  The home screen contains a list of all connections you have access to, along with thumbnails of any recently used or active connection.

Managing Sessions in CIPAM

1. Click Active Sessions to navigate the session management screen. The session management screen displays all active sessions and allows system administrators to kill them as required.

2. When a user accesses a particular remote desktop connection, a unique session is created and it appears in the list of active sessions in the Session Management screen. Each active session is displayed in a sortable table, showing the corresponding user’s username, how long the session has been active, the IP address of the machine from which the user is connecting, and the name of the connection being used.

   

3. To kill one or more sessions, select the sessions by clicking their checkboxes.

4. Once all desired sessions have been selected, clicking Kill Sessions will immediately disconnect those users from the associated connection.

   The same filtering format applies - a search term containing spaces must be enclosed in double quotes to avoid being interpreted as multiple terms, and only history records which contain each term will be included in the history table. Unlike the table of active sessions, however, the filter will only take effect once you click the “Search” button. This is due to the nature of the connection history, as the number of records may be quite extensive.

   Connection History

   The connection history screen displays a table of the most recent connections, including the user that used that connection, the time the connection began, how long the connection was used, and whether a corresponding recording is available for viewing:

   You can also Download the connection history in a CSV file if required. Click on ‘View’ to view the recorded session of the corresponding connection.

   

   Recordings are only made for a connection if an administrator explicitly configures the connection to produce recordings, and those recordings are only available from this screen if the administrator explicitly configures the connection to store those recordings in a location dedicated for future in-browser playback.

   User Management

   Click Users within the list of settings sections to navigate to the user management screen. Here you can add new users, edit the properties and privileges of existing users, and view the times that each user last logged in.

   

   To add a new user, click the New User button. This takes you to a screen where you are allowed to enter the details of the new user, such as the password and username. Note that, unless you specify otherwise, the new user will have no access to any existing connections, nor any administrative privileges, and you need to manually set the user’s password before they log in.

   To edit a user, just click on the user you wish to edit. You will be taken to a screen which allows you to change the user’s password, expire their password (such that it must be changed at the next login), add, or remove administrative permissions, and add or remove read access to specific connections, sharing profiles, or groups.

   

   If you have to delete the user’s permission, you will also see a “Delete” button. Clicking this button will permanently delete the user. Alternatively, if you only wish to temporarily disable the account, checking “Login disabled” will achieve the same effect while not removing the user entirely. If they attempt to log in, the attempt will be rejected if their account does not exist at all.

   

   Note:

   When a regular user requests for the access of privileged entitlement, upon approving the request, the user will be converted to Privileged user.

   Edit Group Membership

   When editing a user, the group the user is a member of may be modified within the “Groups” section. By default, only the group user is already a member of will be displayed. If you have permission to modify the user’s membership within a group, an “X” icon will be available next to that group’s name. Clicking the “X” will remove the user from that group, taking effect after the user is saved.

   To add users to a group, the arrow next to the list of groups must be clicked to expand the section and reveal all available groups. Available groups may then be checked/unchecked to modify the user’s membership within those groups:

   

   User Group Management

   Click Groups within the list of Settings sections. It takes you to the User Group Management screen. Here you can add new groups, and edit the properties and privileges of existing groups.

   

   To add a new group, click the “New Group” button. This will take you to a screen where you will be allowed to enter the details of the new group, including membership and any permissions that members of the group should have.

   To edit a group, click on the group you wish to edit. You will be taken to a screen which allows you to modify membership, add or remove administrative permissions, and add or remove read access to specific connections, sharing profiles, or connection groups. You can also filter the groups by specifying search terms within the “Filter” field. Connection groups will be filtered by name and connections will be filtered by name or protocol.

   If you have the delete permission on the group, you will also see a “Delete” button. Clicking this button will permanently delete the group. Alternatively, if you only wish to temporarily disable the effects of membership in the group, checking “Disabled” will achieve the same effect while not removing the group entirely.

   

   Group Membership of Groups

   Managing the group membership of groups is more complex than that of users, as groups may contain both users and groups, with permissions from parent groups possibly being inherited. Parent groups, member groups, and member users can all be managed identically to the group memberships of users, with a corresponding section dedicated to each within the user group editor:

   

   Note:

   It is ultimately up to the extension providing the group to determine how permissions granted to that group are inherited, if at all. The database authentication extension implements full recursive inheritance of group permissions, with permissions granted to a group being granted to all members/descendants of that group, regardless of how deeply those members are nested.

   Connections and connection groups

   Clicking “Connections” within the list of settings sections will take you to the connection management screen. The connection management screen allows administrators to create and edit connections, and share profiles, and connection groups. If you have a large number of connections, you can also enter search terms within the “Filter” field to filter the list of connections by name or protocol.

   

   To add a new connection or connection group, click the “New Connection” or “New Group” button, or the “New Connection” or “New Group” placeholders which appear when you expand an existing connection group. These options will take you to a screen where you will be allowed to enter the details of the new object, such as its location, parameters, and name. This name should be descriptive but must also be unique concerning other objects in the same location.

   Once you click “Save”, the new object will be added, but will initially only be usable by administrators and your current user. To grant another user access to the new connection or connection group, you must edit that user or a user group that the user is a member of, checking the box corresponding to the connection or connection group you created.

   Editing connections, sharing profiles, and connection groups work identically to edit a user. Click on the object you wish to edit, and you will be taken to a screen which allows you to edit it. The screen will display all object properties, including its usage history, if applicable.

   If you have the delete permission on the object, you will also see a “Delete” button. Clicking this button will permanently delete the object being edited.

   

   

   

   

   

   

   

   Connection organization and balancing

   Connection groups can be either “organizational” or “balancing”. Each group can contain any number of other connections or groups, but the semantics of the group change depending on the type.

   An organizational group behaves exactly as a folder or directory in a file system. It simply contains connections and other groups but provides no other behaviour. Clicking on an organizational group within a connection list will expand the group, revealing its contents.

   A balancing group behaves as a connection. It dynamically balances load across the connections it contains, choosing the connection with the few active users. Unlike organizational groups, clicking on a balancing group causes a new connection to be opened. The actual underlying connection used depends on which connection has the least load at the time the group was clicked, and whether session affinity is enabled on that group.

   Enabling session affinity for a balancing group ensures that users are consistently routed to the same underlying connections until they log out of CIPAM. The load-balancing behaviour of the balancing group will apply only for the first time a particular user connects to the group. If your users may lose their desktop state if they are routed to a different underlying connection, this option should be enabled.

   

   Connection sharing

   The ability to share a connection is governed by “sharing profiles”. Suppose a sharing profile is created for a connection. In that case, users with access to both that connection and that sharing profile will be able to share the connection with other users by generating connection-sharing links, even if those users do not otherwise have user accounts within CIPAM.

   

   The name of the sharing profile will be presented as an option within the share menu for any users with access, while the level of access granted to users of generated share links will be dictated by the parameters specified for the sharing profile.

   Unlike connections and groups, there is no “New Sharing Profile” button. Sharing profiles are created by clicking the “New Sharing Profile” placeholders which appear when connections are expanded. Just as expanding a connection group reveals the connections or groups therein, expanding a connection reveals the sharing profiles associated with that connection. This holds true with both the list of connections in the connection management screen and the list of connections in the user editor.

   Creating or editing a sharing profile is virtually identical to creating or editing a connection, with the exception that not all connection parameters are available:

   

   How recording storage and playback works

   The CIPAM web application includes support for playing back recordings from the history screen in the administration interface, but that support cannot automatically know where those recordings are stored nor how they are named. The extension documented here provides exactly that missing piece, allowing the web application to find recordings on disk so long as they are named appropriately and stored in a specific location.

   Each history entry has a deterministic, internal, unique identifier called its UUID, and all supported database backends make this UUID available ahead of time with the ${HISTORY_UUID} parameter token. This provides a reliable way for data stored outside the database to be associated with history entries that are otherwise stored purely inside the database, and it is this UUID that the extension searches for when locating the recording for a history entry.

   When a user lists the history of a connection, the recording storage extension additionally searches a predetermined location for session recordings that match either of the following criteria:

   • The recording’s filename is identical to the history entry UUID and directly within the search path.

   • The recording has any name at all and is within a directory whose filename is identical to the history entry UUID and is directly within the search path.

   If such a recording is found, it is available to any user who can view the history entry. The availability of a recording is displayed as a “View” link in the “Logs” column of the history table:

   

   Clicking on that link navigates to a screen with a player that loads the recording and allows it to be played back: