RapidIdentity Administrators' and Users' Guide

A RapidIdentity Connect project can be thought of as a container that holds a collection of Action Sets along with their associated data and log files, RESTPoints, and credentials. By default, there is a single project called <Main> that cannot be deleted. Additional projects can be created as needed or desired.

Projects are isolated from each other at runtime so that Action Sets and RESTPoints in one project can only reference other Action Sets and access files or use credentials from within that same project.

The primary reason for using separate projects is related to access control. Each project can be configured to use separate, per-project roles that can allow a specific set of users to only use that project, or define OAuth credentials that can be used to only access RESTPoints within a single project. Projects are also useful as a way to share, back up, stage, or migrate parts of your Connect configuration.

User-defined Action Sets will be saved in <Main> unless a different project is specified.  These Action Sets may include, but are not limited to, the creation, inclusion, removal, or disabling of various group member user accounts, various SQL queries to obtain or update data, and Action Sets to log or graph data.

As workflow increases, multiple projects will exist and it is likely that Action Set building within projects will involve overlapping characteristics, such as accessing a particular database to extract data or update directories. Duplicate, Export, and Import all allow projects and Action Sets to serve as templates. Projects can be further managed through the Connect Settings - Projects menu.

The Action Sets menu allows you to build and manage Action Sets.

The initial view in the Action Sets menu is a grid or list of existing Action Sets. If no Action Sets exist yet, click Add Action Set + to go to the Community Action Sets menu.

The figure above shows saved Action Sets imported from RapidIdentity Depot for illustrative purposes only. Users can choose to create a new Action Set, open an existing Action Set to continue configuration, or import from RapidIdentity Community to create an Action Set.

Community Action Sets

Community Action Sets are Action Set templates that are available from the Identity Automation Community. To reach this menu, click Add Action Set + from the Action Sets menu.

Hover the mouse over the line of the Action Set and click Import in the rightmost column. Note that if you click the checkbox in the first column, the Import button remains visible.

Once an Action Set has been imported from the Community, it will be visible in the main Action Sets workspace of the project that was selected during import.

Note

The Action Set will show up in the workspace of the project that was chosen when it was imported from the Community, and the Community remains the same across all projects.

The Action Set Builder is a canvas to choose specific actions from the Actions to build Action Sets. Ensure the finished Action Set is named following the RapidIdentity Connect Standards.

The Action Set Builder provides a code-based view, allowing users to enter Action Sets manually.

Actions are entered by clicking the Plus icon that appears at the left of the menu. This will prompt the Add Action sidebar.

Clicking the drop-down indicator next to the plus sign provides a selection of possible next actions to add.

Action Sets - Keyboard Shortcuts

When the Action Set Builder is in Advanced view, you can quickly find and insert any action using just the keyboard by just starting to type the name of the action, which will automatically place you in the Filter Actions... field and show you a list of actions matching what you've started typing. Once the desired action is selected in the list, pressing the Enter key will cause that action to be inserted at the current location in the Action Editor, and an additional press of Enter will start editing the first property of the action.

Additionally, for some of the most common actions, there are shortcut keys that can be pressed to automatically insert the action and, where appropriate, start editing the properties, all with a single keystroke. These numbers are shown on the top of the screen next to the Search bar.

Note

Other keyboard shortcuts that can be used here are + (or the Insert key) to perform the Insert action, or ^ to perform the Insert before action.

Add Section

Clicking Add Section prompts a right sidebar to configure the section's label and suppressTrace settings.

Note

Click to add quotation marks and slashes that will escape a string; click to unescape a string.

Table 18. Connect - Add Section Fields

Field	Description	Supported Types
Label	Give the section a name.	Expression and Variable. Variable allows you to insert the name of an already-defined variable.
suppressTrace	Suppress detailed tracing of the actions in the section.	Boolean, Expression, and Variable. Each type requires a value to be defined.

Add Action

