Bulk Sponsored Account Creation using Workflow and Sponsorship

This example workflow uses a number of components of RapidIdentity to accomplish the creation and management of temporary accounts in RapidIdentity. An applicable use case for this workflow example is managing external user identities that do not originate in a designated source of truth, such as an ERP/HRMS or a Student Information System. This might include use cases where a group of third party individuals need accounts to access organizational resources, but on a temporary or short-term basis; like using institutional facilities to host a course or class where students need to access to computers to get to internet applications or information.

In this workflow, the following components will be utilized:

• Request definition with a form that includes attaching a file

• Multi-Unbound entitlement for bulk account management

• Connect action set to retrieve the file and invoke a provisioning process

• Sponsorship to allocate the management of accounts to an owner

Video Overview and Demonstration

The Workflow Component

In the workflow, there is a form for making the request that also allows for uploading a CSV file with information for account creation. The assumption in this example is that the person uploading the file and making the request is aware of the required format of information within the CSV file. The request is made by the requestor, and then moves to an approval step where an approval is required to move to the next step, or the workflow ends. Upon approval, a call is made to Connect, passing the information from the form to the Connect action set to be executed.

The Workflow Form

The form contains the following input fields for gathering information for the request:

• Non-Credit Students CSV (file upload)

• Accounts Active Through (Date/Time)

The Ask Approval Step

The approval step in this example forwards the approval to the Tenant Administrator group in RapidIdentity with an approval window of 5 days. After the approval window reaches 2 days, it is then escalated to the Tenant Administrator group again and must be approved within the 5 day window or will be rejected. The escalation group could be a completely different person or group if desired.

The Connect Action

In the Connect Action (upon approval), the workflow triggers an action set called BulkSponsoredAccounts in the wfm project (this can be derived from the Connect Action Name field which contains the value “wfm.BulkSponsoredAccounts”. To invoke this action successfully, there are 3 inputs required: attachmentID, requestor, and expiredate (outlined below). Since this is running on the same tenant, there is no need to populate the Connect Base URL, username, or password fields. Finally, the Trace Enabled checkbox is checked for logging purposes, and the workflow is expecting a return of ‘true’ from the Connect Action Set to continue.

The Value Pairs

The value pairs in this example align with the input variables in the Connect Action set (outlined in a later section HERE). These variables pass critical information from the workflow to the Connect action set for proper execution. Each of these will be detailed below.

attachmentID=’%form.attachment_id}’ is the first value pair defined. To break this down, the left value, “attachmentID” is what is defined as the id of the input field in the form on the request. The right value is pulling the actual information from the workflow form when the request is submitted. In this case, it is referring to a workflow expression ‘%{form.attachment_id}’ which will pull the identifier from the attachment that is uploaded by the requestor. This value will allow us to refer to the attachment once we are in the Connect action set (VERY IMPORTANT).

requestor=’%{requestor.dn}’ is the value pair that that passes the distinguished name (LDAP DN) of the person making the request to the Connect action, and will be passed to the Connect action to be added to the ‘manager’ attribute to indicate the Sponsor for the account. NOTE: this value comes from the Request engine itself, and is not a form value (the expression starts with requestor instead of form). In this example, we will assume this would be the assigned Sponsor when the accounts are created, but in practical application the requestor could be someone different from the person that would be the sponsor. If they were different, then simply adding another value pair to indicate the intended sponsor using identifiable information such as an email address, username, or other identifier would allow them to be assigned as the sponsor.

expiredate=’%{form.expiredate}’ is the value pair that is passed from the form input (date/time) to be passed to the Connect action to set the value for the expiration date of the account in the sponsorship module. This value will technically be placed in the ‘idautoPersonEndDate’ attribute in the RapidIdentity metadirectory for the account.

The Connect Action Set

The Connect action set that is triggered from the workflow is the BulkSponsoredAccounts action set in the wfm project. In this example, the action set is going to be quite simple without a lot of validation, error correction, and other production-specific logic that would normally be included. The following content will walk through the action set and explain what is happening as the Connect action set runs.

Input Parameters Section

