Worked example: using workflows and the API to provision and deprovision in an on-premises system

Trelica workflows can provision and deprovision users in systems that have APIs that are exposed to the Internet.

Some systems however are hosted internally but you may still want to provision and deprovision access: a good example of this would be Microsoft Active Directory (AD).

Create API credentials

Go to Admin > Settings > API Access and crreate some credentials.

You will need the following scopes:

• Read workflows
• Read workflow runs
• Execute workflow runs

Optionally you may also need:

• Read workflow run secrets

See the section below about setting passwords to decide if you need this scope.

Using the credentials from Powershell

Trelica has Powershell module which wraps some elements of the API and in particular helps with securely storing credentials.

Please read the full article, but in short, you can install the module using:

Install-Module -Name Trelica -Scope CurrentUser

Then you will need to set your credentials:

Initialize-TrelicaCredentials

Initialize-TrelicaCredentials -BaseUrl https://eu.trelica.com

The first time you run this, you will be prompted to enter your Client ID and Secret at the User and Password prompts respectively:

PowerShell credential request
Please enter your Trelica API Client ID and Secret when prompted for User and Password respectively
User: UaQD5J21ARhKjQyFTYokxkieXqM9SM9RaUMHxQBIPjD
Password for user UaQD5J21ARhKjQyFTYokxkieXqM9SM9RaUMHxQBIPjD: ***

credential                                baseUrl
----------                                -------
System.Management.Automation.PSCredential https://app.trelica.com

Your credentials will now be saved in a JSON file in a folder called Trelica under your user account's "home" path.

To exchange these stored credentials for a valid OAuth token, then use

Initialize-TrelicaCredentials | Get-TrelicaContext

The 'context' is a Powershell object that contains the path to Trelica (e.g. app.trelica.com or eu.trelica.com depending on whether you defined the credentials by passing in a -BaseUrl parameter), and also an access token (which has a life-span of 60 minutes).

Creating the workflow

1. Create two new workflows, one called New Hire and one called Terminate Users.
2. The key step in each worfklow is a 'Signal' step which means that the workflow will wait until prompted to move on.
3. Add Signal steps to each workflow.
4. Rename your signal step to Waiting for Active Directory Synch and ensure that it has a primary button called Continue.

Creating the Powershell script

We can now create a Powershell script that can be run on a schedule (e.g. hourly), and can use the Trelica API to:

1. Look for workflow runs that are waiting on signal steps
2. Get information about the subject of the workflow (e.g. person's email address, name)
3. Carry out an action (e.g. create a new user in Active Directory)
4. Call the 'Continue' signal to tell the workflow to move on to the next step.

Have a look at the script here:

We recommend you fork this from Github and then modify it to meet your needs.

Understanding the script

ProcessWorkflow takes the Trelica context and finds a workflow with a given name: by default the script will check for the two workflows with the names you used above.

The function then gets a list of workflow runs that are not terminated, and where they have a step with a specific name, in the 'waiting' state.

For each of these runs, it calls ProcessWorkflowRuns which calls a nominated Powershell function for each run.

The two processing functions implemented are ProcessProvisioningWorkflowRun and ProcessDeprovisioningWorkflowRun.

Configuring the script

There's a block of things you can configure at the top of the script.

The first two items control whether the script will actually do anything. We recommend getting everything up and working with DRY_RUN set to true.

Setting DEBUG to true will emit JSON received - we recommend leaving this off initially, but if you're modifying thing it can helpful to enable.

# Set to $true to do a dry run, not connecting to AD or posting results to Trelica
$DRY_RUN = $true

# Set to $true to write out JSON received from Trelica 
$DEBUG = $false

Beneath this block are some settings which are mostly self-explanatory. They either match things in your Active Directory (e.g. ADHOST, DOMAIN, DEFAULT_OU etc), or the Trelica workflow (e.g. PROVISIONING_WORKFLOW_LIST, STEP_NAME or ACTION_NAME):

# Core settings
$ADHOST = "XXXXXXXXXXX"
$PROVISIONING_WORKFLOW_LIST = @("New Hire") 
$DEPROVISIONING_WORKFLOW_LIST = @("Terminate Users")
$STEP_NAME = "Waiting for Active Directory Synch"
$ACTION_NAME = "Continue"

# Specific settings for provisioning workflows
$DOMAIN = "corp.example.org"
$DEFAULT_OU = "Users/All"
$TEAM_TO_OU_MAP = @{
    "Engineering"="Users/Dev"
    "DevOps"="Users/Dev"
}
$NEW_USER_GROUPS = @("AllUsers")

If you've set up the workflow with the suggested names above then you should be able to run this script without changes.

If you've stored some credentials as described earlier then you should be able to run:

Initialize-TrelicaCredentials | Get-TrelicaContext | ./ADWorkflowSync.ps1

If you want to re-run without regenerating a new token each time you can store the context and just pass it when you run the ADWorkflowSync script:

$context = Initialize-TrelicaCredentials | Get-TrelicaContext
$context | ./ADWorkflowSync.ps1

You should see something like:

DRY RUN: NOT CONNECTING TO AD OR POSTING BACK TO TRELICA


DEPROVISIONING WORKFLOWS
========================
Requesting runs for Workflow 'Terminate Users' (ID 642b47bc2e7728704491e6cf) and Action Step ID 642b2b3d2e7728704491e2ab...

PROVISIONING WORKFLOWS
======================
Requesting runs for Workflow 'New Hire' (ID 642b2b152e7728704491e22d) and Action Step ID 642b2b3d2e7728704491e2ab...
                                                                                                                        

DONE

This is correct as there are probably no workflow runs at the required state.

Trigger a workflow run

Select a user and click Trigger now.

Now re-run the script:

$context | ./ADWorkflowSync.ps1

You should now see something different:

DEPROVISIONING WORKFLOWS
========================
Requesting runs for Workflow 'Terminate Users' (ID 642b47bc2e7728704491e6cf) and Action Step ID 642b2b3d2e7728704491e2ab...
> Processing run ID 642c1c9b733e0269ffb3a307: 'Bob Leaver' at 2023-49-04 14:49 +02:00
-------------------------------------------------------------------------------------
INFO: Deprovisioning AD user 'bob.leaver'...
POSTing 'Continue' action for run ID 642c1c9b733e0269ffb3a307: 'Bob Leaver'...
^^^^ DRY RUN: NOT EXECUTING

Calling AD

There are two functions which actually make Powershell calls to do things in Active Directory.

If DRY_RUN is set to true then these functions will out what they will do, but won't actually do anything, which is very useful when testing. They also won't call back to Trelica to move the workflow forward, so you can re-run freely.

ProcessProvisioningWorkflowRun

By default this will create a new user in AD and add them to preset groups.

The user will be assigned to an OU based on Team membership, and assigned a password defined by Trelica (see below).

ProcessDeprovisioningWorkflowRun

This function will remove a user from all groups in AD and then disable the account.

A note about setting passwords

You may want to have Trelica create a password that is used across Google and AD.

To do this, you can make the password available through the API, but this requires a number of steps.

Firstly, the password field should be created manually with a known name (we recommend password).

Go to the workflow and choose Fields list: 

Create a new field called password of type Password and click Create.

When creating the Google Workspace user, under Set password to, choose Form field, and select the newly created password field in the dropdown:

This field can then be used in emails and a time-limited link will be sent to the user so that they can view the password:

In terms of the Powershell script:

1. API credentials will require the Read workflow run secrets scope.

2. The API calls need to explicitly specify the password (or 'secret') field names to fetch. If you rename the field then you will need to change it in several places in the script.

This is done in ProcessWorkflow:

# pull back any runs that are waiting
Write-Host "Requesting runs for Workflow '$WorkflowName' (ID $id) and Action Step ID $actionStepId..." 
$filter = @{
    filter = 'status ne "Terminated" and steps[status eq "Waiting" and id eq "' + $actionStepId + '"]'
    variables = 'password' 
}

The password field is also explicitly referenced in ProcessProvisioningWorkflowRun:

 # get the password from the workflow run variables context
$password = $Run.context.variables.password