Clicking Add Action prompts a right sidebar to choose the action to be included in that step. Actions are divided into two categories: Core Actions and User Defined Actions. User Defined Actions will be visible once custom Action Sets are saved to a project. Navigate through the folder categories to find the desired action, or use the Search for action bar at the top of the menu.

Each action has a different set of fields, but the functional commonalities are as follows:

Table 19. Add Action Fields

Field Item	Description
Red Asterisk ()	Used next to a field title to denote that the value is required
Escape (quote) value ()	Click this to add characters into the field that will escape the string
Unescape (unquote) value ()	Click this to remove characters from the field
Dropdown List ()	Clicking this will expand a dropdown list of values that can be used in this field
Edit Value ()	Usually used in conjunction with Dropdown List or Password, clicking this icon will replace the current input field with a code editor. This is to support values for the particular field being either inline code expressions or variable names from elsewhere in the context
View Characters ()	Usually used in conjunction with Password, clicking this icon will show the characters entered for a password instead of obscuring it with asterisks

Detailed Tracing

The Detailed Tracing option is presented whenever an Action Set is run, either manually from the open Action Set itself or from the project's Action Set screen. A confirmation window will display with this option at the top.

Selecting Enable Detailed Tracing is useful to help "debug" Action Sets that do not run properly. One example of a detailed trace with one error is shown below.

In this Action Set, the variable sample was defined; however the log action was configured to execute the samples variable. Thus, the log action needs to be configured to execute sample to run properly. When fixed, the Action Set runs properly.

Detailed trace allows you to see a log of each action and the value (if any) that it returns. With detailed trace turned off, you will only see errors, warnings, and the output of any explicit log() actions within the Action Set.

The detailed trace is particularly useful for more complicated Action Sets involving the manipulation of records and record fields. The detailed trace displays records and JavaScript objects as formatted JSON to enhance readability. XML objects, date objects, and most Java objects embedded inside the record or JavaScript object display as a string value. Strings display as a string literal, including necessary quotes and escaping.

The Files module allows users to access action and Action Set files, edit text files, and to manage RapidIdentity Connect file directories associated with the currently selected Connect project.

The RapidIdentity Connect Files module UI is very similar to the RapidIdentity Portal Files module.

The principal difference between the RapidIdentity Portal and RapidIdentity Connect Files module UIs is that RapidIdentity Connect does not contain a File Share menu from which to access external file systems; RapidIdentity Connect allows users to start with the Folders Directory Tree and the Action Bar.

Portal Files module provides the capability to set an S3 file share to public, a capability not found in the Connect Files module.

To review these shared functionalities, visit the User Files Module.

In RapidIdentity, an Action Set that has been configured and scheduled to run at a predetermined time is called a job. The Connect Jobs Module shows each of the jobs that have been previously built and scheduled, and provides administrators with the ability to create, configure, run, and manage jobs.

To create a new job, click Add Job +. The resulting right sidebar will have two tabs: Details and Schedule.

This tab holds the majority of the configuration data for the job. The menu's screenshot has been split into two for spacing purposes.

Add Job - Details Tab

Table 20. Add Job - Details Tab Fields

Field	Description
Name	Give the job a name (must be unique within the project)
Description	Optional brief description of the job
Action Set	Choose an Action Set Note If the selected Action Set has any input parameters, fields for those parameters will also display.
Enable Trace	Click this checkbox to enable detailed tracing on this job
Skip if Previous Instance Still Running	Click this checkbox to disregard the scheduled run time if a previous instance of the job is still running
Enable Timeout	This setting is used to keep jobs from running indefinitely. When enabled, enter the number of seconds to allow the job to run. If the job takes longer than this time, the job will be cancelled. Note Setting the value to less than or equal to 0 indicates that there is no timeout.
Email Recipients	Enter the email addresses of individuals who will receive a run notification from this job
Attach Trace Log	Click this checkbox to attach a copy of the tracing on this job
Log Retention	Retention policy for the job log. There are three options: Inherit - Use the same log retention policy as the parent project Always Retain - Keep all logs until manually deleted. Note that this will eventually take up a significant portion of space on the server Retain For - Number of days the logs should be kept before automatic deletion

