The MSactivator™ provides a support for REST API. These API can be used by third-party service, application or script to manage your MSactivator™ instance.

Enabling REST API support

The API is enabled by default. No additional configuration is required.

Authentication

With version 2.9.x

Starting with MSactivator™ version 2.9.1, the authentication is managed by Keycloak which is included in the product.

When making requests to MSactivator™ using the REST API, you will need:

  • A valid admin username and password (so that a token can be generated and an authenticated session can be established).

  • Appropriate access permissions for the requested resource (controlled by admin profile)

Using curl, you may save the authentication information as a HTTP header to allow subsequent requests to be accepted automatically.

authentication request
curl -k -H 'Content-Type: application/x-www-form-urlencoded' \
  -XPOST https://<MSA IP or FQDN>/auth/realms/main/protocol/openid-connect/token \
  -d 'username=<USERNAME>&password=<PASSWORD>&grant_type=password&client_id=utilisateurs'
authentication response
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ2LW5uQnJkY3NOY1dmVUxDZ2RzUVhQcnptMkFhQzRDbjJPaEhHaFR5VlowIn0.eyJleHAiOjE3MjU1MjA4NjEsImlhdCI6MTcyNTUyMDU2MSwianRpIjoiYTY1Mjk2YjAtYTc0MC00ZjgwLWFlYzItM2Q3YWYzZjU4YTZjIiwiaXNzIjoiaHR0cHM6Ly8xMC4zMS4xLjIyOS9hdXRoL3JlYWxtcy9tYWluIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImY6MDY5MjMwYjctY2ZkZi00OGQ5LWFhMTQtZDMyNmRlMjAwNDRiOjEiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJ1dGlsaXNhdGV1cnMiLCJzZXNzaW9uX3N0YXRlIjoiYmI4NjMyMGYtM2FiNC00ZWYwLTgwNTktYWM2ZWU1ZWZjNTBhIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyIke2F1dGhCYXNlVXJsfSJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSB1YmlSb2xlIGVtYWlsIiwic2lkIjoiYmI4NjMyMGYtM2FiNC00ZWYwLTgwNTktYWM2ZWU1ZWZjNTBhIiwicm9sZSI6IlN1cGVyIEFkbWluaXN0cmF0ZXVyIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJyb2xlX2lkIjoiMSIsIm5hbWUiOiJuY3Jvb3QiLCJhY3Rvcl9pZCI6IjEiLCJ1c2VybmFtZSI6Im5jcm9vdCJ9.Weu9xq82rjA5r-3GQtBU0liNpoyUuj4tDvHlvlWG8gC1iHQo9aV5exfBm3fRlsFyNwR_XBUnOIcg4U8rwF35D58fF3bvC5D3meM1X9WaXx6RYH0qDgoVNfIyqmR0xmj4SWn_gr4C4N3RE8JVUYbnWGwcbbLCI9gP8O9q6POtGPaCT51gSE6bmpYFHU1hpVoPnw99GBFutWi5iNUl4kkKbcBXDwZzbQPN5DE44a_YupGxqsCH7t38duUwilx0gOuVjPRD9itbdNI_wZxyIHB_couxg3RZuSIIJrH100GIcK4Nc6CO8IsZRSZBdsBnuNutuVJAhAzsFahRkvRhFt7LUw",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiYTMwNGY4MS1jMDFkLTRiZDEtYjM2Mi0wOTM0MTExNjhkMTMifQ.eyJleHAiOjE3MjU1MjIzNjEsImlhdCI6MTcyNTUyMDU2MSwianRpIjoiMmQyZjE3YjMtNGRjZi00M2M4LWE3N2ItMTQzYzYzY2U3N2E4IiwiaXNzIjoiaHR0cHM6Ly8xMC4zMS4xLjIyOS9hdXRoL3JlYWxtcy9tYWluIiwiYXVkIjoiaHR0cHM6Ly8xMC4zMS4xLjIyOS9hdXRoL3JlYWxtcy9tYWluIiwic3ViIjoiZjowNjkyMzBiNy1jZmRmLTQ4ZDktYWExNC1kMzI2ZGUyMDA0NGI6MSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJ1dGlsaXNhdGV1cnMiLCJzZXNzaW9uX3N0YXRlIjoiYmI4NjMyMGYtM2FiNC00ZWYwLTgwNTktYWM2ZWU1ZWZjNTBhIiwic2NvcGUiOiJwcm9maWxlIHViaVJvbGUgZW1haWwiLCJzaWQiOiJiYjg2MzIwZi0zYWI0LTRlZjAtODA1OS1hYzZlZTVlZmM1MGEifQ.dHxEnX8Y4mLTASwVuhSbfg1oyr2lzeaVMNiRo0-IYPXq8JAYxzl5V0S5qk9UgEsh6VzksONjjXSgGAEn_pBlmQ",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "bb86320f-3ab4-4ef0-8059-ac6ee5efc50a",
    "scope": "profile ubiRole email"
}

