# RapidIdentity Administrators' and Users' Guide

##### Using RapidIdentity Connect

The RapidIdentity Connect module allows administrators to manage functionality across RapidIdentity Connect, build and apply Action Sets, request and apply OAuth credentials, integrate RESTPoints, and manage select RapidIdentity Connect module files.

###### Projects

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.

###### Connect Action Sets Module

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.

###### Action Set Builder

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.

Action Set Builder

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.

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.

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:

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.

###### Connect Files Module

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.

### Note

The Search function in this module searches through file contents instead of file names.

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.

###### Connect Jobs 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.

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

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.

###### Connect RESTPoints Module

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 +.

###### RESTPoints Method Fields

The configurable fields available to edit are based the Method/Path (i.e. the HTTP verb) selected.

Field

Description

Notes

Enabled

Click the checkbox to enable the RESTPoint.

Description

An optional description for the RESTPoint.

HTTP Method

Required. The method the RESTPoint will use.

Supported methods: GET; DELETE; HEAD; OPTIONS; PUT; PATCH; and POST

Path

Required. The path must start with a forward slash and may contain one or more path parameter placeholders in the form of {name} as described by the @Path annotation in the JAX-RS API.

The combination of the Method and Path must be unique within the project.

If the project is called "test", the Project Base URL will be: https://server[:port]/dss/ws/restpoints/test/

When the project is <Main>, the Project Base URL is: https://server[:port]/dss/ws/restpoints/.main/

Consumes*

The MIME media type that the RESTPoint expects as the content of the REST Request.

*This field is only enabled for PUT, PATCH, and POST methods.

Produces

The MIME media type that the RESTPoint will return in the REST Response.

The available MIME media types are: application/json, application/octet-stream, application/xml, application/x-www-form-urlencoded, text/csv, text/plain, text/xml, and */*.

Authentication

The default authentication is the same as the project, however, the default authentication can be overridden on a specific RESTPoint.

Each enabled RESTPoint must have at least one authentication method defined.

Same As Project

Use the same authentication method as is configured in the project's Details menu. Note that if this box is checked, the rest of the options become disabled.

OAuth 1.0a

The REST request is signed as described in the OAuth Core1.0a specification using an empty string for the value of both oauth_token and oauth_token_secret and the HMAC-SHA1 or HMAC-SHA256 signing method.

HTTP Basic (using OAuth keys)

HTTP Basic Authentication using the OAuth consumer key as the username, and consumer secret as the password.

RapidIdentity roles or permissions - any username/password that can be used to authenticate to RapidIdentity will be able to call the RESTPoint.

Anonymous

Does not require any authentication.

Action Set

Required. The Action Set to which the RESTPoint maps.

After you select an Action Set here, if that Action Set has any input properties, you will also get a set of fields to specify how to map the REST request to those input properties.

###### Connect OAuth1 Consumers Module

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.

###### Connect OAuth2 Credentials Module

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.

Table 21. OAuth2 Credential - Google Fields

Field

Description

Name

Give the credential a name (must be unique within the project.)

Provider

The chosen provider (in this case, Google)

Client ID

Google Client ID for this credential

Client Secret

Google Client Secret for this credential

Username to be used for this credential

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.

Table 22. OAuth2 Credential - Google Extended Fields

Field

Description

Name

Give the credential a name (must be unique within the project.)

Provider

The chosen provider (In this case, Google Extended)

Open the JSON file you received when you created the Service Account Key and copy and the paste the contents into the Google Service Account JSON field.

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

OAuth2 Credential - Edmodo
Table 23. OAuth2 Credential - Edmodo Fields

Fields

Description

Name

Give the credential a name that makes it easy to

Provider

The chosen provider (In this case, Edmodo)

Edmodo username that corresponds to the eventual RapidIdentity Connect Action for Edmodo OAuth

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).

###### Connect Status Module

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.

###### Connect Job Logs Module

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.

###### Connect Settings - General

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.

HTTP Client

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

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.

Email

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.

SSH/SFTP Client

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.

###### Connect Settings - Projects

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.

###### Connect Settings - Community Adapters

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.

###### General Standards
• Do not store values in core schema that doesn’t describe the data. For example, don’t store a job code value in the physicalDeliveryOfficeName attribute.

• Verify the use of custom attributes with a Solution Architect (or Manager of Services) to ensure proper use

• Requests for new custom attributes must be made to Solution Architect (or Manager of Services)

• Use “employeeID” attribute for storing employee ID’s and student ID’s.

• If there is a chance of overlap, add a prefix of “E” for employees or “S” for students. Store the *original* value in the “employeeNumber” attribute. For example, an employee with an employee ID of 1234 would have employeeID=E1234 and employeeNumber=1234.

• Always use double quotes (“) when referring to strings

• The only exception is when you have a string within a string, in which case you will use a single quote for the inner string (‘). e.g. “INSERT INTO table (‘column1’) VALUES (foo’)”

• Always refer to record fields using record[‘field’] syntax. (i.e. refrain from using record.field)

• Using consistent syntax helps everyone understand the usage.

• record[‘givenName’].toUpperCase() <-- standard

• record.givenName.toUpperCase() <-- not standard

 AD Attribute Description givenName First name sn Last name middleName Middle name employeeID Employee or student ID idautoPersonJobCode Job code title Job title departmentNumber Department code department Department name idautoPersonPriLocCode Location/building/office/campus code physicalDeliveryOfficeName Location/building/office/campus name streetAddress Address l City st State postalCode Zip code mail Email address displayName Full name employeeType Person type (e.g. Staff, Student, Sponsored) idautoStatus Account status (e.g. A, I) idautoPersonGradeLevel Student grade level