How to Create a System Connector?

Prerequisites

• Ensure you have the appropriate permission to use Moveworks Setup. You must have have either an Admin or user roles assigned to you in order to create and view connectors.
• Ensure that you have provided correct access to the service account you are using for creating a connector. You can view this guide in order to find all the access requirement guides for the systems that Moveworks supports.
• Go to the guide for the system you’re trying to set up a connector for and follow the steps in the guide to make sure you’ve provided the necessary access to Moveworks before beginning to setup the connector.

Configuration

Here is an example of creating a ServiceNow connector under System Connectors.

• Go to the Connectors module in Moveworks Setup, by clicking on Manage Connectors under Core Platform, and then click on System Connectors.
• Click on Create New in the top right corner.
• You will then see a list of all the systems supported by Moveworks. Select the system you are trying to create a connector for. In this example it would be ServiceNow. If you can’t find the system you’re looking for, use the search bar on top right to search for the system. Then click on Add Creds.

• Provide a Name to the connector, please keep in mind this name is also going to be considered as the unique Integration ID for this system.
  It will be defined in configurations like Identity ingestion and Permissioning.

• Depending on the instance, provide the base URL. Choosing Common Base URL renders the section for the URL where only your instance name would need to be provided and the domain would be pre-filled.

• Choosing Custom Base URL renders the section for the URL where you need to define the complete URL including the domain as this method is chosen when the domain name is not the default.

• Next, select an authentication type. Please note that this depends on the configurations that you have made on the ServiceNow instance. We provide Auth methods in this drop down which specific to the integration.

  • In this case we are using Basic Auth which requires Username and Password.
    Note: Once the password has been saved, it will no longer show up in the UI as it is encrypted.

    

    To learn more about creating service accounts, generating credentials and using them to create connectors, view the guides here.

📘

If there is an Auth method you would like Moveworks to Support. Please reach out to the Support Team.

• Once you have provided the credentials for your authentication type, go ahead and click Save.

Please make sure you provide the correct credentials and inputs. Once a connector is created, it cannot be deleted. Although you can have multiple connectors per system and can also edit existing connectors.

Validation

In order to validate if the connector which has been setup is working as expected, We need to navigate to the User Identity > Import Users where we need to select the connector for the source we have set up.

You will see a table with all the identity sources that you have previously selected. Here you will come across a "View Sample" button for each source. This is a quick way to check if the connector being used for the source system is configured correctly.

Clicking on "View Sample" makes a live API call to the source system and fetches the identity data using the default attributes if the connector has been setup correctly.

📘

Native Connector Validation is coming soon !

The current validation method serves as a workaround until we support native connector validation.

---

How to Setup a Creator Studio Connector?

Prerequisites

• Ensure you have the appropriate permission to use Moveworks Setup. You must have have either an Admin or user roles assigned to you in order to create and view connectors.
• Ensure that you have provided correct access to the service account you are using for creating a connector. Since these permissions are associated with systems which are not natively integrated with Moveworks you will need to look up the appropriate documentation for the same.
• Network Allowlisting - Please make sure that our production services can access your applications. See documentation.

Configuration

We start by setting the Basic connector Info where we start by providing :

• Name
• Description
• Base URL
• Auth Config

Securely store credentials based on your auth type:

Setting up Connector Auth Types

Creator Studio connectors support multiple auth types below :

No Auth

• Authorization details will not be included in a request sent by Moveworks unless you specify an authentication method.
• If your request does not need authorization, simply choose No Auth from the Auth Config dropdown list.

API Key Auth

• In order to setup a Connector using API Key Auth you can follow the guide here.

Bearer Token Auth

• Bearer Token Auth can be configured the same way that API Key Auth is configured.

Basic Auth

• Basic authentication entails sending a validated username and password along with your request.
• The Authorization header sends the API a Base64 encoded string that encapsulates your username and password values, preceded by the term 'Basic' in the following format:
  Basic Base64Encoded("<username>:<password>")
• To set this up, choose Basic Auth from the Auth Config dropdown list.
• Next, input your API username and password into their respective fields.

OAuth 2.0 with Grant Type : Client Credentials

• OAuth 2.0 with Client Credentials grant type entails sending a valid Client ID and Client Secret in exchange for an Access Token. This Access Token is then used in subsequent requests, usually as a Bearer Token, to authenticate the API Request.
• To set this up, choose Oauth2 from the Auth Config dropdown list.
• Required Info :

• Oauth 2 Grant Type: This should be set to Client Credentials Grant

• Client ID: This is where you input your actual Client ID value itself.

• Client Secret: This is where you input your actual Client Secret value itself.

• Client Credentials Grant Scope: This is where you can optionally input scopes associated with the OAuth credentials.

  • Note: Multiple scopes are separated by a single space

• Oauth2 Token Url: This is where you input the full token URL.

• Oauth2 Client Authentication: This can be left blank.
  Moveworks will try making the request with both Basic Auth and Request Body Auth by default.
• Header Auth Key, Header Auth Value Pattern, Oauth2 Custom Grant Type, Oauth2 Custom Oauth Request Options Custom Grant Type, Oauth2 Custom Oauth Request Options Additional Headers should all be left blank.
• If needed, you can leverage Oauth2 Custom Oauth Request Options Additional Request Data to send additional body data needed for the request.
  • Data is sent in x-www-form-urlencoded format in the body like so:
  JSON

  curl --location 'URL' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=abcd-1234' \
  --data-urlencode 'client_secret=secret123456' \
  --data-urlencode 'Custom-body=abcde12345' \
  

OAuth 2.0 with Grant Type : Refresh Token

