cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Announcements
configure & troubleshoot anyconnect

ISE ERS API Examples

32297
Views
27
Helpful
0
Comments

image.png

 

 

Get Started

Cisco Devnet ISE API Documentation (http://cs.co/ise-api)

ERS API Change Password findings

 

Known issues

If you're processing more than 100 records. These are enhancements.
CSCve05681 ERS Get-All takes very long time for response
CSCvg64354 ENH ISE ERS calls should be processed much faster

 

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

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

We have also published the ISE ERS API SDK Reference (http://cs.co/ise-api) in Cisco DevNet.

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 -k --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

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 -k -v -X POST --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 -k --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:

 To view the user, login to the ISE PAN and navigate to Administration > Identity Management > Groups > User Identity Groups and you should see the new user in the list.

 

 

Create an Endpoint Group and Assign an Endpoint

Create Endpoint Group

Create an Endpoint Group called 'Whitelist':

curl -k  --include --header 'Content-Type:application/json' --header 'Accept: application/json' --user admin:C1sco12345 --request POST https://198.18.133.27:9060/ers/config/endpointgroup  --data '
{
  "EndPointGroup" : {
    "name" : "Whitelist",
    "description" : "Whitelist Group"
  }
}'

Response:

HTTP/1.1 201 Created
Set-Cookie: JSESSIONIDSSO=DE751A5AB7DE7632A20D7F0243F70812; Path=/; Secure; HttpOnly
Set-Cookie: APPSESSIONID=B6E01C9EB49B98C8EC3B59AC6EDD555F; 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/endpointgroup/f8757da0-03ee-11e9-a407-0242292e7b74
Date: Tue, 18 Dec 2018 19:19:56 GMT
Content-Type: application/json;charset=utf-8
Content-Length: 0
Server:
 
Note the Location field in the response which contains the Endpoint Group's GroupID (f8757da0-03ee-11e9-a407-0242292e7b74) - this GroupID is critical for assignment of an endpoint to the group.

 

Create Endpoint

You can now add a new endpoint to this Whitelist group using a Name, Description, MAC address and the GroupID from above:

curl -k  --include --header 'Content-Type:application/json' --header 'Accept: application/json' --user admin:C1sco12345 --request POST https://198.18.133.27:9060/ers/config/endpoint  --data '
{
  "ERSEndPoint" : {
    "name" : "Whitelisted_Endpoint",
    "description" : "Whitelisted Endpoint",
    "mac" : "00:01:02:03:04:05",
    "groupId" : "f8757da0-03ee-11e9-a407-0242292e7b74",
    "staticGroupAssignment" : true } }'

Response:

HTTP/1.1 201 Created
Set-Cookie: JSESSIONIDSSO=BF31E7B81F678313870B78394CDBA34E; Path=/; Secure; HttpOnly
Set-Cookie: APPSESSIONID=0AF23384A6152D2BB213E005ED732A34; 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/endpoint/3dd754e0-03ef-11e9-a407-0242292e7b74
Date: Tue, 18 Dec 2018 19:43:47 GMT
Content-Type: application/json;charset=utf-8
Content-Length: 0
Server:

The Location field in the Response provides the resource ID for the newly created Endpoint if you want to get the information about it or refer to it in a future request.

To view the new Endpoint Identity Group, login to the ISE Administration node and navigate to Administration > Identity Management > Groups > Endpoint Identity Groups and you should see the name of the new group in the list.

ISE will automatically profile the endpoint in this example (00:01:02:03:04:05) as a "3Com-Device" simply based on it's MAC address without any additional profiling data from the endpoint. You may statically assign it to a profile using the additional attributes:

Attribute Type Description
profileId String profileID of an ISE endpont Profile.
Use the REST command
staticProfileAssignment Boolean true

 

 

Create an Endpoint with Custom Attributes

You may want to use your own IT web application to register and manage network access for IOT endpoints in your network with ISE. You can do this using the ISE REST APIs although typically you will need to create some endpoint custom attributes in ISE to help you manage ownership, network privileges, and perhaps even an expiration of the authorization.

Define ISE Endpoint Custom Attributes

Login to your ISE Administration node and navigate to Administration > Identity Management > Settings > Endpoint Custom Attributes where you may add custom endpoint attributes:

 

image.png

 

You must create the custom attributes in the ISE GUI before they can be used via API. Typically people want to create one or more of the following custom attributes for endpoint management:

Attribute Type Description
Created Long Date and Time of endpoint creation (Unix Epoch time)
Expiration Long Date and Time of endpoint access expiration (Unix Epoch time)
Owner String Name or username of employee responsible for endpoint
Authorization String Name of a network authorization privilege to give the endpoint

 

 
Note that ISE will not automatically remove your endpoints based on the custom attributes - that is for your or your custom web application to manage.

 

Create an Endpoint with Custom Attributes

You can create a new endpoint just like the last one, only this time, you may add custom attribute fields for managing it:

curl -k  --include --header 'Content-Type:application/json' --header 'Accept: application/json' --user admin:C1sco12345 --request POST https://198.18.133.27:9060/ers/config/endpoint  --data '
{
  "ERSEndPoint" : {
    "name" : "Demo Device",
    "description" : "IOT device",
    "mac" : "00:01:02:03:04:06",
    "groupId" : "f8757da0-03ee-11e9-a407-0242292e7b74",
    "staticGroupAssignment" : true,
    "customAttributes" : {
      "customAttributes" : {
        "Owner" : "thomas",
        "Authorization" : "Internet",
        "Created" : "1545321639",
        "Expiration" : "1549008000"
      }
    }
  }
}'

Response:

HTTP/1.1 201 Created
Set-Cookie: JSESSIONIDSSO=BECE6E106BFA472A121167EE9195B7FE; Path=/; Secure; HttpOnly
Set-Cookie: APPSESSIONID=4514D067161FC9A1BFA6EB9DAD7B30BE; 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/endpoint/ead581e0-0470-11e9-a407-0242292e7b74
Date: Thu, 20 Dec 2018 16:04:23 GMT
Content-Type: application/json;charset=utf-8
Content-Length: 0
Server:

To see the new endpoint definition with it's custom attributes in the ISE Administration node, go to Context Visibility > Endpoints, click on it in the list, then select the Attributes tab:

 

image.png 

 

You could now use these endpoint custom attributes in an ISE Authorization policy so that any endpoint with a specific Authorization privilege will be allowed Internet access when connected:

image.png

 

 

Read

Get All ISE Administrators Using cURL and JSON

curl -k --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

Get endpoints per endpoint group and perform appropriate action.

curl -k --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

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

Delete an Endpoint

You may quickly delete an endpoint by requesting a Delete using the endpoint ID:

curl -k --include --header 'Accept: application/json' --user admin:C1sco12345  --request DELETE https:/198.18.133.27:9060/ers/config/endpoint/ead581e0-0470-11e9-a407-0242292e7b74

Response:

HTTP/1.1 204 No Content
Cache-Control: no-cache, no-store, must-revalidate
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: JSESSIONIDSSO=913F64A3577206E5D4A390470C0178A1; Path=/; Secure; HttpOnly
Set-Cookie: APPSESSIONID=9759D7179E2036B452FA53393BD71CEE; Path=/ers; Secure; HttpOnly
Pragma: no-cache
Date: Thu, 20 Dec 2018 17:15:50 GMT
Content-Type: application/json;charset=utf-8
Server:

The HTTP 204 is considered a successful Delete.

An HTTP 404 will be returned if the endpoint with that endpoint ID cannot be found or does not exist.

 

 

Resources