cancel
Showing results for 
Search instead for 
Did you mean: 
cancel

ISE ERS API Examples

22523
Views
17
Helpful
0
Comments

image.png

 

 

Get Started

 

Devnet Documentation

 

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).

 

Note: its good practice to disable CSRF to make sure you are able to authenticate successfully

 

Optionally: You can map external AD groups to these RBAC groups mentioned above. You can find the option external in ERS Admin and ERS operator group for that.

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
    Name ers-admin ers-operator
    Status Enabled Enabled
    Password ****** ******
    Re-Enter Password ****** ******
    Admin Groups ERS Admin ERS 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 Extension Chrome Poster Extension

 

All extensions have the same basic options.

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

 

Field GET
URL https://198.18.133.27:9060/ers/config/node
Method GET (Read)
Username ers-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, --insecure Accept 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 with the file:

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'

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

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

 We don't have any examples of Delete, yet.

 

Resources

CreatePlease to create content
Ask the Expert- DMVPN on Cisco routers