• OAuth 2.0 with Refresh Token grant type entails sending a valid Client ID and Client Secret in exchange for an Access Token and a Refresh Token.
• This Access Token is then used in subsequent requests, usually as a Bearer Token, to authenticate the API Request. When this Access Token is expired, the Refresh Token is used to retrieve a new one from the token url.
• To set this up, choose Oauth2 from the Auth Config dropdown list.

• Oauth 2 Grant Type: This should be set to Refresh Token Grant

• Client ID: This is where you input your actual Client ID value itself.

• Client Secret: This is where you input your actual Client Secret value itself.

• Refresh Token Grant Refresh Token: This is where you input your actual Refresh Token value itself.

• Client Credentials Grant Scope: Leave this blank.

• Oauth2 Token Url: This is where you input the full token URL.

• Oauth2 Client Authentication: This can be left blank.
  Moveworks will try making the request with both Basic Auth and Request Body Auth by default.
• Header Auth Key, Header Auth Value Pattern, Oauth2 Custom Grant Type, Oauth2 Custom Oauth Request Options Custom Grant Type, Oauth2 Custom Oauth Request Options Additional Headers, and Oauth2 Custom Oauth Request Options Additional Request Data should all be left blank.

OAuth 2.0 with Grant Type : Password Credentials

• OAuth 2.0 Password Credentials is an authentication method that allows a user to exchange their username and password for an Access Token.
• This Access Token can be used in subsequent requests to authenticate API calls, typically as a Bearer Token.
  When the Access Token expires, the user's credentials can be used to obtain a new one from the authorization server.
• To set this up, choose Oauth2 from the Auth Config dropdown list.

Required Info for the connector.

• Oauth 2 Grant Type: This should be set to Password Grant

• Client ID: This is where you input your actual Client ID value itself.

• Client Secret: This is where you input your actual Client Secret value itself.

• Password Grant Username: This is where you input your actual Username value itself.

• Password Grant Password: This is where you input your actual Password value itself.

• Oauth2 Token Url: This is where you input the full token URL.

Now we move on to adding the additional info in the connector.

• Oauth2 Client Authentication: This can be left blank.
  Moveworks will try making the request with both Basic Auth and Request Body Auth by default.
• Header Auth Key, Header Auth Value Pattern, Oauth2 Custom Grant Type, Oauth2 Custom Oauth Request Options Custom Grant Type should all be left blank.
• If needed, you can leverage Oauth2 Custom Oauth Request Options Additional Headers to send additional Headers needed for the request.
  • This is what your headers will look like:

  Client-Id: XXX
  Client-Secret: YYY
  Username: AAA
  Password: BBB
  

  If you want to add any additional headers they'll get added to the headers:

  Client-Id: XXX
  Client-Secret: YYY
  Username: AAA
  Password: BBB
  Customer-Header: Custom-Value
  

• If needed, you can leverage Oauth2 Custom Oauth Request Options Additional Request Data to send additional body data needed for the request.
  • data is sent in x-www-form-urlencoded format in the body like so:
  JSON

  curl --location 'URL' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=abcd-1234' \
  --data-urlencode 'client_secret=secret123456' \
  --data-urlencode 'Custom-body=abcde12345' \
  

OAuth 2.0 with Grant Type : jwt-bearer

• In order to setup this Auth Type please follow our guide for setting up OAuth 2.0 - JWT Bearer Auth.

On Premise Auth

On Premise Auth is used when you want to leverage the Moveworks On Premise Agent for your authentication. If you choose to do this, please follow these steps. Please be sure to be on agent version 2.10.*

• Configure the Moveworks On Premise Agent following this installation guide. Please make a note of the Service Name you have entered during the agent configuration as you’ll need it later.
• Create the connector with “On Premise Auth” as the authentication type. Enter the service name from step 1.

Auth Types Not Currently Supported:

If you need to use any of the below connectors for your use case, please make an idea post in Moveworks Community.

• OAuth 2.0 - Grant Type: Authorization Code
• OAuth 1.0
• Cookie Auth
• Client Credentials Header Auth
• PKI Auth
• NTLM Auth

---

How to Edit Creator Studio Connector Credentials

• Navigate to Creator Studio Connectors within my apps

• Select the edit button for the connector you wish to change.

• You're taken to a page that resembles the authentication tab when creating a new connector. You are able to edit any fields that need to be changed here.

❗️

Secret Values will NOT be revealed.

Please note that your secret key will show up as empty in the UI if it has been previously saved. If you change a non-secret value, but the secret stays blank, the secret will not be changed. However, if you put in a new secret, it will be overwritten.

• After you are done making your edits, press the save button and the connector will be updated with the new values. Changes may take ~3-5 minutes to process.
• After changes are saved, go test your connector. To do this:
  • Go to an action, event, path, or query that is using the edited connector.
  • Test that the connector is working as intended through the HTTP editor.
  • Go back to Creator Studio Connectors -> Edit to make any changes after testing.
  • Repeat if necessary.

This feature is still in Limited Preview. Please request access for it through this community post.

If you request access, you must also acknowledge the following limitations:

• Moveworks does not currently support role based access control for connectors. This means that with this features, developers will be edit connectors that they have not created. Please be cautious when editing connectors and ensure that you are editing the correct one.
• There is currently no visibility into which plugins will be affected as part of this change. When making connector edits, make sure that you are aware of the plugins you will be affected and do rigorous testing.

How to Delete a connector

1. Navigate to Creator Studio Connectors within my apps

2. Select the delete icon for the connector you wish to delete.

   

3. Confirm that you wish to delete the connector. Please be cautious, it is not possible to undo this change.

   

If you get an error such as the one picture below, it means that you're connector is still in use in Creator Studio. Please be sure to delete all references of that connector and try again