ISE ERS API Examples

 

 

Get Started

 

Enable the ERS APIs

The ERS APIs are disabled by default for security so you must enable it.

  1. Login to your ISE PAN
  2. Navigate to Administration > System > Settings and select ERS Settings from the left panel.
  3. Enable the ERS APIs by selecting Enable ERS for Read/Write
  4. Select Save to save your changes.

 

After enabling ERS, it is available for Create, Read, Update, Delete (CRUD) operations on an ISE Policy Administration Node (PAN) and for Read-Only access (GET requests) on any ISE Policy Service Node (PSN).

 

 

View the ERS API SDK

  1. You may use the default admin account to view the ISE ERS Software Development Kit (SDK) at https://ise.domain.com:9060/ers/sdk

 

Create ERS API Users

You can use the default ISE admin account for ERS APIs since it has SuperUser privileges. However, it is recommended to create separate users with the ERS Admin (Read/Write) or ERS Operator (Read-Onlly) privileges to use the ERS APIs so you can separately track and audit their activities.

  1. Navigate to Administration > System > Admin Access
  2. Choose Administrators > Admin Users from the left pane
  3. Choose  +Add > Create an Admin User to create a new ers-admin and ers-operator accounts.
    New Administrator
    Nameers-adminers-operator
    StatusEnabledEnabled
    Password************
    Re-Enter Password************
    Admin GroupsERS AdminERS Operator

 

 

 

How to Invoke the REST APIs

 

Browser Extensions

Probably the easiest and most accessible way for most users to play with REST APIs is via a web browser extensions.

 

Firefox RESTED ExtensionChrome Poster Extension

 

All extensions have the same basic options.

To get a list of all ISE nodes in your deployment, try the following :

 

FieldGET
URLhttps://198.18.133.27:9060/ers/config/node
MethodGET (Read)
Usernameers-admin
Password******
Headers

Content-Type: application/json

Accept-Type: application/json

 

 

cURL

 

If you prefer to use a command line, the cURL utility is probably the best and easiest choice for doing quick and dirty REST API calls.

 

To get a list of all ISE nodes in your deployment, try the following :

curl --include --header 'Accept: application/json' --user admin:C1sco12345  https://198.18.133.27:9060/ers/config/node

 

cURL

Option


Description
-H, --header <header>

Header to include in the request.

Use one per header.

-i, --include

Include the HTTP result headers in the output.

This is useful after creating (HTTP POST/PUT) an object to get it's Location identifier:

Location: https://198.18.133.27:9060/ers/config/internaluser/75a43806-bd5e-42ef-80a8-c47e759234bd

-k, --insecureAccept insecure connections. Useful if you are playing with ISE using a self-signed certificate.
-u, --user <username:password>Specify the username & password to authenticate the ERS user

 

 

 

Create

 

Create an Internal User with an XML File

 

Version : ISE 1.3

Create an add_internal_user.xml XML file to create user user2 :

 

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns3:inernaluser xmlns:ns2=“ers.ise.cisco.com” xmlns:ns3=“identity.ers.ise.cisco.com” name=“user2”>
  <changePassword>true</changePassword>
  <customAttribute/>
  <enabled>true</enabled>
  <firstName>first</firstName>
  <lastName>last</lastName>
  <password>C!sco123</password>
</ns3:internaluser>



 

Run the curl command:

curl -v -X POST -k --tlsv1 -H "Content-Type: application/vnd.com.cisco.ise.identity.internaluser.1.0+xml" https://ers-admin:ers-password@ise.domain.com:9060/ers/config/internaluser -d @add_internal_user.xml

 

 

 

Create an Internal User with cURL and JSON

 

Create and enable the user 'thomas' in the default Internal Users database and do not require him to change his password upon login:

curl --include --header 'Content-Type:application/json' --header 'Accept: application/json' --user admin:C1sco12345 --request POST https://198.18.133.27:9060/ers/config/internaluser  --data '

{

  "InternalUser" : {

    "name" : "thomas",

    "password" : "C1sco12345",

    "changePassword" : false

  }

}'

Response:

HTTP/1.1 201 Created

Set-Cookie: JSESSIONIDSSO=D4C830896B06B529CECCA61640B0193D; Path=/; Secure; HttpOnly

Set-Cookie: APPSESSIONID=C93E2BE40459768481F24D6DFA10B29D; Path=/ers; Secure; HttpOnly

Cache-Control: no-cache, no-store, must-revalidate

Pragma: no-cache

Expires: Thu, 01 Jan 1970 00:00:00 GMT

Location: https://198.18.133.27:9060/ers/config/internaluser/75a43806-bd5e-42ef-80a8-c47e759234bd

Date: Sat, 17 Mar 2018 20:32:31 GMT

Content-Type: application/json;charset=utf-8

Content-Length: 0

Server:

 

 

 

Read

 

 

Get All ISE Administrators Using cURL and JSON

curl  --header  'Accept: application/json'  --user admin:C1sco12345  https://198.18.133.27:9060/ers/config/adminuser

Response:

{

  "SearchResult" : {

    "total" : 1,

    "resources" : [ {

      "id" : "55c1b32f-9a89-4969-9ba2-151c8b03d3f1",

      "name" : "admin",

      "description" : "Default Admin User",

      "link" : {

        "rel" : "self",

        "href" : "https://198.18.133.27:9060/ers/config/adminuser/55c1b32f-9a89-4969-9ba2-151c8b03d3f1",

        "type" : "application/xml"

      }

    } ]

  }

}

 

 

Get Endpoints by Endpoint GroupID

 

Version : ISE 1.3

Get endpoints per endpoint group and perform appropriate action.

curl  --header  'Accept: application/json' --user admin:C1sco12345  https://ise-pan.domain.com:9060/ers/config/endpoint?filter=groupId.EQ.210d87c0-c260-11e2-9e10-0050568e01f0

 

 

Get Endpoint ID Group by Name

 

Version : ISE 1.2

Find the endpoint id group with a group name (e.g. GL-0)

curl -k -H 'Accept: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml' --user admin:C1sco12345 'https://ise-pan.domain.com:9060/ers/config/endpointgroup?filter=name.EQ.GL-0'

 

Response :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult xmlns:ns2="ers.ise.cisco.com" total="1">
  <resources>
    <resource name="GL-0" id="d27edfa0-889d-11e3-b246-000c2916b229" description="">
      <link type="application/xml" href="https://ise-pan.domain.com:9060/ers/config/endpointgroup/d27edfa0-889d-11e3-b246-000c2916b229" rel="self"/>
    </resource>
  </resources>
</ns2:searchResult>



 

 

 

Get Endpoint by MAC

 

Find the endpoint id using the MAC address :

curl -k -H 'Accept: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml' --user admin:C1sco12345  'https://ers-username:ers-password@ise-pan.domain.com:9060/ers/config/endpoint?filter=mac.EQ.11:22:33:44:55:66'

Response :

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult xmlns:ns2="ers.ise.cisco.com" total="1">
  <resources>
    <resource id="046f1250-bc6e-11e4-9baf-000c2916b229">
      <link type="application/xml" href="https://ise-pan.domain.com:9060/ers/config/endpoint/046f1250-bc6e-11e4-9baf-000c2916b229" rel="self"/>
     </resource>
   </resources>
</ns2:searchResult>



 

 

 

Get Endpoint Info by Resource ID

 

Get endpoint info by its Resource ID

curl -k 'https://ers-admin:ers-password@ise.domain.com:9060/ers/config/endpoint/046f1250-bc6e-11e4-9baf-000c2916b229' -H 'Accept: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml'

 

ISE Response :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:endpoint xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com" id="046f1250-bc6e-11e4-9baf-000c2916b229">
  <link type="application/xml" href="https://ise-pan.domain.com:9060/ers/config/endpoint/046f1250-bc6e-11e4-9baf-000c2916b229" rel="self"/>
  <groupId>04f15020-f42f-11e2-bd54-005056bf2f0a</groupId>
  <identityStore></identityStore>
  <identityStoreId></identityStoreId>
  <mac>11:22:33:44:55:66</mac><portalUser></portalUser>
  <profileId>36c0ee30-f42f-11e2-bd54-005056bf2f0a</profileId>
  <staticGroupAssignment>false</staticGroupAssignment>
  <staticProfileAssignment>false</staticProfileAssignment>
</ns3:endpoint>



 

 

 

Update

 

 

Update Endpoint : Statically Assign to an Identity Group

 

Create an XML file named endpoint.xml with the endpoint changes :

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:endpoint xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com">
  <groupId>d27edfa0-889d-11e3-b246-000c2916b229</groupId>
  <identityStore></identityStore>
  <identityStoreId></identityStoreId>
  <mac>11:22:33:44:55:66</mac>
  <portalUser></portalUser>
  <profileId>36c0ee30-f42f-11e2-bd54-005056bf2f0a</profileId>
  <staticGroupAssignment>true</staticGroupAssignment>
  <staticProfileAssignment>false</staticProfileAssignment>
</ns3:endpoint>







 

Note: To remove an endpoint from an ID group, simply change staticGroupAssignment to false.

 

Update ISE using the XML file above :

curl -k -X PUT 'https://ers-username:ers-password@ise-pan.domain.com:9060/ers/config/endpoint/046f1250-bc6e-11e4-9baf-000c2916b229' -H 'Content-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml; charset=utf-8' -d @endpoint.xml

 

ISE Response :

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <ns2:updatedFields xmlns:ns2="ers.ise.cisco.com">
  <updatedField field="groupId">
    <newValue>d27edfa0-889d-11e3-b246-000c2916b229</newValue>
    <oldValue>04ea7250-f42f-11e2-bd54-005056bf2f0a</oldValue>
  </updatedField>
  <updatedField field="staticGroupAssignment">
    <newValue>true</newValue>
    <oldValue>false</oldValue>
  </updatedField>
</ns2:updatedFields>







 

 

 

Delete

 

 

 

 

Resources