The Schedule tab provides a granular timing interface where the job can be scheduled to run by minute, hour, day, and/or month. Note that the final schedule is cumulative, and all four time categories can be used to customize the run times for that job.

Schedule Tab - Minute & Hour Configuration

Schedule Tab - Day & Month Configuration

Managing Connect Jobs

Once a job has been created, it will show in the main Jobs module workspace. Administrators can edit the Details of these jobs or, when the job is selected, can export, delete, run, or enable/disable the job. The import option is also available on the Action Bar.

The different jobs created in RapidIdentity will show on this screen, with the checkmark on the left denoting whether that job is enabled or disabled. (Disabled jobs have a greyed out checkmark; enabled jobs display one that's a slightly brighter green.)

Import a .json or .xml file to create a new job, or Export an existing one for use elsewhere. Delete, Run, and Enable/Disable function as expected - Delete and Enable/Disable both require confirmation to complete. Click the Details button to edit a job's configuration.

RESTPoints is a RapidIdentity Connect feature that allows you to create a RESTful API based on Action Sets. The RESTPoint acts as an interface between the RapidIdentity Connect Action Set and the service provider. The RapidIdentity Connect Action Set serves as a programming function and returns a response value, and the RESTPoint will connect the Action Set to the service provider.

All RESTPoints are created by clicking Add RESTPoint +.

The OAuth1 Consumers interface allows administrators to generate the OAuth1 Consumer Key and Consumer Secret for use with the RESTPoints OAuth 1.0a and HTTP Basic (using OAuth Keys) authentication methods. You can create Consumers for any existing project or All (*) projects, and that consumer will be open to any Action Set and RESTPoint within that project.

Note

Consumer credentials created under All (*) projects are accessible by any project on the system. This option is only available in OAuth1 Consumers and OAuth 2 Credentials.

To see the Consumer Key and the Consumer Secret, click Details at the bottom right of the OAuth1 Consumer card.

The Consumer Secret is hidden by default and can be view by clicking Show. Clicking Hide hides the Consumer Secret.

Both the Consumer Key and Consumer Secret are immutable, however, it is possible to delete and recreate a Consumer with the same name to regenerate.

Currently, the RapidIdentity Connect OAuth2 Credentials tab allows administrators to add Google, Google Extended (i.e. Service Accounts), and Edmodo OAuth 2.0 credentials.

Read Configuring OAuth2 for G-Suite Adapter for specific information on Google OAuth2 configuration.

Create credentials for any existing project or All (*) projects, and those credentials will be open to any Action Set and RESTPoint within that project.

Administrators can select an existing project, leave the Project set as <Main>, or choose to apply this to All (*) projects.

Note

Consumer credentials created under All (*) projects are accessible by any project on the system. This option is only available in OAuth1 Consumers and OAuth 2 Credentials.

Upon selecting the appropriate project and clicking Add, selecting Google, Google Extended, or Edmodo opens a specific Request OAuth Credential window.

Each provider choice has different fields that must be populated, and Google and Edmodo provide choices for permissions that can be assigned to each credential.

Edmodo's login mechanism, Edmodo Connect, and Google APIs both employ the OAuth 2.0 protocol to authenticate and authorize, and RapidIdentity Connect supports both.

The Google Credential menu provides permissions settings that can be set for this individual credential, as well as an Add Custom Permission field.

The Add Custom Permission button allows administrators to specify additional scopes to authorize when the desired scope is not listed. This allows administrators to make API calls that are not supported by RapidIdentity Connect directly.

Google Extended does not provide more options for permissions, as those would be configured within the JSON contents.

Edmodo provides the option to select permissions to be granted to this credential.

Once the request is complete, the workspace will display the credential.

To remove the credential, click the checkbox and then click Delete (administrators should also go to the Google Developers Console to delete the Client ID as well for applicable credentials).

For actions or Action Sets scheduled (or run manually), the RapidIdentity Connect Status module allows Action Set viewing.

It's likely that when first viewing the status module the workspace will not contain information, even after clicking the Action Bar's Refresh action button. However, if accessing the Status module while an Action Set is running, the grid interface will display information. The workspace is static between manual refreshes.

If a process is taking too long to finish or has hung up, select the job to be terminated and click Kill Process in the Action Bar. Some jobs provide a View Log option as well.

Each time a job is run in RapidIdentity Connect, a log file for that job is saved in the Job Logs Module. The folder structure displayed here is directly correlated to the names of the jobs and the order in which they were run.

At the top jobs folder level, the only options are Import and Search. To use the Search function, simply enter the desired term to locate and click the Search button. The maximum number of lines to display per file defaults to 20, but this number can be increased or decreased.

At the lower folder level, Open, Rename, and Delete also activate on the Action Bar. With a single item chosen, Download and Edit become options as well.

The General Settings option in the RapidIdentity Connect Module provides administrators with an interface to customize server settings for the Connect server. This is accessed through Connect > Settings > General.

The settings are grouped into five sections; the menu's screenshot has been separated by section for layout purposes.

Scheduler Thread Pool Size dictates how many concurrent jobs may run on any Connect server in the cluster at any given time.

Asynchronous Action Set Thread Pool Size dictates how many concurrent asynchronous Action Sets may run on any Connect server in that cluster at any given time.

These settings define the default connection and socket timeout in milliseconds. The connection timeout value is the time allowed to form the TCP connection, and the socket timeout value is the timeout for responses to individual requests. The default values are 30000 ms (30 seconds) for the default connection and 600000 ms (10 minutes) for the socket timeout. The upper limit for each of these values is 214,783,647 milliseconds or about 59.6 hours. It is possible that a response could take longer than 10 minutes, and in those cases, it is advisable to adjust the timeout value on a case by case basis rather than setting the timeout value to zero (an infinite timeout).

Log Retention defines the number of days to retain the job and run logs. Administrators can choose to always retain or define a specific number of days; acceptable values are between 1 and 36500.

For emails sent in correlation to jobs, this setting defines the size in MB over which RapidIdentity will compress or zip attached log files before sending. The default for this field is 1.

This section provides administrators the option to allow weak cryptographic algorithms. Specific algorithms can be defined using the options parameter with the openRemoteCLI() and openRemoteCLIWithCert() actions. An algorithm specified by either of these actions override the selection of this particular System setting.

A RapidIdentity Connect project is the comprehensive collection and organization of all Action Sets to accomplish one or more designated tasks.

The Projects screen is accessed from the Settings menu visible at the bottom of the Connect menu. Navigate to Connect > Settings > Projects to enable the main Projects screen.

From the main Projects screen, select an existing project to activate Action Buttons for that project to Delete, Export, Clone, or  Import a project. The Export option saves a project as a "dssproject" file.

To edit an existing project, hover over the project line and click the Details button in the rightmost column. This will prompt a right sidebar menu.

Updating any of the interface fields activates the Save button. Clicking the magnifying glass icon to the right of the Admin, Operator, or Auditor field boxes opens a directory service browser window.

Admin, Operator, and Auditor are project-specific roles. These grant the same privileges to a single project that the corresponding system roles Connect Admin, Connect Operator, and Connect Auditor grant for all projects. More information on Roles is available in Roles Defined.

Notwithstanding individual customer needs, administrators can navigate to locate the appropriate LDAP group to assign Admin, Operator, or Auditor roles.

Community Adapters are additional adapters that are available from the Identity Automation Community and provide integration with additional systems not directly supported by the built-in adapters. The adapters that have been imported already are visible through Connect > Settings > Community Adapters.

To import a Community Adapter from the Depot, click Add Community Adapter +.

Select the desired adapter and click Import in the far right column.

Adapters can also be imported directly as .jar files using the Import function.

The imported Community Adapter will now be visible on the main Community Adapters workspace. From here, you can disable or delete an imported adapter or add more as needed.