-
Notifications
You must be signed in to change notification settings - Fork 21
pxGrid Provider
pxGrid nodes connect to pxGrid Controller to perform control operations that facilitates communications between consumer nodes and provider nodes.
This guide discuss HTTP APIs use by provider nodes.
The HTTP APIs are all POST methods using JSON:
Request URL: https://<pxgrid-hostname>:8910/pxgrid/control/[method]
Request Method: POST
Content-Type: application/json
Accept: application/json
Authorization: Basic [nodeName]:[password if password-based authentication, otherwise empty string]
[nodeName] has a limit of 100 characters. It can contains alphanumerics (a-z, 0-9), dashes (-), underscores (_), and periods (.). It is case-insensitive.
Steps required for providing pxGrid supported services:
| Name | Description | |
|---|---|---|
| 1 | AccountActivate | Activate once at provider startup |
| 2 | ServiceRegister/ServiceReregister/ServiceUnregister | |
| 3 | AccessSecret | Get unique secret between 2 nodes |
| 4 | Authorization | If required, this is used to check authorization |
https://<pxgrid-hostname>:8910/pxgrid/control/AccountActivate
Client must activate the account before proceeding to other APIs. The 'accountState' in the response can be PENDING, DISABLED or ENABLED. ISE UI will display the new account in PENDING state for administrator to approve.
For PENDING state, the recommended wait time for retrying AccountActivate is at least 60 seconds. For DISABLED state, the recommended wait time for retrying AccountActivate is at least 5 minutes. Once ENABLED state is responded, the consumer can continue to use other APIs.
{ "description": string (max 50 characters. Alphanumerics, spaces, underscores(_), comma(,), dashes(-) and periods(.)) }
{ "accountState": string (PENDING,DISABLE or ENABLED) "version": string (e.g "2.0.2.1") }
https://<pxgrid-hostname>:8910/pxgrid/control/ServiceRegister
ServiceRegister is used to register a service name with its properties and operations.
name is a string (alphanumerics and periods(.) of max 50 characters)
properties will be sent to the consumers who is looking up for the service. It is an array of name and value pairs.
name is a string (alphanumerics of max 50 characters).
value is a string (max 100 characters).
operations are array of service and operation pairs this provider will used for Authorization API. This lets the pxGrid controller knows the possible combinations of services and operations, in which can be used to setup rules.
service is a string (alphanumerics and periods(.) of max 50 characters).
operation is a string (alphanumerics of max 50 characters).
ServiceRegister returns id and a reregisterTimeMillis.
id is used for subsequence ServiceReregister and ServiceUnregister commands.
reregisterTimeMillis is the time in milliseconds that this service must re-register in order to keep the service alive.
Otherwise, pxGrid Controller will assume the service is no long available and remove the entry.
{
"name":"com.cisco.ise.config.anc",
"properties":
{
"restBaseUrl":"https://pxgrid-041.cisco.com:8910/pxgrid/ise/config/anc",
"wsPubsubService":"com.cisco.ise.pubsub",
"statusTopic":"/topic/com.cisco.ise.config.anc.status"
},
"operations":[
{
"service": "com.cisco.ise.config.anc",
"operation": "gets"
},
{
"service": "com.cisco.ise.config.anc",
"operation": "sets"
},
{
"service": "com.cisco.ise.pubsub",
"operation": "publish /topic/com.cisco.ise.config.anc.status"
},
{
"service": "com.cisco.ise.pubsub",
"operation": "subscribe /topic/com.cisco.ise.config.anc.status"
}
]
}{
"id":"123",
"reregisterTimeMillis":60000
}https://<pxgrid-hostname>:8910/pxgrid/control/ServiceReregister
ServiceReregister is used to signify that the service is still active.
This must be periodically triggered according to the reregisterTimeMillis
ServiceReregister returns nothing.
{
"id":"123"
}{
}https://<pxgrid-hostname>:8910/pxgrid/control/ServiceReregister
ServiceUnregister is used to un-register a service.
{
"id":"123"
}{
}https://<pxgrid-hostname>:8910/pxgrid/control/AccessSecret
AccessSecret is a unique secret between a Consumer and Provider pair. The use of the secret is dictated by the implementation of the Provider. In the case of ISE, the secret is used as the pasword of HTTP Basic Auth.
{
"peerNodeName":"ise-admin-pxgrid-002"
}{
"secret":"oWhgNC7oNpaulpJ6"
}https://<pxgrid-hostname>:8910/pxgrid/control/Authorization
This is to check the authorization of the requestNodeName to see if it is allowed to perform serviceOperation of serviceName.
The response authorization can be either PERMIT or DENY.
{
"requestNodeName":"node1",
"serviceName":"com.cisco.ise.config.anc",
"serviceOperation":"gets"
}{
"authorization":"PERMIT"
}Multiple pxGrid nodes can be enabled in ISE to provide high availability. All the pxGrid nodes provide the same functionality. A client should be configured with the IP addresses to all and make the call until one of the nodes works.
If none of the nodes work, it is recommended to retry at least 60 seconds later.
pxGrid account can be authenticated by certificate or password.
Certificate-based authentication requires the use of a certificate that is trusted by ISE. Perform AccountActiviate using the client certificate, fill the Basic Auth header with username only.
Password-based authentication requires AccountCreate first to obtain a password, and then perform AccountActivate using the credentials obtained.
Subsequence call will use Basic Auth header with "[username]:" for certificated-based authentication, or "[username]:[password]" for password-based authentication.
https://<pxgrid-hostname>:8910/pxgrid/control/AccountCreate
This is for password-based authentication only. AccountCreate feature is disabled by default and has to be enabled via ISE UI.
This call does not require authentication.
It creates an account with nodeName and returns a generated password for subsequence calls.
[nodeName] has a limit of 100 characters. It can contains alphanumerics (a-z, 0-9), dashes (-), underscores (_), and periods (.). It is case-insensitive.
If the feature is not enabled, an HTTP "503 Service Unavailable" will be returned. If an account with the same nodeName already exist, an HTTP "409 Conflict" will be returned.
{
"nodeName":"MyName01"
}{
"nodeName":"MyName01",
"password":"P9nEaNX0cyA4DRBr"
}