With version 2.8.13 and previous

When making requests to MSactivator™ using the REST API, you will need:

  • A valid admin username and password (so that a token can be generated and an authenticated session can be established).

  • Appropriate access permissions for the requested resource (controlled by admin profile)

Using curl, you may save the authentication information as a HTTP header to allow subsequent requests to be accepted automatically.

authentication request
curl  -k -H 'Content-Type: application/json' \
  -XPOST https://<MSA IP or FQDN>/ubi-api-rest/auth/token \
  -d '{"username":"username", "password":"user password"}'
authentication response
{
	"token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJuY3Jvb3QiLCJpYXQiOjE2NTUxOTQ3MzMsImx2bCI6IjEiLCJleHAiOjE2NTUxOTgzMzN9.kVl5XuqbSnGI59k0dlHmhB9xmPsixS3X24yQ4oWD-S9GgcBWw7X-DAb_S5oqwd0h3R64i_Custn8GeFt34Yzow",  (1)
	"message": "authenticated",
	"authenticated": "true",
	"userDetails": {
		"id": 1,
		"baseRole": {
			"id": 1,
			"name": "Super Administrateur"
		},
		"externalReference": "NCLG1",
		"login": "ncroot",
		"operator": {
			"id": 1,
			"abonnes": [],
			"baseUrl": null,
			"isPartner": false,
			"name": "UBIqube",
			"prefix": "NCL",
			"address": {
				"city": "",
				"country": "",
				"fax": "",
				"mail": "",
				"phone": "",
				"streetName1": "",
				"streetName2": "",
				"streetName3": "",
				"zipCode": ""
			},
			"customersCount": 0,
			"adminsCount": 0,
			"managersCount": 0,
			"externalReference": ""
		},
		"acteurId": 1,
		"address": {
			"city": "",
			"country": "",
			"fax": null,
			"mail": "ncroot@msactivator.com",
			"phone": "",
			"streetName1": "",
			"streetName2": "",
			"streetName3": "",
			"zipCode": ""
		},
		"delegationProfileId": 0,
		"userType": 2,
		"delegations": null,
		"delegationsPerCustomer": {},
		"netceloId": {
			"ubiID": "NCLG1",
			"thePrefix": "NCL",
			"id": 1,
			"customerPrefix": "NCL"
		},
		"isExternalAuth": false,
		"activationKey": "",
		"ccla": false,
		"isActive": true,
		"passwordUpdateDate": "",
		"attachedCustomerIds": null,
		"firstname": "",
		"attachedOperatorIds": null,
		"manageAllUsers": true,
		"name": "ncroot",
		"sort": "NAME",
		"ldapAuthentication": false,
		"delegationProfilePerCustomer": {}
	}
}
1 auth TOKEN

Use the token from the auth response in the Authorization Bearer header to call the MSactivator™ REST API.

curl -H 'Accept: application/json' -H "Authorization: Bearer TOKEN" -XGET 'http://<MSA IP or FQDN>/ubi-api-rest/user/customer-by-manager-id/1

Format

MSactivator™ API uses the JSON format.

