1. technology and computing
2. software
3. databases

Cisco Identity Services Engine API
Reference Guide, Release 1.3
November 12, 2014
Cisco Systems, Inc.
www.cisco.com
Cisco has more than 200 offices worldwide.
Addresses, phone numbers, and fax numbers
are listed on the Cisco website at
www.cisco.com/go/offices.
Text Part Number: OL-26134-01
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL
STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT
WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT
SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE
OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s public
domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS” WITH
ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT
LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF
DEALING, USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING,
WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO
OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
CCDE, CCVP, Cisco Eos, Cisco StadiumVision, the Cisco logo, DCE, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and
Learn is a service mark; and Access Registrar, Aironet, AsyncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, Cisco, the
Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without
Limitation, Enterprise/Solver, EtherChannel, EtherFast, EtherSwitch, Event Center, Fast Step, Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient,
IOS, iPhone, IP/TV, iQ Expertise, the iQ logo, iQ Net Readiness Scorecard, iQuick Study, IronPort, the IronPort logo, LightStream, Linksys, MediaTone, MeetingPlace,
MGX, Networkers, Networking Academy, Network Registrar, PCNow, PIX, PowerPanels, ProConnect, ScriptShare, SenderBase, SMARTnet, Spectrum Expert, StackWise,
The Fastest Way to Increase Your Internet Quotient, TransPath, WebEx, and the WebEx logo are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the
United States and certain other countries.
All other trademarks mentioned in this document or Website are the property of their respective owners. The use of the word partner does not imply a partnership relationship
between Cisco and any other company. (0801R)
Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the
document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental.
Cisco Identity Services Engine API Reference Guide, Release 1.3
© 2014 Cisco Systems, Inc. All rights reserved.
CONTENTS
Preface
vii
Overview of Cisco Identity Services Engine
Purpose
Audience
vii
viii
viii
Document Organization
ix
Document Conventions
ix
Documentation Updates
Product Documentation
x
x
Related Documentation x
Release-Specific Documentation x
Platform-Specific Documentation iii-xi
Obtaining Documentation and Submitting a Service Request
xi
Cisco ISE Monitoring REST APIs
Introduction to the Monitoring REST API
Verifying a Monitoring Node
1-1
1-2
Supported API Calls 1-2
HTTP PUT API Calls 1-8
Session Management Query APIs
2-1
Session Counter API Calls 2-1
Active Sessions Counter 2-1
ActiveCount API Output Schema 2-1
Invoking the ActiveCount API Call 2-2
Sample Data Returned from the ActiveCount API Call 2-2
Posture Sessions Counter 2-2
PostureCount API Output Schema 2-2
Invoking the PostureCount API Call 2-3
Sample Data Returned from the PostureCount API Call 2-3
Profiler Sessions Counter 2-3
ProfilerCount API Output Schema 2-4
Invoking the ProfilerCount API Call 2-4
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
iii
Contents
Sample Data Returned from the ProfilerCount API Call
2-4
Simple Session List API Calls 2-5
Active Sessions List 2-5
ActiveList API Output Schema 2-5
Invoking the ActiveList API Call 2-6
Sample Data Returned from the ActiveList API Call 2-6
Authenticated Sessions List 2-7
AuthList API Output Schema 2-7
Invoking the AuthList API Call 2-8
Sample Data Returned from the AuthList API Call with the null/null Option 2-8
Sample Data Returned from the AuthList API Call with the endtime/null Option 2-9
Sample Data Returned from the AuthList API Call with the null/starttime Option 2-9
Sample Data Returned from the AuthList API Call with the statttime/endtime Option 2-10
Detailed Session Attribute API Calls 2-11
MAC Address Session Search 2-11
MACAddress API Output Schema 2-11
Invoking the MACAddress API Call 2-13
Sample Data Returned from the MACAddress API Call 2-13
User Name Session Search 2-15
UserName API Output Schema 2-15
Invoking the UserName API Call 2-17
Sample Data Returned from the UserName API Call 2-17
NAS IP Address Session Search 2-19
IPAddress API Output Schema 2-19
Invoking the NAS IPAddress API Call 2-21
Sample Data Returned from the IPAddress API Call 2-21
Stale Sessions 2-23
Removing Stale Sessions
Query APIs for Troubleshooting
Cisco Prime NCS API Calls
2-23
3-1
3-1
Troubleshooting Cisco ISE using the Query API Calls 3-1
Node Version and Type API Call 3-1
Version API Output Schema 3-2
Invoking the Version API Call 3-2
Sample Data Returned from the Version API Call 3-2
Failure Reasons API Call 3-3
FailureReasons API Output Schema 3-3
Invoking the FailureReasons API Call 3-4
Sample Data Returned from the FailureReasons API Call
3-4
Cisco Identity Services Engine API Reference Guide, Release 1.2
iv
OL-26134-01
Contents
Authentication Status API Call 3-6
AuthStatus API Output Schema 3-8
Invoking the AuthStatus API Call 3-10
Sample Data Returned from the AuthStatus API Call
Account Status API Call 3-12
AcctStatus API Output Schema 3-12
Invoking the AcctStatus API Call 3-13
Sample Data Returned from the AcctStatus API Call
Change of Authorization REST APIs
Introduction
3-10
3-13
4-1
4-1
CoA Session Management API Calls 4-1
Session Reauthentication API Call 4-1
Reauth API Output Schema 4-2
Invoking the Reauth API Call 4-2
Sample Data Returned from the Reauth API Call 4-3
Session Disconnect API Call 4-3
Disconnect API Output Schema 4-3
Invoking the Disconnect API Call 4-3
Sample Data Returned from the Disconnect API Call 4-4
Cisco ISE External RESTful Services APIs
Introduction to ERS APIs
Overview
5-1
5-1
External RESTful Services API Authentication and Authorization
Enabling External RESTful Services APIs from the GUI
External RESTful Services API Status
Data Validation
Namespaces
5-1
5-2
5-2
5-3
5-3
External RESTful Services SDK
5-4
External RESTful Services Schema File 5-5
Downloading the Schema File 5-6
External RESTful Service Requests and Responses 5-6
External RESTful Service Requests Headers 5-6
External RESTful Service Response Headers 5-7
Common External RESTful Service HTTP Status Codes
Version Control with External RESTful Services APIs
Searching and Filtering
5-7
5-8
5-9
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
v
Contents
Filtering Parameters for External RESTful Services APIs 5-9
Paging Parameters for External RESTful Services APIs 5-10
External RESTful Services System Flow
5-10
Hyperlinks 5-12
Example of links within a search result
Bulk Operations
Guest REST API
5-13
5-13
6-1
An API for Guest User Resources
6-1
Sponsor Authentication and Authorization
6-1
Guest REST API Requests 6-2
Request Structure 6-3
Request Contents 6-4
Bulk Executions 6-4
Guest REST API Responses 6-5
Response Status Codes 6-5
Response Structure 6-6
Guest Passwords 6-6
Response Error Messages 6-6
Unsupported Media Type Example
Versioning 6-8
6-7
Searching and Filtering 6-8
Filtering Parameters 6-9
Filtering Examples 6-10
Page Size Parameters 6-10
Sorting Parameters 6-10
Example: GET First 20 Guest User Records and Sort ascending by the Last Name
External RESTful Services API Operations
Overview
6-11
7-1
7-1
Prerequisites for Using the External RESTful Services API Calls
7-1
GetVersion 7-2
Sample Request for GetVersion Operation 7-2
Sample Response for GetVersion Operation 7-2
External RESTful Services APIs for Internal Users 7-2
Retrieve All Internal Users 7-3
Sample Request for Retrieve All Internal Users API 7-3
Sample Response for Retrieve All Internal Users API 7-3
Get Internal Users by ID 7-4
Cisco Identity Services Engine API Reference Guide, Release 1.2
vi
OL-26134-01
Contents
Sample Request for Read Internal Users API 7-4
Sample Response for Read Internal Users API 7-4
Create Internal Users 7-5
Sample Request for Create Internal Users API 7-5
Sample Response for Create Internal Users API 7-6
Update Internal Users 7-6
Sample Request for Update Internal Users API 7-6
Sample Response for Update Internal Users API 7-7
Delete Internal Users 7-7
Sample Request for Delete Internal Users API 7-7
Sample Response for Delete Internal Users API 7-7
External RESTful Services APIs for Endpoints 7-8
Get All Endpoints 7-8
Sample Request for Get All Endpoints API 7-8
Sample Response for Get All Endpoints API 7-9
Get Endpoints by ID 7-9
Sample Request for Read Endpoints API 7-9
Sample Response for Read Endpoints API 7-9
Create Endpoints 7-10
Sample Request for Create Endpoints API 7-10
Sample Response for Create Endpoints API 7-11
Update Endpoints 7-11
Sample Request for Update Endpoints API 7-11
Sample Response for Update Endpoints API 7-11
Delete Endpoints 7-12
Sample Request for Delete Endpoints API 7-12
Sample Response for Delete Endpoints API 7-12
Register Endpoints 7-12
Sample Request for Register Endpoints API 7-13
Sample Response for Register Endpoints API 7-13
Deregister Endpoints 7-13
Sample Request for Deregister Endpoint API Call 7-14
Sample Response for Deregister Endpoint API Call 7-14
Start Bulk Execution for Endpoints 7-14
Sample Request for Start Bulk Execution for Endpoints API Call 7-14
Sample Response for Start Bulk Execution for Endpoints API Call 7-15
Get Bulk Status for Endpoints 7-15
Get Bulk Status for Endpoints Example 7-16
External RESTful APIs for Endpoint Identity Groups
Get All Endpoint Identity Groups 7-17
7-16
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
vii
Contents
Sample Request for Get All Endpoint Identity Groups API Call 7-17
Sample Response for Get All Endpoint Identity Groups API Call 7-17
Get Endpoint Identity Groups by ID 7-18
Sample Request for Read Endpoint Identity Groups API Call 7-18
Sample Response for Read Endpoint Identity Groups API Call 7-18
Create Endpoint Identity Groups 7-18
Sample Request for Create Endpoint Identity Groups API Call 7-19
Sample Response for Create Endpoint Identity Groups API Call 7-19
Update Endpoint Identity Groups 7-19
Sample Request for Update Endpoint Identity Groups API Call 7-19
Sample Response for Update Endpoint Identity Groups API Call 7-20
Delete Endpoint Identity Groups 7-20
Sample Request for Delete Endpoint Identity Groups API Call 7-20
Sample Response for Delete Endpoint Identity Groups API Call 7-20
External RESTful Services APIs for Identity Groups 7-21
Retrieve All Identity Groups 7-21
Sample Request for Retrieve All Identity Group API Call 7-21
Sample Response for Retrieve All Identity Group API Call 7-21
External RESTful Services APIs for Guest Users 7-22
Content Type and Accept Headers 7-22
Get a Guest User 7-23
Get a Guest User Examples 7-23
Get a Guest User by ID Example 7-23
Filter by Usernames that Start with “ilucky” Example 7-24
Filter by Username that Starts with “ilucky” and Last Name that Starts with “J” Example
Filter By the First Name “John” and Sort By Username Example 7-26
Guest User Request and Response Using curl Example 7-26
Get All Guest Users 7-28
Get All Example 7-28
Create a Guest User 7-29
Create a Guest User Example 7-29
Update a Guest User 7-30
Update Guest Users Examples 7-30
Update User Example 7-31
Reset User’s Password Example 7-31
Delete a Guest User 7-32
Delete a Guest User Example 7-32
Suspend a Guest User 7-32
Suspend a Guest User by ID Example 7-33
Reinstate a Guest User 7-33
7-25
Cisco Identity Services Engine API Reference Guide, Release 1.2
viii
OL-26134-01
Contents
Reinstate Guest User Example 7-33
Send an Email to a Guest User 7-34
Send an Email to a Guest User Example 7-34
Send an SMS Text to a Guest User 7-34
Send an SMS Example 7-35
Approve a Guest User 7-35
Approve a Guest User Example 7-35
Deny Approval for a Guest User Account 7-36
Deny a Guest User’s Approval Example 7-36
Start Bulk Execution for Guest Users 7-36
Create Guest Bulk Example 7-37
Get Bulk Status for Guest Users 7-38
Get Bulk Status for Guest Users Example 7-38
Change a Sponsor’s Password 7-39
Change a Sponsor’s Password Example 7-39
External RESTful Services APIs for Portals 7-40
Get All Portals 7-40
Sample Request for Get All Portals Call 7-40
Sample Response for Get All Portals Call 7-40
Get Portal by ID 7-41
Sample Request for Get Portal by ID Call 7-41
Sample Response for Get Portal by ID Call 7-41
External RESTful Services APIs for Network Devices 7-43
Get All Network Devices 7-43
Sample Request for Get All Network Devices Call 7-43
Sample Response for Get All Network Devices Call 7-44
Get Network Device by ID 7-44
Sample Request for Get Network Device by ID Call 7-44
Sample Response for Get Network Device by ID Call 7-44
Create Network Device 7-45
Sample Request for Create Network Device Call 7-45
Sample Response for Create Network Device Call 7-46
Update Network Device 7-46
Sample Request for Update Network Device Call 7-46
Sample Response for Update Network Device Call 7-47
Delete Network Device 7-47
Sample Request for Update Network Device Call 7-47
Sample Response for Update Network Device Call 7-47
External RESTful Services APIs for Network Device Groups
7-47
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
ix
Contents
Get All Network Device Groups 7-48
Sample Request for Get All Network Device Groups API Call 7-48
Sample Response for Get All Network Device Groups API Call 7-48
Get Network Device Group 7-49
Sample Request for Get Network Device Group API Call 7-49
Sample Response for Get Network Device Group API Call 7-49
External RESTful Services APIs for SGTs 7-50
Get All SGTs 7-50
Sample Request for Get All SGTs API Call 7-50
Sample Response for Get All SGTs API Call 7-50
Get SGT by ID 7-51
Sample Request for Get SGT by ID API Call 7-51
Sample Response for Get SGT by ID API Call 7-51
REST API Client 7-52
GET Method 7-52
URI 7-52
Accept Header 7-53
Authorization Header 7-53
Making the GET Request Using POSTMAN 7-53
POST Method 7-54
URI 7-54
Content-Type Header 7-55
Authorization Header 7-55
Making the POST Request Using POSTMAN 7-55
PUT Method 7-56
URI 7-56
Content-Type Header 7-57
Authorization Header 7-57
Making the PUT Request Using POSTMAN 7-57
Delete Method 7-58
URI 7-58
Accept Header 7-59
Authorization Header 7-59
Making the DELETE Request Using POSTMAN 7-59
Cisco ISE Failure Reasons Report
Introduction
A-1
A-1
Viewing Failure Reasons
A-1
Cisco Identity Services Engine API Reference Guide, Release 1.2
x
OL-26134-01
Preface
Revised: 11/12/14, OL-26134-01
This preface explains the objectives, intended audience, and organization of the Cisco Identity Services
Engine API Reference Guide, Release 1.3. The preface also describes the conventions that provide
instructions and provides other types of information in the following sections:
•
Overview of Cisco Identity Services Engine, page vii
•
Purpose, page viii
•
Audience, page viii
•
Document Organization, page ix
•
Document Conventions, page ix
•
Documentation Updates, page x
•
Product Documentation, page x
•
Related Documentation, page x
•
Obtaining Documentation and Submitting a Service Request, page xi
Overview of Cisco Identity Services Engine
Cisco Identity Services Engine (ISE), as a next-generation identity and access control policy platform
enables enterprises to enforce compliance, enhance infrastructure security, and streamline their service
operations. The unique architecture of Cisco ISE allows enterprises to gather real-time contextual
information from networks, users, and devices in order to make proactive governance decisions by tying
identity to various network elements including access switches, wireless LAN controllers (WLCs),
virtual private network (VPN) gateways, and data center switches.
Cisco ISE is a key component of the Cisco Security Group Access Solution. Cisco ISE is a consolidated
policy-based access control solution that:
•
Combines authentication, authorization, accounting (AAA), posture, profiler, and guest
management services into one appliance
•
Enforces endpoint compliance by checking the device posture of all endpoints accessing the
network, including 802.1X environments
•
Provides support for discovery, profiling, policy-based placement, and monitoring of endpoint
devices on the network
•
Enables consistent policy in centralized and distributed deployments allowing services to be
delivered where they are needed
Cisco Identity Services Engine API Reference Guide, Release 1.3
OL-26134-01
vii
•
Employs advanced enforcement capabilities including Security Group Access (SGA) through the
use of Security Group Tags (SGTs) and Security Group (SG) Access Control Lists (ACLs)
•
Supports scalability to support a number of deployment scenarios from small office to large
enterprise environments
The Cisco ISE architecture supports standalone and distributed deployments, allowing you to configure
and manage your network from a centralized portal. For more information on the capabilities of Cisco
ISE, see the Cisco Identity Services Engine Admin Guide, Release 1.3.
Purpose
This application programming interface (API) reference guide provides only a brief high-level overview
of the capabilities afforded by the supported APIs. The purpose of this API reference guide is to provide
a developer, system or network administrator, or system integrator with basic guidelines for using the
outlined APIs within the Cisco ISE deployment.
The REST API calls use queries to determine the following types of data:
•
Number of active sessions
•
Types of active sessions
•
Authentication status of active session
•
MAC addresses in use
•
NAS IP addresses in use
•
Node versions and types
•
Reasons for node session failures
The External RESTful Services APIs and related API calls can be used to perform CRUD (Create, Read,
Update, Delete) operations on Cisco ISE resources. External RESTful Services is based on HTTP
protocol and REST methodology.
Note
For more information about the Cisco ISE network, its nodes and personas, concepts of operation or
usage, or how to use the Cisco ISE user interface, see the Cisco Identity Services Engine Admin Guide,
Release 1.3.
Audience
This API reference guide is intended for experienced system administrators who administer Cisco ISE
appliances within a network environment, system integrators who may want to make use of the APIs, or
third-party partners who have with the responsibility for managing or troubleshooting Cisco ISE
deployments. As a prerequisite to using this API reference guide, you should have a basic understanding
of troubleshooting and diagnostic practices and how to make and interpret API calls.
Cisco Identity Services Engine API Reference Guide, Release 1.3
viii
OL-26134-01
Document Organization
This guide is organized as follows:
•
Part 1 — Cisco ISE Monitoring REST APIs
– Chapter 1, “Introduction to the Monitoring REST API”
– Chapter 2, “Session Management Query APIs”
– Chapter 3, “Query APIs for Troubleshooting”
– Chapter 4, “Change of Authorization REST APIs”
•
Part 2 — Cisco ISE External RESTful Services APIs
– Chapter 5, “Introduction to ERS APIs”
– Chapter 7, “External RESTful Services API Operations”
•
Part 3 — Cisco pxGrid APIs
– Appendix A, “Cisco ISE Failure Reasons Report”
Document Conventions
This section outlines the conventions used throughout this document.
Caution
Note
Means reader be careful. You are capable of doing something that might result in equipment damage or
loss of data.
Means reader take note. Notes contain helpful suggestions or references to materials not contained in
this manual.
This API reference guide uses the following conventions to convey instructions and information.
Item
Convention
Commands, keywords, special terminology, and
options that should be chosen during procedures
boldface font
Variables for which you supply values and new or italic font
important terminology
Displayed session and system information, paths, screen font
and file names
Information you enter
boldface screen
Variables you enter
italic screen
Menu items and button names
boldface font
Indicates menu items to choose, in the order in
which you choose them.
Option > Network Preferences
font
font
Cisco Identity Services Engine API Reference Guide, Release 1.3
OL-26134-01
ix
Documentation Updates
Table 1 lists the updates made to this document since its inception, with the most recent update featured
first in the list.
Table 1
Updates for Cisco Identity Services Engine API Reference Guide, Release 1.3
Date
Description
8-25-2014
Cisco Identity Services Engine (ISE) Release 1.3
Product Documentation
Note
We sometimes update the printed and electronic documentation after original publication. Therefore,
you should also review the documentation on http://www.cisco.com for any updates.
Table 2 lists the related product documentation that is available for Cisco ISE Release 1.3 on
www.cisco.com. To find end-user documentation for all products on www.cisco.com, go to:
http://www.cisco.com/go/techdocs
Related Documentation
This section provides information on release-specific documentation, as well as platform-specific
documentation.
Release-Specific Documentation
Table 2 lists the product documentation available for the Cisco ISE Release. General product
information for Cisco ISE is available at http://www.cisco.com/go/ise. End-user documentation is
available on Cisco.com at
http://www.cisco.com/en/US/products/ps11640/tsd_products_support_series_home.html.
Table 2
Product Documentation for Cisco Identity Services Engine
Document Title
Location
Release Notes for the Cisco Identity Services
Engine, Release 1.3
http://www.cisco.com/en/US/products/ps11640/pr
od_release_notes_list.html
Cisco Identity Services Engine Network
Component Compatibility, Release 1.3
http://www.cisco.com/en/US/products/ps11640/pr
oducts_device_support_tables_list.html
Cisco Identity Services Engine Admin Guide,
Release 1.3
http://www.cisco.com/en/US/products/ps11640/pr
oducts_user_guide_list.html
Cisco Identity Services Engine Hardware
Installation Guide, Release 1.3
http://www.cisco.com/en/US/products/ps11640/pr
od_installation_guides_list.html
Cisco Identity Services Engine API Reference Guide, Release 1.3
x
OL-26134-01
Table 2
Product Documentation for Cisco Identity Services Engine (continued)
Document Title
Location
Cisco Identity Services Engine Migration Guide
for Cisco Secure ACS 5.5 to Release 1.3
http://www.cisco.com/en/US/products/ps11640/pr
od_installation_guides_list.html
Cisco Identity Services Engine Sponsor Portal
User Guide, Release 1.3
http://www.cisco.com/en/US/products/ps11640/pr
oducts_user_guide_list.html
Cisco Identity Services Engine CLI Reference
Guide, Release 1.3
http://www.cisco.com/en/US/products/ps11640/pr
od_command_reference_list.html
Cisco Identity Services Engine API Reference
Guide, Release 1.3
http://www.cisco.com/en/US/products/ps11640/pr
od_command_reference_list.html
Cisco Identity Services Engine Troubleshooting
Guide, Release 1.3
http://www.cisco.com/en/US/products/ps11640/pr
od_troubleshooting_guides_list.html
Regulatory Compliance and Safety Information
for Cisco Identity Services Engine, Cisco 1121
Secure Access Control System, Cisco NAC
Appliance, Cisco NAC Guest Server, and Cisco
NAC Profiler
http://www.cisco.com/en/US/products/ps11640/pr
od_installation_guides_list.html
Cisco Identity Services Engine In-Box
Documentation and China RoHS Pointer Card
http://www.cisco.com/en/US/products/ps11640/pr
oducts_documentation_roadmaps_list.html
Platform-Specific Documentation
Links to Policy Management Business Unit documentation are available on http://www.cisco.com at the
following locations:
•
Cisco ISE
http://www.cisco.com/en/US/products/ps11640/prod_installation_guides_list.html
•
Cisco Secure ACS
http://www.cisco.com/en/US/products/ps9911/tsd_products_support_series_home.html
•
Cisco NAC Appliance
http://www.cisco.com/en/US/products/ps6128/tsd_products_support_series_home.html
•
Cisco NAC Profiler
http://www.cisco.com/en/US/products/ps8464/tsd_products_support_series_home.html
•
Cisco NAC Guest Server
http://www.cisco.com/en/US/products/ps10160/tsd_products_support_series_home.html
Obtaining Documentation and Submitting a Service Request
For information on obtaining documentation, submitting a service request, and gathering additional
information, refer to the monthly What’s New in Cisco Product Documentation, which also lists all new
and revised Cisco technical documentation, at:
http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html
Subscribe to the What’s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed
and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free
service and Cisco currently supports RSS version 2.0.
Cisco Identity Services Engine API Reference Guide, Release 1.3
OL-26134-01
xi
Cisco Identity Services Engine API Reference Guide, Release 1.3
xii
OL-26134-01
PART
1
Cisco ISE Monitoring REST APIs
CH A P T E R
1
Introduction to the Monitoring REST API
The Monitoring REST API allows allow you to gather session and node-specific information by using
Monitoring nodes in your network. A session is defined as the duration between when you access a
desired node and complete the operations needed to gather information.
The following Monitoring REST API categories are supported in Cisco ISE, Release 1.3:
Note
•
Session Management
•
Troubleshooting
•
Change of Authorization (CoA)
You use only supported categories to gather information about endpoints being monitored by the
Monitoring persona. Monitoring is one of three supported personas that a node type can perform in a
Cisco ISE, Release 1.3, deployment. For the remainder of this guide, “Monitoring node” will be used to
describe the Monitoring persona of a Cisco ISE node.
Any attempt to use these categories to gather information about the Policy Service persona of a Cisco
ISE appliance will result in an error. For more information about Cisco ISE nodes and personas, see
Cisco Identity Services Engine Admin Guide, Release 1.3.
Monitoring REST API calls allow you to locate, monitor, and accumulate important real-time,
session-based information stored in individual endpoints in a network. You can access this information
through a Monitoring node.
The real-time, session-based information that you gather can help understand Cisco ISE operations and
assist in diagnosing conditions or issues. It can also be used to troubleshoot error conditions or an
activity or behavior that may be affecting monitoring operations. As shown in Figure 1-1, the Monitoring
REST API calls are used to access the Monitoring node and retrieve important session-based information
that is stored in the Cisco ISE deployment endpoints.
Note
The Monitoring REST API for Cisco ISE, Release 1.2 has been deprecated and the URL path for all
service calls has been changed. Please use the Monitoring REST API for Cisco ISE, Release 1.3.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
1-1
Chapter 1
Introduction to the Monitoring REST API
Verifying a Monitoring Node
Figure 1-1
Monitoring REST API Calls in a Distributed Deployment
Browser-based
client
Cisco ISE Deployment
Web
server
REST
(HTTPS)
APIs
Adminstration
persona
Monitoring
persona
PHP-based
client
310131
Policy service
persona
Remote java
client
Verifying a Monitoring Node
Before you Begin
Before you can successfully invoke the API calls on a Monitoring node, you need to verify that the node
you want to monitor is valid.
Note
To be able to use a public Monitoring REST API, you must first authenticate with Cisco ISE using valid
credentials.
Step 1
Enter valid login credentials (Username and Password) in the Cisco ISE Login window, and click Login.
The Cisco ISE dashboard and user interface appears.
Step 2
Choose Authorization > System > Deployment.
The Deployment Nodes page appears, which lists all configured nodes that are deployed.
Step 3
In the Roles column of the Deployment Nodes page, verify that the role for the target node that you want
to monitor is listed as a Monitoring node.
Supported API Calls
The following tables describe the different types of API calls and provide an example of the API call
format:
•
Table 1-1 on page 1-3—defines API calls for session management.
•
Table 1-2 on page 1-6—defines API calls for troubleshooting.
•
Table 1-3 on page 1-7—defines CoA API calls.
Cisco Identity Services Engine API Reference Guide, Release 1.2
1-2
OL-26134-01
Chapter 1
Introduction to the Monitoring REST API
Supported API Calls
If you intend to use a generic programmatic interface to authenticate with the Monitoring REST API
supported by Cisco ISE, you need to first create a REST-based client that bridges Cisco ISE and the
specific tool you use. You then use this REST client to authenticate with the Cisco ISE Monitoring REST
APIs, marshal and submit the API requests to the Monitoring nodes, and then unmarshal the API
responses and pass them on to the specified tool.
Table 1-1
Cisco ISE Session Management API Calls
API Call Category
Description and Example
Session Counters
ActiveCount
Lists the number of active sessions.
https://<ISEhost>/admin/API/mnt/Session/ActiveCount
PostureCount
Lists the number of Postured endpoints.
https://<ISEhost>/admin/API/mnt/Session/PostureCount
Note
ProfilerCount
Posture is a service that aids in checking the state (or posture)
for all the endpoints that connect to a Cisco ISE network. Cisco
ISE utilizes NAC Agent for checking the posture compliance
of a device.
Lists the number of active Profiler service sessions.
https://<ISEhost>/admin/API/mnt/Session/ProfilerCount
Note
Profiler is a service that aids in identifying, locating, and
determining the capabilities of all attached endpoints on a
Cisco ISE network.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
1-3
Chapter 1
Introduction to the Monitoring REST API
Supported API Calls
Table 1-1
Cisco ISE Session Management API Calls (continued)
API Call Category
Description and Example
Session List
Note
A session list includes the MAC address, network access device (NAD) IP address, username,
and session ID information associated with a session.
ActiveList
Lists all active sessions.
https://<ISEhost>/admin/API/mnt/Session/ActiveList
In this release of Cisco ISE, the maximum number of active
authenticated endpoint sessions that can be displayed is limited
to 250,000.
Note
AuthList
Lists all currently active authenticated sessions.
https://<ISEhost>/admin/API/mnt/Session/AuthList/<parameteroptio
ns>
You can specify the following parameter options that will return
different values:
•
null/null—Lists all active authenticated sessions.
•
null/endtime—Lists all active authenticated sessions after the
specified end time.
•
starttime/null—Lists all active authenticated sessions before the
specified start time.
•
starttime/endtime—Lists all active authenticated sessions between
the specified start time and end time.
Enter the date and time for the start time and end time in the following
format:
YYYY-MM-DD hh:mm:ss.s
where:
•
YYYY—four-digit year
•
MM—two-digit month (01=January, and so on)
•
DD—two-digit day of the month (01 through 31)
•
hh—two-digit hour (00 through 23) (a.m. and p.m. are not
allowed)
•
mm—two-digit minute (00 through 59)
•
ss—two-digit second (00 through 59)
•
s—one or more digits representing a decimal fraction of a second
Note
Every Cisco ISE node is configured with a time zone.
Recommended time zone is UTC.
See Sample Data Returned from the AuthList API Call with the
null/null Option, page 2-8, for samples that show all four parameter
options.
Cisco Identity Services Engine API Reference Guide, Release 1.2
1-4
OL-26134-01
Chapter 1
Introduction to the Monitoring REST API
Supported API Calls
Table 1-1
Cisco ISE Session Management API Calls (continued)
API Call Category
Description and Example
Session Attributes
Note
This is a timestamp-based search for the latest session that contains the specified search
attribute.
MACAddress
Searches the database for the latest session that contains the specified
MAC address.
https://<ISEhost>/admin/API/mnt/Session/MACAddress/<macaddres
s>
UserName
Note
XX:XX:XX:XX:XX:XX is the MAC address format and is not
case sensitive (for example, 0a:0B:0c:0D:0e:0F).
Note
The MAC address serves as the only unique key to finding the
correct session you want to monitor. Use the ActiveList API
call to list all active sessions and their MAC addresses, from
which you can base your MAC address search.
Searches the database for the latest session that contains the specified
username.
https://<ISEhost>/admin/API/mnt/Session/UserName/<username>
Note
IPAddress
Usernames must conform to the same Cisco ISE password
policy used for network usernames. The only invalid character
for the Monitoring REST APIs is the backslash (\) character.
For details, see “User Password Policy” in Cisco Identity
Services Engine User Guide, Release 1.1.
Searches the database for the latest session that contains the specified
NAS IP address.
https://<ISEhost>/admin/API/mnt/Session/IPAddress/<nasipaddress>
Note
xxx.xxx.xxx.xxx is the NAS IP address format (for example,
10.10.10.10).
For specific details about Cisco ISE API calls for session management, see Chapter 2, “Session
Management Query APIs”.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
1-5
Chapter 1
Introduction to the Monitoring REST API
Supported API Calls
Table 1-2
Cisco ISE Troubleshooting API Calls - Troubleshooting
API Call
Description and Example
Version
Lists the node version and type.
https://<ISEhost>/admin/API/mnt/Version
Node type can be any of the following values (0-3):
0—STAND_ALONE_MNT_NODE
1—ACTIVE_MNT_NODE
2—STAND_BY_MNT_NODE
3—NOT_AN_MNT_NODE
Note
STAND_ALONE_MNT_NODE means it is a Monitoring node
that does not function in any distributed deployment.
ACTIVE_MNT_NODE means it is a primary node in a
primary-secondary relationship in a distributed deployment.
STAND_BY_MNT_NODE means it is a secondary node in a
primary-secondary pair in a distributed deployment.
NOT_AN_MNT_NODE means it is not a Monitoring node. See
Cisco Identity Services Engine User Guide, Release 1.1 for
details about the supported ISE nodes and personas.
FailureReasons
Lists the reasons for failure.
https://<ISEhost>/admin/API/mnt/FailureReasons
Each failure reason displays an error code (failureReason id), a brief
description (code), a failure reason (cause), and a possible response
(resolution), as shown in the following example:
<failureReason id="100009">
<code> 100009 WEBAUTH_FAIL
<cause> This may or may not be indicating a violation.
<resolution> Please review and resolve this issue according to your
organization's policy.
Note
The FailureReasons API call to be called only once to gather the
information from the Monitoring node. You should store the
contents of any returned failure reasons into your own file system
or database. The returned contents of these API calls are intended
to be used for reference purposes. If you experience any issues
during authentication, you should compare the failure reason
code provided in the authentication response with the list of
failure reasons that you have stored in your own file system or
database.
For a complete list of Cisco ISE failure reasons, see Appendix A, “Cisco
ISE Failure Reasons Report”.
Cisco Identity Services Engine API Reference Guide, Release 1.2
1-6
OL-26134-01
Chapter 1
Introduction to the Monitoring REST API
Supported API Calls
Table 1-2
Cisco ISE Troubleshooting API Calls - Troubleshooting (continued)
API Call
Description and Example
AuthStatus
Lists the authentication status for all sessions.
https://<ISEhost>/admin/API/mnt/AuthStatus/MACAddress/<macaddre
ss>/<numberofseconds>/<numberofrecordspermacaddress>/All
Note
The seconds parameter <numberofseconds> is user-configurable,
the range is from 0 to 432000 seconds (5 days).
Get Session Accounting Status
AcctStatus
Lists the accounting status of all sessions within a specific period of time.
https://<ISEhost>/admin/API/mnt/Session/AcctStatusTT/MACAddress/
<macaddress>/<numberof seconds>
Note
The seconds parameter <numberofseconds> is user-configurable,
with the range is from 0 to 432000 seconds (5 days).
For specific details about Cisco ISE API calls for troubleshooting, see Chapter 2, “Session Management
Query APIs”.
Table 1-3
Cisco ISE Change of Authorization API Calls
API Call
Description and Example
Reauth
Sends a session reauthentication command and type.
https://<ISEhost>/admin/API/mnt/CoA/Reauth/<serverhostname>/
<macaddress>/<reauthtype>/<nasipaddress>/
<destinationipaddress>
Where <ISEhost> denotes the ip address of the ISE host,
<serverhostname> denotes the name of the ISE server, <nasipaddress>
denotes the identifying ip address of NAS, and <destinationipaddress>
denotes the ip address of the destination.
Reauth type can be any of the following values (0-2):
0—REAUTH_TYPE_DEFAULT
1—REAUTH_TYPE_LAST
2—REAUTH_TYPE_RERUN
Note
If you do not know the NAS IP address, you can enter the required
values up to that point and the API will use these values in its
search query. However, you must know the MAC address to
perform this API call, but you can leave other parameters as null.
This API call can only be executed on a Monitoring ISE node, which
submits the requests to perform CoA remotely. The Administration ISE
node is not involved or required to execute these CoA API calls.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
1-7
Chapter 1
Introduction to the Monitoring REST API
Supported API Calls
Table 1-3
Cisco ISE Change of Authorization API Calls (continued)
API Call
Description and Example
Session Disconnect
Disconnect
Sends a session disconnect command and port option type.
https://<ISEhost>/admin/API/mnt/CoA/Disconnect/<serverhostname>/
<macaddress>/<disconnecttype>/<nasipaddress>/
<destinationipaddress>
Port option type can be any of the following values (0-2):
0—DYNAMIC_AUTHZ_PORT_DEFAULT
1—DYNAMIC_AUTHZ_PORT_BOUNCE
2—DYNAMIC_AUTHZ_PORT_SHUTDOWN
Note
If you do not know the NAS IP address, enter the required values
up to that point and the API will use these values in its search
query. However, you must know the MAC address to perform this
API call, but you can leave other parameters as null.
For details about Cisco ISE Change of Authorization API calls, see Chapter 4, “Change of Authorization
REST APIs”.
HTTP PUT API Calls
Similar to AuthStatus API call in Table 1-2, there is an HTTP PUT version of an API call that allows
clients to retrieve account status. The Monitoring REST API supports both HTTP PUT and HTTP GET
calls, with the examples in this guide documenting HTTP GET calls. HTTP PUT addresses the need for
calls that require parameter inputs. The following schema file example is a request for account status:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="acctRequest" type="mnTRESTAcctRequest"/>
<xs:complexType name="mnTRESTAcctRequest">
<xs:complexContent>
<xs:extension base="mnTRESTRequest">
<xs:sequence>
<xs:element name="duration" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="mnTRESTRequest" abstract="true">
<xs:sequence>
<xs:element name="valueList">
<xs:complexType>
<xs:sequence>
<xs:element name="value" type="xs:string" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="searchCriteria" type="xs:string"/>
</xs:sequence>
</xs:complexType>
Cisco Identity Services Engine API Reference Guide, Release 1.2
1-8
OL-26134-01
Chapter 1
Introduction to the Monitoring REST API
Supported API Calls
</xs:schema>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
1-9
Chapter 1
Introduction to the Monitoring REST API
Supported API Calls
Cisco Identity Services Engine API Reference Guide, Release 1.2
1-10
OL-26134-01
CH A P T E R
2
Session Management Query APIs
This chapter describes the session management API calls that provide the means for retrieving important
session-related information from within the Cisco Monitoring ISE node in your Cisco ISE deployment.
Session Counter API Calls
The following session counter API calls let you quickly gather a current count of session-related
information on a target Cisco Monitoring ISE node in your Cisco ISE deployment:
•
Active sessions (ActiveCount)—An active session is one that is authenticated onto the network.
•
Postured sessions (PostureCount)—Postured state is asserted when posture is concluded
(Compliant/Noncompliant). Posture is optional, for example, IP-phone/printer would not go to
Postured state. Postured state is a short lived interim state, since after Postured, it moves to Started
state when accounting start is set.
•
Profiled sessions (ProfilerCount)
These various states are meant to troubleshoot if an endpoint gets stuck in any of the phases.
Active Sessions Counter
You can use the ActiveCount API call to retrieve a count of all currently active sessions. This section
provides a schema file output example, a procedure for counting all active sessions by invoking the
ActiveCount API call, and a sample of the active sessions data returned after this API call is issued.
ActiveCount API Output Schema
This sample schema file is the output of the ActiveCount API call for retrieving a count of the active
sessions on the target Monitoring persona of an ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="sessionCount" type="activeCount"/>
<xs:complexType name="activeCount">
<xs:sequence>
<xs:element name="count" type="xs:int"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-1
Chapter 2
Session Management Query APIs
Session Counter API Calls
Invoking the ActiveCount API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the ActiveCount API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/<specific-api-call>):
https://acme123/admin/API/mnt/Session/ActiveCount
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents the target Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the ActiveCount API Call
The following example illustrates the data returned (number of active sessions) when you invoke an
ActiveCount API call on a target Cisco Monitoring ISE node:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<sessionCount>
<count>5</count>
</sessionCount>
Posture Sessions Counter
You can use the PostureCount API call to retrieve a current count of all currently active Posture sessions.
PostureCount API Output Schema
This sample schema file is the output of the PostureCount API call for retrieving a count of the current
active Posture sessions on the target Cisco Monitoring ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-2
OL-26134-01
Chapter 2
Session Management Query APIs
Session Counter API Calls
<xs:element name="sessionCount" type="postureCount"/>
<xs:complexType name="postureCount">
<xs:sequence>
<xs:element name="count" type="xs:int"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Invoking the PostureCount API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the PostureCount API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/Session/<specific-api-call>):
https://acme123/admin/API/mnt/Session/PostureCount
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents the target Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the PostureCount API Call
The following example illustrates the data returned (number of current active Posture sessions) when you
invoke a PostureCount API call on a target Cisco Monitoring ISE node:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<sessionCount>
<count>3</count>
</sessionCount>
Profiler Sessions Counter
You can use the ProfilerCount API call to retrieve a count of all currently active Profiler sessions.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-3
Chapter 2
Session Management Query APIs
Session Counter API Calls
ProfilerCount API Output Schema
This sample schema file is the output of the ProfilerCount API call for retrieving a count of the current
active Profiler sessions on the target Cisco Monitoring ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="sessionCount" type="profilerCount"/>
<xs:complexType name="profilerCount">
<xs:sequence>
<xs:element name="count" type="xs:int"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Invoking the ProfilerCount API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the ProfilerCount API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/Session/<specific-api-call>):
https://acme123/admin/API/mnt/Session/ProfilerCount
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the ProfilerCount API Call
The following example illustrates the data returned (number of active Profiler sessions) when you invoke
a ProfilerCount API call on a target Cisco Monitoring ISE node:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<sessionCount>
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-4
OL-26134-01
Chapter 2
Session Management Query APIs
Simple Session List API Calls
<count>1</count>
</sessionCount>
Simple Session List API Calls
The following simple session list API calls let you quickly gather session-related information such as
the MAC address, the network access device (NAD) IP address, user name, and session ID associated
with a current active session on a target Cisco Monitoring ISE node in your Cisco ISE deployment:
•
Active sessions list (ActiveList)
•
Authenticated sessions list (AuthList)
Active Sessions List
You can use the ActiveList API call to list all currently active sessions.
Note
The maximum number of active authenticated endpoint sessions that can be displayed is limited to
100,000.
ActiveList API Output Schema
This sample schema file is the output of the ActiveList API call for retrieving a list of the current active
sessions (and session-related information) on the target Cisco Monitoring ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="activeSessionList" type="simpleActiveSessionList"/>
<xs:complexType name="simpleActiveSessionList">
<xs:sequence>
<xs:element name="activeSession" type="simpleActiveSession" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="noOfActiveSession" type="xs:int" use="required"/>
</xs:complexType>
<xs:complexType name="simpleActiveSession">
<xs:sequence>
<xs:element name="user_name" type="xs:string" minOccurs="0"/>
<xs:element name="calling_station_id" type="xs:string" minOccurs="0"/>
<xs:element name="nas_ip_address" type="xs:string" minOccurs="0"/>
<xs:element name="acct_session_id" type="xs:string" minOccurs="0"/>
<xs:element name="audit_session_id" type="xs:string" minOccurs="0"/>
<xs:element name="server" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-5
Chapter 2
Session Management Query APIs
Simple Session List API Calls
Invoking the ActiveList API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the ActiveList API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/Session/<specific-api-call>):
https://acme123/admin/API/mnt/Session/ActiveList
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node, because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the ActiveList API Call
The following example illustrates the session-related data returned from the list of active sessions when
you invoke an ActiveList API call on a target Cisco Monitoring ISE node:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<activeSessionList noOfActiveSession="5">
<activeSession>
<calling_station_id>00:0C:29:FA:EF:0A</calling_station_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
<activeSession>
<calling_station_id>70:5A:B6:68:F7:CC</calling_station_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
<activeSession>
<user_name>tom_wolfe</user_name>
<calling_station_id>00:14:BF:5A:0C:03</calling_station_id>
<nas_ip_address>10.203.107.161</nas_ip_address>
<acct_session_id>00000032</acct_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-6
OL-26134-01
Chapter 2
Session Management Query APIs
Simple Session List API Calls
<activeSession>
<user_name>graham_hancock</user_name>
<calling_station_id>00:50:56:8E:28:BD</calling_station_id>
<nas_ip_address>10.203.107.161</nas_ip_address>
<acct_session_id>0000002C</acct_session_id>
<audit_session_id>0ACB6BA10000002A165FD0C8</audit_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
<activeSession>
<user_name>ipepvpnuser</user_name>
<calling_station_id>172.23.130.89</calling_station_id>
<nas_ip_address>10.203.107.45</nas_ip_address>
<acct_session_id>A2000070</acct_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
</activeSessionList>
Authenticated Sessions List
You can use the AuthList API call to retrieve a list of all currently active authenticated sessions.
Note
The maximum number of active authenticated endpoint sessions that can be displayed is limited to
100,000.
AuthList API Output Schema
This sample schema file is the output of the AuthList API call for retrieving a list of all currently active
authenticated sessions within a specified period of time (or for no specified time using the “null/null”
parameter) on the target Cisco Monitoring ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="activeSessionList" type="simpleActiveSessionList"/>
<xs:complexType name="simpleActiveSessionList">
<xs:sequence>
<xs:element name="activeSession" type="simpleActiveSession" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="noOfActiveSession" type="xs:int" use="required"/>
</xs:complexType>
<xs:complexType name="simpleActiveSession">
<xs:sequence>
<xs:element name="user_name" type="xs:string" minOccurs="0"/>
<xs:element name="calling_station_id" type="xs:string" minOccurs="0"/>
<xs:element name="nas_ip_address" type="xs:string" minOccurs="0"/>
<xs:element name="acct_session_id" type="xs:string" minOccurs="0"/>
<xs:element name="audit_session_id" type="xs:string" minOccurs="0"/>
<xs:element name="server" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-7
Chapter 2
Session Management Query APIs
Simple Session List API Calls
Invoking the AuthList API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the AuthList API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/Session/<specific-api-call>):
Note
The first of the following two examples uses a defined starttime and null parameter, which
displays a list of the currently active sessions that were authenticated after the specified start
time. The second example uses the null/null parameter that displays a list of all currently active
authenticated sessions. See Sample Data Returned from the AuthList API Call with the null/null
Option, page 2-8, which displays samples of the four parameter setting types for this API call.
https://acme123/admin/API/mnt/Session/AuthList/2010-12-14 15:33:15/null
https://acme123/admin/API/mnt/Session/AuthList/null/null
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the AuthList API Call with the null/null Option
The following example illustrate the list of currently active authenticated sessions that is returned when
you invoke an AuthList API call using the null/null option:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<activeSessionList noOfActiveSession="3">
<activeSession>
<user_name>ipepwlcuser</user_name>
<calling_station_id>00:26:82:7B:D2:51</calling_station_id>
<nas_ip_address>10.203.107.10</nas_ip_address>
<audit_session_id>0acb6b0c000000174D07F487</audit_session_id>
<server>HAREESH-R6-1-PDP2</server>
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-8
OL-26134-01
Chapter 2
Session Management Query APIs
Simple Session List API Calls
</activeSession>
<activeSession>
<user_name>tom_wolfe</user_name>
<calling_station_id>00:50:56:8E:28:BD</calling_station_id>
<nas_ip_address>10.203.107.161</nas_ip_address>
<acct_session_id>00000035</acct_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
<activeSession>
<user_name>graham_hancock</user_name>
<calling_station_id>00:14:BF:5A:0C:03</calling_station_id>
<nas_ip_address>10.203.107.161</nas_ip_address>
<acct_session_id>00000033</acct_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
</activeSessionList>
Sample Data Returned from the AuthList API Call with the endtime/null Option
The following example illustrate the list of currently active authenticated sessions that is returned when
you invoke an AuthList API call using the endtime/null option:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<activeSessionList noOfActiveSession="3">
<activeSession>
<user_name>ipepwlcuser</user_name>
<calling_station_id>00:26:82:7B:D2:51</calling_station_id>
<nas_ip_address>10.203.107.10</nas_ip_address>
<audit_session_id>0acb6b0c0000001F4D08085A</audit_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
<activeSession>
<user_name>hunter_thompson</user_name>
<calling_station_id>00:50:56:8E:28:BD</calling_station_id>
<nas_ip_address>10.203.107.161</nas_ip_address>
<acct_session_id>00000035</acct_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
<activeSession>
<user_name>bob_ludlum</user_name>
<calling_station_id>00:14:BF:5A:0C:03</calling_station_id>
<nas_ip_address>10.203.107.161</nas_ip_address>
<acct_session_id>00000033</acct_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
</activeSessionList>
Sample Data Returned from the AuthList API Call with the null/starttime Option
The following example illustrate the list of currently active authenticated sessions that is returned when
you invoke an AuthList API call using the null/starttime option:
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-9
Chapter 2
Session Management Query APIs
Simple Session List API Calls
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<activeSessionList noOfActiveSession="3">
<activeSession>
<user_name>ipepwlcuser</user_name>
<calling_station_id>00:26:82:7B:D2:51</calling_station_id>
<nas_ip_address>10.203.107.10</nas_ip_address>
<audit_session_id>0acb6b0c0000001F4D08085A</audit_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
<activeSession>
<user_name>bob_ludlum</user_name>
<calling_station_id>00:50:56:8E:28:BD</calling_station_id>
<nas_ip_address>10.203.107.161</nas_ip_address>
<acct_session_id>00000035</acct_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
<activeSession>
<user_name>tom_wolfe</user_name>
<calling_station_id>00:14:BF:5A:0C:03</calling_station_id>
<nas_ip_address>10.203.107.161</nas_ip_address>
<acct_session_id>00000033</acct_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
</activeSessionList>
Sample Data Returned from the AuthList API Call with the statttime/endtime Option
The following example illustrate the list of currently active authenticated sessions that is returned when
you invoke an AuthList API call using the starttime/endtime option:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<activeSessionList noOfActiveSession="3">
<activeSession>
<user_name>ipepwlcuser</user_name>
<calling_station_id>00:26:82:7B:D2:51</calling_station_id>
<nas_ip_address>10.203.107.10</nas_ip_address>
<audit_session_id>0acb6b0c0000001F4D08085A</audit_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
<activeSession>
<user_name>graham_hancock</user_name>
<calling_station_id>00:50:56:8E:28:BD</calling_station_id>
<nas_ip_address>10.203.107.161</nas_ip_address>
<acct_session_id>00000035</acct_session_id>
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
<activeSession>
<user_name>hunter_thompson</user_name>
<calling_station_id>00:14:BF:5A:0C:03</calling_station_id>
<nas_ip_address>10.203.107.161</nas_ip_address>
<acct_session_id>00000033</acct_session_id>
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-10
OL-26134-01
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<server>HAREESH-R6-1-PDP2</server>
</activeSession>
</activeSessionList>
Detailed Session Attribute API Calls
The following detailed session attribute API calls let you quickly search the latest session for key
information, such as the following:
•
MAC address session search (MACAddress)
•
User name session search (UserName)
•
NAS IP address session search (IPAddress associated with a target Monitoring ISE node)
MAC Address Session Search
You can use the MACAddress API call to retrieve a specified MAC address from a current, active
session. This API call lists a variety of session-related information drawn from node database tables.
MACAddress API Output Schema
This sample schema file is the output of the MACAddress API call for retrieving a specified MAC
address from the current active sessions:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="sessionParameters" type="restsdStatus"/>
<xs:complexType
<xs:sequence>
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
name="restsdStatus">
name="passed" type="xs:anyType" minOccurs="0"/>
name="failed" type="xs:anyType" minOccurs="0"/>
name="user_name" type="xs:string" minOccurs="0"/>
name="nas_ip_address" type="xs:string" minOccurs="0"/>
name="failure_reason" type="xs:string" minOccurs="0"/>
name="calling_station_id" type="xs:string" minOccurs="0"/>
name="nas_port" type="xs:string" minOccurs="0"/>
name="identity_group" type="xs:string" minOccurs="0"/>
name="network_device_name" type="xs:string" minOccurs="0"/>
name="acs_server" type="xs:string" minOccurs="0"/>
name="authen_protocol" type="xs:string" minOccurs="0"/>
name="framed_ip_address" type="xs:string" minOccurs="0"/>
name="network_device_groups" type="xs:string" minOccurs="0"/>
name="access_service" type="xs:string" minOccurs="0"/>
name="auth_acs_timestamp" type="xs:dateTime" minOccurs="0"/>
name="authentication_method" type="xs:string" minOccurs="0"/>
name="execution_steps" type="xs:string" minOccurs="0"/>
name="radius_response" type="xs:string" minOccurs="0"/>
name="audit_session_id" type="xs:string" minOccurs="0"/>
name="nas_identifier" type="xs:string" minOccurs="0"/>
name="nas_port_id" type="xs:string" minOccurs="0"/>
name="nac_policy_compliance" type="xs:string" minOccurs="0"/>
name="auth_id" type="xs:long" minOccurs="0"/>
name="auth_acsview_timestamp" type="xs:dateTime" minOccurs="0"/>
name="message_code" type="xs:string" minOccurs="0"/>
name="acs_session_id" type="xs:string" minOccurs="0"/>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-11
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
name="service_selection_policy" type="xs:string" minOccurs="0"/>
name="authorization_policy" type="xs:string" minOccurs="0"/>
name="identity_store" type="xs:string" minOccurs="0"/>
name="response" type="xs:string" minOccurs="0"/>
name="service_type" type="xs:string" minOccurs="0"/>
name="cts_security_group" type="xs:string" minOccurs="0"/>
name="use_case" type="xs:string" minOccurs="0"/>
name="cisco_av_pair" type="xs:string" minOccurs="0"/>
name="ad_domain" type="xs:string" minOccurs="0"/>
name="acs_username" type="xs:string" minOccurs="0"/>
name="radius_username" type="xs:string" minOccurs="0"/>
name="nac_role" type="xs:string" minOccurs="0"/>
name="nac_username" type="xs:string" minOccurs="0"/>
name="nac_posture_token" type="xs:string" minOccurs="0"/>
name="nac_radius_is_user_auth" type="xs:string" minOccurs="0"/>
name="selected_posture_server" type="xs:string" minOccurs="0"/>
name="selected_identity_store" type="xs:string" minOccurs="0"/>
name="authentication_identity_store" type="xs:string" minOccurs="0"/>
name="azn_exp_pol_matched_rule" type="xs:string" minOccurs="0"/>
name="ext_pol_server_matched_rule" type="xs:string" minOccurs="0"/>
name="grp_mapping_pol_matched_rule" type="xs:string" minOccurs="0"/>
name="identity_policy_matched_rule" type="xs:string" minOccurs="0"/>
name="nas_port_type" type="xs:string" minOccurs="0"/>
name="query_identity_stores" type="xs:string" minOccurs="0"/>
name="selected_azn_profiles" type="xs:string" minOccurs="0"/>
name="sel_exp_azn_profiles" type="xs:string" minOccurs="0"/>
name="selected_query_identity_stores" type="xs:string" minOccurs="0"/>
name="eap_tunnel" type="xs:string" minOccurs="0"/>
name="tunnel_details" type="xs:string" minOccurs="0"/>
name="cisco_h323_attributes" type="xs:string" minOccurs="0"/>
name="cisco_ssg_attributes" type="xs:string" minOccurs="0"/>
name="other_attributes" type="xs:string" minOccurs="0"/>
name="response_time" type="xs:long" minOccurs="0"/>
name="nad_failure" type="xs:anyType" minOccurs="0"/>
name="destination_ip_address" type="xs:string" minOccurs="0"/>
name="acct_id" type="xs:long" minOccurs="0"/>
name="acct_acs_timestamp" type="xs:dateTime" minOccurs="0"/>
name="acct_acsview_timestamp" type="xs:dateTime" minOccurs="0"/>
name="acct_session_id" type="xs:string" minOccurs="0"/>
name="acct_status_type" type="xs:string" minOccurs="0"/>
name="acct_session_time" type="xs:long" minOccurs="0"/>
name="acct_input_octets" type="xs:string" minOccurs="0"/>
name="acct_output_octets" type="xs:string" minOccurs="0"/>
name="acct_input_packets" type="xs:long" minOccurs="0"/>
name="acct_output_packets" type="xs:long" minOccurs="0"/>
name="acct_class" type="xs:string" minOccurs="0"/>
name="acct_terminate_cause" type="xs:string" minOccurs="0"/>
name="acct_multi_session_id" type="xs:string" minOccurs="0"/>
name="acct_authentic" type="xs:string" minOccurs="0"/>
name="termination_action" type="xs:string" minOccurs="0"/>
name="session_timeout" type="xs:string" minOccurs="0"/>
name="idle_timeout" type="xs:string" minOccurs="0"/>
name="acct_interim_interval" type="xs:string" minOccurs="0"/>
name="acct_delay_time" type="xs:string" minOccurs="0"/>
name="event_timestamp" type="xs:string" minOccurs="0"/>
name="acct_tunnel_connection" type="xs:string" minOccurs="0"/>
name="acct_tunnel_packet_lost" type="xs:string" minOccurs="0"/>
name="security_group" type="xs:string" minOccurs="0"/>
name="cisco_h323_setup_time" type="xs:dateTime" minOccurs="0"/>
name="cisco_h323_connect_time" type="xs:dateTime" minOccurs="0"/>
name="cisco_h323_disconnect_time" type="xs:dateTime" minOccurs="0"/>
name="framed_protocol" type="xs:string" minOccurs="0"/>
name="started" type="xs:anyType" minOccurs="0"/>
name="stopped" type="xs:anyType" minOccurs="0"/>
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-12
OL-26134-01
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<xs:element name="ckpt_id" type="xs:long" minOccurs="0"/>
<xs:element name="type" type="xs:long" minOccurs="0"/>
<xs:element name="nad_acsview_timestamp" type="xs:dateTime" minOccurs="0"/>
<xs:element name="vlan" type="xs:string" minOccurs="0"/>
<xs:element name="dacl" type="xs:string" minOccurs="0"/>
<xs:element name="authentication_type" type="xs:string" minOccurs="0"/>
<xs:element name="interface_name" type="xs:string" minOccurs="0"/>
<xs:element name="reason" type="xs:string" minOccurs="0"/>
<xs:element name="endpoint_policy" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Invoking the MACAddress API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the MACAddress API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/<specific-api-call>/<macaddress>):
https://acme123/admin/API/mnt/Session/MACAddress/0A:0B:0C:0D:0E:0F
Step 5
Note
Make sure that you specify the MAC address using the XX:XX:XX:XX:XX:XX format.
Note
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the MACAddress API Call
The following example illustrates the session-related data returned from the list of active sessions when
you invoke an ActiveList API call:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
-
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-13
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<sessionParameters>
<passed xsi:type="xs:boolean">true</passed>
<failed xsi:type="xs:boolean">false</failed>
<user_name>hunter_thompson</user_name>
<nas_ip_address>10.203.107.161</nas_ip_address>
<calling_station_id>00:14:BF:5A:0C:03</calling_station_id>
<nas_port>50115</nas_port>
<identity_group>Profiled</identity_group>
<network_device_name>Core-Switch</network_device_name>
<acs_server>HAREESH-R6-1-PDP2</acs_server>
<authen_protocol>Lookup</authen_protocol>
<network_device_groups>
Device Type#All Device Types,Location#All Locations
</network_device_groups>
<access_service>RADIUS</access_service>
<auth_acs_timestamp>2010-12-15T02:11:12.359Z</auth_acs_timestamp>
<authentication_method>mab</authentication_method>
<execution_steps>
11001,11017,11027,15008,15048,15004,15041,15004,15013,24209,24211,22037,15036,15048,15048,
15004,15016,11022,11002
</execution_steps>
<audit_session_id>0ACB6BA1000000351BBFBF8B</audit_session_id>
<nas_port_id>GigabitEthernet1/0/15</nas_port_id>
<nac_policy_compliance>Pending</nac_policy_compliance>
<auth_id>1291240762077361</auth_id>
<auth_acsview_timestamp>2010-12-15T02:11:12.360Z</auth_acsview_timestamp>
<message_code>5200</message_code>
<acs_session_id>HAREESH-R6-1-PDP2/81148292/681</acs_session_id>
<service_selection_policy>MAB</service_selection_policy>
<identity_store>Internal Hosts</identity_store>
<response>
{UserName=00-14-BF-5A-0C-03; User-Name=00-14-BF-5A-0C-03;
State=ReauthSession:0ACB6BA1000000351BBFBF8B;
Class=CACS:0ACB6BA1000000351BBFBF8B:HAREESH-R6-1-PDP2/81148292/681;
Termination-Action=RADIUS-Request; cisco-av-pair=url-redirect-acl=ACL-WEBAUTH-REDIRECT;
cisco-av-pair=url-redirect=https://HAREESH-R6-1-PDP2.cisco.com:8443/guestportal/gateway?se
ssionId=0ACB6BA1000000351BBFBF8B&action=cwa;
cisco-av-pair=ACS:CiscoSecure-Defined-ACL=#ACSACL#-IP-ACL-DENY-4ced8390; }
</response>
<service_type>Call Check</service_type>
<use_case>Host Lookup</use_case>
<cisco_av_pair>audit-session-id=0ACB6BA1000000351BBFBF8B</cisco_av_pair>
<acs_username>00:14:BF:5A:0C:03</acs_username>
<radius_username>00:14:BF:5A:0C:03</radius_username>
<selected_identity_store>Internal Hosts</selected_identity_store>
<authentication_identity_store>Internal Hosts</authentication_identity_store>
<identity_policy_matched_rule>Default</identity_policy_matched_rule>
<nas_port_type>Ethernet</nas_port_type>
<selected_azn_profiles>CWA</selected_azn_profiles>
<other_attributes>
ConfigVersionId=44,DestinationIPAddress=10.203.107.162,DestinationPort=1812,Protocol=Radiu
s,Framed-MTU=1500,EAP-Key-Name=,CPMSessionID=0ACB6BA1000000351BBFBF8B,CPMSessionID=0ACB6BA
1000000351BBFBF8B,EndPointMACAddress=00-14-BF-5A-0C-03,HostIdentityGroup=Endpoint Identity
Groups:Profiled,Device Type=Device Type#All Device Types,Location=Location#All
Locations,Model Name=Unknown,Software Version=Unknown,Device IP
Address=10.203.107.161,Called-Station-ID=04:FE:7F:7F:C0:8F
</other_attributes>
<response_time>77</response_time>
<acct_id>1291240762077386</acct_id>
<acct_acs_timestamp>2010-12-15T02:12:30.779Z</acct_acs_timestamp>
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-14
OL-26134-01
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<acct_acsview_timestamp>2010-12-15T02:12:30.780Z</acct_acsview_timestamp>
<acct_session_id>00000038</acct_session_id>
<acct_status_type>Interim-Update</acct_status_type>
<acct_session_time>78</acct_session_time>
<acct_input_octets>13742</acct_input_octets>
<acct_output_octets>6277</acct_output_octets>
<acct_input_packets>108</acct_input_packets>
<acct_output_packets>66</acct_output_packets>
<acct_class>
CACS:0ACB6BA1000000351BBFBF8B:HAREESH-R6-1-PDP2/81148292/681
</acct_class>
<acct_delay_time>0</acct_delay_time>
<started xsi:type="xs:boolean">false</started>
<stopped xsi:type="xs:boolean">false</stopped>
</sessionParameters>
User Name Session Search
You can use the UserName API call to retrieve a specified user name from a current, active session. This
API will list a variety of session-related information drawn from node database tables.
UserName API Output Schema
This sample schema file is the output of the UserName API call for retrieving a specified user name from
the current active sessions:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="sessionParameters" type="restsdStatus"/>
<xs:complexType
<xs:sequence>
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
name="restsdStatus">
name="passed" type="xs:anyType" minOccurs="0"/>
name="failed" type="xs:anyType" minOccurs="0"/>
name="user_name" type="xs:string" minOccurs="0"/>
name="nas_ip_address" type="xs:string" minOccurs="0"/>
name="failure_reason" type="xs:string" minOccurs="0"/>
name="calling_station_id" type="xs:string" minOccurs="0"/>
name="nas_port" type="xs:string" minOccurs="0"/>
name="identity_group" type="xs:string" minOccurs="0"/>
name="network_device_name" type="xs:string" minOccurs="0"/>
name="acs_server" type="xs:string" minOccurs="0"/>
name="authen_protocol" type="xs:string" minOccurs="0"/>
name="framed_ip_address" type="xs:string" minOccurs="0"/>
name="network_device_groups" type="xs:string" minOccurs="0"/>
name="access_service" type="xs:string" minOccurs="0"/>
name="auth_acs_timestamp" type="xs:dateTime" minOccurs="0"/>
name="authentication_method" type="xs:string" minOccurs="0"/>
name="execution_steps" type="xs:string" minOccurs="0"/>
name="radius_response" type="xs:string" minOccurs="0"/>
name="audit_session_id" type="xs:string" minOccurs="0"/>
name="nas_identifier" type="xs:string" minOccurs="0"/>
name="nas_port_id" type="xs:string" minOccurs="0"/>
name="nac_policy_compliance" type="xs:string" minOccurs="0"/>
name="auth_id" type="xs:long" minOccurs="0"/>
name="auth_acsview_timestamp" type="xs:dateTime" minOccurs="0"/>
name="message_code" type="xs:string" minOccurs="0"/>
name="acs_session_id" type="xs:string" minOccurs="0"/>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-15
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
name="service_selection_policy" type="xs:string" minOccurs="0"/>
name="authorization_policy" type="xs:string" minOccurs="0"/>
name="identity_store" type="xs:string" minOccurs="0"/>
name="response" type="xs:string" minOccurs="0"/>
name="service_type" type="xs:string" minOccurs="0"/>
name="cts_security_group" type="xs:string" minOccurs="0"/>
name="use_case" type="xs:string" minOccurs="0"/>
name="cisco_av_pair" type="xs:string" minOccurs="0"/>
name="ad_domain" type="xs:string" minOccurs="0"/>
name="acs_username" type="xs:string" minOccurs="0"/>
name="radius_username" type="xs:string" minOccurs="0"/>
name="nac_role" type="xs:string" minOccurs="0"/>
name="nac_username" type="xs:string" minOccurs="0"/>
name="nac_posture_token" type="xs:string" minOccurs="0"/>
name="nac_radius_is_user_auth" type="xs:string" minOccurs="0"/>
name="selected_posture_server" type="xs:string" minOccurs="0"/>
name="selected_identity_store" type="xs:string" minOccurs="0"/>
name="authentication_identity_store" type="xs:string" minOccurs="0"/>
name="azn_exp_pol_matched_rule" type="xs:string" minOccurs="0"/>
name="ext_pol_server_matched_rule" type="xs:string" minOccurs="0"/>
name="grp_mapping_pol_matched_rule" type="xs:string" minOccurs="0"/>
name="identity_policy_matched_rule" type="xs:string" minOccurs="0"/>
name="nas_port_type" type="xs:string" minOccurs="0"/>
name="query_identity_stores" type="xs:string" minOccurs="0"/>
name="selected_azn_profiles" type="xs:string" minOccurs="0"/>
name="sel_exp_azn_profiles" type="xs:string" minOccurs="0"/>
name="selected_query_identity_stores" type="xs:string" minOccurs="0"/>
name="eap_tunnel" type="xs:string" minOccurs="0"/>
name="tunnel_details" type="xs:string" minOccurs="0"/>
name="cisco_h323_attributes" type="xs:string" minOccurs="0"/>
name="cisco_ssg_attributes" type="xs:string" minOccurs="0"/>
name="other_attributes" type="xs:string" minOccurs="0"/>
name="response_time" type="xs:long" minOccurs="0"/>
name="nad_failure" type="xs:anyType" minOccurs="0"/>
name="destination_ip_address" type="xs:string" minOccurs="0"/>
name="acct_id" type="xs:long" minOccurs="0"/>
name="acct_acs_timestamp" type="xs:dateTime" minOccurs="0"/>
name="acct_acsview_timestamp" type="xs:dateTime" minOccurs="0"/>
name="acct_session_id" type="xs:string" minOccurs="0"/>
name="acct_status_type" type="xs:string" minOccurs="0"/>
name="acct_session_time" type="xs:long" minOccurs="0"/>
name="acct_input_octets" type="xs:string" minOccurs="0"/>
name="acct_output_octets" type="xs:string" minOccurs="0"/>
name="acct_input_packets" type="xs:long" minOccurs="0"/>
name="acct_output_packets" type="xs:long" minOccurs="0"/>
name="acct_class" type="xs:string" minOccurs="0"/>
name="acct_terminate_cause" type="xs:string" minOccurs="0"/>
name="acct_multi_session_id" type="xs:string" minOccurs="0"/>
name="acct_authentic" type="xs:string" minOccurs="0"/>
name="termination_action" type="xs:string" minOccurs="0"/>
name="session_timeout" type="xs:string" minOccurs="0"/>
name="idle_timeout" type="xs:string" minOccurs="0"/>
name="acct_interim_interval" type="xs:string" minOccurs="0"/>
name="acct_delay_time" type="xs:string" minOccurs="0"/>
name="event_timestamp" type="xs:string" minOccurs="0"/>
name="acct_tunnel_connection" type="xs:string" minOccurs="0"/>
name="acct_tunnel_packet_lost" type="xs:string" minOccurs="0"/>
name="security_group" type="xs:string" minOccurs="0"/>
name="cisco_h323_setup_time" type="xs:dateTime" minOccurs="0"/>
name="cisco_h323_connect_time" type="xs:dateTime" minOccurs="0"/>
name="cisco_h323_disconnect_time" type="xs:dateTime" minOccurs="0"/>
name="framed_protocol" type="xs:string" minOccurs="0"/>
name="started" type="xs:anyType" minOccurs="0"/>
name="stopped" type="xs:anyType" minOccurs="0"/>
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-16
OL-26134-01
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<xs:element name="ckpt_id" type="xs:long" minOccurs="0"/>
<xs:element name="type" type="xs:long" minOccurs="0"/>
<xs:element name="nad_acsview_timestamp" type="xs:dateTime" minOccurs="0"/>
<xs:element name="vlan" type="xs:string" minOccurs="0"/>
<xs:element name="dacl" type="xs:string" minOccurs="0"/>
<xs:element name="authentication_type" type="xs:string" minOccurs="0"/>
<xs:element name="interface_name" type="xs:string" minOccurs="0"/>
<xs:element name="reason" type="xs:string" minOccurs="0"/>
<xs:element name="endpoint_policy" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Invoking the UserName API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the UserName API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/<specific-api-call>/<username>):
https://acme123/admin/API/mnt/Session/UserName/graham_hancock
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the UserName API Call
The following example illustrates the session-related data returned from the list of active sessions when
you invoke a UserName API call:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<sessionParameters>
<passed xsi:type="xs:boolean">true</passed>
<failed xsi:type="xs:boolean">false</failed>
<user_name>graham_hancock</user_name>
<nas_ip_address>10.203.107.161</nas_ip_address>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-17
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<calling_station_id>00:14:BF:5A:0C:03</calling_station_id>
<nas_port>50115</nas_port>
<identity_group>Profiled</identity_group>
<network_device_name>Core-Switch</network_device_name>
<acs_server>HAREESH-R6-1-PDP2</acs_server>
<authen_protocol>Lookup</authen_protocol>
<network_device_groups>
Device Type#All Device Types,Location#All Locations
</network_device_groups>
<access_service>RADIUS</access_service>
<auth_acs_timestamp>2010-12-15T02:11:12.359Z</auth_acs_timestamp>
<authentication_method>mab</authentication_method>
<execution_steps>
11001,11017,11027,15008,15048,15004,15041,15004,15013,24209,24211,22037,15036,15048,15048,
15004,15016,11022,11002
</execution_steps>
<audit_session_id>0ACB6BA1000000351BBFBF8B</audit_session_id>
<nas_port_id>GigabitEthernet1/0/15</nas_port_id>
<nac_policy_compliance>Pending</nac_policy_compliance>
<auth_id>1291240762077361</auth_id>
<auth_acsview_timestamp>2010-12-15T02:11:12.360Z</auth_acsview_timestamp>
<message_code>5200</message_code>
<acs_session_id>HAREESH-R6-1-PDP2/81148292/681</acs_session_id>
<service_selection_policy>MAB</service_selection_policy>
<identity_store>Internal Hosts</identity_store>
<response>
{UserName=graham_hancock; User-Name=graham_hancock;
State=ReauthSession:0ACB6BA1000000351BBFBF8B;
Class=CACS:0ACB6BA1000000351BBFBF8B:HAREESH-R6-1-PDP2/81148292/681;
Termination-Action=RADIUS-Request; cisco-av-pair=url-redirect-acl=ACL-WEBAUTH-REDIRECT;
cisco-av-pair=url-redirect=https://HAREESH-R6-1-PDP2.cisco.com:8443/guestportal/gateway?se
ssionId=0ACB6BA1000000351BBFBF8B&action=cwa;
cisco-av-pair=ACS:CiscoSecure-Defined-ACL=#ACSACL#-IP-ACL-DENY-4ced8390; }
</response>
<service_type>Call Check</service_type>
<use_case>Host Lookup</use_case>
<cisco_av_pair>audit-session-id=0ACB6BA1000000351BBFBF8B</cisco_av_pair>
<acs_username>graham_hancock</acs_username>
<radius_username>00:14:BF:5A:0C:03</radius_username>
<selected_identity_store>Internal Hosts</selected_identity_store>
<authentication_identity_store>Internal Hosts</authentication_identity_store>
<identity_policy_matched_rule>Default</identity_policy_matched_rule>
<nas_port_type>Ethernet</nas_port_type>
<selected_azn_profiles>CWA</selected_azn_profiles>
<other_attributes>
ConfigVersionId=44,DestinationIPAddress=10.203.107.162,DestinationPort=1812,Protocol=Radiu
s,Framed-MTU=1500,EAP-Key-Name=,CPMSessionID=0ACB6BA1000000351BBFBF8B,CPMSessionID=0ACB6BA
1000000351BBFBF8B,EndPointMACAddress=00-14-BF-5A-0C-03,HostIdentityGroup=Endpoint Identity
Groups:Profiled,Device Type=Device Type#All Device Types,Location=Location#All
Locations,Model Name=Unknown,Software Version=Unknown,Device IP
Address=10.203.107.161,Called-Station-ID=04:FE:7F:7F:C0:8F
</other_attributes>
<response_time>77</response_time>
<acct_id>1291240762077386</acct_id>
<acct_acs_timestamp>2010-12-15T02:12:30.779Z</acct_acs_timestamp>
<acct_acsview_timestamp>2010-12-15T02:12:30.780Z</acct_acsview_timestamp>
<acct_session_id>00000038</acct_session_id>
<acct_status_type>Interim-Update</acct_status_type>
<acct_session_time>78</acct_session_time>
<acct_input_octets>13742</acct_input_octets>
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-18
OL-26134-01
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<acct_output_octets>6277</acct_output_octets>
<acct_input_packets>108</acct_input_packets>
<acct_output_packets>66</acct_output_packets>
<acct_class>
CACS:0ACB6BA1000000351BBFBF8B:HAREESH-R6-1-PDP2/81148292/681
</acct_class>
<acct_delay_time>0</acct_delay_time>
<started xsi:type="xs:boolean">false</started>
<stopped xsi:type="xs:boolean">false</stopped>
</sessionParameters>
NAS IP Address Session Search
You can use the IPAddress API call to retrieve data for a specified NAS IP address from a current session.
This API will list a variety of session-related information drawn from node database tables.
IPAddress API Output Schema
This sample schema file is the output of the IPAddress API call for retrieving a specified NAS IP address
from the current active sessions:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="sessionParameters" type="restsdStatus"/>
<xs:complexType
<xs:sequence>
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
name="restsdStatus">
name="passed" type="xs:anyType" minOccurs="0"/>
name="failed" type="xs:anyType" minOccurs="0"/>
name="user_name" type="xs:string" minOccurs="0"/>
name="nas_ip_address" type="xs:string" minOccurs="0"/>
name="failure_reason" type="xs:string" minOccurs="0"/>
name="calling_station_id" type="xs:string" minOccurs="0"/>
name="nas_port" type="xs:string" minOccurs="0"/>
name="identity_group" type="xs:string" minOccurs="0"/>
name="network_device_name" type="xs:string" minOccurs="0"/>
name="acs_server" type="xs:string" minOccurs="0"/>
name="authen_protocol" type="xs:string" minOccurs="0"/>
name="framed_ip_address" type="xs:string" minOccurs="0"/>
name="network_device_groups" type="xs:string" minOccurs="0"/>
name="access_service" type="xs:string" minOccurs="0"/>
name="auth_acs_timestamp" type="xs:dateTime" minOccurs="0"/>
name="authentication_method" type="xs:string" minOccurs="0"/>
name="execution_steps" type="xs:string" minOccurs="0"/>
name="radius_response" type="xs:string" minOccurs="0"/>
name="audit_session_id" type="xs:string" minOccurs="0"/>
name="nas_identifier" type="xs:string" minOccurs="0"/>
name="nas_port_id" type="xs:string" minOccurs="0"/>
name="nac_policy_compliance" type="xs:string" minOccurs="0"/>
name="auth_id" type="xs:long" minOccurs="0"/>
name="auth_acsview_timestamp" type="xs:dateTime" minOccurs="0"/>
name="message_code" type="xs:string" minOccurs="0"/>
name="acs_session_id" type="xs:string" minOccurs="0"/>
name="service_selection_policy" type="xs:string" minOccurs="0"/>
name="authorization_policy" type="xs:string" minOccurs="0"/>
name="identity_store" type="xs:string" minOccurs="0"/>
name="response" type="xs:string" minOccurs="0"/>
name="service_type" type="xs:string" minOccurs="0"/>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-19
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
name="cts_security_group" type="xs:string" minOccurs="0"/>
name="use_case" type="xs:string" minOccurs="0"/>
name="cisco_av_pair" type="xs:string" minOccurs="0"/>
name="ad_domain" type="xs:string" minOccurs="0"/>
name="acs_username" type="xs:string" minOccurs="0"/>
name="radius_username" type="xs:string" minOccurs="0"/>
name="nac_role" type="xs:string" minOccurs="0"/>
name="nac_username" type="xs:string" minOccurs="0"/>
name="nac_posture_token" type="xs:string" minOccurs="0"/>
name="nac_radius_is_user_auth" type="xs:string" minOccurs="0"/>
name="selected_posture_server" type="xs:string" minOccurs="0"/>
name="selected_identity_store" type="xs:string" minOccurs="0"/>
name="authentication_identity_store" type="xs:string" minOccurs="0"/>
name="azn_exp_pol_matched_rule" type="xs:string" minOccurs="0"/>
name="ext_pol_server_matched_rule" type="xs:string" minOccurs="0"/>
name="grp_mapping_pol_matched_rule" type="xs:string" minOccurs="0"/>
name="identity_policy_matched_rule" type="xs:string" minOccurs="0"/>
name="nas_port_type" type="xs:string" minOccurs="0"/>
name="query_identity_stores" type="xs:string" minOccurs="0"/>
name="selected_azn_profiles" type="xs:string" minOccurs="0"/>
name="sel_exp_azn_profiles" type="xs:string" minOccurs="0"/>
name="selected_query_identity_stores" type="xs:string" minOccurs="0"/>
name="eap_tunnel" type="xs:string" minOccurs="0"/>
name="tunnel_details" type="xs:string" minOccurs="0"/>
name="cisco_h323_attributes" type="xs:string" minOccurs="0"/>
name="cisco_ssg_attributes" type="xs:string" minOccurs="0"/>
name="other_attributes" type="xs:string" minOccurs="0"/>
name="response_time" type="xs:long" minOccurs="0"/>
name="nad_failure" type="xs:anyType" minOccurs="0"/>
name="destination_ip_address" type="xs:string" minOccurs="0"/>
name="acct_id" type="xs:long" minOccurs="0"/>
name="acct_acs_timestamp" type="xs:dateTime" minOccurs="0"/>
name="acct_acsview_timestamp" type="xs:dateTime" minOccurs="0"/>
name="acct_session_id" type="xs:string" minOccurs="0"/>
name="acct_status_type" type="xs:string" minOccurs="0"/>
name="acct_session_time" type="xs:long" minOccurs="0"/>
name="acct_input_octets" type="xs:string" minOccurs="0"/>
name="acct_output_octets" type="xs:string" minOccurs="0"/>
name="acct_input_packets" type="xs:long" minOccurs="0"/>
name="acct_output_packets" type="xs:long" minOccurs="0"/>
name="acct_class" type="xs:string" minOccurs="0"/>
name="acct_terminate_cause" type="xs:string" minOccurs="0"/>
name="acct_multi_session_id" type="xs:string" minOccurs="0"/>
name="acct_authentic" type="xs:string" minOccurs="0"/>
name="termination_action" type="xs:string" minOccurs="0"/>
name="session_timeout" type="xs:string" minOccurs="0"/>
name="idle_timeout" type="xs:string" minOccurs="0"/>
name="acct_interim_interval" type="xs:string" minOccurs="0"/>
name="acct_delay_time" type="xs:string" minOccurs="0"/>
name="event_timestamp" type="xs:string" minOccurs="0"/>
name="acct_tunnel_connection" type="xs:string" minOccurs="0"/>
name="acct_tunnel_packet_lost" type="xs:string" minOccurs="0"/>
name="security_group" type="xs:string" minOccurs="0"/>
name="cisco_h323_setup_time" type="xs:dateTime" minOccurs="0"/>
name="cisco_h323_connect_time" type="xs:dateTime" minOccurs="0"/>
name="cisco_h323_disconnect_time" type="xs:dateTime" minOccurs="0"/>
name="framed_protocol" type="xs:string" minOccurs="0"/>
name="started" type="xs:anyType" minOccurs="0"/>
name="stopped" type="xs:anyType" minOccurs="0"/>
name="ckpt_id" type="xs:long" minOccurs="0"/>
name="type" type="xs:long" minOccurs="0"/>
name="nad_acsview_timestamp" type="xs:dateTime" minOccurs="0"/>
name="vlan" type="xs:string" minOccurs="0"/>
name="dacl" type="xs:string" minOccurs="0"/>
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-20
OL-26134-01
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<xs:element name="authentication_type" type="xs:string" minOccurs="0"/>
<xs:element name="interface_name" type="xs:string" minOccurs="0"/>
<xs:element name="reason" type="xs:string" minOccurs="0"/>
<xs:element name="endpoint_policy" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Invoking the NAS IPAddress API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the IPAddress API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/<specific-api-call>/<nasipaddress>):
https://acme123/admin/API/mnt/Session/IPAddress/10.10.10.10
Step 5
Note
Make sure that you specify the NAS IP address using the xxx.xxx.xxx.xxx format.
Note
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the IPAddress API Call
The following example illustrates the session-related data returned from the list of active sessions when
you invoke an IPAddress API call:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<sessionParameters>
<passed xsi:type="xs:boolean">true</passed>
<failed xsi:type="xs:boolean">false</failed>
<user_name>ipepvpnuser</user_name>
<nas_ip_address>10.10.10.10</nas_ip_address>
<calling_station_id>172.23.130.90</calling_station_id>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-21
Chapter 2
Session Management Query APIs
Detailed Session Attribute API Calls
<nas_port>1015</nas_port>
<identity_group>iPEP-VPN-Group</identity_group>
<network_device_name>iPEP-HA-Routed</network_device_name>
<acs_server>HAREESH-R6-1-PDP2</acs_server>
<authen_protocol>PAP_ASCII</authen_protocol>
<network_device_groups>
Device Type#All Device Types,Location#All Locations
</network_device_groups>
<access_service>RADIUS</access_service>
<auth_acs_timestamp>2010-12-15T19:57:29.885Z</auth_acs_timestamp>
<authentication_method>PAP_ASCII</authentication_method>
<execution_steps>
11001,11017,15008,15048,15048,15004,15041,15004,15013,24210,24212,22037,15036,15048,15048,
15004,15016,11002
</execution_steps>
<audit_session_id>0acb6be4000000044D091DA9</audit_session_id>
<nac_policy_compliance>NotApplicable</nac_policy_compliance>
<auth_id>1291240762083580</auth_id>
<auth_acsview_timestamp>2010-12-15T19:57:29.887Z</auth_acsview_timestamp>
<message_code>5200</message_code>
<acs_session_id>HAREESH-R6-1-PDP2/81148292/693</acs_session_id>
<service_selection_policy>iPEP-VPN</service_selection_policy>
<identity_store>Internal Users</identity_store>
<response>
{User-Name=ipepvpnuser; State=ReauthSession:0acb6be4000000044D091DA9;
Class=CACS:0acb6be4000000044D091DA9:HAREESH-R6-1-PDP2/81148292/693;
Termination-Action=RADIUS-Request; }
</response>
<service_type>Framed</service_type>
<cisco_av_pair>
audit-session-id=0acb6be4000000044D091DA9,ipep-proxy=true
</cisco_av_pair>
<acs_username>ipepvpnuser</acs_username>
<radius_username>ipepvpnuser</radius_username>
<selected_identity_store>Internal Users</selected_identity_store>
<authentication_identity_store>Internal Users</authentication_identity_store>
<identity_policy_matched_rule>Default</identity_policy_matched_rule>
<nas_port_type>Virtual</nas_port_type>
<selected_azn_profiles>iPEP-Unknown-Auth-Profile</selected_azn_profiles>
<tunnel_details>Tunnel-Client-Endpoint=(tag=0) 172.23.130.90</tunnel_details>
<other_attributes>
ConfigVersionId=44,DestinationIPAddress=10.203.107.162,DestinationPort=1812,Protocol=Radiu
s,Framed-Protocol=PPP,Proxy-State=Cisco Secure
ACS9e733142-070a-11e0-c000-000000000000-2906094480-3222,CPMSessionID=0acb6be4000000044D091
DA9,CPMSessionID=0acb6be4000000044D091DA9,Device Type=Device Type#All Device
Types,Location=Location#All Locations,Model Name=Unknown,Software Version=Unknown,Device
IP Address=10.203.107.228,Called-Station-ID=172.23.130.94
</other_attributes>
<response_time>20</response_time>
<acct_id>1291240762083582</acct_id>
<acct_acs_timestamp>2010-12-15T19:57:30.281Z</acct_acs_timestamp>
<acct_acsview_timestamp>2010-12-15T19:57:30.283Z</acct_acsview_timestamp>
<acct_session_id>F1800007</acct_session_id>
<acct_status_type>Start</acct_status_type>
<acct_class>
CACS:0acb6be4000000044D091DA9:HAREESH-R6-1-PDP2/81148292/693
</acct_class>
<acct_delay_time>0</acct_delay_time>
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-22
OL-26134-01
Chapter 2
Session Management Query APIs
Stale Sessions
<framed_protocol>PPP</framed_protocol>
<started xsi:type="xs:boolean">true</started>
<stopped xsi:type="xs:boolean">false</stopped>
</sessionParameters>
Stale Sessions
Some devices, such as Wireless Lan Controllers (WLCs), may allow stale sessions to linger. In such
cases, you can use the HTTP DELETE API call to manually delete the inactive sessions. To do so, use
cURL, a free 3rd-party command line tool for transferring data with URL (HTTP, HTTPS) syntax.
ISE no longer tracks those sessions. This is to mitigate the case when ISE lost connectivity to the
network for an extended period of time, and missed a pile of accounting stops from the WLC/NAD. You
can clear such stale information from ISE using this API.
Note
GNU Wget, the free utility for retrieving files using HTTP and HTTPS, does not support the HTTP
DELETE API call.
Removing Stale Sessions
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
Note
Step 4
API calls are case-sensitive, and must be entered carefully. The variable <mntnode> represents
a Cisco Monitoring ISE node.
To manually delete a stale session for a MAC address, issue the following API call on the command line:
curl -X DELETE https://<mntnode>/admin/API/mnt/Session/Delete/MACAddress/<madaddress>
Step 5
To manually delete a stale session for a session ID, issue the following API call on the command line:
curl -X DELETE https://<mntnode>/admin/API/mnt/Session/Delete/SessionID/<sid#>
Step 6
To manually delete all sessions on the Monitoring node, issue the following API call on the command
line:
curl -X DELETE https://<mntnode>/admin/API/mnt/Session/Delete/All
Related Topics
•
Verifying a Monitoring Node, page 1-2
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
2-23
Chapter 2
Session Management Query APIs
Stale Sessions
Cisco Identity Services Engine API Reference Guide, Release 1.2
2-24
OL-26134-01
CH A P T E R
3
Query APIs for Troubleshooting
This chapter provides examples and describes how to use the individual Cisco Prime Network Control
System (NCS) REST API calls.
Cisco Prime NCS API Calls
The Cisco Prime NCS API calls provide a mechanism for retrieving key troubleshooting information
about the target Cisco Monitoring ISE node sessions that include node version and type, failure reasons,
authentication status, and accounting status.
Troubleshooting Cisco ISE using the Query API Calls
Cisco Prime NCS troubleshooting API calls send status requests to the target Cisco Monitoring ISE node
in your Cisco ISE deployment and retrieve the following diagnostic-related information:
•
Node version and type (using the Version API call)
•
Failure reasons (using the FailureReasons API call)
•
Authentication status (using the AuthStatus API call)
•
Accounting status (using the AcctStatus API call)
Node Version and Type API Call
You can use the Version API call to test the REST programmatic interface (PI) service and the credentials
of each node. This section provides a schema file output example, a procedure for requesting the version
of the Cisco ISE software and the node type by invoking this API call, and a sample of the node version
and type that is returned after this API call is issued.
The node types can be any of the following:
•
STANDALONE_MNT_NODE = 0
•
ACTIVE_MNT_NODE= 1
•
BACKUP_MNT_NODE = 2
•
NOT_AN_MNT_NODE = 3
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
3-1
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
Version API Output Schema
This sample schema file is the output of the Version API call after sending it to the target Cisco
Monitoring ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="product" type="product"/>
<xs:complexType name="product">
<xs:sequence>
<xs:element name="version" type="xs:string" minOccurs="0"/>
<xs:element name="type_of_node" type="xs:int"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string"/>
</xs:complexType>
</xs:schema>
Invoking the Version API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
If your login is unsuccessful, click the Problem logging in? link in the Login page and follow the
instructions in Step 2.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the Version API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/<specific-api-call>):
https://acme123/admin/API/mnt/Version
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the Version API Call
The following example illustrates the data returned when you invoke a Version API call on a target Cisco
Monitoring ISE node. This API call returns the following two values for the target node:
Cisco Identity Services Engine API Reference Guide, Release 1.2
3-2
OL-26134-01
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
•
Node version (this example displays 1.0.3.032).
•
Type of Cisco Monitoring ISE node (this example displays a “1”, which means an active Cisco
Monitoring ISE node).
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<product name="Cisco Identity Services Engine">
<version>1.0.3.032</version>
<type_of_node>1</type_of_node>
</product>
Failure Reasons API Call
You can use the FailureReasons API call to return a list of failure reasons returned in the authentication
status check done on the target node. This section provides a schema file output example, a procedure
for requesting a list of all failure reasons logged by the Cisco Monitoring ISE node by invoking this API
call, and a sample of the failure reasons returned after this API call is issued. Each failure reason that is
returned consists of the following elements shown in Table 3-1.
Note
For details about using the Cisco ISE Failure Reasons Editor to access the complete list of failure
reasons, see Cisco ISE Failure Reasons Report, page A-1.
Table 3-1
Note
Product Documentation for Cisco Identity Services Engine
Failure Reason Elements
Example
Failure reason ID
<failureReason id="11011">
Code
<11011 RADIUS listener failed>
Cause
<Could not open one or more of the ports
used to receive RADIUS requests>
Resolution
<Ensure that the ports 1812, 1813, 1645 and
1646 are not being used by another process
on the system>
You can also check for failure reason reports using the Cisco ISE user interface (click Monitor >
Reports > Catalog > Failure Reasons), which will display failure reason reports.
FailureReasons API Output Schema
This sample schema file is the output of the FailureReasons API call after sending the request to a target
Cisco Monitoring ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="failureReasonList" type="failureReasonList"/>
<xs:complexType name="failureReasonList">
<xs:sequence>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
3-3
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
<xs:element name="failureReason" type="failureReason" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="failureReason">
<xs:sequence>
<xs:element name="code" type="xs:string" minOccurs="0"/>
<xs:element name="cause" type="xs:string" minOccurs="0"/>
<xs:element name="resolution" type="xs:string" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="id" type="xs:string"/>
</xs:complexType>
</xs:schema>
Invoking the FailureReasons API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
If your login is unsuccessful, click the Problem logging in? link in the Login page and follow the
instructions in Step 2.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the FailureReasons API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/<specific-api-call>):
https://acme123/admin/API/mnt/FailureReasons
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the FailureReasons API Call
The following example illustrates the data returned when you invoke a FailureReasons API call on a
target Cisco Monitoring ISE node. This API call returns a list of failure reasons from the target node,
and each failure reason is defined by a failure ID, a failure code, a cause, and a resolution (if known).
Cisco Identity Services Engine API Reference Guide, Release 1.2
3-4
OL-26134-01
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
Note
The following FailureReasons API call example only displays a small sample of data that can be
returned.
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<failureReasonList>
<failureReason id="100001">
<code>
100001 AUTHMGR-5-FAIL Authorization failed for client
</code>
<cause>This may or may not be indicating a violation</cause>
<resolution>
Please review and resolve according to your organization's policy
</resolution>
</failureReason>
<failureReason id="100002">
<code>
100002 AUTHMGR-5-SECURITY_VIOLATION Security violation on the interface
</code>
<cause>This may or may not be indicating a violation</cause>
<resolution>
Please review and resolve according to your organization's policy
</resolution>
</failureReason>
<failureReason id="100003">
<code>
100003 AUTHMGR-5-UNAUTHORIZED Interface unauthorized
</code>
<cause>This may or may not be indicating a violation</cause>
<resolution>
Please review and resolve according to your organization's policy
</resolution>
</failureReason>
<failureReason id="100004">
<code>
100004 DOT1X-5-FAIL Authentication failed for client
</code>
<cause>This may or may not be indicating a violation</cause>
<resolution>
Please review and resolve according to your organization's policy
</resolution>
</failureReason>
<failureReason id="100005">
<code>100005 MAB-5-FAIL Authentication failed for client</code>
<cause>This may or may not be indicating a violation</cause>
-
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
3-5
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
<resolution>
Please review and resolve according to your organization's policy
</resolution>
</failureReason>
<failureReason id="100006">
<code>
100006 RADIUS-4-RADIUS_DEAD RADIUS server is not responding
</code>
<cause>This may or may not be indicating a violation</cause>
<resolution>
Please review and resolve according to your organization's policy
</resolution>
</failureReason>
<failureReason id="100007">
<code>
100007 EPM-6-POLICY_APP_FAILURE Interface ACL not configured
</code>
<cause>This may or may not be indicating a violation</cause>
<resolution>
Please review and resolve according to your organization's policy
</resolution>
</failureReason>
Related Topics
•
Verifying a Monitoring Node, page 1-2
•
Appendix A, “Cisco ISE Failure Reasons Report”
Authentication Status API Call
You can use the AuthStatus API call to check the authentication status of sessions on the target node.
The query associated with this API call requires at least one MAC address to be searched for a match,
with a user-configurable limit of the most recent records for the specified MAC address returned.
This section provides a schema file output example, a procedure for sending a a request to search for
session authentication status on a target Monitoring mode by invoking this API call, and a sample of the
data returned after this API call is issued.
The AuthStatus API call lets you configure the following search-related parameters:
•
Duration—Defines the number of seconds in which an attempt is made to search and retrieve the
authentication status records associated with the designated MAC address. Valid user-configurable
values range from 1 to 864000 seconds (10 days). If you enter a value of 0 seconds, this specifies a
default duration of 10 days.
•
Records—Defines the number of session records to be searched per MAC address. Valid
user-configurable values range from 1 to 500 records. If you enter 0, this specifies a default setting
of 200 records.
Note
If you specify the value 0 for both the duration and the records parameters, this API call
returns only the very latest authentication session record associated with the designated
MAC address(es).
Cisco Identity Services Engine API Reference Guide, Release 1.2
3-6
OL-26134-01
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
Here is an example of the generic form of a URL with the Duration and Records attributes:
https://10.10.10.10/admin/API/mnt/AuthStatus/MACAddress/01:23:45:67:89:98/900000/2/All
•
Attributes—Defines the number of attributes in the authentication status table that are returned from
an authentication status search using the AuthStatus API call. Valid values include 0 (the default),
All, or user_name+acs_timestamp (see the AuthStatus schema example, AcctStatus API Output
Schema, page 3-12).
– If you enter “0”, the attributes defined in Table 3-2 are returned. These are listed in the
restAuthStatus section of the output schema.
– If you enter “All”, a fuller set of attributes are returned. These are listed in the
fullRESTAuthStatus section of the output schema.
– If you enter the values listed in the schema for user_name+acs_timestamp, only those attributes
are returned. The user_name and acs_timestamp attributes are listed in the restAuthStatus
section of the output schema.
Table 3-2
Authentication Status Table Attributes
Attribute
Description
name=”passed” or name=”failed” Authentication status results:
•
Passed
•
Failed
name=”user_name”
User name
name=”nas_ip_address”
IP address/hostname for the network access device
name=”failure_reason”
Reason for session authentication failure
name=”calling_station_id”
Source IP address
name=”nas_port”
Network access server port
name=”identity_group”
A logical group consisting of related users and hosts
name=”network_device_name”
Name of the network device
name=”acs_server”
Name of the Cisco ISE appliance
name=”eap_authentication”
Extensible Authentication Protocol (EAP) method used for
authentication request
name=”framed_ip_address”
Address configured for a specific user
network_device_groups”
A logical group consisting of related network devices
name=”access_service”
Applied access service
name=”acs_timestamp”
Time stamp that is associated with the Cisco ISE authentication
request
name=”authentication_method”
Identifies the method used in authentication
name=”execution_steps”
List of message codes for each diagnostic message logged while
processing the request
name=”radius_response”
Type of RADIUS response (for example, VLAN or ACL)
name=”audit_session_id”
ID of the authentication session
name=”nas_identifier”
A network access server (NAS) associated with a specific resource
name=”nas_port_id”
ID of the NAS port used
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
3-7
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
Table 3-2
Authentication Status Table Attributes (continued)
Attribute
Description
name=”nac_policy_compliance”
Reflects Posture status (compliant or non-compliant)
name=”selected_azn_profiles”
Identifies the profile used in authorization
name=”service_type”
Indicates a framed user
name=”eap_tunnel”
Tunnel or outer method used for EAP authentication
name=”message_code”
Identifier of the audit message that defines the processed request
result
name=”destination_ip_address”
Identifies the destination IP address
AuthStatus API Output Schema
This sample schema file is the output of the AuthStatus API call after sending it to a specified session
on the target Cisco Monitoring ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="authStatusOutputList" type="fullRESTAuthStatusOutputList"/>
<xs:complexType name="fullRESTAuthStatusOutputList">
<xs:sequence>
<xs:element name="authStatusList" type="fullRESTAuthStatusList" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="fullRESTAuthStatusList">
<xs:sequence>
<xs:element name="authStatusElements" type="fullRESTAuthStatus" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="key" type="xs:string"/>
</xs:complexType>
<xs:complexType name="fullRESTAuthStatus">
<xs:complexContent>
<xs:extension base="restAuthStatus">
<xs:sequence>
<xs:element name="id" type="xs:long" minOccurs="0"/>
<xs:element name="acsview_timestamp" type="xs:dateTime" minOccurs="0"/>
<xs:element name="acs_session_id" type="xs:string" minOccurs="0"/>
<xs:element name="service_selection_policy" type="xs:string" minOccurs="0"/>
<xs:element name="authorization_policy" type="xs:string" minOccurs="0"/>
<xs:element name="identity_store" type="xs:string" minOccurs="0"/>
<xs:element name="response" type="xs:string" minOccurs="0"/>
<xs:element name="cts_security_group" type="xs:string" minOccurs="0"/>
<xs:element name="use_case" type="xs:string" minOccurs="0"/>
<xs:element name="cisco_av_pair" type="xs:string" minOccurs="0"/>
<xs:element name="ad_domain" type="xs:string" minOccurs="0"/>
<xs:element name="acs_username" type="xs:string" minOccurs="0"/>
<xs:element name="radius_username" type="xs:string" minOccurs="0"/>
<xs:element name="nac_role" type="xs:string" minOccurs="0"/>
<xs:element name="nac_username" type="xs:string" minOccurs="0"/>
<xs:element name="nac_posture_token" type="xs:string" minOccurs="0"/>
<xs:element name="nac_radius_is_user_auth" type="xs:string" minOccurs="0"/>
<xs:element name="selected_posture_server" type="xs:string" minOccurs="0"/>
Cisco Identity Services Engine API Reference Guide, Release 1.2
3-8
OL-26134-01
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
<xs:element name="selected_identity_store" type="xs:string" minOccurs="0"/>
<xs:element name="authentication_identity_store" type="xs:string"
minOccurs="0"/>
<xs:element name="azn_exp_pol_matched_rule" type="xs:string" minOccurs="0"/>
<xs:element name="ext_pol_server_matched_rule" type="xs:string" minOccurs="0"/>
<xs:element name="grp_mapping_pol_matched_rule" type="xs:string" minOccurs="0"/>
<xs:element name="identity_policy_matched_rule" type="xs:string" minOccurs="0"/>
<xs:element name="nas_port_type" type="xs:string" minOccurs="0"/>
<xs:element name="query_identity_stores" type="xs:string" minOccurs="0"/>
<xs:element name="sel_exp_azn_profiles" type="xs:string" minOccurs="0"/>
<xs:element name="selected_query_identity_stores" type="xs:string"
minOccurs="0"/>
<xs:element name="tunnel_details" type="xs:string" minOccurs="0"/>
<xs:element name="cisco_h323_attributes" type="xs:string" minOccurs="0"/>
<xs:element name="cisco_ssg_attributes" type="xs:string" minOccurs="0"/>
<xs:element name="other_attributes" type="xs:string" minOccurs="0"/>
<xs:element name="response_time" type="xs:long" minOccurs="0"/>
<xs:element name="nad_failure" type="xs:anyType" minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="restAuthStatus">
<xs:sequence>
<xs:element name="passed" type="xs:anyType" minOccurs="0"/>
<xs:element name="failed" type="xs:anyType" minOccurs="0"/>
<xs:element name="user_name" type="xs:string" minOccurs="0"/>
<xs:element name="nas_ip_address" type="xs:string" minOccurs="0"/>
<xs:element name="failure_reason" type="xs:string" minOccurs="0"/>
<xs:element name="calling_station_id" type="xs:string" minOccurs="0"/>
<xs:element name="nas_port" type="xs:string" minOccurs="0"/>
<xs:element name="identity_group" type="xs:string" minOccurs="0"/>
<xs:element name="network_device_name" type="xs:string" minOccurs="0"/>
<xs:element name="acs_server" type="xs:string" minOccurs="0"/>
<xs:element name="eap_authentication" type="xs:string" minOccurs="0"/>
<xs:element name="framed_ip_address" type="xs:string" minOccurs="0"/>
<xs:element name="network_device_groups" type="xs:string" minOccurs="0"/>
<xs:element name="access_service" type="xs:string" minOccurs="0"/>
<xs:element name="acs_timestamp" type="xs:dateTime" minOccurs="0"/>
<xs:element name="authentication_method" type="xs:string" minOccurs="0"/>
<xs:element name="execution_steps" type="xs:string" minOccurs="0"/>
<xs:element name="radius_response" type="xs:string" minOccurs="0"/>
<xs:element name="audit_session_id" type="xs:string" minOccurs="0"/>
<xs:element name="nas_identifier" type="xs:string" minOccurs="0"/>
<xs:element name="nas_port_id" type="xs:string" minOccurs="0"/>
<xs:element name="nac_policy_compliance" type="xs:string" minOccurs="0"/>
<xs:element name="selected_azn_profiles" type="xs:string" minOccurs="0"/>
<xs:element name="service_type" type="xs:string" minOccurs="0"/>
<xs:element name="eap_tunnel" type="xs:string" minOccurs="0"/>
<xs:element name="message_code" type="xs:string" minOccurs="0"/>
<xs:element name="destination_ip_address" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
3-9
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
Invoking the AuthStatus API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
If your login is unsuccessful, click the Problem logging in? link in the Login page and follow the
instructions in Step 2.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the AuthStatus API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/<specific-api-call>/MACAddress/
<macaddress>/<seconds>/<numberofrecordspermacaddress>/All):
https://acme123/admin/API/mnt/AuthStatus/MACAddress/00:50:56:10:13:02/120/100/Al
l
Note
Step 5
The REST API calls are case-sensitive. The use of “mnt” in the API call convention represents
a Cisco Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the AuthStatus API Call
The following example illustrates the data returned when you invoke a AuthStatus API call on a target
Cisco Monitoring ISE node:
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<authStatusOutputList>
<authStatusList key="00:0C:29:46:F3:B8"><authStatusElements>
<passed xsi:type="xs:boolean">true</passed>
<failed xsi:type="xs:boolean">false</failed>
<user_name>suser77</user_name>
<nas_ip_address>10.77.152.209</nas_ip_address>
<calling_station_id>00:0C:29:46:F3:B8</calling_station_id>
<identity_group>User Identity Groups:Guest</identity_group>
<acs_server>guest-240</acs_server>
<acs_timestamp>2012-10-05T10:50:56.515Z</acs_timestamp>
<execution_steps>5231</execution_steps>
<message_code>5231</message_code>
<id>1349422277270561</id>
Cisco Identity Services Engine API Reference Guide, Release 1.2
3-10
OL-26134-01
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
<acsview_timestamp>2012-10-05T10:50:56.517Z</acsview_timestamp>
<identity_store>Internal Users</identity_store>
<response_time>146</response_time>
<other_attributes>ConfigVersionId=81,EndPointMACAddress=00-0C-29-46-F3-B8,PortalName=Defau
ltGuestPortal,
CPMSessionID=0A4D98D1000001F26F0C04D9,CiscoAVPair=</other_attributes>
</authStatusElements>
<authStatusElements>
<passed xsi:type="xs:boolean">true</passed>
<failed xsi:type="xs:boolean">false</failed>
<user_name>00:0C:29:46:F3:B8</user_name>
<nas_ip_address>10.77.152.209</nas_ip_address>
<calling_station_id>00:0C:29:46:F3:B8</calling_station_id>
<identity_group>Guest_IDG</identity_group>
<network_device_name>switch</network_device_name>
<acs_server>guest-240</acs_server>
<authentication_method>mab</authentication_method>
<authentication_protocol>Lookup</authentication_protocol>
<acs_timestamp>2012-10-05T10:49:47.915Z</acs_timestamp>
<execution_steps>11001,11017,11027,15049,15008,15048,15048,15004,15041,15006,15013,24209,2
421
1,22037,15036,15048,15004,15016,11022,11002</execution_steps>
<response>{UserName
=00:0C:29:46:F3:B8; User-Name=00-0C-29-46-F3-B8;
State=ReauthSession:0A4D98D1000001F26F0C04D9;
Class=CACS:0A4D98D1000001F26F0C04D9:guest-240/138796808/76;
Termination-Action=RADIUS-Request; Tunnel-Type=(tag=1) VLAN;
Tunnel-Medium-Type=(tag=1) 802; Tunnel-Private-Group-ID=(tag=1) 2;
cisco-av-pair=url-redirect-acl=ACL-WEBAUTH-REDIRECT;
cisco-av-pair=url-redirect=https://guest-240.cisco.com:8443/guestportal/gateway?
sessionId=0A4D98D1000001F26F0C04D9&action=cwa;
cisco-av-pair=ACS:CiscoSecure-Defined-ACL=#ACSACL#-IP-pre-posture-506e980a;
cisco-av-pair=profile-name=WindowsXP-Workstation;}</response
><audit_session_id>0A4D98D1000001F26F0C04D9</audit_session_id><nas_po
rt_id>GigabitEthernet1/0/17</nas_port_id><posture_status>Pending</posture_status>
<selected_azn_profiles>CWA_Redirect</selected_azn_profiles>
<service_type>Call Check</service_type>
<message_code>5200</message_code>
<nac_policy_compliance>Pending</nac_policy_compliance>
<id>1349422277270556</id>
<acsview_timestamp>2012-10-05T10:49:47.915Z</acsview_timestamp>
<identity_store>Internal Endpoints</identity_store>
<response_time>13</response_time>
<other_attributes>ConfigVersionId=81,DestinationPort=1812,Protocol=Radius,AuthorizationPol
icyMatchedRule=CWA_Redirect,
NAS-Port=50117,Framed-MTU=1500,NAS-Port-Type=Ethernet,EAP-Key-N
ame=,cisco-nas-port=GigabitEthernet1/0/17,AcsSessionID=guest-240/138796808/76,Us
eCase=Host Lookup,SelectedAuthenticationIdentityStores=Internal
Endpoints,ServiceSelectionMatchedRule=MAB,IdentityPolicyMatchedRule=Default,CPMS
essionID=0A4D98D1000001F26F0C04D9,EndPointMACAddress=00-0C-29-46-F3-B8,EndPointM
atchedProfile=WindowsXP-Workstation,ISEPolicySetName=Default,HostIdentityGroup=E
ndpoint Identity Groups:Guest_IDG,Device Type=Device Type#All Device
Types,Location=Location#All Locations,Device IP
Address=10.77.152.209,Called-Station-ID=00:24:F7:73:9A:91,CiscoAVPair=audit-sess
ion-id=0A4D98D1000001F26F0C04D9</other_attributes>
</authStatusElements>
</authStatusList>
</authStatusOutputList>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
3-11
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
Account Status API Call
You can use the AcctStatus API call to retrieve the latest device and session account information on the
target node. This section provides a schema file output example, a procedure for sending a request for
the latest device and session information by invoking this API call, and a sample of the data returned
after this API call is issued. The AcctStatus API call lets you configure a time-related parameter:
•
Duration—Defines the number of seconds in which an attempt is made to search and retrieve the
latest account device records associated with the designated MAC address. Valid user-configurable
values range from 1 to 432000 seconds (5 days). For example,
– If you enter a value of 2400 seconds (40 minutes), this means that you want the latest account
device records for the designated MAC address that are available in the past 40 minutes.
– If you enter a value of 0 seconds, this specifies a default duration of 15 minutes (900 seconds).
This means that you want the latest account device records for the designated MAC address that
are available within this time period.
The AcctList API call provides the following account status data fields as API outputs (see Table 3-3):
Table 3-3
Accounting Status Data Fields
Data Field
Description
MAC address
MAC address of the client
audit-session-id
Authentication session ID
Packets in
Packets received count total
Packets out
Packets transmitted count total
Bytes in
Bytes received count total
Bytes out
Bytes transmitted count total
Session time
Duration of current sessions
AcctStatus API Output Schema
This sample schema file is the output of the AcctStatus API call after sending it to a specified session
on the target Cisco Monitoring ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="acctStatusOutputList" type="restAcctStatusOutputList"/>
<xs:complexType name="restAcctStatusOutputList">
<xs:sequence>
<xs:element name="acctStatusList" type="restAcctStatusList" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="restAcctStatusList">
<xs:sequence>
<xs:element name="acctStatusElements" type="restAcctStatus" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="macAddress" type="xs:string"/>
<xs:attribute name="username" type="xs:string"/>
</xs:complexType>
Cisco Identity Services Engine API Reference Guide, Release 1.2
3-12
OL-26134-01
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
<xs:complexType name="restAcctStatus">
<xs:sequence>
<xs:element name="calling_station_id" type="xs:string" minOccurs="0"/>
<xs:element name="audit_session_id" type="xs:string" minOccurs="0"/>
<xs:element name="paks_in" type="xs:long" minOccurs="0"/>
<xs:element name="paks_out" type="xs:long" minOccurs="0"/>
<xs:element name="bytes_in" type="xs:long" minOccurs="0"/>
<xs:element name="bytes_out" type="xs:long" minOccurs="0"/>
<xs:element name="session_time" type="xs:long" minOccurs="0"/>
<xs:element name="username" type="xs:string" minOccurs="0"/>
<xs:element name="server" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Invoking the AcctStatus API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
If your login is unsuccessful, click the Problem logging in? link in the Login page and follow the
instructions in Step 2.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the AcctStatus API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component
(/admin/API/mnt/<specific-api-call>/MACAddress/<macaddress>/
<durationofcurrenttime>):
https://acme123/admin/API/mnt/AcctStatus/MACAddress/00:26:82:7B:D2:51/1200
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the AcctStatus API Call
The following example illustrates the data returned when you invoke an AcctStatus API call on a target
Cisco Monitoring ISE node:
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
3-13
Chapter 3
Query APIs for Troubleshooting
Troubleshooting Cisco ISE using the Query API Calls
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<acctStatusOutputList>
<acctStatusList macAddress="00:25:9C:A3:7D:48">
<acctStatusElements>
<calling_station_id>00:25:9C:A3:7D:48</calling_station_id>
<audit_session_id>0acb6b0b0000000B4D0C0DBD</audit_session_id>
<paks_in>0</paks_in>
<paks_out>0</paks_out>
<bytes_in>0</bytes_in>
<bytes_out>0</bytes_out>
<session_time>240243</session_time>
<server>HAREESH-R6-1-PDP1</server>
</acctStatusElements>
</acctStatusList>
</acctStatusOutputList>
Cisco Identity Services Engine API Reference Guide, Release 1.2
3-14
OL-26134-01
CH A P T E R
4
Change of Authorization REST APIs
This chapter provides examples and describes how to use the following individual Change of
Authorization (CoA) REST API calls that are supported in this release of Cisco Identity Services Engine.
Introduction
The CoA API calls provide the means for sending session authentication and session disconnect
commands to a specified Cisco Monitoring ISE node in your Cisco ISE deployment.
CoA Session Management API Calls
The CoA session management API calls allow you to send reauthentication and disconnect commands
to a specified session on a target Cisco Monitoring ISE node in your Cisco ISE deployment:
•
Session reauthentication (Reauth)
•
Session disconnection (Disconnect)
Session Reauthentication API Call
The Session Reauthentication API Call constitutes the following types:
•
REAUTH_TYPE_DEFAULT = 0
•
REAUTH_TYPE_LAST = 1
•
REAUTH_TYPE_RERUN = 2
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
4-1
Chapter 4
Change of Authorization REST APIs
CoA Session Management API Calls
Reauth API Output Schema
This sample schema file is the output of the Reauth API call after sending it to a specified session on the
target Cisco Monitoring ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="remoteCoA" type="coAResult"/>
<xs:complexType name="coAResult">
<xs:sequence>
<xs:element name="results" type="xs:boolean" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="requestType" type="xs:string"/>
</xs:complexType>
</xs:schema>
Invoking the Reauth API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Step 4
Enter the Reauth API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/CoA/<specific-api-call>/<macaddress>/
<reauthtype>:
https://acme123/admin/API/mnt/CoA/Reauth/server12/00:26:82:7B:D2:51
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Cisco Identity Services Engine API Reference Guide, Release 1.2
4-2
OL-26134-01
Chapter 4
Change of Authorization REST APIs
CoA Session Management API Calls
Sample Data Returned from the Reauth API Call
The following example illustrates the data returned when you invoke a Reauth API call on a target Cisco
Monitoring ISE node. Two possible results can be returned from invoking this command:
•
True indicates that the command was successfully executed.
•
False means that the command was not executed (due to a variety of conditions).
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<remoteCoA requestType="reauth">
<results>true</results>
</remoteCoA>
Session Disconnect API Call
The Session Disconnect API call constitutes the following disconnect port option types:
•
DYNAMIC_AUTHZ_PORT_DEFAULT = 0
•
DYNAMIC_AUTHZ_PORT_BOUNCE = 1
•
DYNAMIC_AUTHZ_PORT_SHUTDOWN = 2
Disconnect API Output Schema
This sample schema file is the output of the Disconnect API call after sending it to a specified session
on the target Cisco Monitoring ISE node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="remoteCoA" type="coAResult"/>
<xs:complexType name="coAResult">
<xs:sequence>
<xs:element name="results" type="xs:boolean" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="requestType" type="xs:string"/>
</xs:complexType>
</xs:schema>
Invoking the Disconnect API Call
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or ip
address>/admin/).
Step 2
Enter the username and case-sensitive password, that was specified and configured during the initial
Cisco ISE setup.
Step 3
Click Login or press Enter.
For example, when you initially log into a Cisco Monitoring ISE node with the hostname of acme123,
this would display the following URL Address field for this node:
https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdash
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
4-3
Chapter 4
Change of Authorization REST APIs
CoA Session Management API Calls
Step 4
Enter the Disconnect API call in the URL Address field of the target node by replacing the “/admin/”
component with the API call component (/admin/API/mnt/CoA/<Disconnect>/<serverhostname>/
<macaddress>/<portoptiontype>:
https://acme123/admin/API/mnt/CoA/Disconnect/server12/00:26:82:7B:D2:51
Note
Step 5
You must carefully enter each API call in the URL Address field of a target node because these
calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco
Monitoring ISE node.
Press Enter to issue the API call.
Related Topics
•
Verifying a Monitoring Node, page 1-2
Sample Data Returned from the Disconnect API Call
The following example illustrates the data returned when you invoke a Disconnect API call on a target
Cisco Monitoring ISE node. Two possible results can be returned by invoking this command:
•
True indicates that the command was successfully executed.
•
False means that the command was not executed (due to a variety of conditions).
This XML file does not appear to have any style information associated with it. The
document tree is shown below.
<remoteCoA requestType="reauth">
<results>true</results>
</remoteCoA>
Cisco Identity Services Engine API Reference Guide, Release 1.2
4-4
OL-26134-01
PART
2
Cisco ISE External RESTful Services APIs
CH A P T E R
5
Introduction to ERS APIs
•
Overview, page 5-1
•
Supported Cisco ISE Resources, page 5-1
•
External RESTful Services API Authentication and Authorization, page 5-2
•
Enabling External RESTful Services APIs from the GUI, page 5-2
•
External RESTful Services API Status, page 5-3
•
Data Validation, page 5-3
•
Namespaces, page 5-3
•
External RESTful Services SDK, page 5-4
•
External RESTful Services Schema File, page 5-4
•
External RESTful Service Requests and Responses, page 5-5
•
Version Control with External RESTful Services APIs, page 5-7
•
Searching and Filtering, page 5-8
•
External RESTful Services System Flow, page 5-9
•
Hyperlinks, page 5-11
•
Bulk Operations, page 5-12
Overview
This chapter provides guidelines and examples for using the supported External RESTful Services APIs
and related API calls. These calls enable you to perform CRUD (Create, Read, Update, Delete)
operations on Cisco ISE resources.
Supported Cisco ISE Resources
The Cisco ISE External RESTful Services allow you to perform operations on the following types of ISE
resources:
•
End points
•
End point identity groups
•
Guest users
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
5-1
Chapter 5
Introduction to ERS APIs
External RESTful Services API Authentication and Authorization
•
Identity groups
•
Internal users
•
Portals
•
Profiler policies
•
Network devices
•
Network device groups
•
Security groups
Full request and response examples are provided in Chapter 7, “External RESTful Services API
Operations.”.
External RESTful Services API Authentication and Authorization
The External RESTful Services APIs are based on HTTPS protocol and REST methodology and uses
port 9060.
The External RESTful Services APIs support basic authentication. The authentication credentials are
encrypted and are part of the request header.
The ISE administrator must assign special privileges to a user to perform operations using the External
RESTful Services APIs. The ISE administrator can assign the following two roles to perform operations
using the External RESTful Services APIs:
•
External RESTful Services Admin—For full access to all ERS APIs (GET, POST, DELETE, PUT).
•
External RESTful Services Operator—For Read Only access (GET request only).
If you do not have the required permissions and still try to perform operations using the External
RESTful Services APIs, you will receive an error response.
Related Topics
•
Creating a New Cisco ISE Administrator
•
Sponsor Authentication and Authorization, page 6-1
Enabling External RESTful Services APIs from the GUI
You must enable the Cisco ISE REST API in order for applications developed for a Cisco ISE REST API to
be able to access Cisco ISE. The Cisco REST APIs uses HTTPS port 9060, which is closed by default. If the
Cisco ISE REST APIs are not enabled on the Cisco ISE admin server, the client application will receive a
time-out error from the server for any Guest REST API request.
External RESTful Service requests of all types are valid only for the primary ISE node. Secondary nodes
have read-access (GET requests).
Procedure
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or
ip address>/admin/).
Step 2
Enter your username and case-sensitive password.
Cisco Identity Services Engine API Reference Guide, Release 1.2
5-2
OL-26134-01
Chapter 5
Introduction to ERS APIs
External RESTful Services API Status
Step 3
Click Login or press Enter.
Step 4
Choose Administration > Settings > ERS Settings.
Step 5
Choose Enable ERS for Read/Write for the Primary Administration Node.
Step 6
Choose Enable ERS for Read for All Other Nodes if there are any secondary nodes.
Step 7
Click Submit.
Note
All REST operations are audited and the logs are logged in the system logs.
Related Topics
•
Prerequisites for Using the External RESTful Services API Calls, page 7-1
External RESTful Services API Status
You can verify whether the External RESTful Services APIs are enabled for the primary and secondary
nodes on the Administration > Settings > ERS Settings page in the GUI.
The External RESTful Services APIs are not enabled by default. If you try to evoke the External
RESTful Services API calls before enabling them, you will receive an error response.
External RESTful Services APIs have a debug logging category, which you can enable from the debug
logging page of the Cisco ISE GUI.
Note
For more information, see the Debug Log Configuration Options section of the Cisco Identity Services
Engine Admin Guide, Release 1.3.
Data Validation
CRUD data sent to the server is validated with the same validation rules that Cisco ISE uses for the GUI.
All validations are centralized in a validation layer. All XML data being posted is validated against the
schema.
The following two types of validations occur: data validation and structural validation. Data validation
validates the data to be ISE compliant, for example, mandatory fields, field length, types, and so on.
Where as, structural validation happens against the schema, for example, fields order, names, and so on.
Namespaces
You must maintain strict namespaces within resources names and URIs as follows:
•
Identity for internal user, endpoint, endpoint groups and identity groups
•
SGA for SGT
•
External RESTful Services for all other object resources such as search results that appears in the
response message (the client do need to send ERS namespace in requests)
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
5-3
Chapter 5
Introduction to ERS APIs
External RESTful Services SDK
The Accept/Content-Type headers must contain the following namespaces:
application/vnd.com.cisco.ise.<resource-namespace>.<resource-type>.<major
version>.<minor version>+xml
For example: application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
The request XML should contain the namespace definition as follows:
identity.ers.ise.cisco.com
sga.ers.ise.cisco.com
For example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns:endpoint xmlns:ns="identity.ers.ise.cisco.com" id="id">
<group>Profiled</group>
…
</ns:endpoint>
External RESTful Services SDK
You can use the External RESTful Services SDK to start building your own tools. You can access the
External RESTful Services SDK from the following URL: https://<ISE-ADMIN-NODE>:9060/ers/sdk.
External RESTful Services SDK can be accessed by the External RESTful Services Admin users only.
The SDK consists the following components:
•
Quick reference API documentation
•
List of all available API operations
•
Schema files available for download
•
Sample application in Java available for download
•
Use cases in curl script format
•
Instructions on using Chrome Postman
External RESTful Services Schema File
The External RESTful Services SDK is shipped with three XSD schema files that describe the structure
of the objects that are supported on ISE ERS interfaces.
The three XSD files are:
•
ers.xsd
•
identity.xsd
•
sga.xsd
•
network.xsd
You can use the schema with available tools such as JAXB to generate schema classes.
You can develop HTTP client or use any third-party HTTP client code and integrate it with the schema
classes that are generated from the XSD files.
Cisco Identity Services Engine API Reference Guide, Release 1.2
5-4
OL-26134-01
Chapter 5
Introduction to ERS APIs
External RESTful Service Requests and Responses
Note
The XML sent in the content is validated against the schema, therefore, field order and syntax in the
XML should be the same as it appears in the schema. Otherwise, you will receive a bad request status
code.
Downloading the Schema File
Procedure
Step 1
Enter the following URL in the address bar of your browser to log into the External RESTful Services
SDK page: https://<ISE-ADMIN-NODE>:9060/ers/sdk
Step 2
Enter the Username and the case-sensitive password corresponding to an External RESTful Services
Admin.
Step 3
Click Login or press Enter.
Step 4
In the Downloads category, click Schema Jar (ers-schema-1.3-iteration-01-SNAPSHOT.jar).
Step 5
Save the file to your local machine.
Related Topics
•
External RESTful Services API Authentication and Authorization, page 5-2
External RESTful Service Requests and Responses
This section provides information on the request and response headers as well as the status codes
returned by ERS.
External RESTful Service Requests Headers
Table 5-1
ERS Request Headers
Header
Supported Values
Description of Use
Required
Accept
Guest REST API Resource
Media-Type
Indicates to the server what media
type(s) this client is willing to accept
including the resource version.
Yes, on GET/GET
ALL/DELETE/GET
VERSION operations (these
contain no message body)
Authorization
"Basic " plus username and
password (per RFC 2617
Identifies the authorized user making
this request.
Yes, on all requests.
Content-Length
Guest REST API Resource
Media-Type
Indicates to the server what media
type(s) this client is willing to accept
including the resource version.
Yes, on requests that contain
a message body.
Content-Type
Media type describing the request
message body
Describes the representation and
syntax of the request message body.
Yes, on requests that contain
a message body.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
5-5
Chapter 5
Introduction to ERS APIs
External RESTful Service Requests and Responses
External RESTful Service Response Headers
Table 5-2
ERS Mandatory Response Headers
Header
Supported Values
Description of Use
Required
Content-Length
Length (in bytes) of the response Describes the size of the
message body.
message body.
Content-Type
Media type describing the
response message body.
Describes the representation and Yes, on responses that contain a
syntax of the response message message body.
body.
Location
Canonical URI of a newly
created resource.
Returns a new URI that can be
used to request a representation
of the newly created resource.
Yes, on responses that contain a
message body.
Yes, on responses to requests
that create new server side
resources accessible via a URI.
Common External RESTful Service HTTP Status Codes
Table 5-3
Description of the HTTP Response Codes Returned By ERS
HTTP Status
Description
200 OK
The request was successfully completed. If this request created a new resource
that is addressable with a URI, and a response body is returned containing a
representation of the new resource, a 200 status will be returned with a Location
header containing the canonical URI for the newly created resource.
201 Created
A request that created a new resource was completed, and no response body
containing a representation of the new resource is being returned. A Location
header containing the canonical URI for the newly created resource should also
be returned.
202 Accepted
The request has been accepted for processing, but the processing has not been
completed. Per the HTTP/1.1 specification, the returned entity (if any)
SHOULD include an indication of the request's current status, and either a
pointer to a status monitor or some estimate of when the user can expect the
request to be fulfilled.
204 No Content
The server fulfilled the request, but does not need to return a response message
body.
400 Bad Request
The request could not be processed because it contains missing or invalid
information (such as validation error on an input field, a missing required value,
and so on).
401 Unauthorized
The authentication credentials included with this request are missing or invalid.
403 Forbidden
The server recognized your credentials, but you do not possess authorization to
perform this request.
404 Not Found
The request specified a URI of a resource that does not exist.
405 Method Not
Allowed
The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is
not supported for this request URI.
Cisco Identity Services Engine API Reference Guide, Release 1.2
5-6
OL-26134-01
Chapter 5
Introduction to ERS APIs
Version Control with External RESTful Services APIs
Table 5-3
Note
Description of the HTTP Response Codes Returned By ERS (continued)
HTTP Status
Description
406 Not Acceptable
The resource identified by this request is not capable of generating a
representation corresponding to one of the media types in the Accept header of
the request.
409 Conflict
A creation or update request could not be completed, because it would cause a
conflict in the current state of the resources supported by the server (for
example, an attempt to create a new resource with a unique identifier already
assigned to some existing resource).
415 Unsupported
Media Type
The media type specified in the Accept header is not supported by the server.
This will be the common response when the client resources version is no longer
supported by the server.
429 Too many
requests
There are too many simultaneous ERS requests.
500 Internal Server
Error
The server encountered an unexpected condition which prevented it from
fulfilling the request.
501 Not
Implemented
The server does not (currently) support the functionality required to fulfill the
request.
503 Service
Unavailable
The server is currently unable to handle the request due to temporary
overloading or maintenance of the server.
In addition to the status codes return in the response header, each request might have additional xml
content according to the nature of the request.
Version Control with External RESTful Services APIs
The External RESTful Services APIs provide backward compatibility with previous Cisco ISE versions.
The External RESTful Services APIs has a versioning mechanism for API version management. All
non-guest resources are of version 1.0 and no backward compatibility is required.
Each RESTful resource has a model version (major.minor). The version must be part of the request
header with the syntax as follows:
application/vnd.com.cisco.ise.<resource-namespace>.<resource-type>.<major version>.<minor
version>+xml
For example, to get internal user resource version 1.0, the following request is passed:
DELETE https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
After authenticating and authorizing the request, a version match check is performed with the matching
results mentioned in the following table:
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
5-7
Chapter 5
Introduction to ERS APIs
Searching and Filtering
Versions match
Outcome
No version sent
The server returns status 415 “Unsupported Media
Type”
Client version equal to server version
The server proceeds with processing the request.
Client minor version not equal to server minor The server adds a response warning message
version
describing the versions gap and proceeds processing
the request.
Client and server major version does not match Server returns status 415 with a corresponding error
message.
Note
Each resource has an API to retrieve a list of server supported versions.
Searching and Filtering
All filtering and searching operations are through the use of filtering.
You search for a resource by sending a GET request to a resource URI. By default, the result is the first
page (page index = 0) with default size of 20. By adding filter, sort and paging parameters, described in
the following sections, to the URI, the client can control this search.
The resources resulting from a paging, filter, or sort request are bundled in a <resources> collection,
which contains for each resource its name, ID, description, and link to its full representation. This gives
the client the ability to easily drill down into the resource.
Filtering Parameters for External RESTful Services APIs
You can perform simple filtering operation through the filter query string parameter. You can send more
than one filter. The logical operator common to all filter criteria is by default AND. You can change this
by using the “filtertype=or” query string parameter.
Each resource data model description should specify if an attribute is a filtered field.
For example, to get internal users with first name starting with ‘a’ and belonging to the identity group
‘Finance’, the following request is passed:
GET
/ers/config/internaluser/?page=0&size=20&sortacs=name&filter=name.STARTSW.a&filter=identit
yGroup.EQ.Finance
The following table shows the available filter operators:
Parameter
Description
EQ
Equals
GT
Greater Than
LT
Less Then
STARTSW
Start With
Cisco Identity Services Engine API Reference Guide, Release 1.2
5-8
OL-26134-01
Chapter 5
Introduction to ERS APIs
External RESTful Services System Flow
Parameter
Description
ENDSW
End With
CONTAINS
Contains
The following table shows the list of filterable attributes for each resource:
Resource
Filterable Attributes
Endpoints
mac, portalUser, profile, profileId,
staticGroupAssignment, staticProfileAssignment
Internal User
name
Endpoint Identity Group
name
Identity Groups
name
SGTs
name
Paging Parameters for External RESTful Services APIs
All External RESTful Servive search results are paged. Paging parameter are passed in the URI using
query parameters.
For example, to get internal users first 20 records sorted in accending order by “name” field, the
following request is passed:
GET /ers/config/internaluser?page=0&size=20&sortasc=name
The following table shows the available paging parameters:
Parameter
Description
Default Value
page
Page starting index
0
size
Page size
20 (max. = 100)
sortasc
Sorting field with Ascending direction, out of a set name
of available fields for sorting. (For alphabetic
characters, it is sorted A to Z.)
sortdsc
Sorting field with Descending direction, out of a
set of available fields for sorting. (For alphabetic
characters, it is sorted Z to A.)
name
External RESTful Services System Flow
Common External RESTful Services flow consists of HTTPS request sent from client and an HTTPS
response from server. The flow differs by requests types, URIs, request headers, response headers, and
response contents.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
5-9
Chapter 5
Introduction to ERS APIs
External RESTful Services System Flow
Figure 5-1
ERS Success Flow Sequence
Cisco Identity Services Engine API Reference Guide, Release 1.2
5-10
OL-26134-01
Chapter 5
Introduction to ERS APIs
Hyperlinks
Figure 5-2
ERS Failure Flow Sequence
Hyperlinks
Usage of hyperlinks within XML representation is one of the strongest characteristics of Hypermedia as
the Engine of Application State (HATEOS). Hyperlinks are mostly used to convey to the client that the
resource has a representation at the given URI.
External RESTful Services links are aligned with the Atom definition of links declared in the following
namespace:
http://www.w3.org/2005/Atom namespace.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
5-11
Chapter 5
Introduction to ERS APIs
Bulk Operations
The following table shows the mandatory link attributes for the External RESTful Services:
Attribute
Description
Href
This contains the link's URI.
Rel
This attribute, which originally meant “relation,”
indicates the following type of links:
Type
•
“self”—link to refresh current representation
•
“next”—in collection for getting next page
•
“info”—get more info about of the resource
This is a hint to the media type of the
representation that the server may return for the
link's URI - usually is “application/xml”
Example of links within a search result
The following example shows links within a search result:
<ns2:searchResult xmlns:ns2="ers.ise.cisco.com"
total="1163">
<link rel="self"
href="http://cisco.com/ers/config/internaluser?page=0&size=20"
type="application/xml"/>
<link rel="next" href="http://cisco.com/ers/config/internaluser?page=20&size=20"
type="application/xml"/>
<resources>
<link rel="john doe" href="http://cisco.com/ers/config/internaluser/333"
type="application/xml"/>
<link rel="jeff smit" href="http://cisco.com/ers/config/internaluser/444"
type="application/xml"/>
.
.
.
</resources>
</ns2:searchResult>
Bulk Operations
A bulk request will allow you to send up to 500 operations in a single request (or 5000 operations by
ID). You can run create, update, and delete operations all resources as well as some resource-specific
operations like registering end points.
All operations in a request must be of same type, which means that you cannot send a mixed resources
request.
Each resource has its own transaction and the order of the transactions is not guarantee as it is a
multi-threaded execution.
The Cisco ISE server parses the request and validates its structure. If the request is valid and no other
bulk already in progress, the execution starts and the server returns the status code 202 (ACCEPTED) and
a unique bulk identifier in the LOCATION response header. This ID allows you to track the bulk status
later on using the Get Bulk Status operation. The status report will be available for at least 2 hours after
the operation’s start time.
Cisco Identity Services Engine API Reference Guide, Release 1.2
5-12
OL-26134-01
Chapter 5
Introduction to ERS APIs
Bulk Operations
If a failure occurs while executing on a resource, the failure is logged in the status report and the
execution proceeds to next resource.
Only one bulk execution is allowed to run at a time. If a bulk request is posted while another bulk
execution is still running, the server returns the response status 503 (Service Unavailable) with a
message asking the client to try again later.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
5-13
Chapter 5
Introduction to ERS APIs
Bulk Operations
Cisco Identity Services Engine API Reference Guide, Release 1.2
5-14
OL-26134-01
CH A P T E R
6
Guest REST API
•
An API for Guest User Resources, page 6-1
•
Sponsor Authentication and Authorization, page 6-1
•
Guest REST API Requests, page 6-2
•
Guest REST API Responses, page 6-5
•
The following table lists the headers for responses., page 6-6
•
Searching and Filtering, page 6-8
An API for Guest User Resources
The Cisco Guest API is a REST (Representational State Transfer)-based set of operations that provide
secure and authenticated access to and management of Cisco guest users. With the API, you can create,
read, update, delete, and search for guest users.
When you call the API, you are calling it as if you are a sponsor using the Cisco ISE Sponsor portal to
manage guest users. In order to use the API, you must first enable access to it and then set up sponsor
authentication in ISE.
Full request and response examples are provided in External RESTful Services APIs for Guest Users,
page 7-22.
Sponsor Authentication and Authorization
A sponsor is a special type of Cisco ISE user who can create and manage guest users using the Sponsor
portal. The Guest REST API has the same capabilities as the Sponsor portal. Authentication for the Guest
REST API is similar to the process for authenticating a sponsor. The privileges specified in a sponsor group’s
policies apply to the Guest REST API.
See the Cisco ISE User Guide for more information on sponsors and sponsor groups.
Before You Begin
Like other ISE users, Cisco ISE authenticates sponsors through a local database, or through external
Lightweight Directory Access Protocol (LDAP) or Microsoft Active Directory identity stores. If you are
not using an external identity store, you must create users in Cisco ISE (Administration > Identity
Management > Identities > Users).
Cisco Guest REST API Reference Guide
OL-31414-01
6-1
Chapter 6
Guest REST API
Guest REST API Requests
Procedure
Step 1
Enter the Cisco ISE URL in the address bar of your browser (for example, https://<ise hostname or
ip address>/admin/).
Step 2
Enter your username and case-sensitive password.
Step 3
Click Login or press Enter.
Step 4
Assign the user to the appropriate identity group.
Step 5
Step 6
a.
Choose Administration > Identity Management > Groups > Identity Groups.
b.
Create a new group or edit an existing one. Cisco ISE includes these default sponsor user identity
groups:
•
SponsorAllAccount
•
SponsorGroupAccounts
•
SponsorOwnAccounts
c.
Add the user to the list of members.
d.
Click Save.
Add the user’s identity group to a sponsor group.
a.
Choose Guest Access > Configure > Sponsor Groups.
b.
Create a new sponsor group or edit and existing one.
c.
Click Members.
d.
Add the user’s identity group to the list of sponsor group members and click OK.
e.
Add the guest types and locations that the user can sponsor.
f.
Select the Access ISE guest accounts via the programatic interface (REST API) check box.
g.
Click Save.
Ensure that Sponsor_Portal_Sequence accesses the user’s identity source.
a.
Choose Administration > Identity Management > Identity Source Sequences >
Sponsor_Portal_Sequence.
b.
Choose the user’s identity source database if it hasn’t been selected for the Authentication Search
List.
c.
Click Save.
Related Topics
For further details on sponsors and sponsor groups, see the Cisco ISE User Guide.
Guest REST API Requests
Requests made to the API have the following characteristics:
•
User requests are sent over HTTPS to the Cisco ISE server, and a Response is returned.
•
The URI to access all APIs is the domain name of your primary
https://<ISE-ADMIN-NODE>:9060/ers/config
Cisco Guest REST API Reference Guide
6-2
OL-31414-01
Chapter 6
Guest REST API
Guest REST API Requests
•
API requests are case sensitive and should be entered as shown in this manual.
•
Each guest request needs to set Content Type as:
•
Each guest request needs to set Accept as:
•
Each guest bulk request needs to set Content Type as:
•
Each guest bulk request needs to set Accept as:
•
You also can include the optional Accept-Encoding:gzip header, which compresses the response
payload.
application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
application/vnd.com.cisco.ise.identity.guestuserbulkrequest.1.0+xml
application/vnd.com.cisco.ise.identity.guestuserbulkrequest.1.0+xml
Request Structure
The following table lists the types of request operations that you can use with the Cisco Guest REST
API:
Table 6-1
Request Method Types
Request Type
Operations
GET
Get all resources (Search), Get a resource by its ID, Get a resource version
information.
POST
Create a new guest user.
PUT
Update a guest user.
DELETE
Delete a guest user
The following table lists the mandatory headers for requests:
Table 6-2
Mandatory Request Headers
Header
Values
Description
ACCEPT
Guest REST API Resource
Media-Type
Indicates to the server what media type(s)
this client is willing to accept including the
resource version.
AUTHORIZATION
"Basic " plus username and
password (per RFC 2617
Identifies the authorized user making this
request.
CONTENT-TYPE
Media type describing the request Describes the representation and syntax of
message body
the request message body.
Related Topics
Content Type and Accept Headers, page 7-22
Cisco Guest REST API Reference Guide
OL-31414-01
6-3
Chapter 6
Guest REST API
Guest REST API Requests
Request Contents
The request example below shows the XML content that’s required to create guest user accounts using
either the POST (create) operation.
Note
JSON is not used for Guest REST API.
POST Request Example
POST https://<ISE-Admin-Node>:9060/ers/config/guestuser/
Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Content-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Authorization: Basic xxxxxxxxxxxxxxxxx
<?xml version="1.0" encoding="UTF-8"?>
<ns2:guestuser xmlns:ns2="identity.ers.ise.cisco.com">
<guestAccessInfo>
<fromDate>08/06/2014 23:22</fromDate>
<toDate>08/07/2014 23:22</toDate>
<validDays>1</validDays>
</guestAccessInfo>
<guestInfo>
<company>New Company</company>
<emailAddress>john@example.com</emailAddress>
<firstName>John</firstName>
<lastName>Doe</lastName>
<notificationLanguage>English</notificationLanguage>
<password>12345</password>
<phoneNumber>9999998877</phoneNumber>
<smsServiceProvider>Global Default</smsServiceProvider>
<userName>autoguestuser1</userName>
</guestInfo>
<guestType>Daily</guestType>
<personBeingVisited>sponsor</personBeingVisited>
<portalId>portal101</portalId>
<reasonForVisit>interview</reasonForVisit>
</ns2:guestuser>
Bulk Executions
A bulk request will allow you to send up to 500 operations in a single request, or up to 5000 operations
based on ID.
All operations in a request must be of same type, which means that you cannot send a mixed resources
request.
Each resource has its own transaction and the order of the transactions is not guarantee as it is a
multi-threaded execution.
The Cisco ISE server parses the request and validates its structure. If the request is valid and no other
bulk already in progress, the execution starts and the server returns the status code 202 (ACCEPTED) and
a unique bulk identifier in the LOCATION response header. This ID allows you to track the bulk status
later on using the Get Bulk Status operation. The status report will be available for at least 2 hours after
the operation’s start time.
If a failure occurs while executing on a resource, the failure is logged in the status report and the
execution proceeds to next resource.
Cisco Guest REST API Reference Guide
6-4
OL-31414-01
Chapter 6
Guest REST API
Guest REST API Responses
Only one bulk execution is allowed to run at a time. If a bulk request is posted while another bulk
execution is still running, the server returns the response status 503 (Service Unavailable) with a
message asking the client to try again later.
A bulk execution, including getting the bulk status, uses different headers:
•
Content Type as: application/vnd.com.cisco.ise.identity.guestuserbulkrequest.1.0+xml
•
Accept: application/vnd.com.cisco.ise.identity.guestuserbulkrequest.1.0+xml
Related Topics
•
Start Bulk Execution for Guest Users, page 7-36
Guest REST API Responses
Each request is followed by a server HTTPS response with the standard headers, plus response content.
Response Status Codes
A Response contains an HTTP status code. For the Guest REST API, these can be:
•
20x - Successful operation
•
4xx - Client errors
•
5xx - Server errors
The following table provides more information on the status codes.
Table 6-3
Response Contents Types
Request Type
Status
Response Payload
Get a guest
user by its Id
200
Guest User in its XML representation
All
4xx
(client errors)
A Response with messages describing the error, for example:
unsupported version, or illegal URI
All
5xx
(server error)
A Response with messages describing the error, for example:
runtime exceptions...
Create A guest
user [POST]
201
If no info or warnings, then no content will be sent back. The new
guest user id will be sent in the response “Location” header. If there
is additional info or warning it will be encapsulated in the Response.
Update a guest
user [PUT]
200
Returns a list of updated fields.
Delete a guest
user [Delete]
204
No content.
Related Topics
Response Error Messages, page 6-6
Cisco Guest REST API Reference Guide
OL-31414-01
6-5
Chapter 6
Guest REST API
Guest REST API Responses
Response Structure
The following table lists the headers for responses.
Table 6-4
Mandatory Response Headers
Header
Values
Description
LOCATION
newly created resource ID
for POST only—holds the new resource
ID (as a URI representation)
CONTENT-TYPE
Media type describing the
response message body
Describes the representation and syntax
of the response message body
Guest Passwords
ISE automatically generates a password when a guest is created. It is possible to reset a guest’s password
through the Guest REST API by calling PUT on a specific guest user and providing an empty password.
This is the equivalent of a sponsor resetting a guest’s password from the Sponsor portal.
Use the GET operation to retrieve a guest user’s information and view their password. Cisco ISE guest
passwords are visible in the response to a GET operation as long as the password was:
1.
Automatically generated by ISE.
2.
Reset through this API or via the Sponsor Portal.
In some guest flows, the guest has the ability to change their own password. Cisco ISE guest passwords
that have been changed by the guest are not visible in the sponsor portal and are not visible via the REST
API.
It is possible to reset the password of a guest even if if the sponsor has permission to do so via the sponsor
group permissions..
Related Topics
•
Reset User’s Password Example, page 7-31
•
For further details on guest user password policies, see the Cisco ISE Admin Guide.
Response Error Messages
You are required to use certain headers when you do a POST or PUT request. You will get errors if you
leave one out.
The log files that contains detailed messages that can enable you to correct the operations can be found
in the Cisco ISE UI at the following location:
Operations > Node > Debug Logs > guest.log
Cisco Guest REST API Reference Guide
6-6
OL-31414-01
Chapter 6
Guest REST API
Guest REST API Responses
Table 6-5
Error Codes
HTTP
Status
Error Code
Description
Resource version exception
Resource version sent in the request content is 415
not supported by the server.
Resource media type exception
Media type sent by the client in the ACCEPT
or Content-Type headers is invalid.
Unsupported resource exception
Resource listed in the URI, is not supported by 400
the server.
Unsupported method exception
Request method type is not supported for the
specified URI.
400
Query string validation exception
Search filter or paging parameters are not
valid.
400
Schema validation exception
The request’s XML content does not conform 400
to the API’s schema rules for that resource,
such as including a field that the API does not
recognize or excluding a field that’s
mandatory.
Application resource validation exception
The API is unable to validate some of the
request’s content, such as using invalid
characters in an attribute’s values.
Unauthorized user
The sponsor’s username and password are not 401
valid.
Internal exception
Any unexpected internal server error occurs at 500
runtime.
Conversion exception
Some internal conversions, should be treated
as an internal exception.
500
CRUD operation exception
Executing a CRUD operation, should be
treated as an internal exception.
500
415
400
Unsupported Media Type Example
The following example demonstrates a response that occurs when the client sent an unsupported media
type in the ACCEPT header.
Response
STATUS 415 Unsupported Media Type
Cache-Control: no-cache
Content-Length: 411
Content-Type: application/vnd.com.cisco.ise.ers.ersresponse.1.0+xml
Date: Wed, 11 Dec 2013 05:27:37 GMT
Expires: Wed, 31 Dec 2015 16:00:00 PST
Pragma: No-cache
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
Cisco Guest REST API Reference Guide
OL-31414-01
6-7
Chapter 6
Guest REST API
Searching and Filtering
<ns2:ersResponse
xmlns:ns2="ers.ise.cisco.com" operation="GET-getAll-guestuser">
<link type="application/xml"
href="https://<ISE-Admin-Node>:9060/ers/config/guestuser/" rel="related"/>
<messages>
<ns2:message type="ERROR" code="Resource media type exception">
<title>Wrong media type, check Accept request header.</title>
</ns2:message>
</messages>
</ns2:ersResponse>
Versioning
The Guest REST API for Cisco ISE Release 1.3 is version 2.0. It is designed to be compatible with future
versions.
This REST API is not compatible with previous alpha and beta versions of the Guest REST API.
Each RESTful resource has a model version (major.minor). The version must be part of the request
header with the syntax as follows:
application/vnd.com.cisco.ise.<resource-namespace>.<resource-type>.<major version>.<minor
version>+xml
For example, to get guest user resource version 2.0, the following request is passed:
GET https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
After authenticating and authorizing the request, a version-match check is performed with one of the
following matching results.
Table 6-6
Version-match Results
Version-match
No version sent
Outcome
The server returns status 415 “Unsupported
Media Type”.
Client version equal to server version
The server proceeds with processing the request.
Client minor version not equal to server minor
version
The server adds a response warning message
describing the versions gap and proceeds
processing the request.
Client and server major version does not match
The server returns status 415 with a corresponding
error message.
Searching and Filtering
All filtering and searching operations are through the use of filtering.
You search for a resource by sending a GET request to a resource URI. By default, the result is the first
page (page index = 0) with default size of 20. By adding filter, sort and paging parameters, described in
the following sections, to the URI, the client can control this search.
Cisco Guest REST API Reference Guide
6-8
OL-31414-01
Chapter 6
Guest REST API
Searching and Filtering
The resources resulting from a paging, filter, or sort request are bundled in a <resources> collection,
which contains for each resource its name, ID, description, and link to its full representation. This gives
the client the ability to easily drill down into the resource.
Filtering Parameters
Filtering is available through the filter query string parameter. The structure of a filter is a triplet of field
operator, parameter, and value, separated with dots. For example, use filter=name.STARTSW.g to find all
guest users with usernames that start with the letter ‘g’.
If you use multiple parameters in your filter, the result will be the AND of those parameters. That means that
the results will be users that match all of the parameters sent to the API. Each resource description specifies
if an attribute is a filtered field.
Note
Invalid filters values result in status 400 (Bad Request), with corresponding messages.
The following table shows the parameters available in filter queries.
Table 6-7
Filtering Parameters
Parameter
Description
firstName
Guest’s first name
lastName
Guest’s last name
emailAddress
Guest’s email address
userName
Guest account user name
creationTime
Time the guest account was created
toDate
Expiration date for guest account
guestType
Type of guest
company
Guest’s company
phoneNumber
Guest’s phone number
groupTag
Group
sponsor
Guest’s sponsor
status
Guest account’s status
name
Resource identifier
The following table lists the operations that you can use in filter queries.
Table 6-8
Available Filter Operations
Parameter
Description
EQ
Equals
GT
Greater Than
LT
Less Than
STARTSW
Starts With
Cisco Guest REST API Reference Guide
OL-31414-01
6-9
Chapter 6
Guest REST API
Searching and Filtering
Table 6-8
Available Filter Operations
Parameter
Description
ENDSW
Ends With
CONTAINS
Contains
Filtering Examples
GET Request for Guest Users with First Names that Starts with ‘br’
GET https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/?filter=firstName.STARTSW.br
GET Request for Guest Users with First Name that Starts with 'b' Whose Email Address Includes 'bob'
GET
https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser?filter=firstName.STARTSW.b&filter=email
Address.CONTAINS.bob
GET Request for Guest Users with the Status of “Approved” and Expiration Date in October
GET
https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser?filter=status.EQ.Approved&filter=toDate
.STARTSW.10
Related Topics
Get a Guest User, page 7-23
Page Size Parameters
Search results default to 20 resources per page. Page numbering starts at page '0'. The maximum number
of resources per page cannot be more than 100. Illegal parameter values result in status 400 (Bad
Request) with corresponding messages
The page size parameters can override the defaults by using the paging parameters as described in
Table 6-9.
In the following example, the page size is changed to 50 resources:
GET
https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser?filter=name.STARTSW.b&filter=emailAddre
ss.CONTAINS.bob&size=50&page=0
Sorting Parameters
By default, the sort column is name and the sort direction is sortasc. You can override the defaults by
using the parameters as described in the example below:
GET https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser?size=50&page=0&sortdsc=name
You can find a list of the values that you can use for sorting in Table 6-7 on page 6-9.
Cisco Guest REST API Reference Guide
6-10
OL-31414-01
Chapter 6
Guest REST API
Searching and Filtering
Table 6-9
Available Paging and Sorting Preferences
Parameter
Description
Default Value
page
Page starting index
0
size
Page size
20 (max. = 100)
sortasc
Sorting field with Ascending direction, out of a set name
of available fields for sorting. (For alphabetic
characters, it is sorted A to Z.)
sortdsc
Sorting field with Descending direction, out of a
set of available fields for sorting. (For alphabetic
characters, it is sorted Z to A.)
name
Example: GET First 20 Guest User Records and Sort ascending by the Last Name
Request
GET https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser?page=0&size=20&sortasc=lastName
Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult
xmlns:ns2="ers.ise.cisco.com" total="22">
<nextPage type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser?page=1&size=20&sortasc=lastName"
rel="next"/>
<resources>
<resource name="aname001" id="8e4bf290-6229-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-Admin-Node:9060/ers/config/guestuser/8e4bf290-6229-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="aname002" id="8fe86480-6229-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-Admin-Node:9060/ers/config/guestuser/8fe86480-6229-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
...
<resource name="aname020" id="908b5b40-6229-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-Admin-Node:9060/ers/config/guestuser/908b5b40-6229-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
</resources>
</ns2:searchResult>
Related Topics
•
Filter by Usernames that Start with “ilucky” Example, page 7-24
•
Filter by Username that Starts with “ilucky” and Last Name that Starts with “J” Example, page 7-25
•
Filter By the First Name “John” and Sort By Username Example, page 7-26
Cisco Guest REST API Reference Guide
OL-31414-01
6-11
Chapter 6
Guest REST API
Searching and Filtering
Cisco Guest REST API Reference Guide
6-12
OL-31414-01
CH A P T E R
7
External RESTful Services API Operations
•
Overview, page 7-1
•
Prerequisites for Using the External RESTful Services API Calls, page 7-1
•
GetVersion, page 7-2
•
External RESTful Services APIs for Internal Users, page 7-2
•
External RESTful Services APIs for Endpoints, page 7-8
•
External RESTful APIs for Endpoint Identity Groups, page 7-16
•
External RESTful Services APIs for Identity Groups, page 7-21
•
External RESTful Services APIs for Guest Users, page 7-22
•
External RESTful Services APIs for Portals, page 7-40
•
External RESTful Services APIs for Network Devices, page 7-43
•
External RESTful Services APIs for Network Device Groups, page 7-48
•
External RESTful Services APIs for SGTs, page 7-50
•
REST API Client, page 7-52
Overview
This chapter provides examples of the External RESTful Services API calls, and describes how to use
them. Instructions are provided for issuing the External RESTful Services API calls, as well as examples
of API output schema files and sample data returned.
Prerequisites for Using the External RESTful Services API Calls
You must fulfill the following prerequisites before invoking an External RESTful Services API call:
•
You must have enabled External RESTful Services from the GUI.
•
You must have External RESTful Services Admin privileges.
You can use any REST client like JAVA, curl linux command, python or any other client to invoke
External RESTful Services API calls.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-1
Chapter 7
External RESTful Services API Operations
GetVersion
Related Topics
•
Enabling External RESTful Services APIs from the GUI, page 5-2
•
External RESTful Services API Authentication and Authorization, page 5-2
GetVersion
The GetVersion operation is common to all available resources. It fetches the version information of the
required resource. The following table lists the main characteristics of this operation:
Table 7-1
Main Characteristics of GetVersion Operation
Description
Retrieve the version information of the specified
resource
Synopsis
GET/ers/config/<resource-name>/versioninfo
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Version information
Response Status
200, 400, 401,403,404,415,500
Sample Request for GetVersion Operation
GET https://<ISE-ADMIN-NODE>:9060/ers/config/<resource-type>/versioninfo
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.<resource-namespace>.1.0+xml
Sample Response for GetVersion Operation
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.<resource-namespace>.versoininfo.1.0+xml
Content-Length: 122
{
<?xml version="1.0" encoding="UTF-8"?>
<ns2:versionInfo xmlns:ns2="ers.ise.cisco.com">
<currentServerVersion>1.2</currentServerVersion>
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/<resource-type>/versioninfo" rel="self"/>
<supportedVersions>1.0,1.1,1.2,1.3<supportedVersion>
</ns2:versionInfo>
}
External RESTful Services APIs for Internal Users
The External RESTful Services APIs for Internal users support full CRUD functionality. The following
table lists the External RESTful Services APIs that are available for internal users:
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-2
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Internal Users
Table 7-2
External RESTful Services APIs Available For Internal Users
Operation
HTTP Method
URL
Content
QueryString
Get All Users
GET
/ers/config/internaluser
n/a
Page, Size,
sortacs or
sortdsn,
Filter
Get User
GET
/ers/config/internaluser/{internal n/a
user-id1}
Create User
POST
/ers/config/internaluser/
Update User
PUT
/ers/config/internaluser/{internal internaluser
user-id}
Delete User
DELETE
/ers/config/internaluser/{internal n/a
user-id}
Get InternalUser
Resource Version
Info
GET
/ers/config/internaluser/version
internaluser
n/a
1. Internal user ID is the UUID type as stored in the Cisco ISE database.
Retrieve All Internal Users
You can use this API call to retrieve all the internal users present in Cisco ISE. The following table lists
the main characteristics of this API call:
Table 7-3
Main Characteristics of Retrieve All Internal Users API Call
Description
Retrieve collection of internal users
Synopsis
GET /ers/config/internaluser
Request Headers
Accept, Authorization, Host
QueryString
page, size, sortbyacn, sortbydcn, filter
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
SearchResult
Response Status
200, 400, 401, 403, 404, 415, 429, 500
Sample Request for Retrieve All Internal Users API
GET https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser?page=0&size=20&sortacs=name
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
Sample Response for Retrieve All Internal Users API
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xml
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-3
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Internal Users
Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult total="2" xmlns:ns2="ers.ise.cisco.com">
<resources>
<ns2:resource description="description1" name="name1" id="id1"/>
<ns2:resource description="description2" name="name2" id="id2"/>
</resources>
</ns2:searchResult>
}
Get Internal Users by ID
You can use this API call to get an internal user by the ID in Cisco ISE. The following table lists the
main characteristics of this API call:
Table 7-4
Main Characteristics of Read Internal Users API Call
Description
Retrieve the specified internal user
Synopsis
GET /ers/config/internaluser/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type InternalUser
Response Status
200, 400, 401,403, 404, 415, 429, 500
Sample Request for Read Internal Users API
GET https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.internaluser.1.0+xml
Sample Response for Read Internal Users API
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:internaluser description="description" name="name" id="id"
xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com">
<changePassword>true</changePassword>
<customAttributes>
<entry>
<key>key2</key>
<value>value3</value>
</entry>
<entry>
<key>key1</key>
<value>value1</value>
</entry>
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-4
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Internal Users
</customAttributes>
<email>email@example.com</email>
<enabled>true</enabled>
<firstName>John</firstName>
<identityGroups>identityGroups</identityGroups>
<lastName>Doe</lastName>
<password>12345</password>
</ns3:internaluser>
}
Create Internal Users
You can use this API call to create internal users in Cisco ISE. Password is mandatory for creating
internal users using External RESTful Services APIs. The following table lists the main characteristics
of this API call:
Table 7-5
Main Characteristics of Create Internal Users API Call
Description
Create the specified internal user
Synopsis
POST /ers/config/internaluser/
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
InternalUser
Response Headers
Content-Length, Content-Type, Location
Response Message Body
Resource of type InternalUser
Response Status
201, 400, 401, 403, 415, 429, 500
Sample Request for Create Internal Users API
POST https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser/
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:internaluser description="description" name="name" id="id"
xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com">
<changePassword>true</changePassword>
<customAttributes>
<entry>
<key>key2</key>
<value>value3</value>
</entry>
<entry>
<key>key1</key>
<value>value1</value>
</entry>
</customAttributes>
<email>email@example.com</email>
<enabled>true</enabled>
<firstName>John</firstName>
<identityGroups>identityGroups</identityGroups>
<lastName>Doe</lastName>
<password>12345</password>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-5
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Internal Users
</ns3:internaluser>
}
Sample Response for Create Internal Users API
HTTP/1.1 201 OK (see the location header for the new user’s ID)
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
Location: https://<ISE-ADMIN-NODE>/ers/config/internaluser/444
Update Internal Users
You can use this API call to update internal users in Cisco ISE. You must set the password as ‘********’,
if the password is not getting changed while updating the internal users using the External RESTful
Services APIs. The following table lists the main characteristics of this API call:
Table 7-6
Main Characteristics of Update Internal Users API Call
Description
Update the specified internal user
Synopsis
PUT /ers/config/internaluser/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
InternalUser
Response Headers
Content-Length, Content-Type
Response Message Body
List of updated fields
Response Status
200, 400, 401, 403, 404, 415, 429, 500
Sample Request for Update Internal Users API
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:internaluser description="description" name="name" id="333"
xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com">
<changePassword>true</changePassword>
<customAttributes>
<entry>
<key>key2</key>
<value>value3</value>
</entry>
<entry>
<key>key1</key>
<value>value1</value>
</entry>
</customAttributes>
<email>email@example.com</email>
<enabled>true</enabled>
<firstName>John</firstName>
<identityGroups>IdentityGroups</identityGroups>
<lastName>Doe</lastName>
<password>********</password>
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-6
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Internal Users
</ns3:internaluser>
}
Sample Response for Update Internal Users API
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.updatedfields.1.0+xml
Content-Length: 529
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:updatedFields xmlns:ns2="ers.ise.cisco.com">
<updatedField field="lastname">
<newValue>Doe</newValue>
<oldValue>name</oldValue>
</updatedField>
<updatedField field="dentityGroups">
<newValue>IdentityGroups</newValue>
<oldValue>zzz</oldValue>
</updatedField>
</ns2:updatedFields>
}
Delete Internal Users
You can use this API call to delete internal users from Cisco ISE. The following table lists the main
characteristics of this API call:
Table 7-7
Main Characteristics of Delete Internal Users API Call
Description
Delete the specified internal user
Synopsis
DELETE
/ers/config/internaluser/{internaluser-id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type InternalUser
Response Status
204, 400, 401, 403, 404, 415, 429, 500
Sample Request for Delete Internal Users API
DELETE https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
Sample Response for Delete Internal Users API
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-7
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Endpoints
External RESTful Services APIs for Endpoints
The following table lists the External RESTful Services APIs for end points:
Table 7-8
External RESTful Services APIs Available for Endpoints
Operation
Method
URL
Content
QueryString
Get All Endpoints
GET
/ers/config/endpoint
n/a
page, size,
sortacs or
sortdsn, filter
Get Endpoint
GET
/ers/config/endpoint/{id1}
n/a
Create Endpoint
POST
/ers/config/endpoint/
endpoint
Update Endpoint
PUT
/ers/config/endpoint/{id}
endpoint
Delete Endpoint
DELETE
/ers/config/endpoint/{id}
n/a
/ers/config/endpoint/register
endpoint
Register Endpoint
PUT
Deregister Endpoint
PUT
2
Get Endpoint
GET
Resource Version Info
/ers/config/endpoint/{id}/deregister n/a
/ers/config/endpoint/version
n/a
1. Endpoint ID is the UUID type as stored in the Cisco ISE database.
2. If the endpoint already exists, it will be registered. If it does not exist, it will be first created and then registered. In both the
scenarios, the return status will be 204.
Get All Endpoints
The Get All API for Endpoints works only for retrieving endpoints associated to the user specified in the
filter. The following table lists the main characteristics of this API call:
Table 7-9
Main Characteristics of Get All Endpoints API Call
Description
Retrieve collection of endpoints associated to the specified
internal user
Synopsis
GET /ers/config/endpoint/
Request Headers
Accept, Authorization, Host
QueryString
page, size, sortbyacn, sortbydcn, filter
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
SearchResult
Response Status
200, 400, 401, 403, 404, 415, 429, 500
Sample Request for Get All Endpoints API
GET https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint?filter=userid.EQ.123
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-8
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Endpoints
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml
Sample Response for Get All Endpoints API
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xml
Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult total="2" xmlns:ns2="ers.ise.cisco.com">
<resources>
<resource name=name1" id="id1">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/id1" rel="self"/>
</resource>
<resource name="name2" id="id2">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/id2" rel="self"/>
</resource>
</resources>
</ns2:searchResult>
}
Get Endpoints by ID
You can use this API call to get an endpoint by the ID in Cisco ISE. The following table lists the main
characteristics of this API call:
Table 7-10
Main Characteristics of Read Endpoints API Call
Description
Retrieve the specified endpoint
Synopsis
GET /ers/config/endpoint/{endpoint-id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type InternalUser
Response Status
200, 400, 401,403, 404, 415, 429, 500
Sample Request for Read Endpoints API
GET https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml
Sample Response for Read Endpoints API
HTTP/1.1 200 OK
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-9
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Endpoints
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml
Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:endpoint description="description" name="name" id="id" xmlns:ns2="ers.ise.cisco.com"
xmlns:ns3="identity.ers.ise.cisco.com">
<group>group</group>
<groupId>groupId</groupId>
<identityStore>identityStore</identityStore>
<identityStoreId>identityStoreId</identityStoreId>
<mac>00:01:02:03:04:05</mac>
<portalUser>portalUser</portalUser>
<profile>profile</profile>
<profileId>profileId</profileId>
<staticGroupAssignment>true</staticGroupAssignment>
<staticProfileAssignment>false</staticProfileAssignment>
</ns3:endpoint>
}
Create Endpoints
You can use this API call to create endpoints in Cisco ISE. The following table lists the main
characteristics of this API call:
Table 7-11
Main Characteristics of Create Endpoints API Call
Description
Create the specified endpoint
Synopsis
POST /ers/config/endpoint/
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type InternalUser
Response Status
200, 400, 401,403, 404, 415, 429, 500
Sample Request for Create Endpoints API
POST https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:endpoint description="description" name="name" id="id" xmlns:ns2="ers.ise.cisco.com"
xmlns:ns3="identity.ers.ise.cisco.com">
<group>group</group>
<groupId>groupId</groupId>
<identityStore>identityStore</identityStore>
<identityStoreId>identityStoreId</identityStoreId>
<mac>00:01:02:03:04:05</mac>
<portalUser>portalUser</portalUser>
<profile>profile</profile>
<profileId>profileId</profileId>
<staticGroupAssignment>true</staticGroupAssignment>
<staticProfileAssignment>false</staticProfileAssignment>
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-10
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Endpoints
</ns3:endpoint>
}
Sample Response for Create Endpoints API
HTTP/1.1 201 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml
Location: https://cisco.com/ers/config/endpoint/444
Update Endpoints
You can use this API call to update endpoints in Cisco ISE. The following table lists the main
characteristics of this API call:
Table 7-12
Main Characteristics of Update Endpoints API Call
Description
Update the specified endpoint
Synopsis
PUT /ers/config/endpoint/{endpoint-id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type InternalUser
Response Status
200, 400, 401,403, 404, 415, 429, 500
Sample Request for Update Endpoints API
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:endpoint xmlns:ns2="identity.ers.ise.cisco.com" description="updated"
name="Endpoint">
<mac>AA:AA:AA:AA:AA:AA</mac>
<staticGroupAssignment>false</staticGroupAssignment>
<staticProfileAssignment>false</staticProfileAssignment>
</ns2:endpoint>}
Sample Response for Update Endpoints API
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.updatedfields.1.0+xml
Content-Length: 529
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:updatedFields xmlns:ns2="ers.ise.cisco.com">
<updatedField field="mac">
<newValue>AA:AA:AA:AA:AA:AA</newValue>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-11
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Endpoints
<oldValue>BB:BB:BB:BB:BB:BB</oldValue>
</updatedField>
<updatedField field="staticGroupAssignment">
<newValue>false</newValue>
<oldValue>true</oldValue>
</updatedField>
<updatedField field="staticProfileAssignment">
<newValue>false</newValue>
<oldValue>true</oldValue>
</updatedField>
</ns2:updatedFields>
}
Delete Endpoints
You can use this API call to update endpoints in Cisco ISE. The following table lists the main
characteristics of this API call:
Table 7-13
Main Characteristics of Delete Endpoints API Call
Description
Delete the specified endpoint
Synopsis
DELETE /ers/config/endpoint/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type InternalUser
Response Status
200, 400, 401,403, 404, 415, 429, 500
Sample Request for Delete Endpoints API
DELETE https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml
Sample Response for Delete Endpoints API
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Register Endpoints
You can use this API call to register endpoints in Cisco ISE. The endpoint is created if it doesn’t already
exist. Similar to the GUI registration flow, the endpoint is statically assigned to the Registered Devices
group and portal user and identity store will be set as specified in the content.
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-12
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Endpoints
The following table lists the main characteristics of this API call:
Table 7-14
Main Characteristics of Register Endpoints API Call
Description
Register the specified endpoint
Synopsis
PUT /ers/config/endpoint/register
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
endpoint
Response Headers
Content-Length, Content-Type
Response Message Body
List of updated fields
Response Status
202, 400, 401, 403, 404, 415, 429, 500
Sample Request for Register Endpoints API
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/register
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:endpoint description="description" name="name" id="id" xmlns:ns2="ers.ise.cisco.com"
xmlns:ns3="identity.ers.ise.cisco.com">
<group>group</group>
<groupId>groupId</groupId>
<identityStore>identityStore</identityStore>
<identityStoreId>identityStoreId</identityStoreId>
<mac>00:01:02:03:04:05</mac>
<portalUser>portalUser</portalUser>
<profile>profile</profile>
<profileId>profileId</profileId>
<staticGroupAssignment>true</staticGroupAssignment>
<staticProfileAssignment>false</staticProfileAssignment>
</ns3:endpoint>
}
Sample Response for Register Endpoints API
HTTP/1.1 204 No Content
Date: Thu, 12 Jul 2012 23:59:59 GMT
Deregister Endpoints
You can use this API call to deregister endpoints in Cisco ISE. No content expected in the result. The
following table lists the main characteristics of this API call:
Table 7-15
Main Characteristics of Deregister Endpoints API Call
Description
Deregister the specified endpoint
Synopsis
PUT /ers/config/endpoint/{id}/deregister
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-13
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Endpoints
Table 7-15
Main Characteristics of Deregister Endpoints API Call (continued)
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Message Body
N/A
Response Status
202, 400, 401, 403, 404, 415, 429, 500
Sample Request for Deregister Endpoint API Call
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/123/deregister
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml
Sample Response for Deregister Endpoint API Call
HTTP/1.1 204 No Content
Date: Thu, 12 Jul 2012 23:59:59 GMT
Start Bulk Execution for Endpoints
A bulk execution allows you to send up to 500 CRUD operations of the same type in a single request.
If the request is valid, the server returns the status code 202 (ACCEPTED) and a unique bulk identifier in
the LOCATION response header that you can use to track the bulk status using the Get Bulk Status
operation.
Only one bulk is allowed to run at a time. If a bulk request was posted while another bulk is still running,
the server will return with a response status 503 (Service Unavailable) with a corresponding
descriptive message asking the client to try again later.
Table 7-16
Start Bulk Execution for Endpoints Main Characteristics
Description
Start Execute
Synopsis
PUT /ers/config/endpoint/bulk
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
BulkRequest
Response Headers
Content-Length, Content-Type
Response Message Body
n/a
Response Status
202, 400, 401, 403, 404, 415, 500
Sample Request for Start Bulk Execution for Endpoints API Call
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/bulk HTTP/1.1
Host: {some-ise-node-ip}
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-14
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Endpoints
Authorization: Basic xxxxxxxxxxxxxxxxxxx Content-Type:
application/vnd.com.cisco.ise.ers.bulkrequest.1.0+xml
{
<ns3:endpointBulkRequest
resourceMediaType = "vnd.com.cisco.ise.ers.identity.endpoint.1.0+xml" operationType =
"create"
xmlns:ns2 = "ers.ise.cisco.com"
xmlns:ns3 = "identity.ers.ise.cisco.com">
<resourcesList> <resource
xsi:type = "ns3:ersEndPoint"
description = "created by bulk request"
xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"> <mac>11:22:33:44:55:66</mac>
<staticGroupAssignment>false</staticGroupAssignment>
<staticProfileAssignment>false</staticProfileAssignment>
</resource>
. . .
<resource
xsi:type = "ns3:ersEndPoint"
description = "created by bulk request"
xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"> <group>Profiled</group>
<groupId>804f5350-7808-11e2-bdd0-0050568e01f0</groupId> <identityStore></identityStore>
<identityStoreId></identityStoreId> <mac>11:22:33:44:55:77</mac>
<portalUser></portalUser>
<profile>Apple-iPod</profile> <profileId>b8128870-7808-11e2-bdd0-0050568e01f0</profileId>
<staticGroupAssignment>true</staticGroupAssignment>
<staticProfileAssignment>true</staticProfileAssignment>
</resource> </resourcesList>
</ns3:endpointBulkRequest>
}
Sample Response for Start Bulk Execution for Endpoints API Call
HTTP/1.1 202 ACCEPTED
Date: Thu, 12 Jul 2012 23:59:59 GMT
Location: https://ise-node-ip:9060/ers/config/endpoint/123443545334
Get Bulk Status for Endpoints
If a bulk execution request is valid and no other bulk already in progress, the server returns a unique bulk
identifier in the LOCATION response header. Use this ID to track the bulk status. The status report will
be available for at least 2 hours after the operation’s start time.
Table 7-17
Get Bulk Status Main Characteristics
Description
Monitor the specified bulk execution progress
Synopsis
GET /ers/config/endpoint/bulk/{bulkid}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
n/a
Response Headers
Content-Length, Content-Type
Response Message Body
BulkStatus
Response Status
200, 400, 401, 403, 404, 415, 500
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-15
Chapter 7
External RESTful Services API Operations
External RESTful APIs for Endpoint Identity Groups
Get Bulk Status for Endpoints Example
Request
GET https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/bulk/53454354534 HTTP/1.1
Host: {some-ise-node-ip}
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.bulkStatus.1.0+xml
Response
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.bulkStatus.1.0+xml Content-Length: 16347
{
<ns2:bulkStatus
xmlns:ns2 = "ers.ise.cisco.com"
successCount = "750"
startTime = "Thu Mar 07 17:17:35 IST 2013"
resourcesCount = "750"
operationType = "create"
mediaType =
"vnd.com.cisco.ise.ers.identity.endpoint.1.0+xml"
failCount = "0"
executionStatus = "COMPLETED"
bulkId = "1362669455284">
<resourcesStatus>
<resourceStatus status = "SUCCUESS"
description = "created by bulk request"
id = "23d068d0-873a-11e2-bad4-00215edbb2a8” />
. . . .
<resourceStatus
status = "SUCCUESS"
description = "created by bulk request"
id = "23cfa580-873a-11e2-bad4-00215edbb2a8"/>
</resourcesStatus>
</ns2:bulkStatus>
}
}
External RESTful APIs for Endpoint Identity Groups
The following table lists the External RESTful Services APIs for endpoint identity groups:
Table 7-18
ERS APIs Available for Endpoint Identity Groups
Operation
Method
URL
Content
QueryString
Get All Endpoints
Groups
GET
/ers/config/endpointgroup
n/a
page, size,
sortacs or
sortdsn, filter
Get Endpoint Group
GET
/ers/config/endpointgroup/ n/a
{id1}
Create Endpoint Group
POST
/ers/config/endpointgroup/ Endpointgroup
Update Endpoint Group PUT
/ers/config/endpointgroup/ Endpointgroup
{id}
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-16
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful APIs for Endpoint Identity Groups
Table 7-18
ERS APIs Available for Endpoint Identity Groups (continued)
Operation
Method
URL
Content
Delete Endpoint Group
DELETE
/ers/config/endpointgroup/ n/a
{id}
Get IdentityGroup
Resource Version Info
GET
/ers/config/ endpointgroup n/a
/version
QueryString
1. Endpoint Group ID is the UUID type as stored in the Cisco ISE database.
Get All Endpoint Identity Groups
The following table lisys the main characteristics of the Get All Endpoint Identity Groups API call:
Table 7-19
Main Characteristics of Get All Endpoint Identity Groups API Call
Description
Retrieve a collection of endpoint groups
Synopsis
GET /ers/config/endpoint
Request Headers
Accept, Authorization, Host
QueryString
page, size, sortasc, sortdsc, filter
Request Message Body
n/a
Response Headers
Content-Length, Content-Type
Response Message Body
List of updated fields
Response Status
202, 400, 401, 403, 404, 415, 429, 500
Sample Request for Get All Endpoint Identity Groups API Call
GET https://<ISE-ADMIN-NODE>:9060/ers/config/endpointgroup
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml
Sample Response for Get All Endpoint Identity Groups API Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xml
Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult total="2" xmlns:ns2="ers.ise.cisco.com">
<resources>
<resource name="name1" id="id1" description="description1">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/endpointgroup/id1" rel="self"/>
</resource>
<resource name="name2" id="id2" description="description2">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/endpointgroup/id2" rel="self"/>
</resource>
</resources>
</ns2:searchResult>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-17
Chapter 7
External RESTful Services API Operations
External RESTful APIs for Endpoint Identity Groups
}
Get Endpoint Identity Groups by ID
The following table lists the main characteristics of the Get Endpoint Identity Groups by ID API call:
Table 7-20
Main Characteristics of Read Endpoint Identity Groups API Call
Description
Retrieve the specified endpoint group
Synopsis
GET /ers/config/endpoint/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type Endpoint
Response Status
200, 400, 401,403, 404, 415, 429, 500
Sample Request for Read Endpoint Identity Groups API Call
GET https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml
Sample Response for Read Endpoint Identity Groups API Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml
Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:endpointgroup description="description" name="name" id="id"
xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com">
<systemDefined>true</systemDefined>
</ns3:endpointgroup>
}
Create Endpoint Identity Groups
The following table lists the main characteristics of the Create Endpoint Identity Groups API call:
:
Table 7-21
Main Characteristics of Create Endpoint Identity Groups API Call
Description
Create the specified endpoint group
Synopsis
POST /ers/config/endpoint/
Request Headers
Accept, Authorization, Host
QueryString
N/A
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-18
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful APIs for Endpoint Identity Groups
Table 7-21
Main Characteristics of Create Endpoint Identity Groups API Call (continued)
Request Message Body
Endpoint Group
Response Headers
Content-Length, Content-Type, Location
Response Message Body
Endpoint Goup
Response Status
201, 400, 401, 403, 415, 429, 500
Sample Request for Create Endpoint Identity Groups API Call
POST https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:endpointgroup description="description" name="name" id="id"
xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com">
<systemDefined>true</systemDefined>
</ns3:endpointgroup>
}
Sample Response for Create Endpoint Identity Groups API Call
HTTP/1.1 201 OK (see the location header for the new endpoint ID)
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type:
Location: https://cisco.com/ers/config/endpointgroup/444
Update Endpoint Identity Groups
The following table lists the main characteristics of the Update Endpoint Identity Groups API call:
Table 7-22
Main Characteristics of Update Endpoint Identity Groups API Call
Description
Update the specified endpoint group
Synopsis
PUT /ers/config/endpoint/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
Endpoint Group
Response Headers
Content-Length, Content-Type
Response Message Body
List of updated fields
Response Status
200, 400, 401, 403, 404, 415, 429, 500
Sample Request for Update Endpoint Identity Groups API Call
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/ endpoint /333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml
{
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-19
Chapter 7
External RESTful Services API Operations
External RESTful APIs for Endpoint Identity Groups
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:endpointgroup xmlns:ns2="identity.ers.ise.cisco.com" description="updated" id="0"
name="Group">
<systemDefined>false</systemDefined>
</ns2:endpointgroup>
}
Sample Response for Update Endpoint Identity Groups API Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.updatedfields.1.0+xml
Content-Length: 529
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:updatedFields xmlns:ns2="ers.ise.cisco.com">
<updatedField field="description">
<newValue>updated</newValue>
<oldValue>Group</oldValue>
</updatedField>
</ns2:updatedFields>
}
Delete Endpoint Identity Groups
The following table lists the main characteristics of the Delete Endpoint Identity API call:
Table 7-23
Main Characteristics of Delete Endpoint Identity Groups API Call
Description
Delete the specified endpoint group
Synopsis
DELETE /ers/config/endpointgroup/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
NA
Response Status
204, 400, 401, 403, 404, 415, 429, 500
Sample Request for Delete Endpoint Identity Groups API Call
DELETE https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml
Sample Response for Delete Endpoint Identity Groups API Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-20
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Identity Groups
External RESTful Services APIs for Identity Groups
The following table lists the External RESTful Services APIs for Identity Groups:
Table 7-24
APIs Available for Identity Groups
Operation
Method
URL
Content
Get All Identity Groups
GET
/ers/config/identitygroup n/a
Get IdentityGroup
Resource Version Info
GET
/ers/config/identitygroup n/a
/version
QueryString
page, size, sortacs
or sortdsn, filter
Retrieve All Identity Groups
You can use this API call to retrieve all identity groups in Cisco ISE. The following table lists the main
characteristics of this API call:
Table 7-25
Main Characteristics of Retrieve All Identity Groups API Call
Description
Retrieve a collection of identity group resources
Synopsis
GET /ers/config/identitygroup
Request Headers
Accept, Authorization, Host
QueryString
page, size, sortbyacn, sortbydcn, filter
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
SearchResult
Response Status
200, 400, 401, 403, 404, 415, 429, 500
Sample Request for Retrieve All Identity Group API Call
GET https://<ISE-ADMIN-NODE>:9060/ers/config/identitygroup?page=0&size=20&sortacs=name
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.identitygroup.1.0+xml
Sample Response for Retrieve All Identity Group API Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xml
Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult total="2" xmlns:ns2="ers.ise.cisco.com">
<resources>
<resource name="name1" id="id1" description="description1">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/identitygroup/id1" rel="self"/>
</resource>
<resource name="name2" id="id2" description="description2">
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-21
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/identitygroup/id2" rel="self"/>
</resource>
</resources>
</ns2:searchResult>
}
External RESTful Services APIs for Guest Users
The following table lists the External RESTful Services APIs for Guest Users:
Table 7-26
Supported Scenarios
Operation
Method
URL
Content
Get Specific Guest User
GET
/ers/config/guestuser/{id}
n/a
Get All Guest Users
GET
/ers/config/guestuser/
n/a
Create Guest User
POST
/ers/config/guestuser /
guest user
information
(XML)
Update Guest User
PUT
/ers/config/guestuser/{id}
partial or full
guest user
information
(XML)
Delete Guest User
DELETE
/ers/config/guestuser/{id}
n/a
Suspend Guest User
PUT
/ers/config/guestuser/suspend/{id}
reason
Reinstate Guest User
PUT
/ers/config/guestuser/reinstate/{id}
n/a
Send Email
PUT
/ers/config/guestuser/email/{id}/
portalId/{portalId}
senderEmail
Send SMS
PUT
/ers/config/guestuser/sms/{id}/portalId n/a
/{portalId}
Approve Guest User
PUT
/ers/config/guestuser/approve/{id}
n/a
Deny Guest User
PUT
/ers/config/guestuser/deny/{id}
n/a
Start Bulk Execution
PUT
/ers/config/ guestuser/bulk
BulkRequest
Get Bulk Status
GET
/ers/config/ guestuser/bulk/{bulkId}
n/a
Change Sponsor’s Password
PUT
/ers/config/guestuser/changeSponsor
Password/{portalId}
operationAdd
itionalData
Get All Portals
GET
/ers/config/portal
n/a
Get Portal by ID
GET
/ers/config/portal/{id}
n/a
Get Guest API Info
GET
/ers/config/guestuser/versioninfo
n/a
Content Type and Accept Headers
Each guest account request needs to set the following:
•
Content Type as: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-22
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
•
Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Each bulk execution request needs to set the following:
•
Content Type as: application/vnd.com.cisco.ise.identity.guestuserbulkrequest.1.0+xml
•
Accept: application/vnd.com.cisco.ise.identity.guestuserbulkrequest.1.0+xml
Get a Guest User
You can use the GET operation to retrieve specific guest users from the ISE database using either the
guest’s username or database record ID.
Table 7-27
Get a Guest User Main Characteristics
Description
Retrieve the specified Guest User
Synopsis
GET /ers/config/guestuser/{id}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
n/a
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type GuestUser
Response Status
200, 400, 401, 403, 404, 415, 500
Get a Guest User Examples
•
Get a Guest User by ID Example, page 7-23
•
Filter by Usernames that Start with “ilucky” Example, page 7-24
•
Filter by Username that Starts with “ilucky” and Last Name that Starts with “J” Example, page 7-25
•
Filter By the First Name “John” and Sort By Username Example, page 7-26
•
Guest User Request and Response Using curl Example, page 7-26
Get a Guest User by ID Example
Request
GET https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/3333
Content-Type - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Accept - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Authorization - Basic xxxxxxxxxxxxxxxxxxx
Response
<?xml version="1.0" encoding="UTF-8"?>
<ns3:guestuser xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com"
name="fzvhervocnz" id="af827350-1f0f-11e4-b961-005056103001">
<link type="application/xml" href="https://10.0.10.130:9060/ers/config/guestuser/3333"
rel="self"/>
<customFields/>
<guestAccessInfo>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-23
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
<fromDate>08/08/2014 08:21</fromDate>
<toDate>08/09/2014 08:21</toDate>
<validDays>1</validDays>
</guestAccessInfo>
<guestInfo>
<company>Cisco</company>
<creationTime>08/08/2014 08:21</creationTime>
<emailAddress>doe@example.com</emailAddress>
<enabled>true</enabled>
<firstName>John</firstName>
<lastName>Doe</lastName>
<notificationLanguage>English</notificationLanguage>
<password>12345</password>
<phoneNumber>9999998877</phoneNumber>
<smsServiceProvider>ATT</smsServiceProvider>
<userName>Guest1</userName>
</guestInfo>
<guestType>Daily (default)</guestType>
<personBeingVisited>sponsor@example.com</personBeingVisited>
<reasonForVisit>Interview</reasonForVisit>
<sponsorUserName>SponsoredUser1</sponsorUserName>
<status>Awaiting Initial Login</status>
</ns3:guestuser>
Related Topics
See Guest Passwords, page 2-4 for details on password visibility in the API.
Filter by Usernames that Start with “ilucky” Example
Request
GET https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/?filter=userName.STARTSW.ilucky
Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult
xmlns:ns2="ers.ise.cisco.com" total="8">
<resources>
<resource name="ilucky101" id="a0957160-6224-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/a0957160-6224-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky102" id="e14f4460-6224-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/e14f4460-6224-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky201" id="123581f0-6227-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/123581f0-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky301" id="154f9330-6227-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/154f9330-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky401" id="172c6980-6227-11e3-9bc2-000c2932c73c">
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-24
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/172c6980-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky501" id="19631fa0-6227-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/19631fa0-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky601" id="1b44b0e0-6227-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/1b44b0e0-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky602" id="2e1ac600-6227-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/2e1ac600-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
</resources>
</ns2:searchResult>
Filter by Username that Starts with “ilucky” and Last Name that Starts with “J” Example
Request
GET
https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/?filter=userName.STARTSW.ilucky&filter=
lastName.STARTSW.j
Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult
xmlns:ns2="ers.ise.cisco.com" total="8">
<resources>
<resource name="ilucky101" id="a0957160-6224-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/a0957160-6224-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky102" id="e14f4460-6224-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/e14f4460-6224-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky201" id="123581f0-6227-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/123581f0-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky301" id="154f9330-6227-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/154f9330-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky401" id="172c6980-6227-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/172c6980-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky501" id="19631fa0-6227-11e3-9bc2-000c2932c73c">
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-25
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/19631fa0-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky601" id="1b44b0e0-6227-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/1b44b0e0-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
<resource name="ilucky602" id="2e1ac600-6227-11e3-9bc2-000c2932c73c">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/2e1ac600-6227-11e3-9bc2-000c2932c73
c" rel="self"/>
</resource>
</resources>
</ns2:searchResult>
Filter By the First Name “John” and Sort By Username Example
Request
GET
https://<ISE-Admin-node>:9060/ers/config/guestuser/?page=0&size=10&sortdsc=name&filter=fir
stName.eq.john
Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult
xmlns:ns2="ers.ise.cisco.com" total="2">
<resources>
<resource name="jdoe0002" id="886f5b40-5ece-11e3-8faf-000c29c56fc6">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/886f5b40-5ece-11e3-8faf-000c29c56fc
6" rel="self"/>
</resource>
<resource name="jdoe0001" id="79e5a5a0-5df9-11e3-84f5-000c29c56fc6">
<link type="application/xml"
href="https://ISE-ADMIN-NODE:9060/ers/config/guestuser/79e5a5a0-5df9-11e3-84f5-000c29c56fc
6" rel="self"/>
</resource>
</resources>
</ns2:searchResult>
Guest User Request and Response Using curl Example
The following example describes a request for getting an guest user by ID sent to ISE and its response
using curl Linux command.
curl Command
$ curl -v -k -H 'ACCEPT:application/vnd.com.cisco.ise.identity.guestuser.2.0+xml'
https://username:password@<ISE-ADMIN-NODE>:9060/ers/config/guestuser/user1
* About to connect() to <ISE-ADMIN-NODE> port 9060
*
Trying 111.11.11.111... * connected
* Connected to <ISE-ADMIN-NODE> (<ISE-ADMin-NODE-IP>) port 9060
* successfully set certificate verify locations:
*
CAfile: /usr/share/ssl/certs/ca-bundle.crt
CApath: none
* SSL connection using DHE-RSA-AES256-SHA
* Server certificate:
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-26
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
*
*
*
*
*
* Server
subject: /CN=<ISE-ADMIN-NODE>
start date: 2013-11-26 00:56:55 GMT
expire date: 2014-11-26 00:56:55 GMT
common name: <ISE-ADMIN-NODE>
issuer: /CN=<ISE-ADMIN-NODE>
auth using Basic with user 'username'
GET Guest User by ID Request
> GET /ers/config/guestuser/444
Authorization: Basic xxxxxxxxxxxxxxxx
User-Agent: curl/7.12.1 (i386-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/1.2.1.2
libidn/0.5.6
Host: <ISE-ADMIN-NODE>:9060
Pragma: no-cache
ACCEPT:application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Response
< HTTP/1.1 200 OK
< Pragma: No-cache
< Cache-Control: no-cache
< Expires: Wed, 31 Dec 1969 16:00:00 PST
< Set-Cookie: JSESSIONIDSSO=0FCBC2621A0897193FE3105B3FBA8F16; Path=/; Secure
< Set-Cookie: JSESSIONID=5B6092B3FCCE047F7282C52592FAFC7A; Path=/ers; Secure
< Date: Thu, 02 Jan 2014 23:01:59 GMT
< Content-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
< Content-Length: 1162
< Server:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:guestuser xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com"
name="user1" id="b4bdf2b0-73e1-11e3-8cdf-000c29c56fc6">
<link type="application/xml" href="https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/444"
rel="self"/>
<guestAccessInfo>
<fromDate>08/06/2014 23:26</fromDate>
<toDate>08/07/2014 23:26</toDate>
<validDays>1</validDays>
</guestAccessInfo>
<guestInfo>
<company>New Company</company>
<emailAddress>john@example.com</emailAddress>
<firstName>John</firstName>
<lastName>Doe</lastName>
<notificationLanguage>English</notificationLanguage>
<phoneNumber>9999998877</phoneNumber>
<smsServiceProvider>Global Default</smsServiceProvider>
<userName>user1</userName>
</guestInfo>
<guestType>Daily (default)</guestType>
<personBeingVisited>sponsor@example.com</personBeingVisited>
<portalId>ff2d99e0-2101-11e4-b5cf-005056bf2f0a</portalId>
<reasonForVisit>Interview</reasonForVisit>
</ns3:guestuser>
Related Topics
See Guest Passwords, page 6-6 for details on password visibility in the API.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-27
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
Get All Guest Users
You can use the GET operation to retrieve all guest users in the ISE database and filter the results based
on criteria such as name, username, or email address. The response includes the guest’s username, ID,
and a link to its full representation.
Table 7-28
Get All Guest Users Main Characteristics
Description
Retrieve a collection of Guest Users
Synopsis
GET /ers/config/guestuser/
Request Headers
Accept, Authorization, Host
QueryString
page, size, sortasc, sortdsc, filter
Request Message Body
n/a
Response Headers
Content-Length, Content-Type
Response Message Body
SearchResult
Response Status
200, 400, 401, 403, 404, 415, 500
Related Topics
Filtering Parameters, page 2-8
Get All Example
In the following example, the GET operation retrieves all guest users with a username that starts with
ilu and a first name that starts with b.
Request
GET
https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/?page=0&size=10&sortasc=name&filter=nam
e.STARTSW.ilu&filter=firstName.STARTSW.b
Content-Type - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Accept - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Authorization - Basic xxxxxxxxxxxxxxxxxxx
Response
HTTP/1.1 200 OK;
Date:Sat, 15 Dec 2012 21:55:05 GMT;
Content-Length:1439;
Content-Type:application/vnd.com.cisco.ise.ers.searchresult.1.0+xml;
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult xmlns:ns2="ers.ise.cisco.com" total="6">
<resources>
<ns2:resource name="ilucky01" id="61dc9060-46a1-11e2-b141-000c290fcf9a">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/61dc9060-46a1-11e2-b141-000c290fc
f9a" rel="self"/>
</ns2:resource>
<ns2:resource name="ilucky02" id="3f43bb40-468e-11e2-8f92-000c290fcf9a">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/3f43bb40-468e-11e2-8f92-000c290fc
f9a" rel="self"/>
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-28
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
</ns2:resource>
<ns2:resource name="ilucky03" id="6c65d6d0-468e-11e2-8f92-000c290fcf9a">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/6c65d6d0-468e-11e2-8f92-000c290fc
f9a" rel="self"/>
</ns2:resource>
<ns2:resource name="ilucky04" id="6948bdb0-46a1-11e2-b141-000c290fcf9a">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/6948bdb0-46a1-11e2-b141-000c290fc
f9a" rel="self"/>
</ns2:resource>
<ns2:resource name="ilucky05" id="abbb6440-46a1-11e2-b141-000c290fcf9a">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/abbb6440-46a1-11e2-b141-000c290fc
f9a" rel="self"/>
</ns2:resource>
<ns2:resource name="ilucky06" id="4d9a1530-46fd-11e2-b70b-000c290fcf9a">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/4d9a1530-46fd-11e2-b70b-000c290fc
f9a" rel="self"/>
</ns2:resource>
</resources>
</ns2:searchResult>
Create a Guest User
You can use the POST operation to create a new guest user account, which allows a guest to log in
through the guest flow.
The guestType is required to create a guest user account.
Table 7-29
Create a Guest User Main Characteristics
Description
Create the specified Internal User
Synopsis
POST /ers/config/guestuser/
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
GuestUser
Response Headers
Content-Length, Content-Type, Location
Response Message Body
Resource of type GuestUser
Response Status
201, 400, 401, 403, 415, 500
Create a Guest User Example
Request
POST https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/
Content-Type - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Accept - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Authorization - Basic xxxxxxxxxxxxxxxxxxx
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:guestuser xmlns:ns2="identity.ers.ise.cisco.com">
<guestAccessInfo>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-29
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
<fromDate>08/08/2014 08:15</fromDate>
<toDate>08/09/2014 08:15</toDate>
<validDays>1</validDays>
</guestAccessInfo>
<guestInfo>
<company>New Company</company>
<emailAddress>doe@example.com</emailAddress>
<firstName>John</firstName>
<lastName>Doe</lastName>
<notificationLanguage>English</notificationLanguage>
<phoneNumber>9999998877</phoneNumber>
<smsServiceProvider>Global Default</smsServiceProvider>
<userName>guestuser1</userName>
</guestInfo>
<guestType>Daily (default)</guestType>
<personBeingVisited>sponsor@example.com</personBeingVisited>
<portalId>ff2d99e0-2101-11e4-b5cf-005056bf2f0a</portalId>
<reasonForVisit>Interview</reasonForVisit>
</ns2:guestuser>
Response
HTTP/1.1 201 Created;
Date:Sat, 15 Dec 2012 21:20:51 GMT;
Content-Length:0;
Location:https://<ISE-ADMIN-NODE>/ers/config/guestuser/e1bb8290-6ccb-11e3-8cdf-000c29c56fc
6;
Set-Cookie:JSESSIONID=28CF43F1ACCC7448BED7255DC7B787EE; Path=/ers;
Secure;JSESSIONIDSSO=DB6D6900088D1863CA84863570392E4C; Path=/; Secure;
Content-Type:application/xml;
Related Topics
See Guest Passwords, page 2-4 for details on password visibility in the API.
Update a Guest User
Updating a resource using the PUT operation gives you the ability to change the attributes of an existing
guest user. A full or partial update can be done of the guest user’s attributes.
Table 7-30
Update a Guest User Main Characteristics
Description
Update the specified Guest User
Synopsis
PUT /ers/config/guestuser/{id}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
GuestUser
Response Headers
Content-Length, Content-Type
Response Message Body
List of updated fields
Response Status
200, 400, 401, 403, 404, 415, 500
Update Guest Users Examples
•
Update User Example, page 7-31
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-30
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
•
Reset User’s Password Example, page 7-31
Update User Example
Request
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/name/ilucky101
Content-Type - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Accept - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Authorization - Basic xxxxxxxxxxxxxxxxxxx
<?xml version="1.0" encoding="UTF-8"?>
<ns2:guestuser xmlns:ns2="identity.ers.ise.cisco.com">
<portalId>ff2d99e0-2101-11e4-b5cf-005056bf2f0a</portalId>
<reasonForVisit>Interview</reasonForVisit>
</ns2:guestuser>
Response
Status:200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:updatedFields xmlns:ns2="ers.ise.cisco.com">
<updatedField field="ReasonForVisit">
<newValue>Interview</newValue>
<oldValue>no reason</oldValue>
</updatedField>
<updatedField field="validDays">
<newValue>0</newValue>
<oldValue>1</oldValue>
</updatedField>
</ns2:updatedFields>
Reset User’s Password Example
Request
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/e1bb8290-6ccb-11e3-8cdf-000c29c56f
c6
Content-Type - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Accept - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Authorization - Basic xxxxxxxxxxxxxxxxxxx
<?xml version="1.0" encoding="UTF-8"?>
<ns2:guestuser xmlns:ns2="identity.ers.ise.cisco.com">
<guestInfo>
<password/>
</guestInfo>
<portalId>ff2d99e0-2101-11e4-b5cf-005056bf2f0a</portalId>
</ns2:guestuser>
Response
Status:200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:updatedFields xmlns:ns2="ers.ise.cisco.com">
<updatedField field="validDays">
<newValue>0</newValue>
<oldValue>1</oldValue>
</updatedField>
<updatedField field="GuestInfo.Password">
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-31
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
<newValue>;AuJ5h:0</newValue>
</updatedField>
</ns2:updatedFields>
Related Topics
See Guest Passwords, page 2-4 for details on password visibility in the API.
Delete a Guest User
You can delete a guest user’s record from the ISE database using the database record ID. The user will
not be able to log in during their next attempt.
Table 7-31
Delete a Guest User Main Characteristics
Description
Delete the specified Guest User
Synopsis
DELETE /ers/config/guestuser/{id}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
n/a
Response Headers
Content-Length, Content-Type
Response Message Body
n/a
Response Status
204, 400, 401, 403, 404, 415, 500
Delete a Guest User Example
Request
DELETE https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/3333
Content-Type - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Accept - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Authorization - Basic xxxxxxxxxxxxxxxxxxx
Response
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Suspend a Guest User
Use the PUT operation to suspend a specific guest user. The user will not be able to log in during their
next attempt. You must include a reason for the suspension. The reason can include spaces.
Table 7-32
Suspend a Guest User Main Characteristics
Description
Suspend the specified Guest User
Synopsis
PUT /ers/config/guestuser/suspend/{id}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-32
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
Table 7-32
Suspend a Guest User Main Characteristics
Request Message Body
reason
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type GuestUser
Response Status
204, 400, 401, 403, 404, 415, 500
Suspend a Guest User by ID Example
Request
PUT https:/<ISE-ADMIN-NODE>:9060/ers/config/guestuser/suspend/3333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Content-Type - application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
<?xml version="1.0" encoding="UTF-8"?>
<ns3:operationAdditionalData xmlns:ns2="identity.ers.ise.cisco.com"
xmlns:ns3="ers.ise.cisco.com">
<requestAdditionalAttributes>
<additionalAttribute name="reason" value="AUP not accepted"/>
</requestAdditionalAttributes>
</ns3:operationAdditionalData>
Response
HTTP/1.1 204 No Content
Sat, 15 Dec 2012 10:14:38 GMT
Reinstate a Guest User
Use the PUT operation to reinstate a suspended guest’s user account.
Table 7-33
Reinstate a Guest User Main Characteristics
Description
Reinstate the specified Guest User
Synopsis
PUT /ers/config/guestuser/reinstate/{id}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
n/a
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type GuestUser
Response Status
204, 400, 401, 403, 404, 415, 500
Reinstate Guest User Example
Request
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/reinstate/33
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-33
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
Response
HTTP/1.1 204 OK
Date: Sat, 15 Dec 2012 10:20:48 GMT
Send an Email to a Guest User
Use the PUT operation to send an email to a guest user’s email account. This requires an SMTP server
to be configured in Cisco ISE.
The request requires a portal ID because the portal configuration contains information needed for the
email body and subject.
Table 7-34
Send an Email to a Guest User Main Characteristics
Description
Send an email to the specified Guest User
Synopsis
PUT /ers/config/guestuser/email/{id}/portalId/
{portalID}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
senderEmail
Response Headers
Content-Length, Content-Type
Response Message Body
n/a
Response Status
204, 400, 401, 403, 404, 415, 500
Send an Email to a Guest User Example
Request
PUT
https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/email/4444/portalId/ff2d99e0-2101-11e4b5cf-005056bf2f0a
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept:
application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
<?xml version="1.0" encoding="UTF-8"?>
<ns3:operationAdditionalData xmlns:ns2="identity.ers.ise.cisco.com"
xmlns:ns3="ers.ise.cisco.com">
<requestAdditionalAttributes>
<additionalAttribute name="senderEmail" value="sender Email"/>
</requestAdditionalAttributes>
</ns3:operationAdditionalData>
Response
HTTP/1.1 204 OK
Date: Sat, 15 Dec 2012 10:20:48 GMT
Send an SMS Text to a Guest User
Use the PUT operation to send a text message to a guest user’s mobile phone. This requires an SMTP
server to be configured in Cisco ISE.
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-34
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
The request requires a portal ID because the portal configuration contains information needed for the
text body.
Table 7-35
Send an Email to a Guest User Main Characteristics
Description
Send an sms to the specified Guest User
Synopsis
PUT /ers/config/guestuser/sms/{id}/portalId/
{portalID}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
n/a
Response Headers
Content-Length, Content-Type
Response Message Body
n/a
Response Status
204, 400, 401, 403, 404, 415, 500
Send an SMS Example
Request
PUT
https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/sms/444/portalId/ff2d99e0-2101-11e4-b5c
f-005056bf2f0a
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept:
application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Response
HTTP/1.1 204 OK
Date: Sat, 15 Dec 2012 10:20:48 GMT
Approve a Guest User
This operation allows you to approve a guest user account. This requires using the guest account ID.
Table 7-36
Get API Version Main Characteristics
Description
Approve the specified Guest User
Synopsis
PUT /ers/config/guestuser/approve/{id}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
n/a
Response Headers
Content-Length, Content-Type
Response Message Body
API version
Response Status
200, 400, 401, 403, 404, 415, 500
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-35
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
Approve a Guest User Example
Request
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/approve/3333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Response
HTTP/1.1 204 OK
Date: Sat, 15 Dec 2012 10:20:48 GMT
Deny Approval for a Guest User Account
This operation allows you to deny approval for a guest user account. This requires using the guest
account ID.
Table 7-37
Get API Version Main Characteristics
Description
Deny the specified Guest User
Synopsis
PUT /ers/config/guestuser/deny/{id}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
n/a
Response Headers
Content-Length, Content-Type
Response Message Body
API version
Response Status
200, 400, 401, 403, 404, 415, 500
Deny a Guest User’s Approval Example
Request
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/deny/7777
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Response
HTTP/1.1 204 OK
Date: Sat, 15 Dec 2012 10:20:48 GMT
Start Bulk Execution for Guest Users
A bulk request will allow you to send up to 500 operations in a single request, or up to 5000 operations
based on ID.
If the request is valid, the server returns the status code 202 (ACCEPTED) and a unique bulk identifier in
the LOCATION response header that you can use to track the bulk status using the Get Bulk Status
operation.
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-36
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
Only one bulk is allowed to run at a time. If a bulk request was posted while another bulk is still running,
the server will return with a response status 503 (Service Unavailable) with a corresponding
descriptive message asking the client to try again later.
Table 7-38
Start Bulk Execution Main Characteristics
Description
Start Execute
Synopsis
PUT /ers/config/guestuser/bulk
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
BulkRequest
Response Headers
Content-Length, Content-Type
Response Message Body
n/a
Response Status
202, 400, 401, 403, 404, 415, 500
Create Guest Bulk Example
Request
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/bulk
Authorization: Basic
Content-Type: application/vnd.com.cisco.ise.identity.guestuserbulkrequest.1.0+xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:bulkRequest xsi:type="ns2:guestUserBulkRequest"
resourceMediaType="vnd.com.cisco.ise.identity.guestuser.1.0+xml"
operationType="create"
xmlns:ns2="identity.ers.ise.cisco.com"
xmlns:ns3="ers.ise.cisco.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<resourcesList>
<resource xsi:type="ns2:GuestUser" description="created by bulk">
<portalId>6ab68890-d0f1-11e3-a1d5-005056bf4687</portalId>
<guestAccesstInfo>
<groupTag>group</groupTag>
<validDays>2</validDays>
<location>London</location>
<ssid>guest_ssid</ssid>
</guestAccesstInfo>
<guestInfo>
<company>new company</company>
<emailAddress>joe@example.com</emailAddress>
<enabled>true</enabled>
<firstName>John</firstName>
<lastName>Doe</lastName>
<phoneNumber>6033203311</phoneNumber>
<userName>lucky7</userName>
<password>1234</password>
<notificationLanguage>English</notificationLanguage>
<smsServiceProvider>ATT</smsServiceProvider>
</guestInfo>
<guestType>DAILY</guestType>
<reasonForVisit>interview</reasonForVisit>
<personBeingVisited>sponsor@cisco.com</personBeingVisited>
</resource>
...
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-37
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
<resource xsi:type="ns2:GuestUser" description="created by bulk">
<portalId>6ab68890-d0f1-11e3-a1d5-005056bf4687</portalId>
<guestAccesstInfo>
<groupTag>group</groupTag>
<validDays>3</validDays>
<location>London</location>
<ssid>guest_ssid</ssid>
</guestAccesstInfo>
<guestInfo>
<company>new company</company>
<emailAddress>mary@example.com</emailAddress>
<enabled>true</enabled>
<firstName>Mary</firstName>
<lastName>Sue</lastName>
<phoneNumber>6039990000</phoneNumber>
<userName>lucky13</userName>
<password>1234</password>
<notificationLanguage>English</notificationLanguage>
<smsServiceProvider>ATT</smsServiceProvider>
</guestInfo>
<guestType>DAILY</guestType>
<reasonForVisit>interview</reasonForVisit>
<personBeingVisited>sponsor@cisco.com</personBeingVisited>
</resource>
</resourcesList>
</ns3:bulkRequest>
Response
HTTP/1.1 202 ACCEPTED
Date: Thu, 12 Jul 2012 23:59:59 GMT
Location: https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/123443545334
Related Topics
Get Bulk Status for Endpoints, page 7-15
Get Bulk Status for Guest Users
If a bulk execution request is valid and no other bulk already in progress, the server returns a unique bulk
identifier in the LOCATION response header. Use this ID to track the bulk status. The status report will
be available for at least 2 hours after the operation’s start time.
Table 7-39
Get Bulk Status Main Characteristics
Description
Monitor the specified bulk execution progress
Synopsis
GET /ers/config/guestuser/bulk/{bulkid}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
n/a
Response Headers
Content-Length, Content-Type
Response Message Body
BulkStatus
Response Status
200, 400, 401, 403, 404, 415, 500
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-38
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Guest Users
Get Bulk Status for Guest Users Example
Request
GET https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/bulk/53454354534 HTTP/1.1
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.guestuserbulkrequest.1.0+xml
Response
HTTP/1.1 200 OK
Date: Thu Mar 07 18:17:35 IST 2013 GMT
Content-Type: application/vnd.com.cisco.ise.ers.guestuserbulkrequest.1.0+xml
Content-Length: 16347
{
<ns2:bulkStatus
xmlns:ns2 = "ers.ise.cisco.com"
successCount = "50"
startTime = "Thu Mar 07 17:17:35 IST 2013"
resourcesCount = "50"
operationType = "create"
resourceMediaType = "vnd.com.cisco.ise.ers.identity.guestuser.1.0+xml"
failCount = "0"
executionStatus = "COMPLETED"
bulkId = "53454354534">
<resourcesStatus>
<resourceStatus
status = "SUCCUESS"
description = "created by bulk request"
id = "23d068d0-873a-11e2-bad4-00215edbb2a8"/>
...
<resourceStatus
status = "SUCCUESS"
description = "created by bulk request"
id = "23cfa580-873a-11e2-bad4-00215edbb2a8"/>
</resourcesStatus>
</ns2:bulkStatus>
}
Change a Sponsor’s Password
This operation allows you to change the password of the sponsor who is currently logged in. This
requires using the portal ID.
Table 7-40
Get API Version Main Characteristics
Description
Update the logged-in sponsor’s password
Synopsis
PUT
/ers/config/guestuser/changeSponsorPassword/
{portalId}
Request Headers
Accept, Authorization, Host
QueryString
n/a
Request Message Body
n/a
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-39
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Portals
Table 7-40
Get API Version Main Characteristics
Response Headers
Content-Length, Content-Type
Response Message Body
API version
Response Status
200, 400, 401, 403, 404, 415, 500
Change a Sponsor’s Password Example
Request
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/changeSponsorPassword/88888
Host: cisco.com
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
<?xml version="1.0" encoding="UTF-8"?>
<ns3:operationAdditionalData xmlns:ns2="identity.ers.ise.cisco.com"
xmlns:ns3="ers.ise.cisco.com">
<requestAdditionalAttributes>
<additionalAttribute name="newPassword" value="Cisco1234"/>
<additionalAttribute name="currentPassword" value="Autom8me"/>
</requestAdditionalAttributes>
</ns3:operationAdditionalData>
Response
HTTP/1.1 204 OK
Date: Sat, 15 Dec 2012 10:20:48 GMT
External RESTful Services APIs for Portals
The following table lists the External RESTful Services APIs for Portals:
Table 7-41
APIs Available for Portals
Operation
Method
URL
Content
QueryString
Get All Portals
GET
/ers/config/portal
n/a
Page, Size,
sortacs or sortdsn,
Filter
Get Portal by ID
GET
/ers/config/portal/{id}
n/a
Get All Portals
The following table lists the main characteristics of the Get All Portals API call:
Table 7-42
Main Characteristics of Get All Portals API Call
Description
Retrieve a collection of portals
Synopsis
GET /ers/config/portal
Request Headers
Accept, Authorization, Host
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-40
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Portals
Table 7-42
Main Characteristics of Get All Portals API Call (continued)
QueryString
page, size, sortbyacn, sortbydcn, filter
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
SearchResult
Response Status
200, 400, 401, 403, 404, 415,500
Sample Request for Get All Portals Call
GET https://<ISE-ADMIN-NODE>:9060/ers/config/portal
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.portal.1.0+xml
Sample Response for Get All Portals Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xml
Content-Length: 16347
{
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <ns2:searchResult total="2"
xmlns:ns2="ers.ise.cisco.com">
<resources>
<resource name="portal1" id="id1">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/portal/id1" rel="self"/>
</resource>
<resource name="portal2" id="id2">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/portal/id2" rel="self"/>
</resource>
</resources>
</ns2:searchResult>
Get Portal by ID
The following table lists the main characteristics of the Get Portal by ID API call:
Table 7-43
Main Characteristics of Get Portal by ID API Call
Description
Retrieve the specified portal
Synopsis
GET /ers/config/portal/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type Portal
Response Status
200, 400, 401,403, 404, 415, 500
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-41
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Portals
Sample Request for Get Portal by ID Call
GET https://<ISE-ADMIN-NODE>:9060/ers/config/portal/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.identity.portal.1.0+xml
Sample Response for Get Portal by ID Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.identity.portal.1.0+xml Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:portal name="sponsor" id="d7b703f0-b073-11e3-bd6c- 005056a15fa7"
xmlns:ns2="ers.ise.cisco.com"
xmlns:ns3="identity.ers.ise.cisco.com">
<link type="application/xml"
href="https://<ISE-ADMIN-NODE>:9060/ers/config/portal/333" rel="self"/>
<allowSponsorToChangeOwnPassword>false</allowSponsorToChangeOwnPassword>
<GuestUserFieldList>
<GuestUserField>
<customType>false</customType>
<dataType>DROPDOWN</dataType>
<dictionaryLabelKey>ui_sms_provider_label</dictionaryLabelKey>
<labelName>SMS Service Provider</labelName>
<required>true</required>
</GuestUserField>
<GuestUserField>
<customType>false</customType>
<dataType>TEXT</dataType>
<dictionaryLabelKey>ui_company_label</dictionaryLabelKey>
<labelName>Company</labelName>
<required>true</required>
</GuestUserField>
<GuestUserField>
<customType>false</customType>
<dataType>TEXT</dataType>
<dictionaryLabelKey>ui_first_name_label</dictionaryLabelKey>
<labelName>First name</labelName>
<required>true</required>
</GuestUserField>
<GuestUserField>
<customType>false</customType>
<dataType>TEXT</dataType>
<dictionaryLabelKey>ui_reason_visit_label</dictionaryLabelKey>
<labelName>Reason for visit</labelName>
<required>true</required>
</GuestUserField>
<GuestUserField>
<customType>true</customType>
<dataType>TEXT</dataType>
<dictionaryLabelKey>ui_ssn-number_text_label</dictionaryLabelKey>
<instructionText>social </instructionText>
<labelName>ssn-number</labelName>
<required>false</required>
</GuestUserField>
<GuestUserField>
<customType>false</customType>
<dataType>PHONE</dataType>
<dictionaryLabelKey>ui_phone_number_label</dictionaryLabelKey>
<labelName>Phone number</labelName>
<required>true</required>
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-42
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Network Devices
</GuestUserField>
<GuestUserField>
<customType>false</customType>
<dataType>EMAIL</dataType>
<dictionaryLabelKey>ui_person_visited_label</dictionaryLabelKey>
<labelName>Person being visited</labelName>
<required>true</required>
</GuestUserField>
<GuestUserField>
<customType>false</customType>
<dataType>EMAIL</dataType>
<dictionaryLabelKey>ui_email_address_label</dictionaryLabelKey>
<labelName>Email address</labelName>
<required>true</required>
</GuestUserField>
<GuestUserField>
<customType>false</customType>
<dataType>TEXT</dataType>
<dictionaryLabelKey>ui_last_name_label</dictionaryLabelKey>
<labelName>Last name</labelName>
<required>true</required>
</GuestUserField>
</GuestUserFieldList>
</ns3:portal>
}
External RESTful Services APIs for Network Devices
The following table lists the External RESTful Services APIs for Network Devices:
Table 7-44
APIs Available for Portals
Operation
Method
URL
Content
QueryString
Get All Network Devices
GET
/ers/config/networkdevice
n/a
Page, Size,
sortacs or sortdsn,
Filter
Get Network Device
GET
/ers/config/networkdevice
/{id}
n/a
Create Network Device
POST
/ers/config/networkdevice
networkde
vice
Update Network Device
PUT
/ers/config/networkdevice
/{id}
networkde
vice
Delete Network Device
DELETE
/ers/config/networkdevice
/{id}
n/a
Get Network Device
Resource Version Info
GET
/ers/config/ networkdevice
/versioninfo
n/a
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-43
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Network Devices
Get All Network Devices
The following table lists the main characteristics of the Get All Network Devices API call:
Table 7-45
Main Characteristics of Get All Network Devices API Call
Description
Retrieve a collection of network device resources
Synopsis
GET /ers/config/networkdevice
Request Headers
Accept, Authorization, Host
QueryString
page, size, sortbyacn, sortbydcn, filter
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
SearchResult
Response Status
200, 400, 401, 403, 404, 415, 500
Sample Request for Get All Network Devices Call
GET https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevice?page=1&size=20&sortacs=name
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.network.networkdevice.1.0+xml
Sample Response for Get All Network Devices Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xml Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns2:searchResult
xmlns:ns2="ers.ise.cisco.com" total="1">
<resources>
<resource name="nd1" id="0d008bb0-2539-11e3-84ad00215edbb2a8">
<link type="application/xml"
href="https://10.56.13.196:9060/ers/config/networkdevice/0d0
08bb0-2539-11e3-84ad-00215edbb2a8" rel="self"/>
</resource>
</resources>
</ns2:searchResult>
}
Get Network Device by ID
The following table lists the main characteristics of the Get Network Device by ID API call:
Table 7-46
Main Characteristics of Get Network Device by ID API Call
Description
Retrieve the specified network device
Synopsis
GET /ers/config/networkdevice/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-44
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Network Devices
Table 7-46
Main Characteristics of Get Network Device by ID API Call (continued)
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type Network Device
Response Status
200, 400, 401, 403, 404, 415, 500
Sample Request for Get Network Device by ID Call
GET https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevice/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.network.networkdevice.1.0+xml
Sample Response for Get Network Device by ID Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.network.networkdevice.1.0+xml Content-Length:
16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns3:networkdevice
xmlns:ns2="ers.ise.cisco.com"
xmlns:ns3="network.ers.ise.cisco.com" name="nd1"
id="0d008bb0-2539-11e3-84ad-00215edbb2a8">
<link type="application/xml"
href="https://10.56.13.196:9060/ers/config/networkdevice/0d0
08bb0-2539-11e3-84ad-00215edbb2a8" rel="self"/>
<authenticationSettings>
<enableKeyWrap>false</enableKeyWrap>
<keyInputFormat>ASCII</keyInputFormat>
<networkProtocol>RADIUS</networkProtocol>
<radiusSharedSecret>*****</radiusSharedSecret>
</authenticationSettings>
<NetworkDeviceIPList>
<NetworkDeviceIP>
<ipaddress>1.2.3.4</ipaddress>
<mask>32</mask>
</NetworkDeviceIP>
</NetworkDeviceIPList>
<modelName>Unknown</modelName>
<NetworkDeviceGroupList>
<NetworkDeviceGroup>1d8c62b0-2539-11e3-84ad00215edbb2a8</NetworkDeviceGroup>
<NetworkDeviceGroup>37053aa0-2539-11e3-84ad00215edbb2a8</NetworkDeviceGroup>
</NetworkDeviceGroupList>
<softwareVersion>Unknown</softwareVersion>
</ns3:networkdevice>
}
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-45
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Network Devices
Create Network Device
The following table lists the main characteristics of the Create Network Device API call:
Table 7-47
Main Characteristics of Create Network Device API Call
Description
Create a specified network device
Synopsis
POST /ers/config/networkdevice/
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
NetworkDevice
Response Headers
Content-Length, Content-Type, Location
Response Message Body
N/A
Response Status
200, 400, 401, 403, 415, 500
Sample Request for Create Network Device Call
POST https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevice/
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.network.networkdevice.1.0+xml {
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:networkdevice
xmlns:ns2="ers.ise.cisco.com"
xmlns:ns3="network.ers.ise.cisco.com" name="nd2">
<authenticationSettings>
<enableKeyWrap>false</enableKeyWrap>
<keyInputFormat>ASCII</keyInputFormat>
<networkProtocol>RADIUS</networkProtocol>
<radiusSharedSecret>acsi</radiusSharedSecret>
</authenticationSettings>
<NetworkDeviceIPList>
<NetworkDeviceIP>
<ipaddress>1.2.3.4</ipaddress>
<mask>32</mask>
</NetworkDeviceIP>
</NetworkDeviceIPList>
<modelName>Unknown</modelName>
<NetworkDeviceGroupList>
<NetworkDeviceGroup>1d8c62b0-2539-11e3-84ad00215edbb2a8</NetworkDeviceGroup>
<NetworkDeviceGroup>37053aa0-2539-11e3-84ad00215edbb2a8</NetworkDeviceGroup>
</NetworkDeviceGroupList>
<softwareVersion>Unknown</softwareVersion>
</ns3:networkdevice>
}
Sample Response for Create Network Device Call
HTTP/1.1 201 OK (see location header for the ID of the new device)
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.network.networkdevice.1.0+xml
Location: https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevice/444
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-46
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Network Devices
Update Network Device
The following table lists the main characteristics of the Update Network Device API call:
Table 7-48
Main Characteristics of Update Network Device API Call
Description
Update a specified network device
Synopsis
PUT /ers/config/networkdevice/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
NetworkDevice
Response Headers
Content-Length, Content-Type
Response Message Body
List of updated fields
Response Status
200, 400, 401, 403, 415, 500
Sample Request for Update Network Device Call
PUT https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevice/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.cisco.ise.network.networkdevice.1.0+xml {
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:networkdevice
xmlns:ns2="ers.ise.cisco.com"
xmlns:ns3="network.ers.ise.cisco.com"
name="nd2_updated">
<authenticationSettings>
<enableKeyWrap>true</enableKeyWrap>
</authenticationSettings>
</ns3:networkdevice>
}
Sample Response for Update Network Device Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.updatedfields.1.0+xml Content-Length: 529
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns2:updatedFields
xmlns:ns2="ers.ise.cisco.com">
<updatedField field="name">
<newValue>nd2_updated</newValue>
<oldValue>nd2</oldValue>
</updatedField>
<updatedField field="enableKeywrap">
<newValue>true</newValue>
<oldValue>false</oldValue>
</updatedField>
</ns2:updatedFields>
}
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-47
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Network Device Groups
Delete Network Device
The following table lists the main characteristics of the Delete Network Device API call:
Table 7-49
Main Characteristics of Delete Network Device API Call
Description
Delete a specified network device
Synopsis
DELETE /ers/config/networkdevice/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
N/A
Response Status
200, 204, 400, 401, 403, 404, 415, 500
Sample Request for Update Network Device Call
DELETE https://<ISE-ADMIN-NODE>:9060/ers/config/networjdevice/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.network.networkdevice.1.0+xml
Sample Response for Update Network Device Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
External RESTful Services APIs for Network Device Groups
The following table lists the External RESTful Services APIs for Network Device Groups:
Table 7-50
APIs Available for SGTs
Operation
Method
URL
Content
Get All Network
Device Groups
GET
/ers/config/networkdeviceg n/a
roup
Get Network
Device Group
GET
/ers/config/networkdeviceg n/a
roup/{id}
Get Network
Device Group
Resource Version
Info
GET
/ers/config/networkdeviceg n/a
roup/versioninfo
QueryString
page, size, sortacs
or sortdsn, filter
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-48
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for Network Device Groups
Get All Network Device Groups
The following table lists the main characteristics of the Get All Network Device Groups API call:
Table 7-51
Main Characteristics of Get All Network Device Groups API Call
Description
Retrieve a collection of Network Device Groups
resources
Synopsis
GET /ers/config/networkdevicegroup
Request Headers
Accept, Authorization, Host
QueryString
page, size, sortbyacn, sortbydcn, filter
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
SearchResult
Response Status
200, 400, 401, 403, 404, 415, 500
Sample Request for Get All Network Device Groups API Call
GET
https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevicegroup?page=1&size=20&sortacs=name
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.network.networkdevicegroup.1.0+xml
Sample Response for Get All Network Device Groups API Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xml Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult
xmlns:ns2="ers.ise.cisco.com" total="0">
<resources>
<resource name="Location#All Locations#loc1" id="1d8c62b0-2539-11e3-84ad-00215edbb2a8"
description="xxx">
<link type="application/xml"
href="https://10.56.13.196:9060/ers/config/networkdevicegroup/1d8c62b0-2539-11e3-84ad-0021
5edbb2a8" rel="self"/>
</resource>
<resource name="Device Type#All Device Types#device type 555"
id="37053aa0-2539-11e3-84ad-00215edbb2a8" description="vvv">
<link type="application/xml"
href="https://10.56.13.196:9060/ers/config/networkdevicegrou
p/37053aa0-2539-11e3-84ad-00215edbb2a8" rel="self"/>
</resource>
</resources>
</ns2:searchResult>
}
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-49
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for SGTs
Get Network Device Group
The following table lists the main characteristics of the Get Network Device Groups API call:
Table 7-52
Main Characteristics of Get Network Device Group API Call
Description
Retrieve the specified Network Device group
Synopsis
GET /ers/config/networkdevicegroup/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type NetworkDeviceGroup
Response Status
200, 400, 401, 403, 404, 415, 429, 500
Sample Request for Get Network Device Group API Call
GET https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevicegroup/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.network.networkdevicegroup.1.0+xml
Sample Response for Get Network Device Group API Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.network.networkdevicegroup.1.0 +xml
Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns3:networkdevicegroup
xmlns:ns2="ers.ise.cisco.com"
xmlns:ns3="network.ers.ise.cisco.com" name="Location#All
Locations#loc1" id="1d8c62b0-2539-11e3-84ad-00215edbb2a8"
description="xxx">
<link type="application/xml"
href="https://10.56.13.196:9060/ers/config/networkdevicegrou
p/1d8c62b0-2539-11e3-84ad-00215edbb2a8" rel="self"/>
<type>Location</type>
</ns3:networkdevicegroup>
}
External RESTful Services APIs for SGTs
The following table lists the External RESTful Services APIs for SGTs:
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-50
OL-26134-01
Chapter 7
External RESTful Services API Operations
External RESTful Services APIs for SGTs
Table 7-53
APIs Available for SGTs
Operation
Method
URL
Content
QueryString
Get All SGTs
GET
/ers/config/sgt
n/a
page, size, sortacs
or sortdsn, filter
Get SGT
GET
/ers/config/sgt/{id1}
n/a
Get GST Resource
Version Info
GET
/ers/config/sgt/versioninfo
n/a
1. The SGT ID is the UUID type as stored in the Cisco ISE database.
Get All SGTs
The following table lists the main characteristics of the Get All SGTs API call:
Table 7-54
Main Characteristics of Get All SGTs API Call
Description
Retrieve a collection of SGT resources
Synopsis
GET /ers/config/sgt
Request Headers
Accept, Authorization, Host
QueryString
page, size, sortbyacn, sortbydcn, filter
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
SearchResult
Response Status
200, 400, 401, 403, 404, 415, 429, 500
Sample Request for Get All SGTs API Call
GET https://<ISE-ADMIN-NODE>:9060/ers/config/sgt?page=0&size=20&sortacs=name
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.sga.sgt.1.0+xml
Sample Response for Get All SGTs API Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xml
Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:searchResult total="2" xmlns:ns2="ers.ise.cisco.com">
<resources>
<resource name="name1" id="id1" description="description1">
<link type="application/xml" href="https://<ISE-ADMIN-NODE>:9060/ers/config/sgt/id1"
rel="self"/>
</resource>
</resources>
</ns2:searchResult>
}
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-51
Chapter 7
External RESTful Services API Operations
REST API Client
Get SGT by ID
The following table lists the main characteristics of the Get SGT by ID API call:
Table 7-55
Main Characteristics of Get SGTs API Call
Description
Retrieve the specified SGT
Synopsis
GET /ers/config/sgt/{id}
Request Headers
Accept, Authorization, Host
QueryString
N/A
Request Message Body
N/A
Response Headers
Content-Length, Content-Type
Response Message Body
Resource of type InternalUser
Response Status
200, 400, 401, 403, 404, 415, 429, 500
Sample Request for Get SGT by ID API Call
GET https://<ISE-ADMIN-NODE>:9060/ers/config/sgt/333
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/vnd.com.cisco.ise.sga.sgt.1.0+xml
Sample Response for Get SGT by ID API Call
HTTP/1.1 200 OK
Date: Thu, 12 Jul 2012 23:59:59 GMT
Content-Type: application/vnd.com.cisco.ise.sga.sgt.1.0+xml
Content-Length: 16347
{
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:sgt description="description" name="name" id="id" xmlns:ns2="ers.ise.cisco.com"
xmlns:ns3="sga.ers.ise.cisco.com">
<generationId>generationId</generationId>
<isTagFromRange>isTagFromRange</isTagFromRange>
<value>1</value>
</ns3:sgt>
}
REST API Client
The External RESTful Services APIs enable you to perform CRUD (Create, Read, Update, Delete)
operations on Cisco ISE resources. To build and test applications using the External RESTful Services
APIs that communicate with and perform operations on Cisco ISE servers, you can use any industry
standard REST API client, such as the POSTMAN plugin for Google Chrome.
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-52
OL-26134-01
Chapter 7
External RESTful Services API Operations
REST API Client
Designed according to REST architecture and principles, POSTMAN enables you to send and retrieve
standard HTTP and HTTPS requests and responses using the Google Chrome web browser. You can use
the following standard HTTP methods to perform CRUD operations on Cisco ISE resources:
•
GET
•
POST
•
PUT
•
DELETE
The ERS API enables you to use these HTTP requests in various API calls, which in turn enable you to
perform operations on the Cisco ISE servers. For a comprehensive list of operations in which these
HTTP requests are used, see <ERS API Operations>.
Note
To download the POSTMAN plugin, go to
https://chrome.google.com/webstore/detail/postman-rest-client/
fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en. For more information on using the POSTMAN plugin, go
to https://github.com/a85/POSTMan-Chrome-Extension/wiki.
GET Method
Requests a representation of the specified resource. Requests using GET only retrieve data and do have
any other effect.
Note
This section shows how to use the POSTMAN plugin to invoke an ERS API call. This API call uses the
GET HTTP method in addition to other components of the ERS API, which are not described in this
section. For more details on various ERS API components such as the characteristics, requests, and
responses, see External RESTful Services API Operations.
The request body of the ERS API call that uses the GET HTTPS method contains the following three
building blocks:
•
URI
•
Accept Header
•
Authorization Header
URI
The GET method sends the URI to the Cisco ISE server and the HTTP reply is the raw result data. A
typical URI must adhere to the following format:
•
https://<Cisco ISE Server address:<port>/<namespace>/config/<Cisco ISE Resouce Name>
Where <Cisco ISE Server Address> denotes the server address of the Cisco ISE server, <port>
denotes the port 9060, <namespace> denotes the namespace to which the ISE Resource belongs to,
and <Cisco ISE Resource Name> denotes the name of the Cisco ISE Resource.
The following example shows the URI that requests data for the interaluser ISE Resource:
•
https://10.56.13.196:9060/ers/config/internaluser.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-53
Chapter 7
External RESTful Services API Operations
REST API Client
Note
The URI is not the request body; it is just a URL. This URL is sent to the server using the GET method.
Accept Header
The Accept Header must adhere to the following format:
•
application/vnd.com.cisco.ise.<resource-namespace>.<resource-type>.<major version>.<minor
version>+xml
Where <resource-namespace> denotes the namespace to which the ISE Resource belongs to,
<resource-type> denotes the type of the ISE Resource, <major-version> denotes the major version
number of the ISE deployment, and <minor-version> denotes the minor version number of the ISE
deployment.
The following example shows a typical accept header:
•
application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
Authorization Header
The Authorization Header contains the encryption authorization key that is embedded into the GET
request. After specifying the authorization credentials, you must generate the encryption key, which is
then embedded into the request body.
Note
For more information on generating the encryption key, see Making the GET Request Using POSTMAN,
page 7-54.
Making the GET Request Using POSTMAN
Procedure
Step 1
Open the POSTMAN plugin in the Google Chrome browser.
Step 2
Create a new collection using the options in the left pane.
Note
For more information on using the POSTMAN plugin, go to
https://github.com/a85/POSTMan-Chrome-Extension/wiki.
Step 3
From the drop-down menu, choose GET.
Step 4
In the URL bar, enter the URI.
The URI specifies the Cisco ISE server with which you are trying to communicate and the ISE resource
that you are trying to access. For more information on the format of the URI, see URI, page 7-53.
Step 5
Click the Basic Auth tab.
The options that enable you to specify the user access credentials appear.
Step 6
Specify your access credentials in the Username and Password fields and click Refresh Headers.
POSTMAN displays an Authorization header with an encryption key.
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-54
OL-26134-01
Chapter 7
External RESTful Services API Operations
REST API Client
Step 7
Add an accept header by specifying the following value:
application/vnd.com.cisco.ise.ers.<namespace>.<ise resource>.1.0+xml
For more information on the Accept Header, see Accept Header, page 7-54.
Note
Step 8
Click Send.
The POSTMAN plugin displays a 200 OK status response indicating that the request is successful. The
request also returns the details of the resources that you have specified in the URL.
POST Method
Requests that the server accept the entity enclosed in the request as a new subordinate of the web
resource identified by the URI.
Note
This section shows how to use the POSTMAN plugin to invoke an ERS API call. This API call uses the
POST HTTP method in addition to other components of the ERS API, which are not described in this
section. For more details on various ERS API components such as the characteristics, requests, and
responses, see External RESTful Services API Operations.
The request body of the ERS API call that uses the POST HTTP method contains the following three
building blocks:
•
URI
•
Content-Type Header
•
Authorization Header
URI
The POST method sends the URI to the Cisco ISE server. A typical URI must adhere to the following
format:
•
https://<Cisco ISE Server address:<port>/<namespace>/config/<Cisco ISE Resouce Name>
Where <Cisco ISE Server Address> denotes the server address of the Cisco ISE server, <port>
denotes the port 9060, <namespace> denotes the namespace to which the ISE Resource belongs to,
and <Cisco ISE Resource Name> denotes the name of the Cisco ISE Resource.
The following example shows the URI that requests data for the interaluser ISE Resource:
•
Note
https://10.56.13.196:9060/ers/config/internaluser.
The URI is not the request body; it is just a URL. This URL is sent to the server using the POST method.
Content-Type Header
The Content-Type Header must adhere to the following format:
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-55
Chapter 7
External RESTful Services API Operations
REST API Client
•
application/vnd.com.cisco.ise.<resource-namespace>.<resource-type>.<major version>.<minor
version>+xml
Where <resource-namespace> denotes the namespace to which the ISE Resource belongs to,
<resource-type> denotes the type of the ISE Resource, <major-version> denotes the major version
number of the ISE deployment, and <minor-version> denotes the minor version number of the ISE
deployment.
The following example shows a typical accept header:
•
application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
Authorization Header
The Authorization Header contains the encryption authorization key that is embedded into the POST
request. After specifying the authorization credentials, you must generate the encryption key, which is
then embedded into the request body.
Note
For more information on generating the encryption key, see Making the POST Request Using
POSTMAN, page 7-56.
Making the POST Request Using POSTMAN
Procedure
Step 1
Open the POSTMAN plugin in the Google Chrome browser.
Step 2
Create a new collection using the options in the left pane.
Note
For more information on using the POSTMAN plugin, go to
https://github.com/a85/POSTMan-Chrome-Extension/wiki.
Step 3
From the drop-down menu, choose POST.
Step 4
In the URI bar, enter the URI.
The URI specifies the Cisco ISE server with which you are trying to communicate and the ISE resource
that you are trying to access. For more information on the format of the URI, see URI, page 7-55.
Step 5
Click the Basic Auth tab.
The options that enable you to specify the user access credentials appear.
Step 6
Specify your access credentials in the Username and Password fields and click Refresh Headers.
POSTMAN displays an Authorization header with an encryption key.
Step 7
Add a Content-Type header by specifying the following value:
application/vnd.com.cisco.ise.ers.<namespace>.<ise resource>.1.0+xml
Note
For more information on the Accept Header, see Content-Type Header, page 7-55.
Step 8
From the drop-down menu that appears next to the raw button, choose XML.
Step 9
Click raw.
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-56
OL-26134-01
Chapter 7
External RESTful Services API Operations
REST API Client
Step 10
The POSTMAN plugin opens an editing pane that enables you to specify the body of the POST request.
Step 11
Enter the message body of your POST request in the editing pane.
Note
Step 12
This message body must contain the details corresponding to the ISE resource that you trying to create
on the ISE server. For example, while creating an interaluser, you must specify details such as the name
of internaluser, description of the interaluser, password, and so on. For more details on the message body
of the ERS APIs that use the POST request and the details of the ISE resources that you need to specify,
see External RESTful Services API Operations.
Click Send.
The POSTMAN plugin displays a 201 CREATED status response indicating that the request is
successful. You can go to the ISE GUI to verify whether the ISE resource you have added appears in the
ISE GUI.
PUT Method
Requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already
existing resource, it is modified; if the URI does not point to an existing resource, then the server can
create the resource with that URI.
Note
This section shows how to use the POSTMAN plugin to invoke an ERS API call. This API call uses the
PUT HTTP method in addition to other components of the ERS API, which are not described in this
section. For more details on various ERS API components such as the characteristics, requests, and
responses, see External RESTful Services API Operations.
The request body of the ERS API call that uses the POST HTTP method contains the following three
building blocks:
•
URI
•
Content-Type Header
•
Authorization Header
URI
The PUT method sends the URI to the Cisco ISE server. A typical URI must adhere to the following
format:
•
https://<Cisco ISE Server address:<port>/<namespace>/config/<Cisco ISE Resouce Name>
Where <Cisco ISE Server Address> denotes the server address of the Cisco ISE server, <port>
denotes the port 9060, <namespace> denotes the namespace to which the ISE Resource belongs to,
and <Cisco ISE Resource Name> denotes the name of the Cisco ISE Resource.
The following example shows the URI that requests data for the interaluser ISE Resource:
•
https://10.56.13.196:9060/ers/config/internaluser.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-57
Chapter 7
External RESTful Services API Operations
REST API Client
Note
The URI is not the request body; it is just a URL. This URL is sent to the server using the PUT method.
Content-Type Header
The Content-Type Header must adhere to the following format:
•
application/vnd.com.cisco.ise.<resource-namespace>.<resource-type>.<major version>.<minor
version>+xml
Where <resource-namespace> denotes the namespace to which the ISE Resource belongs to,
<resource-type> denotes the type of the ISE Resource, <major-version> denotes the major version
number of the ISE deployment, and <minor-version> denotes the minor version number of the ISE
deployment.
The following example shows a typical accept header:
•
application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
Authorization Header
The Authorization Header contains the encryption authorization key that is embedded into the PUT
request. After specifying the authorization credentials, you must generate the encryption key, which is
then embedded into the request body.
Note
For more information on generating the encryption key, see Making the PUT Request Using POSTMAN,
page 7-58.
Making the PUT Request Using POSTMAN
Procedure
Step 1
Open the POSTMAN plugin in the Google Chrome browser.
Step 2
Create a new collection using the options in the left pane.
Note
For more information on using the POSTMAN plugin, go to
https://github.com/a85/POSTMan-Chrome-Extension/wiki.
Step 3
From the drop-down menu, choose PUT.
Step 4
In the URI bar, enter the URI.
The URI specifies the Cisco ISE server with which you are trying to communicate and the ISE resource
that you are trying to access. For more information on the format of the URI, see URI, page 7-57.
Step 5
Click the Basic Auth tab.
The options that enable you to specify the user access credentials appear.
Step 6
Specify your access credentials in the Username and Password fields and click Refresh Headers.
POSTMAN displays an Authorization header with an encryption key.
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-58
OL-26134-01
Chapter 7
External RESTful Services API Operations
REST API Client
Step 7
Add a Content-Type header by specifying the following value:
application/vnd.com.cisco.ise.ers.<namespace>.<ise resource>.1.0+xml
Note
For more information on the Accept Header, see Content-Type Header, page 7-58.
Step 8
From the drop-down menu that appears next to the raw button, choose XML.
Step 9
Click raw.
Step 10
The POSTMAN plugin opens an editing pane that enables you to specify the body of the POST request.
Step 11
Enter the message body of your POST request in the editing pane.
Note
Step 12
This message body must contain the details corresponding to the ISE resource that you trying to update
on the ISE server. For example, while updating an interaluser, you must specify details such as the name
of internaluser, description of the interaluser, password, and so on. For more details on the message body
of the ERS APIs that use the POST request and the details of the ISE resources that you need to specify,
see External RESTful Services API Operations.
Click Send.
The POSTMAN plugin displays a 201 CREATED status response indicating that the request is
successful. You can go to the ISE GUI to verify whether the ISE resource you have added appears in the
ISE GUI.
Delete Method
Deletes the specified resource.
Note
This section shows how to use the POSTMAN plugin to invoke an ERS API call. This API call uses the
DELETE HTTP method in addition to other components of the ERS API, which are not described in this
section. For more details on various ERS API components such as the characteristics, requests, and
responses, see External RESTful Services API Operations.
The request body of the ERS API call that uses the DELETE HTTP method contains the following three
building blocks:
•
URI
•
Accept Header
•
Authorization Header
URI
The DELETE method sends the URI to the Cisco ISE server. A typical URI must adhere to the following
format:
•
https://<Cisco ISE Server address:<port>/<namespace>/config/<Cisco ISE Resouce Name>
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-59
Chapter 7
External RESTful Services API Operations
REST API Client
Where <Cisco ISE Server Address> denotes the server address of the Cisco ISE server, <port>
denotes the port 9060, <namespace> denotes the namespace to which the ISE Resource belongs to,
and <Cisco ISE Resource Name> denotes the name of the Cisco ISE Resource.
The following example shows the URI that requests data for the interaluser ISE Resource:
•
Note
https://10.56.13.196:9060/ers/config/internaluser.
The URI is not the request body; it is just a URL. This URL is sent to the server using the GET method.
Accept Header
The Accept Header must adhere to the following format:
•
application/vnd.com.cisco.ise.<resource-namespace>.<resource-type>.<major version>.<minor
version>+xml
Where <resource-namespace> denotes the namespace to which the ISE Resource belongs to,
<resource-type> denotes the type of the ISE Resource, <major-version> denotes the major version
number of the ISE deployment, and <minor-version> denotes the minor version number of the ISE
deployment.
The following example shows a typical accept header:
•
application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
Authorization Header
The Authorization Header contains the encryption authorization key that is embedded into the DELETE
request. After specifying the authorization credentials, you must generate the encryption key, which is
then embedded into the request body.
Note
For more information on generating the encryption key, see Making the DELETE Request Using
POSTMAN, page 7-60.
Making the DELETE Request Using POSTMAN
Procedure
Step 1
Open the POSTMAN plugin in the Google Chrome browser.
Step 2
Create a new collection using the options in the left pane.
Note
For more information on using the POSTMAN plugin, go to
https://github.com/a85/POSTMan-Chrome-Extension/wiki.
Step 3
From the drop-down menu, choose DELETE.
Step 4
In the URL bar, enter the URI.
The URI specifies the Cisco ISE server with which you are trying to communicate and the ISE resource
that you are trying to access. For more information on the format of the URI, see URI, page 7-59.
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-60
OL-26134-01
Chapter 7
External RESTful Services API Operations
REST API Client
Step 5
Click the Basic Auth tab.
The options that enable you to specify the user access credentials appear.
Step 6
Specify your access credentials in the Username and Password fields and click Refresh Headers.
POSTMAN displays an Authorization header with an encryption key.
Step 7
Add an accept header by specifying the following value:
application/vnd.com.cisco.ise.ers.<namespace>.<ise resource>.1.0+xml
Note
Step 8
For more information on the Accept Header, see Accept Header, page 7-60.
Click Send.
The POSTMAN plugin displays a 200 OK status response indicating that the request is successful. The
ISE resource that you have specified is deleted from the ISE server.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
7-61
Chapter 7
External RESTful Services API Operations
REST API Client
Cisco Identity Services Engine API Reference Guide, Release 1.2
7-62
OL-26134-01
A P P E N D I X
A
Cisco ISE Failure Reasons Report
This appendix provides a procedure you can use to access the Cisco ISE Failure Reasons report. The
Cisco ISE Failure Reason report allows you to view the list of failure reasons.
Introduction
The Cisco ISE Failure Reason report is an option in the Cisco ISE user interface that provides
information about all of the failure reasons that could be encountered. You can use this to check on those
that are returned as output from a Get Failure Reason Mapping call when using the Cisco ISE Query
troubleshooting API.
The Cisco ISE Failure Reasons report lets you access the complete list of failure reasons defined by the
Cisco ISE software that apply to Cisco Monitoring ISE node operations. The following procedure lets
you view or edit the list of defined failure reasons. You must log into the Cisco ISE user interface of the
target Cisco Monitoring ISE node to view and access the failure reasons. For details about logging in,
see Verifying a Monitoring Node, page 1-2.
Viewing Failure Reasons
Step 1
Choose Operations > Reports > Authnetication Summary report.
Step 2
In the navigation panel, expand Monitoring and select Failure Reason Editor.
Step 3
Choose Failure Reasons from the list of filters provided.
Step 4
Provide the failure reason that you are looking for.
Step 5
Click Run.
A list of failure reasons appears in the right panel.
Step 6
Click on any failure reason to get a detailed report in a new window.
Cisco Identity Services Engine API Reference Guide, Release 1.2
OL-26134-01
A-1
Appendix A
Cisco ISE Failure Reasons Report
Viewing Failure Reasons
Cisco Identity Services Engine API Reference Guide, Release 1.2
A-2
OL-26134-01