The input parameters for the action set take the values passed in through the value pairs in the Connect Action step in the workflow. As described above in the Value Pairs section, the attachmentID is the id of the file that was uploaded in the form; the requestor is the value of the requestor Distinguished Name (DN) from the Workflow Request engine, and te expiredate is the date string from the workflow form date/time field.

The Variables Section

In this section, there are variables being set that will be used in later actions in the action set.

• date_now = now() sets the current date in a standard date format

• date_now_string = formatDate(date_now, “yyyyMMddhhmmss.SSS”) sets the format of the current date (e.g., 20250715093100.000)

• fileName = ““ sets the fileName variable to blank/null to start with

The Open Connections Section

In this section, the logic is simply opening an active connection to the RapidIdentity metadirectory and the RapidIdentity Cloud Portal instance. We open the connection to the metadirectory to look up account metadata, or to create/update metadata; and the Portal connection is to invoke native Portal API calls for sponsorship, workflow, groups, etc.

The Get Requestor Account Information Section

This section contains the logic that is used to take the DN value from the requestor input, and lookup the account information in the metadirectory.

• requestor_record = getLDAPRecord(session_meta, requestor, “*”) - this simply uses the current open metadirectory session and passes the reqeustor DN value in to lookup the record and bring back all of the metadata (as indicated by the “*”)

• sponsor = requestor_record[‘@dn’] - this sets a variable called “sponsor” to the DN value of the requestor (could have also used requestor here, since it was the DN value, but often it is best practice to indeed validate that the identity exists and is active)

• sponsor_first_name = requestor_record[‘givenName’] - uses the value of the givenName attribute from requestor_record to set a variable called sponsor_first_name

• sponsor_last_name = requestor_record[‘sn’] - uses the value of the sn attribute from requestor_record to set a variable called sponsor_last_name

• sponsor_mail = requestor_record[‘mail’] - uses the value of the mail attribute from requestor_record to set a variable called sponsor_mail

The Get File Contents Section

This section of the Connect action is designed to use the value of the attachmentID from the workflow form, pass it into a RapidIdentity native API call, and retrieve the attached file for use in the Connect action set.

• res = httpGET(session_ri.url + “api/rest/workflow/attachments/” + attachmentID, {“Authorization”: “Bearer “ + session_ri.token}) - this is the API call to get the file attached to the workflow form

  • session_ri.url - this is using the “url” property of the RI Portal session established in order to get the base URL of the RI Portal

  • “api/rest/workflow/attachments/” - this is the native RI API call for getting a file attachment from a workflow

  • attachmentID - this is the id of the attachment

    • The above combined might be something like “https://demo.idautodemo.com/api/rest/workflow/attachments/c99790d7-a298-4229-9915-ee5c47820d99”

  • {“Authorization”: “Bearer “ + session_ri.token} - passed into the API call as a header indicating the Bearer Authorization Token using the token value established when creating the RI Portal session

• if (res.statusCode ≥200 && res.statusCode < 300) - validates that the return status code from the API call is a value greater than or equal to 200 but less than 300 (these are standard HTML status codes, and some software returns a 200 for success or 201, and generally the value would be indicated as specific if the return code from the API is indicated)

• fileName = “bulk_sponsored/Sponsored_Accounts_For_” + sponsor_first_name + “_” + sponsor_last_name + “_” + date_now_string + “.csv” - this sets the file name to be saved on the RI tenant for processing using some of the variables that were set above. NOTE: this file would be saved in the project file area in a folder called “bulk_sponsored”

  • A value for this combination might look like: “bulk_sponsored/Sponsored_Accounts_For_John_Smith_20250731023645.889.csv”

• result = saveToFile(fileName, res.data) - this is the Connect action to save the file that was named in the previous action, and the contents of the file are represented by res.data (the data from the API call with the variable name of “res”)

