The Generic REST Provisioning connector supports all Create, Read, Update & Delete actions on users in target systems that do not support SCIM but do have a user management REST API available.
Adding the Generic REST Provisioning Connector
- In your OneLogin Administrative account, go to Applications > Applications > Add App.
- In the search field, enter Generic REST.
- Select the Generic REST Provisioning connector.
- Specify a name for the connector and click Save.
Parameters
In the Parameters tab you will add any additional parameters that you want to provision to your application.
By default, the user fields firstname, lastname, email and username are available in the default template to use as values to pass to the REST API parameters. It is only necessary to add additional parameters if you want to pass through other user fields. However, it is also recommended to update the template to use parameters for the firstname, lastname, email and username values as well.
Configuration
Go to the Configuration tab. The Application Details section at the top of the page is used to configure the REST API calls. If you will need to configure single sign-on for your application using a different connector.
- The API Communication (JSON) text box contains a sample JSON configuration that could be used to provision users into another OneLogin tenant.
- It will be necessary to modify the JSON template to define how the connector will communicate with the external system’s REST API for supported actions.
The template contains seven sample REST API actions as separate objects within the JSON:
- create
- update
- disable
- enable
- delete
- search
- lookup
OAuth 2.0 get token
Each call that uses OAuth 2.0 authentication begins with a get_token object. This is used to define the Auth Type used to connect to the API endpoint. Values such as API keys, Passwords, Client Secrets can be defined in the Target System Secret 1 and Target System Secret 2 text boxes below the API Communication (JSON) text box. Target System Secret 1 maps to {$parameters.secret1} and Target System Secret 2 maps to {$parameters.secret2}.
In the sample, you can see {$parameters.secret1} and {$parameters.secret2} are used to pass in Client ID and Client Secret to the OneLogin REST API.
The output of the get_token call is used as input to authenticate the subsequent call as defined by the next sub object. In the default template, the output is an access token that is included as a bearer token in the authorization header of the subsequent call. Each high-level object (“create”, “update”, “enable”, “disable”, etc.) then contains a sub object that defines which REST API call and parameters to use to perform each method.
For example, the “create” object contains the API endpoint, parameters, etc.
The Parameters can match to user fields and/or custom fields. For more information, see Provisioning Additional Attributes.
The “path” attribute defines which API endpoint will perform the desired action such as Create a user, and the “method” attribute defines the HTTP verb to be used.
NOTE: the full path of the endpoint is not specified. The first part is defined at the end the JSON with the base_url name/value pair.
The “responses” object is used to define the expected response and how to extract data from the response. In the example above, a successful user creation results in a HTTP 201 response. The “extract” object defines that the unique id of the newly created user (which OneLogin requires for subsequent operations) is taken from the “id” parameter in the response body.
This id can then be referenced in other parts of the template, such as the update operation. It is referred to as {$login.provisioning_user_id}
If a request does not return anybody, then you can skip the extract section completely. An example is when deleting a user.
The full sample that comes with the Generic REST Provisioning Connector can be found here:
{
"create": [
{
"name": "get_token",
"description": "Obtain oauth2 access token for Target OneLogin Tenant via client credentials flow",
"path": "/auth/oauth2/v2/token",
"method": "post",
"headers": {
"Content-Type": "application/json",
"Authorization": "client_id:{$parameters.secret1}, client_secret:{$parameters.secret2}"
},
"body": {
"grant_type": "client_credentials"
},
"responses": {
"200": {
}
}
},
{
"name": "Create_User_OneLogin",
"description": "Task to create users in the Target OneLogin Tenant",
"body": {
"email": "{$user.email}",
"firstname": "{$user.firstname}",
"lastname": "{$user.lastname}",
"username": "{$user.username}"
},
"method": "post",
"path": "api/2/users",
"headers": {
"Authorization": "bearer {$responses.get_token.body.access_token}",
"Content-Type": "application/json"
},
"responses": {
"201": {
"extract": {
"*by_path": "body.id"
}
}
}
}
],
"update": [
{
"name": "get_token",
"description": "Obtain oauth2 access token for Target OneLogin Tenant via client credentials flow",
"path": "/auth/oauth2/v2/token",
"method": "post",
"headers": {
"Content-Type": "application/json",
"Authorization": "client_id:{$parameters.secret1}, client_secret:{$parameters.secret2}"
},
"body": {
"grant_type": "client_credentials"
},
"responses": {
"200": {
}
}
},
{
"name": "Update_User_OneLogin",
"description": "Task to update users in the Target OneLogin Tenant",
"path": "api/2/users/{$login.provisioning_user_id}",
"headers": {
"Authorization": "bearer {$responses.get_token.body.access_token}",
"Content-Type": "application/json"
},
"method": "put",
"body": {
"email": "{$user.email}",
"firstname": "{$user.firstname}",
"lastname": "{$user.lastname}",
"username": "{$user.username}"
},
"responses": {
"200": {
"extract": {
"*by_path": "body.id"
}
}
}
}
],
"disable": [
{
"name": "get_token",
"description": "Obtain oauth2 access token for Target OneLogin Tenant via client credentials flow",
"path": "/auth/oauth2/v2/token",
"method": "post",
"headers": {
"Content-Type": "application/json",
"Authorization": "client_id:{$parameters.secret1}, client_secret:{$parameters.secret2}"
},
"body": {
"grant_type": "client_credentials"
},
"responses": {
"200": {
}
}
},
{
"name": "Disable_User_OneLogin",
"description": "Task to disable users in the Target OneLogin Tenant when they are disabled in the source tenant",
"path": "api/2/users/{$login.provisioning_user_id}",
"headers": {
"Authorization": "bearer {$responses.get_token.body.access_token}",
"Content-Type": "application/json"
},
"method": "put",
"body": {
"status": "{$user.status}"
},
"responses": {
"200": {
"extract": {
"*raw": "{$login.provisioning_user_id}"
}
}
}
}
],
"enable": [
{
"name": "get_token",
"description": "Obtain oauth2 access token for Target OneLogin Tenant via client credentials flow",
"path": "/auth/oauth2/v2/token",
"method": "post",
"headers": {
"Content-Type": "application/json",
"Authorization": "client_id:{$parameters.secret1}, client_secret:{$parameters.secret2}"
},
"body": {
"grant_type": "client_credentials"
},
"responses": {
"200": {
}
}
},
{
"name": "Enable_User_OneLogin",
"description": "Task to enable users in the Target OneLogin Tenant when they are enabled in the source tenant",
"path": "api/2/users/{$login.provisioning_user_id}",
"headers": {
"Authorization": "bearer {$responses.get_token.body.access_token}",
"Content-Type": "application/json"
},
"method": "put",
"body": {
"status": "{$user.status}"
},
"responses": {
"200": {}
}
}
],
"delete": [
{
"name": "get_token",
"description": "Obtain oauth2 access token for Target OneLogin Tenant via client credentials flow",
"path": "/auth/oauth2/v2/token",
"method": "post",
"headers": {
"Content-Type": "application/json",
"Authorization": "client_id:{$parameters.secret1}, client_secret:{$parameters.secret2}"
},
"body": {
"grant_type": "client_credentials"
},
"responses": {
"200": {
}
}
},
{
"name": "Delete_User_OneLogin",
"description": "Task to delete users in the Target OneLogin Tenant when this Workflow Application is unassigned",
"path": "api/2/users/{$login.provisioning_user_id}",
"headers": {
"Authorization": "bearer {$responses.get_token.body.access_token}",
"Content-Type": "application/json"
},
"method": "delete",
"responses": {
"204": {}
}
}
],
"search": [
{
"name": "get_token",
"description": "Obtain oauth2 access token for Target OneLogin Tenant via client credentials flow",
"path": "/auth/oauth2/v2/token",
"method": "post",
"headers": {
"Content-Type": "application/json",
"Authorization": "client_id:{$parameters.secret1}, client_secret:{$parameters.secret2}"
},
"body": {
"grant_type": "client_credentials"
},
"responses": {
"200": {
}
}
},
{
"name": "Search_User_OneLogin",
"description": "Task to search for the user to see if already existing in the Target OneLogin Tenant when this Workflow Application is assigned",
"path": "api/2/users",
"headers": {
"Authorization": "bearer {$responses.get_token.body.access_token}",
"Content-Type": "application/json"
},
"parameters": {
"email": "{$user.email}"
},
"responses": {
"200": {
"extract": {
"*by_path": "body.0.id"
}
}
}
}
],
"lookup": [
{
"name": "get_token",
"description": "Obtain oauth2 access token for Target OneLogin Tenant via client credentials flow",
"path": "/auth/oauth2/v2/token",
"method": "post",
"headers": {
"Content-Type": "application/json",
"Authorization": "client_id:{$parameters.secret1}, client_secret:{$parameters.secret2}"
},
"body": {
"grant_type": "client_credentials"
},
"responses": {
"200": {
}
}
},
{
"name": "Lookup_User_OneLogin",
"description": "Task to lookup the user in the target OneLogin environment after the create or update action runs and will return the user profile",
"path": "/api/2/users/{$login.provisioning_user_id}",
"headers": {
"Authorization": "bearer {$responses.get_token.body.access_token}",
"Content-Type": "application/json"
},
"responses": {
"200": {
"extract": {
"email": {
"*by_path": "body.email"
},
"username": {
"*by_path": "body.email"
},
"user_id": {
"*by_path": "body.id"
},
"first_name": {
"*by_path": "body.firstname"
},
"last_name": {
"*by_path": "body.lastname"
}
}
}
}
}
],
"base_url": "https://{ol_subdomain}.onelogin.com",
"skip_empty_body_properties": true
}The “update”, “enable”, “disable”, “delete” and “lookup” operations all act on an account in the endpoint that is already linked to a OneLogin user. OneLogin identifies the account with the parameter {$login.provisioning_user_id}, which was obtained by extracting the unique id returned from the “create” operation. In most cases, this will be included in the request URL, as shown above. For some APIs, this may be included in the request body instead.
The ”search” operation is used to check whether an account already exists in the endpoint. This is called when a user is assigned to the application in OneLogin. The connector will first “search” for an account with the same user id in the endpoint. If an account is found, the “update” operation is performed, and the account is updated with the data from OneLogin. If no account is found, the “create” operation is performed and a new account is created in the endpoint and linked to OneLogin.
The ”parameters” object defines the query string that is used in the “search” operation. In the above example, the parameters are defined as:
"email": "{$user.email}"
The attribute name is the first part of the query string (before the = sign) and the attribute value is the second part of the query string. This means that the user’s email value from OneLogin is used to make an API call as follows:
api/2/users?email=example.user@mydomain.com
The “extract” object defines how to get the unique id of the user from the search results.
You can define more complex search criteria and extraction. For example, if you were searching for a user in Entra ID via the list users API, you could use the following syntax:
{
"path": "/v1.0/users",
"parameters": {
"$filter": "mail eq '{$parameters.email}'"
},
"responses": {
"200": {},
"extract": {
"*by_path":"body.value.0.id"
}
}
}
You will need to click the Enable button under API Connection to ensure that the connector will work.
You can insert a pause between two tasks by using the following code:
{
"s": 15,
"ms": 1500
}"create": [{
"s": 15,
"ms": 1500
},
{
"name": "Dummy Task that will never execute",
"path": "/api/now/table/sc_req_item",
"method": "post",
"headers": {
"Authorization": "Basic ######################",
"Content-Type": "application/json",
"Accept": "application/json"
},
"body": {
"short_description": "Request for a new laptop for {$user.email} from OneLogin Integration",
"quantity": "1",
"cat_item": "{$parameters.cat_item}",
"requested_for": "{$user.username}"
},
"responses": {
"201" : {},
"extract":{
"*raw":"{$user.id}"
}
}
}
]You can also connect to a target system that supports Basic Auth. The following example outlines how to connect to a developer ServiceNow instance and perform user lifecycle management activities using Basic Auth.
{
"create": [
{
"name": "Create_User_SNOW",
"description": "Task to create users in the Target ServiceNow environment",
"path": "/api/now/table/sys_user",
"method": "post",
"body": {
"user_name": "{$parameters.username}",
"first_name": "{$parameters.firstname}",
"last_name": "{$parameters.lastname}",
"email": "{$parameters.email}",
"title": "Developer",
"department": "IT"
},
"responses": {
"201" : {},
"extract":{
"*by_path": "body.result.sys_id"
}
}
}
],
"update": [
{
"name": "Update_User_SNOW",
"description": "Task to update users in the Target ServiceNow environment",
"path": "/api/now/table/sys_user/{$login.provisioning_user_id}",
"method": "put",
"body": {
"user_name": "{$parameters.username}",
"first_name": "{$parameters.firstname}",
"last_name": "{$parameters.lastname}",
"email": "{$parameters.email}",
"title": "Developer",
"department": "IT"
},
"responses": {
"200" : {},
"extract":{
"*by_path": "body.result.sys_id"
}
}
}],
"disable": {
"name": "Disable_User_SNOW",
"description": "Task to disable users in the Target ServiceNow environment",
"path": "/api/now/table/sys_user/{$login.provisioning_user_id}",
"method": "put",
"body": {
"active": "false"
},
"responses": {
"200" : {},
"extract":{
"*by_path": "body.result.sys_id"
}
}
},
"enable": {
"name": "Enable_User_SNOW",
"description": "Task to enable users in the Target ServiceNow environment",
"path": "/api/now/table/sys_user/{$login.provisioning_user_id}",
"method": "put",
"body": {
"active": "true",
"locked_out": "false"
},
"responses": {
"200" : {},
"extract":{
"*by_path": "body.result.sys_id"
}
}
},
"delete": [{
"name": "Delete_User_SNOW",
"description": "Task to create users in the Target ServiceNow environment",
"path": "/api/now/table/sys_user/{$login.provisioning_user_id}",
"method": "delete",
"responses": {
"200" : {}
}
}
],
"search": [
{
"name": "Search_User_SNOW",
"description": "Task to search for a user in the Target ServiceNow environment",
"path": "/api/now/table/sys_user",
"parameters": {
"email": "{$user.email}"
},
"responses": {
"200": {},
"extract":{
"*by_path": "body.result.0.sys_id"
}
}
}],
"lookup": [
{
"name": "Lookup_User_SNOW",
"description": "Task to lookup a specific user in the Target ServiceNow environment",
"path": "/api/now/table/sys_user/{$login.provisioning_user_id}",
"responses": {
"200": {
"extract": {
"email": {
"*by_path": "body.result.email"
},
"username": {
"*by_path": "body.result.user_name"
},
"user_id": {
"*by_path": "body.result.sys_id"
},
"first_name": {
"*by_path": "body.result.first_name"
},
"last_name": {
"*by_path": "body.result.last_name"
}
}
}
}
}
],
"base_url": "https://devxxxxxxx.service-now.com",
"headers": {
"Authorization": "Basic {$parameters.secret1}",
"Content-Type": "application/json",
"Accept": "application/json"
},
"skip_empty_body_properties": true
}Extracting and Using Data
You can extract data responses from a target connector using the syntax {$responses.FunctionName.extracted.xyz}, where "xyz" stands for the desired name of the extracted files.
Search_User_SPP function to extract the spp_user_id data.{
"name": "Search_User_SPP",
"description": "Task to search for the userid of the associated user in SPP. This is required for the Create_SPP_Entitlement task ",
"path": "service/core/v4/Users",
"headers": {
"Authorization": "bearer {$responses.get_spp_api_token.body.UserToken}",
"Content-Type": "application/json",
"Accept": "application/json"
},
"parameters": {
"filter": "EmailAddress eq '{$parameters.main_ol_user_email}'"
},
"responses": {
"200": {
"extract": {
"spp_user_id": {
"*by_path": "body.0.Id"
}
}
}
}
},
{
"name": "Create_SPP_Entitlement",
"description": "Task to create role/entitlement in the Target SPP",
"body": {
"Name": "{$user.username}",
"Members": [
{
"Id" : "{$responses.Search_User_SPP.extracted.spp_user_id}"
}
]
},
"method": "post",
"path": "service/core/v4/Roles",
"headers": {
"Authorization": "bearer {$responses.get_spp_api_token.body.UserToken}",
"Content-Type": "application/json",
"Accept": "application/json"
},
"responses": {
"201": {
}
}
}Provisioning Users
Go to the Provisioning tab and select Enable Provisioning. For your initial testing, you might want to leave the Require Admin Approval options selected for the create, delete, and update operations.
Select appropriate values for the user deletion and user suspension operations in OneLogin as per your requirements, then click Save.
You can then go to the Access tab and assign a role to the application. All members of the role will be provisioned to the application.
Provisioning Additional Attributes
In the Parameters tab, you can add additional parameters:
These parameters can then be used within the JSON when necessary:
For the attribute values, the syntax $user means that the value is taken directly from the user’s equivalent attribute value. For example $user.lastname maps to the user’s last name value.
The syntax $parameter means that the value is taken from the user’s attribute that is mapped in the Parameters tab. The name here must exactly match the API name in the Parameters tab. E.g. “$parameters.department” corresponds to the “department” in the Parameters tab.
Note how the firstname, lastname, username, and email, attributes are mapped to $user attribute values. These are the only attributes that should be mapped to $user attribute values.
We recommended replacing the attribute values for firstname, lastname, username, and email with $parameter attribute values instead. This gives you more control over, and visibility of, the attribute values used. E.g. the create user part of the template would appear as follows (updates highlighted).
$user with $parameter.You must then add corresponding parameters in the Parameters tab by selecting the plus icon on the top right. In the New Field dialog, enter the field name. The value you enter is both the display name and the API name for the new parameter and is case sensitive. Click Save. In the next screen, select the OneLogin attribute that you wish to map to the new parameter.
When extending the schema with additional attributes, always map them to $parameter attribute values, and add the corresponding parameter, with the exact same name (case sensitive) in the Parameters tab.
If you are unsure which schema or attribute name to use, consult with the application vendor.
NOTE: Only the create, search, and update operations have to return an id value when a provisioning action is attempted.
The following example shows how to get and use an id value from the external system that the API is connected to.
{
"name": "Create_User_OneLogin",
"description": "Task to create users in the Target OneLogin Tenant",
"body": {
"email": "{$user.email}",
"firstname": "{$user.firstname}",
"lastname": "{$user.lastname}",
"username": "{$user.username}"
},
"method": "post",
"path": "api/2/users",
"headers": {
"Authorization": "bearer {$responses.get_token.body.access_token}",
"Content-Type": "application/json"
},
"responses": {
"201": {
"extract": {
"*by_path": "body.id"
}
}
}
}Rules
You can define Rules to map different values to parameters for different sets of users just as you can for any other application connector.