Example API commands

For the full list of available commands, see the MSactivator™ API guide on your MSactivator™ instance: http://<MSA IP or FQDN>/swagger

User login

HTTP Request: /ubi-api-rest/auth/token

Method: POST

Parameter Name Type Description

username

String

User name

password

String

Password

Example:

{
	"username": "test",
	"password": "test1234567890"
}

Response:

{
	"token": "<TOKEN>",		(1)
	"message": "authenticated",
	"authenticated": "true",
	"userDetails": {
		"id": 18,

		... (2)

		"externalReference": "UBIG18",
		"login": "test",
		"firstname": "",
		"manageAllUsers": true,
		"name": "test",
		"sort": "NAME",
		"ldapAuthentication": false,
		"delegationProfilePerCustomer": {}
	}
}
1 the authentication token to use in the HTTP header of the REST API calls
2 the JSON response has been shortened for this documentation

Ping an IP address from the CoreEngine

HTTP Request: /ubi-api-rest/device/ping/{$ip_address}

Method: GET

Parameter Name Type Description

ip_address

String

The IP address to ping

Example:

/ubi-api-rest/device/ping/127.0.0.1

Response:

{
	"status": "OK",
	"rawJSONResult": "{\"sms_status\":\"OK\",\"sms_code\":\"\",\"sms_message\":\"--- 127.0.0.1 ping statistics ---\\n5 packets transmitted, 5 received, 0% packet loss, time 3999ms\\nrtt min/avg/max/mdev = 0.031/0.036/0.043/0.006 ms\"}",
	"message": "--- 127.0.0.1 ping statistics ---\n5 packets transmitted, 5 received, 0% packet loss, time 3999ms\nrtt min/avg/max/mdev = 0.031/0.036/0.043/0.006 ms"
}

Call microservice functions

HTTP Request: /ubi-api-rest/ordercommand/execute/{device_id}/{command_name}

Method: POST

Parameter Name Type Description

device_id

Long

The database identifier of the Managed Entity

command_name

String

One of CREATE, UPDATE, DELETE

body

String

the payload with the microservice parameters

Example:

/ubi-api-rest/ordercommand/execute/156/CREATE
{
	"simple_firewall": {
		"789": {
			"object_id": "789",
			"src_ip": "7.8.3.0",
			"src_mask": "255.255.255.0",
			"dst_ip": "8.8.3.0",
			"dst_mask": "255.255.255.0",
			"service": "http",
			"action": "deny"
		}
	}
}

Response:

{
	"commandId": 0,
	"status": "OK",
	"message": "access-list 789 extended deny object http 7.8.3.0 255.255.255.0 8.8.3.0 255.255.255.0 log\n"
}

Configuration variables

HTTP Request: /variables/{deviceId}/{name}

Method: GET

Parameter Name Type Description

deviceId

Long

Id of device (Number format) has to be higher than 0, Example = 3453

name

String

Name of the variable, Example = var1

Configuration

HTTP Request: /system-admin/v1/msa_vars

Method: POST

Body:

[
  {
    "name": "string",
    "lastUpdate": "string",
    "comment": "string",
    "value": "string"
  }
]

Workflow

HTTP Request: orchestration/service/execute/{ubiqubeId}

Method: POST

Parameter Name Type Description

ubiqubeId

String

Id of the subtenant. A combination of the tenant prefix and the subtenant database ID. Example UBI123.

serviceName

String

Relative path of the workflow

processName

String

Relative path of the process

Body:

the payload JSON contains the parameter to pass to the process thus depends on the variables of the workflow

[
  {
    "name": "string",
    "lastUpdate": "string",
    "comment": "string",
    "value": "string"
  }
]

Example: call the process "Create Instance" of the worklflow "Helloworld"

This workflow is part of the MSActivator mini-lab and maintained in a github repository.

POST

/ubi-api-rest/orchestration/service/execute/BLRA7?serviceName=Process/Tutorials/Helloworld/Helloworld&processName=Process/Helloworld/Process_create_instance

{"name":"jack"}