• } else { no_file_email = sendEmailWithDefaults(requestor_record[‘mail’], “Invalid File for Non-Credit Bulk Account Request”, “The file…” - this action sends an email to the requestor indicating that there is a problem with the file (uses the property for “mail” from the record retrieved for the requestor from the metadirectory)

• close… - these close statements close the open sessions with the metadirectory and RI Portal and then return a value of “false” to the workflow to indicate it failed, then exits the Connect action set (this is in the ELSE statement, meaning that if a status code outside of the acceptable range is returned, it will fail, and the action set should stop)

The File Validation Section

In this section, the Connect action “isFile” is used to validate that the file is actually a file. If it is not valid, then an email is sent to the requestor, the connections are closed, and a value of “false” is returned to the workflow to end it.

File Iteration and Record Preparation Section

In this section, a lot of the work is taking place. The main purpose is to open the file that was just saved, read in the rows of data, and prepare the records for being written into the RapidIdentity metadirectory to create the Sponsored accounts. A few key points to cover in this section include:

• In the beginning of the forEach statement, there is an “if” action that is validating that each row of data in the CSV has the proper information included (id, first name, last name, phone number, and email address)

  • If the information does not exist in the row (record), then an email is sent to the requestor, the connections are closed, and a value of “false” is returned to the workflow to stop it from continuing

• The renameRecordFields action is used to translate between the names of the fields in the CSV to attribute names that the data will be stored in when written to RapidIdentity.

• There are some additional data points that are added to the record to make it ready to be (1) a valid RapidIdentity account, and (2) designated sponsored account. These include:

  • objectClass - indicating to the metadirectory that this is an object that inherits the idautoPerson attributes

  • employeeType - set to sponsored to indicate to RI this is a sponsored account type

  • idautoPersonAffiliation - visual and categorical identifier for classifying the account as a “Non-Credit Student)

  • idautoID - the random generation of an idautoID value, which will be the unique identifier for the account as well as the CN (canonical name) value for the DN (distinguished name) in the metadirectory

  • idautoPersonEndDate - the expiration date for the account as part of the Sponsored account values

  • manager - using the requestor value passed in from the workflow, added to the “sponsor” variable, to be indicated as the Sponsor for the account

  • username - using the GenerateUsername action set to create a unique username for the account

The Set Claim Code Section

This section uses a helpful Connect action that is called generatePortalPasswordForPolicy that uses the established RI Portal session to refer to a defined password policy by the id number of the policy to generate a unique claim code value for this account. The password policy has some of the following properties (the screen captures are NOT exhaustive):

Note

This password policy is NOT enabled - it does not need to be in order for Connect to refer to it. Also, the option for ALLOW RANDOM PASSWORD GENERATION is enabled.

For the claim code generation, the code should be randomly generated to be 8 characters and should include at least one uppercase letter, lowercase letter, number, and special character.

The Save Record Section

In this section, the newly formed record is saved to RapidIdentity, essentially creating the Sponsored account. It also kicks off an action to sync the account into any eligible groups and sends a claim email to the newly created account. Some specific items to mention include:

• saveLDAPRecord - will save the account to the metadirectory, and with the appropriate values for attributes, will appear as a sponsored account (employeeType = sponsored, manager = [value], and idautoPersonEndDate = [date]

• The MetaSyncRoles() action set is a separate action set that runs a forced group sync (probably would NOT do this in a production environment across ALL roles)

• The fn_claim_email action set is a separate action set that takes the email address, first name, and claim code and sends a nicely formatted email so the new user can claim their account

• If the create is NOT successful, it will just move to the next record (this is where additional validation and alerting would be useful to notify the requestor that an account was not created)

The Ending and Close Section

This section has a placeholder for sending a report to the requestor and sponsor (if they were different), but has not been built out. This is where a digest of the activity could be put into a report indicating the accounts that were successfully created with their account information, or that had failed and reason for the failure. The last actions are just closing the records, and the sessions to the metadirectory and RI Portal.

Note

The successful completion of the action set in Connect will return a value of “true” automatically. Since this action set was triggered by a workflow, the successful completion of the action set would return “true” and the workflow would move to the next defined step indicated in the workflow.

The Entitlement Component

The entitlement is mostly a required placeholder for this particular workflow. It is purposely set to MULTI_UNBOUND for the binding type, so that it is not tied specifically to the Requestor or Recipient, and is able to be requested as many times as needed.

The main things to call out on the entitlement are the binding (MULTI_UNBOUND), the Access Control (Role-Based / Portal Sponsor - only sponsors can request this entitlement), and then the Grant/Revoke Workflows, as well as the Grant Workflow Form.