Cisco Identity Services Engine API Reference Guide, Release 1 · United States and certain other...

Cisco Identity Services Engine API Reference Guide, Release 1.4January 18, 2017

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

http://www.cisco.com

http://www.cisco.com/go/offices

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.4© 2015 Cisco Systems, Inc. All rights reserved.

OL-26134-01

C O N T E N T S

Preface vii

Overview of Cisco Identity Services Engine vii

Purpose viii

Audience viii

Document Organization ix

Document Conventions ix

Documentation Updates x

Product Documentation 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 1-1

Verifying a Monitoring Node 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

iiiCisco Identity Services Engine API Reference Guide, Release 1.4

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

Audit Session ID Search 2-23

Audit Session ID API Output Schema 2-23

Invoking the Audit Session ID API Call 2-25

Sample Data Returned from the Audit Session ID API Call 2-25

Stale Sessions 2-26

Removing Stale Sessions 2-26

Query APIs for Troubleshooting 3-1

Cisco Prime NCS API Calls 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

ivCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Contents

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

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 3-10

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 3-13

Change of Authorization REST APIs 4-1

Introduction 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 5-1

Overview 5-1

Supported Cisco ISE Resources 5-1

External RESTful Services API Authentication and Authorization 5-2

Enabling External RESTful Services APIs from the GUI 5-2

External RESTful Services API Status 5-3

Data Validation 5-3

Namespaces 5-3

External RESTful Services SDK 5-4

External RESTful Services Schema File 5-4

Downloading the Schema File 5-5

External RESTful Service Requests and Responses 5-5

vCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Contents

External RESTful Service Requests Headers 5-5

External RESTful Service Response Headers 5-6

Common External RESTful Service HTTP Status Codes 5-6

Version Control with External RESTful Services APIs 5-7

Searching and Filtering 5-8

Filtering Parameters for External RESTful Services APIs 5-8

Paging Parameters for External RESTful Services APIs 5-9

External RESTful Services System Flow 5-9

Hyperlinks 5-11

Example of links within a search result 5-12

Bulk Operations 5-12

Guest REST API 6-1

An API for Guest User Resources 6-1

Sponsor Authentication and Authorization 6-1

Guest REST API Requests 6-3

Request Structure 6-3

Request Contents 6-4

Bulk Executions 6-5

Guest REST API Responses 6-5

Response Status Codes 6-6

Response Structure 6-6

Guest Passwords 6-6

Response Error Messages 6-7

Unsupported Media Type Example 6-8

Versioning 6-8

Searching and Filtering 6-9

Filtering Parameters 6-9

Filtering Examples 6-10

Page Size Parameters 6-11

Sorting Parameters 6-11

Example: GET First 20 Guest User Records and Sort ascending by the Last Name 6-11

External RESTful Services API Operations 7-1

Overview 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

viCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Contents

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

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

viiCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Contents

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 Services APIs for Endpoint Certificates 7-16

Create Endpoint Certificate 7-17

Sample Request for Create Endpoint Certificate API Call 7-17

Sample Response for Create Endpoint Certificate API Call 7-17

External RESTful Services APIs for Endpoint Identity Groups 7-17

Get All Endpoint Identity Groups 7-18

Sample Request for Get All Endpoint Identity Groups API Call 7-18

Sample Response for Get All Endpoint Identity Groups API Call 7-18

Get Endpoint Identity Groups by ID 7-19

Sample Request for Read Endpoint Identity Groups API Call 7-19

Sample Response for Read Endpoint Identity Groups API Call 7-19

Create Endpoint Identity Groups 7-20

Sample Request for Create Endpoint Identity Groups API Call 7-20

Sample Response for Create Endpoint Identity Groups API Call 7-20

Update Endpoint Identity Groups 7-20

Sample Request for Update Endpoint Identity Groups API Call 7-21

Sample Response for Update Endpoint Identity Groups API Call 7-21

Delete Endpoint Identity Groups 7-21

Sample Request for Delete Endpoint Identity Groups API Call 7-22

Sample Response for Delete Endpoint Identity Groups API Call 7-22

External RESTful Services APIs for Identity Groups 7-22

Retrieve All Identity Groups 7-22

Sample Request for Retrieve All Identity Group API Call 7-22

Sample Response for Retrieve All Identity Group API Call 7-23

Get Identity Groups by ID 7-23

Sample Request for Get Identity Group by ID API Call 7-23

Sample Response for Get Identity Group by ID API Call 7-23

External RESTful Services APIs for Guest Users 7-24

Content Type and Accept Headers 7-24

Get a Guest User 7-25

Get a Guest User Examples 7-25

Get a Guest User by ID Example 7-25

Filter by Usernames that Start with “ilucky” Example 7-26

Filter by Username that Starts with “ilucky” and Last Name that Starts with “J” Example 7-27

Filter By the First Name “John” and Sort By Username Example 7-28

Guest User Request and Response Using curl Example 7-28

viiiCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Contents

Get All Guest Users 7-29

Get All Example 7-30

Create a Guest User 7-31

Guest User XML Structure 7-31

Create a Guest User Example 7-32

Update a Guest User 7-33

Update User Example 7-33

Delete a Guest User 7-33

Delete a Guest User Example 7-34

Suspend a Guest User 7-34

Suspend a Guest User by ID Example 7-34

Reinstate a Guest User 7-35

Reinstate Guest User Example 7-35

Send an Email to a Guest User 7-35

Send an Email to a Guest User Example 7-36

Send an SMS Text to a Guest User 7-36

Send an SMS Example 7-37

Approve a Guest User 7-37

Approve a Guest User Example 7-37

Deny Approval for a Guest User Account 7-38

Deny a Guest User’s Approval Example 7-38

Reset Password for a Guest User Account 7-38

Reset a Guest User’s Password Example 7-39

Start Bulk Execution for Guest Users 7-39

Create Guest Bulk Example 7-39

Get Bulk Status for Guest Users 7-41

Get Bulk Status for Guest Users Example 7-41

Change a Sponsor’s Password 7-42

Change a Sponsor’s Password Example 7-42

External RESTful Services APIs for Portals 7-42

Get All Portals 7-43

Sample Request for Get All Portals Call 7-43

Sample Response for Get All Portals Call 7-43

Get Portal by ID 7-44

Sample Request for Get Portal by ID Call 7-44

Sample Response for Get Portal by ID Call 7-44

External RESTful Services APIs for Profiles 7-45

Get All Profiles 7-46

Sample Request for Get All Profiles Call 7-46

Sample Response for Get All Profiles Call 7-46

ixCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Contents

Get Portal by ID 7-47

Sample Request for Get Portal by ID Call 7-47

Sample Response for Get Portal by ID Call 7-47

External RESTful Services APIs for Network Devices 7-47

Get All Network Devices 7-48

Sample Request for Get All Network Devices Call 7-48

Sample Response for Get All Network Devices Call 7-48

Get Network Device by ID 7-49

Sample Request for Get Network Device by ID Call 7-49

Sample Response for Get Network Device by ID Call 7-49

Create Network Device 7-50

Sample Request for Create Network Device Call 7-50

Sample Response for Create Network Device Call 7-50

Update Network Device 7-51

Sample Request for Update Network Device Call 7-51

Sample Response for Update Network Device Call 7-51

Delete Network Device 7-52

Sample Request for Update Network Device Call 7-52

Sample Response for Update Network Device Call 7-52

External RESTful Services APIs for Network Device Groups 7-52

Get All Network Device Groups 7-53

Sample Request for Get All Network Device Groups API Call 7-53

Sample Response for Get All Network Device Groups API Call 7-53

Get Network Device Group 7-54

Sample Request for Get Network Device Group API Call 7-54

Sample Response for Get Network Device Group API Call 7-54

External RESTful Services APIs for SGTs 7-54

Get All SGTs 7-55

Sample Request for Get All SGTs API Call 7-55

Sample Response for Get All SGTs API Call 7-55

Get SGT by ID 7-56

Sample Request for Get SGT by ID API Call 7-56

Sample Response for Get SGT by ID API Call 7-56

REST API Client 7-56

GET Method 7-57

URI 7-57

Accept Header 7-58

Authorization Header 7-58

Making the GET Request Using POSTMAN 7-58

xCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Contents

POST Method 7-59

URI 7-59

Content-Type Header 7-59


Making the POST Request Using POSTMAN 7-60

PUT Method 7-61

URI 7-61

Content-Type Header 7-62


Making the PUT Request Using POSTMAN 7-62

Delete Method 7-63

URI 7-63

Accept Header 7-64


Making the DELETE Request Using POSTMAN 7-64

Cisco ISE Failure Reasons Report A-1

Introduction A-1

Viewing Failure Reasons A-1

xiCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Contents

xiiCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Preface

Revised: 1/18/17, OL-26134-01

This preface explains the objectives, intended audience, and organization of the Cisco Identity Services Engine API Reference Guide, Release 1.4. 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 EngineCisco 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

viiCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

http://www.cisco.com/en/US/products/ps11640/products_user_guide_list.html

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

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

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

viiiCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Document OrganizationThis 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 ConventionsThis section outlines the conventions used throughout this document.

Caution Means reader be careful. You are capable of doing something that might result in equipment damage or loss of data.

Note 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 important terminology

italic font

Displayed session and system information, paths, and file names

screen font

Information you enter boldface screen font

Variables you enter italic screen font

Menu items and button names boldface font

Indicates menu items to choose, in the order in which you choose them.

Option > Network Preferences

ixCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Documentation UpdatesTable 1 lists the updates made to this document since its inception, with the most recent update featured first in the list.

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 DocumentationThis section provides information on release-specific documentation, as well as platform-specific documentation.

Release-Specific DocumentationTable 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 1 Updates for Cisco Identity Services Engine API Reference Guide, Release 1.4

Date Description

8-25-2014 Cisco Identity Services Engine (ISE) Release 1.3

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/prod_release_notes_list.html

Cisco Identity Services Engine Network Component Compatibility, Release 1.3

http://www.cisco.com/en/US/products/ps11640/products_device_support_tables_list.html

Cisco Identity Services Engine Admin Guide, Release 1.3


Cisco Identity Services Engine Hardware Installation Guide, Release 1.3

http://www.cisco.com/en/US/products/ps11640/prod_installation_guides_list.html

xCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

http://www.cisco.com/en/US/products/ps11640/prod_release_notes_list.html

http://www.cisco.com/en/US/products/ps11640/products_device_support_tables_list.html



http://cisco.com


http://www.cisco.com/go/techdocs

http://www.cisco.com/go/ise

http://www.cisco.com/en/US/products/ps11640/tsd_products_support_series_home.html

Platform-Specific DocumentationLinks to Policy Management Business Unit documentation are available on http://www.cisco.com at the following locations:

• Cisco ISEhttp://www.cisco.com/en/US/products/ps11640/prod_installation_guides_list.html

• Cisco Secure ACShttp://www.cisco.com/en/US/products/ps9911/tsd_products_support_series_home.html

• Cisco NAC Appliancehttp://www.cisco.com/en/US/products/ps6128/tsd_products_support_series_home.html

• Cisco NAC Profilerhttp://www.cisco.com/en/US/products/ps8464/tsd_products_support_series_home.html

• Cisco NAC Guest Serverhttp://www.cisco.com/en/US/products/ps10160/tsd_products_support_series_home.html

Obtaining Documentation and Submitting a Service RequestFor 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 Migration Guide for Cisco Secure ACS 5.5 to Release 1.3


Cisco Identity Services Engine Sponsor Portal User Guide, Release 1.3


Cisco Identity Services Engine CLI Reference Guide, Release 1.3

http://www.cisco.com/en/US/products/ps11640/prod_command_reference_list.html

Cisco Identity Services Engine API Reference Guide, Release 1.3


Cisco Identity Services Engine Troubleshooting Guide, Release 1.3

http://www.cisco.com/en/US/products/ps11640/prod_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


Cisco Identity Services Engine In-Box Documentation and China RoHS Pointer Card

http://www.cisco.com/en/US/products/ps11640/products_documentation_roadmaps_list.html

Table 2 Product Documentation for Cisco Identity Services Engine (continued)

Document Title Location

xiCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01





http://www.cisco.com/en/US/products/ps11640/prod_troubleshooting_guides_list.html


http://www.cisco.com/en/US/products/ps11640/products_documentation_roadmaps_list.html







http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html

xiiCisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

P A R T 1

Cisco ISE Monitoring REST APIs

Cisco IdentityOL-26134-01

C H 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.4:

• Session Management

• Troubleshooting

• Change of Authorization (CoA)

Note 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.4, 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.4.

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

1-1 Services Engine API Reference Guide, Release 1.4

Chapter 1 Introduction to the Monitoring REST API Verifying a Monitoring Node

Figure 1-1 Monitoring REST API Calls in a Distributed Deployment

Verifying a Monitoring NodeBefore 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 CallsThe 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.

Adminstrationpersona

Policy servicepersona

Monitoringpersona

Webserver

Browser-basedclient

Remote javaclient

PHP-basedclient

Cisco ISE Deployment

REST(HTTPS)APIs

3101

31

1-2Cisco Identity Services Engine API Reference Guide, Release 1.4

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

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


OL-26134-01


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

Note In this release of Cisco ISE, the maximum number of active authenticated endpoint sessions that can be displayed is limited to 250,000.

AuthList Lists all currently active authenticated sessions.

https://<ISEhost>/admin/API/mnt/Session/AuthList/<parameteroptions>

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.

Table 1-1 Cisco ISE Session Management API Calls (continued)



OL-26134-01


For specific details about Cisco ISE API calls for session management, see Chapter 2, “Session Management Query APIs”.

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/<macaddress>

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.

UserName Searches the database for the latest session that contains the specified username.

https://<ISEhost>/admin/API/mnt/Session/UserName/<username>

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

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

Audit Session ID Searches the database for the latest session that contains the specified audit session ID.

https://<ISEhost>/admin/API/mnt/Session/Active/SessionID/<audit-session-id>/0

Note Use the ActiveList API call to list all active sessions and their audit session IDs, from which you can base your audit session ID search. Alternatively, you can obtain the audit session ID from the Live Sessions page in the Admin portal.

Table 1-1 Cisco ISE Session Management API Calls (continued)



OL-26134-01




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


OL-26134-01



For specific details about Cisco ISE API calls for troubleshooting, see Chapter 2, “Session Management Query APIs”.

AuthStatus Lists the authentication status for all sessions.

https://<ISEhost>/admin/API/mnt/AuthStatus/MACAddress/<macaddress>/<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/AcctStatusTT/MACAddress/<macaddress>/<numberof seconds>

Note The seconds parameter <numberofseconds> is user-configurable, with the range is from 0 to 432000 seconds (5 days).

Table 1-2 Cisco ISE Troubleshooting API Calls - Troubleshooting (continued)


Table 1-3 Cisco ISE Change of Authorization API Calls


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 starting from NAS IP address as null. If the NAS IP address is provided then it's necessary to also provide the Destination IP address.

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.


OL-26134-01


For details about Cisco ISE Change of Authorization API calls, see Chapter 4, “Change of Authorization REST APIs”.

HTTP PUT API CallsSimilar 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>

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.

Table 1-3 Cisco ISE Change of Authorization API Calls (continued)



OL-26134-01


</xs:schema>


OL-26134-01



OL-26134-01


C H 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 CallsThe 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 CounterYou 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:


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


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

Step 5 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 CounterYou 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:



OL-26134-01


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


Related Topics


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 CounterYou can use the ProfilerCount API call to retrieve a count of all currently active Profiler sessions.


OL-26134-01


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:


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


Related Topics


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>


OL-26134-01

Chapter 2 Session Management Query APIs Simple Session List API Calls

<count>1</count></sessionCount>

Simple Session List API CallsThe 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 ListYou 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:


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


OL-26134-01


Invoking the ActiveList API Call






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


Related Topics


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>


OL-26134-01


-<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 ListYou 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:


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


OL-26134-01


Invoking the AuthList API Call





https://acme123/admin/LoginAction.do#pageId=com_cisco_xmp_web_page_tmpdashStep 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



Related Topics


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>


OL-26134-01


</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:


OL-26134-01


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>


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

• Endpoint IP address session search (EndPointIPAddress)

• Audit session ID search (Audit Session ID)

MAC Address Session SearchYou 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:


<xs:element name="sessionParameters" type="restsdStatus"/>

<xs:complexType name="restsdStatus"> <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="authen_protocol" 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="auth_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"/>


OL-26134-01


<xs:element name="auth_id" type="xs:long" minOccurs="0"/> <xs:element name="auth_acsview_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="message_code" type="xs:string" 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="service_type" 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"/> <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="selected_azn_profiles" 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="eap_tunnel" 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:element name="destination_ip_address" type="xs:string" minOccurs="0"/> <xs:element name="acct_id" type="xs:long" minOccurs="0"/> <xs:element name="acct_acs_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="acct_acsview_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="acct_session_id" type="xs:string" minOccurs="0"/> <xs:element name="acct_status_type" type="xs:string" minOccurs="0"/> <xs:element name="acct_session_time" type="xs:long" minOccurs="0"/> <xs:element name="acct_input_octets" type="xs:string" minOccurs="0"/> <xs:element name="acct_output_octets" type="xs:string" minOccurs="0"/> <xs:element name="acct_input_packets" type="xs:long" minOccurs="0"/> <xs:element name="acct_output_packets" type="xs:long" minOccurs="0"/> <xs:element name="acct_class" type="xs:string" minOccurs="0"/> <xs:element name="acct_terminate_cause" type="xs:string" minOccurs="0"/> <xs:element name="acct_multi_session_id" type="xs:string" minOccurs="0"/> <xs:element name="acct_authentic" type="xs:string" minOccurs="0"/> <xs:element name="termination_action" type="xs:string" minOccurs="0"/> <xs:element name="session_timeout" type="xs:string" minOccurs="0"/> <xs:element name="idle_timeout" type="xs:string" minOccurs="0"/> <xs:element name="acct_interim_interval" type="xs:string" minOccurs="0"/> <xs:element name="acct_delay_time" type="xs:string" minOccurs="0"/> <xs:element name="event_timestamp" type="xs:string" minOccurs="0"/> <xs:element name="acct_tunnel_connection" type="xs:string" minOccurs="0"/> <xs:element name="acct_tunnel_packet_lost" type="xs:string" minOccurs="0"/> <xs:element name="security_group" type="xs:string" minOccurs="0"/> <xs:element name="cisco_h323_setup_time" type="xs:dateTime" minOccurs="0"/> <xs:element name="cisco_h323_connect_time" type="xs:dateTime" minOccurs="0"/>


OL-26134-01


<xs:element name="cisco_h323_disconnect_time" type="xs:dateTime" minOccurs="0"/> <xs:element name="framed_protocol" type="xs:string" minOccurs="0"/> <xs:element name="started" type="xs:anyType" minOccurs="0"/> <xs:element name="stopped" type="xs:anyType" minOccurs="0"/> <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 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

Note Make sure that you specify the MAC address using the XX:XX:XX:XX:XX:XX format.



Related Topics


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:


OL-26134-01



-<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?sessionId=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=Radius,Framed-MTU=1500,EAP-Key-Name=,CPMSessionID=0ACB6BA1000000351BBFBF8B,CPMSessionID=0ACB6BA1000000351BBFBF8B,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


OL-26134-01


</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><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 SearchYou 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:



<xs:complexType name="restsdStatus"> <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="authen_protocol" 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="auth_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"/>


OL-26134-01


<xs:element name="auth_id" type="xs:long" minOccurs="0"/> <xs:element name="auth_acsview_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="message_code" type="xs:string" 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="service_type" 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"/> <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="selected_azn_profiles" 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="eap_tunnel" 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:element name="destination_ip_address" type="xs:string" minOccurs="0"/> <xs:element name="acct_id" type="xs:long" minOccurs="0"/> <xs:element name="acct_acs_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="acct_acsview_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="acct_session_id" type="xs:string" minOccurs="0"/> <xs:element name="acct_status_type" type="xs:string" minOccurs="0"/> <xs:element name="acct_session_time" type="xs:long" minOccurs="0"/> <xs:element name="acct_input_octets" type="xs:string" minOccurs="0"/> <xs:element name="acct_output_octets" type="xs:string" minOccurs="0"/> <xs:element name="acct_input_packets" type="xs:long" minOccurs="0"/> <xs:element name="acct_output_packets" type="xs:long" minOccurs="0"/> <xs:element name="acct_class" type="xs:string" minOccurs="0"/> <xs:element name="acct_terminate_cause" type="xs:string" minOccurs="0"/> <xs:element name="acct_multi_session_id" type="xs:string" minOccurs="0"/> <xs:element name="acct_authentic" type="xs:string" minOccurs="0"/> <xs:element name="termination_action" type="xs:string" minOccurs="0"/> <xs:element name="session_timeout" type="xs:string" minOccurs="0"/> <xs:element name="idle_timeout" type="xs:string" minOccurs="0"/> <xs:element name="acct_interim_interval" type="xs:string" minOccurs="0"/> <xs:element name="acct_delay_time" type="xs:string" minOccurs="0"/> <xs:element name="event_timestamp" type="xs:string" minOccurs="0"/> <xs:element name="acct_tunnel_connection" type="xs:string" minOccurs="0"/> <xs:element name="acct_tunnel_packet_lost" type="xs:string" minOccurs="0"/> <xs:element name="security_group" type="xs:string" minOccurs="0"/> <xs:element name="cisco_h323_setup_time" type="xs:dateTime" minOccurs="0"/> <xs:element name="cisco_h323_connect_time" type="xs:dateTime" minOccurs="0"/>


OL-26134-01


<xs:element name="cisco_h323_disconnect_time" type="xs:dateTime" minOccurs="0"/> <xs:element name="framed_protocol" type="xs:string" minOccurs="0"/> <xs:element name="started" type="xs:anyType" minOccurs="0"/> <xs:element name="stopped" type="xs:anyType" minOccurs="0"/> <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 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



Related Topics


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>


OL-26134-01


<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><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?sessionId=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=Radius,Framed-MTU=1500,EAP-Key-Name=,CPMSessionID=0ACB6BA1000000351BBFBF8B,CPMSessionID=0ACB6BA1000000351BBFBF8B,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>


OL-26134-01


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

NAS IP Address Session SearchYou 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:



<xs:complexType name="restsdStatus"> <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="authen_protocol" 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="auth_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="auth_id" type="xs:long" minOccurs="0"/> <xs:element name="auth_acsview_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="message_code" type="xs:string" minOccurs="0"/> <xs:element name="acs_session_id" type="xs:string" minOccurs="0"/> <xs:element name="service_selection_policy" type="xs:string" minOccurs="0"/>


OL-26134-01


<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="service_type" 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"/> <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="selected_azn_profiles" 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="eap_tunnel" 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:element name="destination_ip_address" type="xs:string" minOccurs="0"/> <xs:element name="acct_id" type="xs:long" minOccurs="0"/> <xs:element name="acct_acs_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="acct_acsview_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="acct_session_id" type="xs:string" minOccurs="0"/> <xs:element name="acct_status_type" type="xs:string" minOccurs="0"/> <xs:element name="acct_session_time" type="xs:long" minOccurs="0"/> <xs:element name="acct_input_octets" type="xs:string" minOccurs="0"/> <xs:element name="acct_output_octets" type="xs:string" minOccurs="0"/> <xs:element name="acct_input_packets" type="xs:long" minOccurs="0"/> <xs:element name="acct_output_packets" type="xs:long" minOccurs="0"/> <xs:element name="acct_class" type="xs:string" minOccurs="0"/> <xs:element name="acct_terminate_cause" type="xs:string" minOccurs="0"/> <xs:element name="acct_multi_session_id" type="xs:string" minOccurs="0"/> <xs:element name="acct_authentic" type="xs:string" minOccurs="0"/> <xs:element name="termination_action" type="xs:string" minOccurs="0"/> <xs:element name="session_timeout" type="xs:string" minOccurs="0"/> <xs:element name="idle_timeout" type="xs:string" minOccurs="0"/> <xs:element name="acct_interim_interval" type="xs:string" minOccurs="0"/> <xs:element name="acct_delay_time" type="xs:string" minOccurs="0"/> <xs:element name="event_timestamp" type="xs:string" minOccurs="0"/> <xs:element name="acct_tunnel_connection" type="xs:string" minOccurs="0"/> <xs:element name="acct_tunnel_packet_lost" type="xs:string" minOccurs="0"/> <xs:element name="security_group" type="xs:string" minOccurs="0"/> <xs:element name="cisco_h323_setup_time" type="xs:dateTime" minOccurs="0"/> <xs:element name="cisco_h323_connect_time" type="xs:dateTime" minOccurs="0"/> <xs:element name="cisco_h323_disconnect_time" type="xs:dateTime" minOccurs="0"/> <xs:element name="framed_protocol" type="xs:string" minOccurs="0"/> <xs:element name="started" type="xs:anyType" minOccurs="0"/> <xs:element name="stopped" type="xs:anyType" minOccurs="0"/> <xs:element name="ckpt_id" type="xs:long" minOccurs="0"/>


OL-26134-01


<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 NAS IPAddress API Call






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

Note Make sure that you specify the NAS IP address using the xxx.xxx.xxx.xxx format.



Related Topics



OL-26134-01


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><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=Radius,Framed-Protocol=PPP,Proxy-State=Cisco Secure ACS9e733142-070a-11e0-c000-000000000000-2906094480-3222,CPMSessionID=0acb6be4000000044D091


OL-26134-01


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><framed_protocol>PPP</framed_protocol><started xsi:type="xs:boolean">true</started><stopped xsi:type="xs:boolean">false</stopped></sessionParameters>

Endpoint IP Address Session SearchYou can use the EndPointIPAddress API call to retrieve session directory information from a current, active session. This section provides a schema file output example, a procedure for searching the node database for the latest active session that contains the specified IP address by invoking the EndPointIPAddress API call, and a sample of the endpoint-related data returned after this API call is issued. This API call lists a variety of session directory information drawn from node database tables.

EndPointIPAddress API Output Schema

This sample schema file is the output of the EndPointIPAddress API call for retrieving session directory information about a specified endpoint from the current active 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="sessionParameters" type="restsdStatus"/><xs:complexType name="restsdStatus"><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="authen_protocol" 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="auth_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"/>


OL-26134-01


<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="auth_id" type="xs:long" minOccurs="0"/><xs:element name="auth_acsview_timestamp" type="xs:dateTime" minOccurs="0"/><xs:element name="message_code" type="xs:string" 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="service_type" 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"/><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="selected_azn_profiles" 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="eap_tunnel" 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:element name="destination_ip_address" type="xs:string" minOccurs="0"/><xs:element name="acct_id" type="xs:long" minOccurs="0"/><xs:element name="acct_acs_timestamp" type="xs:dateTime" minOccurs="0"/><xs:element name="acct_acsview_timestamp" type="xs:dateTime" minOccurs="0"/><xs:element name="acct_session_id" type="xs:string" minOccurs="0"/><xs:element name="acct_status_type" type="xs:string" minOccurs="0"/><xs:element name="acct_session_time" type="xs:long" minOccurs="0"/><xs:element name="acct_input_octets" type="xs:string" minOccurs="0"/><xs:element name="acct_output_octets" type="xs:string" minOccurs="0"/><xs:element name="acct_input_packets" type="xs:long" minOccurs="0"/><xs:element name="acct_output_packets" type="xs:long" minOccurs="0"/><xs:element name="acct_class" type="xs:string" minOccurs="0"/><xs:element name="acct_terminate_cause" type="xs:string" minOccurs="0"/><xs:element name="acct_multi_session_id" type="xs:string" minOccurs="0"/><xs:element name="acct_authentic" type="xs:string" minOccurs="0"/><xs:element name="termination_action" type="xs:string" minOccurs="0"/><xs:element name="session_timeout" type="xs:string" minOccurs="0"/><xs:element name="idle_timeout" type="xs:string" minOccurs="0"/><xs:element name="acct_interim_interval" type="xs:string" minOccurs="0"/><xs:element name="acct_delay_time" type="xs:string" minOccurs="0"/><xs:element name="event_timestamp" type="xs:string" minOccurs="0"/><xs:element name="acct_tunnel_connection" type="xs:string" minOccurs="0"/><xs:element name="acct_tunnel_packet_lost" type="xs:string" minOccurs="0"/>


OL-26134-01


<xs:element name="security_group" type="xs:string" minOccurs="0"/><xs:element name="cisco_h323_setup_time" type="xs:dateTime" minOccurs="0"/><xs:element name="cisco_h323_connect_time" type="xs:dateTime" minOccurs="0"/><xs:element name="cisco_h323_disconnect_time" type="xs:dateTime" minOccurs="0"/><xs:element name="framed_protocol" type="xs:string" minOccurs="0"/><xs:element name="started" type="xs:anyType" minOccurs="0"/><xs:element name="stopped" type="xs:anyType" minOccurs="0"/><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 EndPointIPAddress API Call

Note Ensure that you have verified that the target node to which you are issuing an API call is a valid Cisco Monitoring ISE node.

To issue the EndPointIPAddress API call, complete the following steps:

Step 1 Log into the target Cisco Monitoring ISE node.



Step 2 Enter the EndPointIPAddress API call in the URL Address field of the target node by replacing the “/admin/” component with the API call component (/ise/mnt/api/Session/EndPointIPAddress/<endpoint_ip>):

https://acme123/ise/mnt/api/Session/EndPointIPAddress/A.B.C.D



Sample Data Returned from the EndPointIPAddress API Call

The following example illustrates the session-related data returned from the list of active sessions when you invoke an EndPointIPAddress API call on a target Cisco Monitoring ISE node:



OL-26134-01


-<sessionParameters><passed xsi:type="xs:boolean">true</passed><failed xsi:type="xs:boolean">false</failed><user_name>00:0C:29:95:A5:C1</user_name><nas_ip_address>10.77.152.139</nas_ip_address><calling_station_id>00:0C:29:95:A5:C1</calling_station_id><nas_port>50109</nas_port><identity_group>RegisteredDevices</identity_group><network_device_name>switch</network_device_name><acs_server>ise248</acs_server><authen_protocol>Lookup</authen_protocol><framed_ip_address>10.20.40.10</framed_ip_address>-<network_device_groups>Device Type#All Device Types,Location#All Locations</network_device_groups><access_service>RADIUS</access_service><auth_acs_timestamp>2012-03-13T17:02:22.169+05:30</auth_acs_timestamp><authentication_method>mab</authentication_method>-<execution_steps>11001,11017,11027,15008,15048,15048,15004,15041,15006,15013,24209,24211,22037,15036,15048,15004,15016,11022,11002</execution_steps><audit_session_id>0A4D988B000000E337B8D983</audit_session_id><nas_port_id>GigabitEthernet1/0/9</nas_port_id><nac_policy_compliance>Pending</nac_policy_compliance><auth_id>1331101769985927</auth_id><auth_acsview_timestamp>2012-03-13T17:02:22.171+05:30</auth_acsview_timestamp><message_code>5200</message_code><acs_session_id>ise248/120476308/97</acs_session_id><service_selection_policy>MAB</service_selection_policy><authorization_policy>wired_redirect</authorization_policy><identity_store>Internal Endpoints</identity_store>-<response>{UserName=00:0C:29:95:A5:C1; User-Name=00-0C-29-95-A5-C1; State=ReauthSession:0A4D988B000000E337B8D983; Class=CACS:0A4D988B000000E337B8D983:ise248/120476308/97; Termination-Action=RADIUS-Request; Tunnel-Type=(tag=1) VLAN; Tunnel-Medium-Type=(tag=1) 802; Tunnel-Private-Group-ID=(tag=1) 30; cisco-av-pair=url-redirect-acl=ACL-WEBAUTH-REDIRECT; cisco-av-pair=url-redirect=https://ise248.cisco.com:8443/guestportal/gateway?sessionId=0A4D988B000000E337B8D983&action=cwa; cisco-av-pair=ACS:CiscoSecure-Defined-ACL=#ACSACL#-IP-cwa_wired-4f570619; cisco-av-pair=profile-name=WindowsXP-Workstation; }</response><service_type>Call Check</service_type><use_case>Host Lookup</use_case><cisco_av_pair>audit-session-id=0A4D988B000000E337B8D983</cisco_av_pair><acs_username>00:0C:29:95:A5:C1</acs_username><radius_username>00:0C:29:95:A5:C1</radius_username><selected_identity_store>Internal Endpoints</selected_identity_store><authentication_identity_store>Internal Endpoints</authentication_identity_store><identity_policy_matched_rule>Default</identity_policy_matched_rule><nas_port_type>Ethernet</nas_port_type><selected_azn_profiles>wired_cwa_redirect</selected_azn_profiles><response_time>17</response_time><destination_ip_address>10.77.152.248</destination_ip_address>-<other_attributes>


OL-26134-01


ConfigVersionId=15,DestinationPort=1812,Protocol=Radius,Framed-MTU=1500,EAP-Key-Name=,cisco-nas-port=GigabitEthernet1/0/9,CPMSessionID=0A4D988B000000E337B8D983,EndPointMACAddress=00-0C-29-95-A5-C1,EndPointMatchedProfile=WindowsXP-Workstation,HostIdentityGroup=Endpoint Identity Groups:RegisteredDevices,Device Type=Device Type#All Device Types,Location=Location#All Locations,Device IP Address=10.77.152.139,Called-Station-ID=EC:C8:82:55:2E:09</other_attributes><acct_id>1331101769985928</acct_id><acct_acs_timestamp>2012-03-13T17:02:22.365+05:30</acct_acs_timestamp><acct_acsview_timestamp>2012-03-13T17:02:22.366+05:30</acct_acsview_timestamp><acct_session_id>000000FC</acct_session_id><acct_status_type>Interim-Update</acct_status_type><acct_session_time>16411</acct_session_time><acct_input_octets>3053882</acct_input_octets><acct_output_octets>2633472</acct_output_octets><acct_input_packets>20166</acct_input_packets><acct_output_packets>20297</acct_output_packets><acct_class>CACS:0A4D988B000000E337B8D983:ise248/120476308/97</acct_class><acct_delay_time>0</acct_delay_time><started xsi:type="xs:boolean">false</started><stopped xsi:type="xs:boolean">false</stopped><vlan>30</vlan><dacl>#ACSACL#-IP-cwa_wired-4f570619</dacl><endpoint_policy>WindowsXP-Workstation</endpoint_policy></sessionParameters>

Audit Session ID SearchYou can use the Audit Session ID API call to retrieve a specified audit session from a current, active session. This API call lists a variety of session-related information drawn from node database tables.

Audit Session ID API Output Schema

This sample schema file is the output of the Audit Session ID API call for retrieving a specified audit session ID from the current active sessions:



<xs:complexType name="restsdStatus"> <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="authen_protocol" 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"/>


OL-26134-01


<xs:element name="auth_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="auth_id" type="xs:long" minOccurs="0"/> <xs:element name="auth_acsview_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="message_code" type="xs:string" 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="service_type" 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"/> <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="selected_azn_profiles" 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="eap_tunnel" 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:element name="destination_ip_address" type="xs:string" minOccurs="0"/> <xs:element name="acct_id" type="xs:long" minOccurs="0"/> <xs:element name="acct_acs_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="acct_acsview_timestamp" type="xs:dateTime" minOccurs="0"/> <xs:element name="acct_session_id" type="xs:string" minOccurs="0"/> <xs:element name="acct_status_type" type="xs:string" minOccurs="0"/> <xs:element name="acct_session_time" type="xs:long" minOccurs="0"/> <xs:element name="acct_input_octets" type="xs:string" minOccurs="0"/> <xs:element name="acct_output_octets" type="xs:string" minOccurs="0"/> <xs:element name="acct_input_packets" type="xs:long" minOccurs="0"/> <xs:element name="acct_output_packets" type="xs:long" minOccurs="0"/> <xs:element name="acct_class" type="xs:string" minOccurs="0"/> <xs:element name="acct_terminate_cause" type="xs:string" minOccurs="0"/> <xs:element name="acct_multi_session_id" type="xs:string" minOccurs="0"/> <xs:element name="acct_authentic" type="xs:string" minOccurs="0"/> <xs:element name="termination_action" type="xs:string" minOccurs="0"/> <xs:element name="session_timeout" type="xs:string" minOccurs="0"/> <xs:element name="idle_timeout" type="xs:string" minOccurs="0"/>


OL-26134-01


<xs:element name="acct_interim_interval" type="xs:string" minOccurs="0"/> <xs:element name="acct_delay_time" type="xs:string" minOccurs="0"/> <xs:element name="event_timestamp" type="xs:string" minOccurs="0"/> <xs:element name="acct_tunnel_connection" type="xs:string" minOccurs="0"/> <xs:element name="acct_tunnel_packet_lost" type="xs:string" minOccurs="0"/> <xs:element name="security_group" type="xs:string" minOccurs="0"/> <xs:element name="cisco_h323_setup_time" type="xs:dateTime" minOccurs="0"/> <xs:element name="cisco_h323_connect_time" type="xs:dateTime" minOccurs="0"/> <xs:element name="cisco_h323_disconnect_time" type="xs:dateTime" minOccurs="0"/> <xs:element name="framed_protocol" type="xs:string" minOccurs="0"/> <xs:element name="started" type="xs:anyType" minOccurs="0"/> <xs:element name="stopped" type="xs:anyType" minOccurs="0"/> <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 Audit Session ID API Call






Step 4 Enter the Audit Session ID 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/Active/SessionID/<audit-session-id>/0):

https://acme123/admin/API/mnt/Session/Active/SessionID/0A000A770000006B609A13A9/0



Related Topics



OL-26134-01

Chapter 2 Session Management Query APIs Stale Sessions

Sample Data Returned from the Audit Session ID API Call

The following example illustrates the session-related data returned from the list of active sessions when you invoke an Audit Session ID API call:

This XML file does not appear to have any style information associated with it. The document tree is shown below.-<activeSessionList noOfActiveSession="1">

-<activeSession><calling_station_id>00:50:56:10:13:02</calling_station_id><session_state_bit>0</session_state_bit><session_source>0</session_source><acct_session_time>0</acct_session_time><nas_ip_address>10.0.10.119</nas_ip_address><nas_port_id>GigabitEthernet1/0/15</nas_port_id><auth_method>dot1x</auth_method><auth_protocol>PEAP (EAP-MSCHAPv2)</auth_protocol><posture_status>Compliant</posture_status><endpoint_policy>Undetermined</endpoint_policy><server>acme123</server><paks_in>0</paks_in><paks_out>0</paks_out><bytes_in>0</bytes_in><bytes_out>0</bytes_out>

</activeSession></activeSessionList>

Stale SessionsSome 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




Note API calls are case-sensitive, and must be entered carefully. The variable <mntnode> represents a Cisco Monitoring ISE node.


OL-26134-01


Step 4 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



OL-26134-01



OL-26134-01


C H 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 CallsThe 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 CallsCisco 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 CallYou 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


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:


<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




If your login is unsuccessful, click the Problem logging in? link in the Login page and follow the instructions in Step 2.



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



Related Topics


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:


OL-26134-01


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


-<product name="Cisco Identity Services Engine"><version>1.0.3.032</version><type_of_node>1</type_of_node></product>

Failure Reasons API CallYou 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.

Note 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:


<xs:element name="failureReasonList" type="failureReasonList"/>

<xs:complexType name="failureReasonList"> <xs:sequence>

Table 3-1 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>


OL-26134-01


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



Related Topics


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


OL-26134-01


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


OL-26134-01


<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


• Appendix A, “Cisco ISE Failure Reasons Report”

Authentication Status API CallYou 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).


OL-26134-01


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


OL-26134-01


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:


<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"/>

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

Table 3-2 Authentication Status Table Attributes (continued)



OL-26134-01


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


OL-26134-01


Invoking the AuthStatus API Call







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/All

Note The REST API calls are case-sensitive. The use of “mnt” in the API call convention represents a Cisco Monitoring ISE node.


Related Topics


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>


OL-26134-01


<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=DefaultGuestPortal,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,24211,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_port_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,AuthorizationPolicyMatchedRule=CWA_Redirect,NAS-Port=50117,Framed-MTU=1500,NAS-Port-Type=Ethernet,EAP-Key-Name=,cisco-nas-port=GigabitEthernet1/0/17,AcsSessionID=guest-240/138796808/76,UseCase=Host Lookup,SelectedAuthenticationIdentityStores=Internal Endpoints,ServiceSelectionMatchedRule=MAB,IdentityPolicyMatchedRule=Default,CPMSessionID=0A4D98D1000001F26F0C04D9,EndPointMACAddress=00-0C-29-46-F3-B8,EndPointMatchedProfile=WindowsXP-Workstation,ISEPolicySetName=Default,HostIdentityGroup=Endpoint 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-session-id=0A4D98D1000001F26F0C04D9</other_attributes>-</authStatusElements>-</authStatusList>-</authStatusOutputList>


OL-26134-01


Account Status API CallYou 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):

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:


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

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


OL-26134-01


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



Related Topics


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:


OL-26134-01


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>


OL-26134-01


C H 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.

IntroductionThe 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 CallsThe 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 CallThe Session Reauthentication API Call constitutes the following types:

• REAUTH_TYPE_DEFAULT = 0

• REAUTH_TYPE_LAST = 1

• REAUTH_TYPE_RERUN = 2


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 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/1



Related Topics



OL-26134-01


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


-<remoteCoA requestType="reauth"><results>true</results></remoteCoA>

Session Disconnect API CallThe 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:


<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







OL-26134-01


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>/<nasipaddress>/<destinationipaddress>:

https://acme123/admin/API/mnt/CoA/Disconnect/server12/00:26:82:7B:D2:51/2/10.10.10.10/192.168.1.1



Related Topics


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


-<remoteCoA requestType="reauth"><results>true</results></remoteCoA>


OL-26134-01

P A R T 2

Cisco ISE External RESTful Services APIs


C H 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

OverviewThis 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 ResourcesThe 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


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 AuthorizationThe 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 GUIYou 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 2 Enter your username and case-sensitive password.


OL-26134-01

http://www.cisco.com/c/en/us/td/docs/security/ise/1-3/admin_guide/b_ise_admin_guide_13/b_ise_admin_guide_sample_chapter_0110.html#ID45

Chapter 5 Introduction to ERS APIs External RESTful Services API Status


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 StatusYou 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.4.

Data ValidationCRUD 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.

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


OL-26134-01

http://www.cisco.com/c/en/us/td/docs/security/ise/1-3/admin_guide/b_ise_admin_guide_13/b_ise_admin_guide_sample_chapter_01011.html#ID118

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 SDKYou 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 FileThe 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.


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 4 In the Downloads category, click Schema Jar (ers-schema-1.4-iteration-01-SNAPSHOT.jar).

Step 5 Save the file to your local machine.

Related Topics


External RESTful Service Requests and ResponsesThis 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


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.


OL-26134-01

Chapter 5 Introduction to ERS APIs External RESTful Service Requests and Responses

External RESTful Service Response Headers

Common External RESTful Service HTTP Status Codes

Table 5-2 ERS Mandatory Response Headers

Header Supported Values Description of Use Required

Content-Length Length (in bytes) of the response message body.

Describes the size of the message body.

Yes, on responses that contain a message body.

Content-Type Media type describing the response message body.

Describes the representation and syntax of the response message body.

Yes, on responses that contain a message 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 to requests that create new server side resources accessible via a URI.

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.


OL-26134-01

Chapter 5 Introduction to ERS APIs Version Control with External RESTful Services APIs

Note 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 APIsThe 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:


For example, to get internal user resource version 1.0, the following request is passed:

DELETE https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser/333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: 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:

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.

Table 5-3 Description of the HTTP Response Codes Returned By ERS (continued)

HTTP Status Description


OL-26134-01

Chapter 5 Introduction to ERS APIs Searching and Filtering

Note Each resource has an API to retrieve a list of server supported versions.

Searching and FilteringAll 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 APIsYou 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=identityGroup.EQ.Finance

The following table shows the available filter operators:

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 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 Server returns status 415 with a corresponding error message.

Parameter Description

EQ Equals

GT Greater Than

LT Less Then

STARTSW Start With


OL-26134-01

Chapter 5 Introduction to ERS APIs External RESTful Services System Flow

The following table shows the list of filterable attributes for each resource:

Paging Parameters for External RESTful Services APIsAll 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:

External RESTful Services System FlowCommon 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.

ENDSW End With

CONTAINS Contains


Resource Filterable Attributes

Endpoints mac, portalUser, profile, profileId, staticGroupAssignment, staticProfileAssignment

Internal User name

Endpoint Identity Group name

Identity Groups name

SGTs name

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 of available fields for sorting. (For alphabetic characters, it is sorted A to Z.)

name

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


OL-26134-01

Chapter 5 Introduction to ERS APIs External RESTful Services System Flow

Figure 5-1 ERS Success Flow Sequence


OL-26134-01

Chapter 5 Introduction to ERS APIs Hyperlinks

Figure 5-2 ERS Failure Flow Sequence

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


OL-26134-01

http://www.w3.org/2005/Atom namespace

Chapter 5 Introduction to ERS APIs Bulk Operations

The following table shows the mandatory link attributes for the External RESTful Services:

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


Href This contains the link's URI.

Rel This attribute, which originally meant “relation,” indicates the following type of links:

• “self”—link to refresh current representation

• “next”—in collection for getting next page

• “info”—get more info about of the resource

Type 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”


OL-26134-01


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.


OL-26134-01



OL-26134-01


C H 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-3

• Guest REST API Responses, page 6-6

• Searching and Filtering, page 6-9

An API for Guest User ResourcesThe 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-24.

Sponsor Authentication and AuthorizationA 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.

Note The sponsor using the Guest REST API cannot be a part of the ERS-ADMIN role.

See the Cisco ISE User Guide for more information on sponsors and sponsor groups.


Chapter 6 Guest REST API Sponsor Authentication and Authorization

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

Procedure


Step 2 Enter your username and case-sensitive password.


Step 4 Assign the user to the appropriate identity group.

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.

Step 5 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.

Step 6 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.


OL-26134-01

Chapter 6 Guest REST API Guest REST API Requests

Guest REST API RequestsRequests 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

• API requests are case sensitive and should be entered as shown in this manual.

• Each guest request needs to set Content Type as:

application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

• Each guest request needs to set Accept as:

application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

• Each guest bulk request needs to set Content Type as:

application/vnd.com.cisco.ise.identity.guestuserbulkrequest.1.0+xml

• Each guest bulk request needs to set Accept as:

application/vnd.com.cisco.ise.identity.guestuserbulkrequest.1.0+xml

• You also can include the optional Accept-Encoding:gzip header, which compresses the response payload.

Request StructureThe following table lists the types of request operations that you can use with the Cisco Guest REST API:

The following table lists the mandatory headers for requests:

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

Table 6-2 Mandatory Request Headers

Header Values Description

ACCEPT Guest REST API Resource Media-Type


AUTHORIZATION "Basic " plus username and password (per RFC 2617

Identifies the authorized user making this request.

CONTENT-TYPE Media type describing the request message body

Describes the representation and syntax of the request message body.


OL-26134-01


Related Topics

Content Type and Accept Headers, page 7-24

Request ContentsThe XML content below shows the structure of a guest user account, including custom fields:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns3:guestuser name="guestUser" id="123456789" description="ERS Example user " xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com"> <customFields> <entry> <key>some key</key> <value>some value</value> </entry> <entry> <key>another key</key> <value>and its value</value> </entry> </customFields> <guestInfo> <emailAddress>[email protected]</emailAddress> <enabled>true</enabled>

<phoneNumber>3211239034</phoneNumber> <smsServiceProvider>GLobal Default</smsServiceProvider> <userName>DS3ewdsa34wWE</userName> </guestInfo> <guestType>Contractor</guestType> <portalId>23423432523</portalId> <sponsorUserName>Mr Spons</sponsorUserName></ns3:guestuser>

The request example below shows the XML content that’s required to create guest user accounts using either the POST (create) operation.

Note The fields required to create a guest user account do not necessarily correspond to the required fields displayed in the Sponsor Portal. However, the Guest REST API will throw an exception if the Sponsor Portal does not provide the information required to create a guest user account.

POST Request ExamplePOST https://<ISE-Admin-Node>:9060/ers/config/guestuser/

Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xmlContent-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xmlAuthorization: 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>[email protected]</emailAddress> <firstName>John</firstName>


OL-26134-01


<lastName>Doe</lastName> <notificationLanguage>English</notificationLanguage>

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

Note JSON is not used for Guest REST API.

Guest PasswordsISE 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 the resetpassword operation.

You cannot change a guest’s password to a specific string using the REST API.

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.

Related Topics

• Reset Password for a Guest User Account, page 7-38

• For further details on guest user password policies, see the Cisco ISE Admin Guide.

Bulk ExecutionsA 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.


OL-26134-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-39

Guest REST API ResponsesEach request is followed by a server HTTPS response with the standard headers, plus response content.

Response Status CodesA 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.

Related Topics

Response Error Messages, page 6-7

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.


OL-26134-01


Response StructureThe following table lists the headers for responses.

Response Error MessagesYou 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

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

Table 6-5 Error Codes

Error Code DescriptionHTTPStatus

Resource version exception Resource version sent in the request content is not supported by the server.

415

Resource media type exception Media type sent by the client in the ACCEPT or Content-Type headers is invalid.

415

Unsupported resource exception Resource listed in the URI, is not supported by the server.

400

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

400

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.

400

Unauthorized user The sponsor’s username and password are not valid.

401

Internal exception Any unexpected internal server error occurs at runtime.

500


OL-26134-01


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"?>

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

VersioningThe Guest REST API for Cisco ISE Release 1.4 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:


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

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

Table 6-5 Error Codes

Error Code DescriptionHTTPStatus


OL-26134-01

Chapter 6 Guest REST API Searching and Filtering

Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: 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.

Searching and FilteringAll 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 ParametersFiltering 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-6 Version-match Results

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

Table 6-7 Filtering Parameters


firstName Guest’s first name

lastName Guest’s last name


OL-26134-01


The following table lists the operations that you can use in filter queries.

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=emailAddress.CONTAINS.bob

GET Request for Guest Users with the Status of “Approved” and Expiration Date in OctoberGET https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser?filter=status.EQ.Approved&filter=toDate.STARTSW.10

Related Topics

Get a Guest User, page 7-25

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

Table 6-7 Filtering Parameters


Table 6-8 Available Filter Operations


EQ Equals

GT Greater Than

LT Less Than

STARTSW Starts With

ENDSW Ends With

CONTAINS Contains


OL-26134-01


Page Size ParametersSearch 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=emailAddress.CONTAINS.bob&size=50&page=0

Sorting ParametersBy 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.

Example: GET First 20 Guest User Records and Sort ascending by the Last Name

RequestGET 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-000c2932c73c" rel="self"/> </resource>

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 of available fields for sorting. (For alphabetic characters, it is sorted A to Z.)

name

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


OL-26134-01


<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-000c2932c73c" 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-000c2932c73c" rel="self"/> </resource> </resources></ns2:searchResult>

Related Topics

• Filter by Usernames that Start with “ilucky” Example, page 7-26

• Filter by Username that Starts with “ilucky” and Last Name that Starts with “J” Example, page 7-27

• Filter By the First Name “John” and Sort By Username Example, page 7-28


OL-26134-01


C H 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 Services APIs for Endpoint Certificates, page 7-16

• External RESTful Services APIs for Endpoint Identity Groups, page 7-18

• External RESTful Services APIs for Identity Groups, page 7-22

• External RESTful Services APIs for Guest Users, page 7-24

• External RESTful Services APIs for Portals, page 7-43

• External RESTful Services APIs for Profiles, page 7-46

• External RESTful Services APIs for Network Devices, page 7-47

• External RESTful Services APIs for Network Device Groups, page 7-52

• External RESTful Services APIs for SGTs, page 7-55

• REST API Client, page 7-57

OverviewThis 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 CallsYou 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.


Chapter 7 External RESTful Services API Operations GetVersion

Related Topics

• Enabling External RESTful Services APIs from the GUI, page 5-2


GetVersionThe 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:

Sample Request for GetVersion Operation

GET https://<ISE-ADMIN-NODE>:9060/ers/config/<resource-type>/versioninfoAuthorization: Basic xxxxxxxxxxxxxxxxxxxAccept: 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 GMTContent-Type: application/vnd.com.cisco.ise.<resource-namespace>.versoininfo.1.0+xmlContent-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 UsersThe 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:

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


OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Internal Users

Retrieve All Internal UsersYou 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:

Sample Request for Retrieve All Internal Users API

GET https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser?page=0&size=20&sortacs=nameAuthorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.identity.internaluser.1.0+xml

Sample Response for Retrieve All Internal Users API

HTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xml

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/{internaluser-id1}

1. Internal user ID is the UUID type as stored in the Cisco ISE database.

n/a

Create User POST /ers/config/internaluser/ internaluser

Update User PUT /ers/config/internaluser/{internaluser-id}

internaluser

Delete User DELETE /ers/config/internaluser/{internaluser-id}

n/a

Get InternalUser Resource Version Info

GET /ers/config/internaluser/version n/a

Table 7-3 Main Characteristics of Retrieve All Internal Users API Call

Description Retrieve collection of internal users

Synopsis GET /ers/config/internaluser


QueryString page, size, sortbyacn, sortbydcn, filter



Response Message Body SearchResult

Response Status 200, 400, 401, 403, 404, 415, 429, 500


OL-26134-01


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 IDYou 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:

Sample Request for Read Internal Users API

GET https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser/333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.internaluser.1.0+xml

Sample Response for Read Internal Users API

HTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.identity.internaluser.1.0+xmlContent-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>

Table 7-4 Main Characteristics of Read Internal Users API Call

Description Retrieve the specified internal user

Synopsis GET /ers/config/internaluser/{id}


QueryString N/A



Response Message Body Resource of type InternalUser

Response Status 200, 400, 401,403, 404, 415, 429, 500


OL-26134-01


</customAttributes> <email>[email protected]</email> <enabled>true</enabled> <firstName>John</firstName> <identityGroups>identityGroups</identityGroups> <lastName>Doe</lastName> <password>12345</password></ns3:internaluser>}

Create Internal UsersYou 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:

Sample Request for Create Internal Users API

POST https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser/Authorization: Basic xxxxxxxxxxxxxxxxxxxContent-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 protected]</email> <enabled>true</enabled> <firstName>John</firstName> <identityGroups>identityGroups</identityGroups> <lastName>Doe</lastName> <password>12345</password>

Table 7-5 Main Characteristics of Create Internal Users API Call

Description Create the specified internal user

Synopsis POST /ers/config/internaluser/


QueryString N/A

Request Message Body InternalUser

Response Headers Content-Length, Content-Type, Location


Response Status 201, 400, 401, 403, 415, 429, 500


OL-26134-01


</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 GMTContent-Type: application/vnd.com.cisco.ise.identity.internaluser.1.0+xmlLocation: https://<ISE-ADMIN-NODE>/ers/config/internaluser/444

Update Internal UsersYou 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:

Sample Request for Update Internal Users API

PUT https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser/333Authorization: Basic xxxxxxxxxxxxxxxxxxxContent-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 protected]</email> <enabled>true</enabled> <firstName>John</firstName> <identityGroups>IdentityGroups</identityGroups> <lastName>Doe</lastName> <password>********</password>

Table 7-6 Main Characteristics of Update Internal Users API Call

Description Update the specified internal user

Synopsis PUT /ers/config/internaluser/{id}


QueryString N/A

Request Message Body InternalUser


Response Message Body List of updated fields

Response Status 200, 400, 401, 403, 404, 415, 429, 500


OL-26134-01


</ns3:internaluser>}

Sample Response for Update Internal Users API

HTTP/1.1 200 OK Date: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.ers.updatedfields.1.0+xmlContent-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 UsersYou can use this API call to delete internal users from Cisco ISE. The following table lists the main characteristics of this API call:

Sample Request for Delete Internal Users API

DELETE https://<ISE-ADMIN-NODE>:9060/ers/config/internaluser/333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: 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

Table 7-7 Main Characteristics of Delete Internal Users API Call

Description Delete the specified internal user

Synopsis DELETE /ers/config/internaluser/{internaluser-id}


QueryString N/A




Response Status 204, 400, 401, 403, 404, 415, 429, 500


OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Endpoints

External RESTful Services APIs for EndpointsThe following table lists the External RESTful Services APIs for end points:

Get All EndpointsThe 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:

Sample Request for Get All Endpoints API

GET https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint?filter=userid.EQ.123

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}

1. Endpoint ID is the UUID type as stored in the Cisco ISE database.

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

Register Endpoint PUT2

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.

/ers/config/endpoint/register endpoint

Deregister Endpoint PUT /ers/config/endpoint/{id}/deregister n/a

Get Endpoint Resource Version Info

GET /ers/config/endpoint/version n/a

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/






Response Status 200, 400, 401, 403, 404, 415, 429, 500


OL-26134-01


Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml

Sample Response for Get All Endpoints API

HTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xmlContent-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 IDYou 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:

Sample Request for Read Endpoints API

GET https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml

Sample Response for Read Endpoints API

HTTP/1.1 200 OK

Table 7-10 Main Characteristics of Read Endpoints API Call

Description Retrieve the specified endpoint

Synopsis GET /ers/config/endpoint/{endpoint-id}


QueryString N/A




Response Status 200, 400, 401,403, 404, 415, 429, 500


OL-26134-01


Date: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xmlContent-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 EndpointsYou can use this API call to create endpoints in Cisco ISE. The following table lists the main characteristics of this API call:

Note the following while creating an endpoint:

• If you are creating an endpoint with Group static assignment, groupid is mandatory.

• If you are creating an endpoint with Profile static assignment, profileid is mandatory.

• If you are creating an endpoint with both Group and Profile static assignment, both groupid and profileid are required.

If these attributes are not included in the request, endpoint may not be created properly.

Sample Request for Create Endpoints API

POST https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/Authorization: Basic xxxxxxxxxxxxxxxxxxxContent-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml{<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

Table 7-11 Main Characteristics of Create Endpoints API Call

Description Create the specified endpoint

Synopsis POST /ers/config/endpoint/


QueryString N/A




Response Status 200, 400, 401,403, 404, 415, 429, 500


OL-26134-01


<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 Create Endpoints API

HTTP/1.1 201 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xmlLocation: https://cisco.com/ers/config/endpoint/444

Update EndpointsYou can use this API call to update endpoints in Cisco ISE. The following table lists the main characteristics of this API call:

Sample Request for Update Endpoints API

PUT https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/333Authorization: Basic xxxxxxxxxxxxxxxxxxxContent-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"> <staticGroupAssignment>false</staticGroupAssignment> <staticProfileAssignment>false</staticProfileAssignment></ns2:endpoint>}

Table 7-12 Main Characteristics of Update Endpoints API Call

Description Update the specified endpoint

Synopsis PUT /ers/config/endpoint/{endpoint-id}


QueryString N/A




Response Status 200, 400, 401,403, 404, 415, 429, 500


OL-26134-01


Sample Response for Update Endpoints API

HTTP/1.1 200 OK Date: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.ers.updatedfields.1.0+xmlContent-Length: 529{<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:updatedFields xmlns:ns2="ers.ise.cisco.com"> <updatedField field="staticGroupAssignment"> <newValue>false</newValue> <oldValue>true</oldValue> </updatedField><updatedField field="staticProfileAssignment"> <newValue>false</newValue> <oldValue>true</oldValue> </updatedField></ns2:updatedFields>}

Delete EndpointsYou can use this API call to update endpoints in Cisco ISE. The following table lists the main characteristics of this API call:

Sample Request for Delete Endpoints API

DELETE https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml

Sample Response for Delete Endpoints API

HTTP/1.1 204 No Content Date: Thu, 12 Jul 2012 23:59:59 GMT

Table 7-13 Main Characteristics of Delete Endpoints API Call

Description Delete the specified endpoint

Synopsis DELETE /ers/config/endpoint/{id}


QueryString N/A




Response Status 200, 400, 401,403, 404, 415, 429, 500


OL-26134-01


Register EndpointsYou 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.

The following table lists the main characteristics of this API call:

Sample Request for Register Endpoints API

PUT https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/registerAuthorization: Basic xxxxxxxxxxxxxxxxxxxContent-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


Deregister EndpointsYou 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-14 Main Characteristics of Register Endpoints API Call

Description Register the specified endpoint

Synopsis PUT /ers/config/endpoint/register


QueryString N/A

Request Message Body endpoint



Response Status 202, 400, 401, 403, 404, 415, 429, 500


OL-26134-01


Sample Request for Deregister Endpoint API Call

PUT https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/123/deregisterAuthorization: Basic xxxxxxxxxxxxxxxxxxxContent-Type: application/vnd.com.cisco.ise.identity.endpoint.1.0+xml

Sample Response for Deregister Endpoint API Call


Start Bulk Execution for EndpointsA 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-15 Main Characteristics of Deregister Endpoints API Call

Description Deregister the specified endpoint

Synopsis PUT /ers/config/endpoint/{id}/deregister


QueryString N/A


Response Message Body N/A

Response Status 202, 400, 401, 403, 404, 415, 429, 500

Table 7-16 Start Bulk Execution for Endpoints Main Characteristics

Description Start Execute

Synopsis PUT /ers/config/endpoint/bulk


QueryString n/a

Request Message Body BulkRequest


Response Message Body n/a

Response Status 202, 400, 401, 403, 404, 415, 500


OL-26134-01


Sample Request for Start Bulk Execution for Endpoints API Call

PUT https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/bulk HTTP/1.1Host: {some-ise-node-ip}Authorization: Basic xxxxxxxxxxxxxxxxxxx Content-Type: application/vnd.com.cisco.ise.ers.endpointbulkrequest.1.0+xml {<ns3:endpointBulkRequestresourceMediaType = "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> <resourcexsi: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>. . .<resourcexsi: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 EndpointsIf 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}


QueryString n/a

Request Message Body n/a



OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Endpoint Certificates

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

ResponseHTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-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 Services APIs for Endpoint CertificatesThe following table lists the External RESTful Services APIs for endpoint certificates:

Response Message Body BulkStatus

Response Status 200, 400, 401, 403, 404, 415, 500



OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Endpoint Certificates

Create Endpoint CertificateThe following table lists the main characteristics of the Create Endpoint Certificate API call:

:

Sample Request for Create Endpoint Certificate API Call

PUT https://<ISE-ADMIN-NODE>/ers/config/endpointcert/certRequestHTTP Content-Type header:application/vnd.com.cisco.ise.ca.endpointcert.1.0+xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns3:endpointcert xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="ca.ers.ise.cisco.com"> <certTemplateName>Certificate_Template_Name</certTemplateName> <certificateRequest> <entry> <key>san</key> <value>11-22-33-44-55-66</value> </entry> <entry> <key>cn</key> <value>userName [or] machineName</value> </entry> </certificateRequest> <format>PKCS8 [or] PKCS8_CHAIN [or] PKCS12 [or] PKCS12_CHAIN</format> <password>password</password></ns3:endpointcert>

Sample Response for Create Endpoint Certificate API Call

HTTP Status: 200 (OK)

Table 7-18 ERS APIs Available for Endpoint Certificates


Create Endpoint Certificate

POST /ers/config/endpointcert/certRequest/

Octet Stream representing a ZIP file

Get Certificate Resource Version Info

GET /ers/config/endpointcert /version

n/a

Table 7-19 Main Characteristics of Create Endpoint Identity Groups API Call

Description Create an endpoint certificate

Synopsis POST /ers/config/endpointcert/certRequest/


QueryString N/A

Request Message Body Endpoint certificate


Response Message Body Octet Stream representing a ZIP file

Response Status 201, 400, 401, 403, 415, 429, 500


OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Endpoint Identity Groups

Content:[Response is returned as an Octet Stream representing a ZIP file.]

External RESTful Services APIs for Endpoint Identity GroupsThe following table lists the External RESTful Services APIs for endpoint identity groups:

Get All Endpoint Identity GroupsThe following table lisys the main characteristics of the Get All Endpoint Identity Groups API call:

Sample Request for Get All Endpoint Identity Groups API Call

GET https://<ISE-ADMIN-NODE>:9060/ers/config/endpointgroupAuthorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml

Table 7-20 ERS APIs Available for Endpoint Identity Groups


Get All Endpoints Groups

GET /ers/config/endpointgroup n/a page, size, sortacs or sortdsn, filter

Get Endpoint Group GET /ers/config/endpointgroup/{id1}

1. Endpoint Group ID is the UUID type as stored in the Cisco ISE database.

n/a

Create Endpoint Group POST /ers/config/endpointgroup/ Endpointgroup

Update Endpoint Group PUT /ers/config/endpointgroup/{id}

Endpointgroup

Delete Endpoint Group DELETE /ers/config/endpointgroup/{id}

n/a

Get IdentityGroup Resource Version Info

GET /ers/config/ endpointgroup /version

n/a

Table 7-21 Main Characteristics of Get All Endpoint Identity Groups API Call

Description Retrieve a collection of endpoint groups

Synopsis GET /ers/config/endpoint


QueryString page, size, sortasc, sortdsc, filter




Response Status 202, 400, 401, 403, 404, 415, 429, 500


OL-26134-01


Sample Response for Get All Endpoint Identity Groups API Call

HTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xmlContent-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>}

Get Endpoint Identity Groups by IDThe following table lists the main characteristics of the Get Endpoint Identity Groups by ID API call:

Sample Request for Read Endpoint Identity Groups API Call

GET https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml

Sample Response for Read Endpoint Identity Groups API Call

HTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xmlContent-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">

Table 7-22 Main Characteristics of Read Endpoint Identity Groups API Call

Description Retrieve the specified endpoint group

Synopsis GET /ers/config/endpoint/{id}


QueryString N/A



Response Message Body Resource of type Endpoint

Response Status 200, 400, 401,403, 404, 415, 429, 500


OL-26134-01


<systemDefined>true</systemDefined></ns3:endpointgroup>}

Create Endpoint Identity GroupsThe following table lists the main characteristics of the Create Endpoint Identity Groups API call:

:

Sample Request for Create Endpoint Identity Groups API Call

POST https://<ISE-ADMIN-NODE>:9060/ers/config/endpointAuthorization: Basic xxxxxxxxxxxxxxxxxxxContent-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 GMTContent-Type: Location: https://cisco.com/ers/config/endpointgroup/444

Update Endpoint Identity GroupsThe following table lists the main characteristics of the Update Endpoint Identity Groups API call:

Table 7-23 Main Characteristics of Create Endpoint Identity Groups API Call

Description Create the specified endpoint group

Synopsis POST /ers/config/endpoint/


QueryString N/A

Request Message Body Endpoint Group


Response Message Body Endpoint Group

Response Status 201, 400, 401, 403, 415, 429, 500

Table 7-24 Main Characteristics of Update Endpoint Identity Groups API Call

Description Update the specified endpoint group

Synopsis PUT /ers/config/endpoint/{id}


OL-26134-01


Sample Request for Update Endpoint Identity Groups API Call

PUT https://<ISE-ADMIN-NODE>:9060/ers/config/ endpoint /333Authorization: Basic xxxxxxxxxxxxxxxxxxxContent-Type: application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xml{<?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 GMTContent-Type: application/vnd.com.cisco.ise.ers.updatedfields.1.0+xmlContent-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 GroupsThe following table lists the main characteristics of the Delete Endpoint Identity API call:


QueryString N/A

Request Message Body Endpoint Group



Response Status 200, 400, 401, 403, 404, 415, 429, 500

Table 7-24 Main Characteristics of Update Endpoint Identity Groups API Call (continued)

Table 7-25 Main Characteristics of Delete Endpoint Identity Groups API Call

Description Delete the specified endpoint group

Synopsis DELETE /ers/config/endpointgroup/{id}


QueryString N/A



OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Identity Groups

Sample Request for Delete Endpoint Identity Groups API Call

DELETE https://<ISE-ADMIN-NODE>:9060/ers/config/endpoint/333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: 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

External RESTful Services APIs for Identity GroupsThe following table lists the External RESTful Services APIs for Identity Groups:

Retrieve All Identity GroupsYou can use this API call to retrieve all identity groups in Cisco ISE. The following table lists the main characteristics of this API call:


Response Message Body NA

Response Status 204, 400, 401, 403, 404, 415, 429, 500

Table 7-25 Main Characteristics of Delete Endpoint Identity Groups API Call (continued)

Table 7-26 APIs Available for Identity Groups


Get All Identity Groups GET /ers/config/identitygroup n/a page, size, sortacs or sortdsn, filter

Get Identity Group by ID GET ers/config/identitygroup/{id}

n/a

Get IdentityGroup Resource Version Info

GET /ers/config/identitygroup/version

n/a

Table 7-27 Main Characteristics of Retrieve All Identity Groups API Call

Description Retrieve a collection of identity group resources

Synopsis GET /ers/config/identitygroup






OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Identity Groups

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 xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.identity.identitygroup.1.0+xml

Sample Response for Retrieve All Identity Group API Call

HTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xmlContent-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"> <link type="application/xml" href="https://<ISE-ADMIN-NODE>:9060/ers/config/identitygroup/id2" rel="self"/> </resource> </resources></ns2:searchResult>}

Get Identity Groups by IDThe following table lists the main characteristics of the Get Identity Groups by ID API call:


Response Status 200, 400, 401, 403, 404, 415, 429, 500

Table 7-27 Main Characteristics of Retrieve All Identity Groups API Call (continued)

Table 7-28 Main Characteristics of Read Endpoint Identity Groups API Call

Description Retrieve the specified identity group

Synopsis GET /ers/config/identitygroup/{id}


QueryString N/A



Response Message Body Resource of type Endpoint

Response Status 200, 400, 401,403, 404, 415, 429, 500


OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Guest Users

Sample Request for Get Identity Group by ID API Call

GET https://<ISE-ADMIN-NODE>:9060/ers/config/identitygroup/333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.identity.identitygroup.1.0+xml

Sample Response for Get Identity Group by ID API Call

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns3:identitygroup name="name" id="id" description="description" xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com"> <parent>parent</parent></ns3:identitygroup>

External RESTful Services APIs for Guest UsersThe following table lists the External RESTful Services APIs for Guest Users:

Table 7-29 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/{portalId}

n/a

Approve Guest User PUT /ers/config/guestuser/approve/{id} n/a

Deny Guest User PUT /ers/config/guestuser/deny/{id} n/a

Reset Password PUT /ers/config/guestuser/resetpassword/{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/changeSponsorPassword/{portalId}

operationAdditionalData


OL-26134-01


Content Type and Accept HeadersEach guest account request needs to set the following:

• Content Type as: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

• 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 UserYou can use the GET operation to retrieve specific guest users from the ISE database using either the guest’s username or database record ID.

Get a Guest User Examples

• Get a Guest User by ID Example, page 7-26

• Filter by Usernames that Start with “ilucky” Example, page 7-26

• Filter by Username that Starts with “ilucky” and Last Name that Starts with “J” Example, page 7-27

• Filter By the First Name “John” and Sort By Username Example, page 7-28

• Guest User Request and Response Using curl Example, page 7-29

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

Table 7-29 Supported Scenarios

Operation Method URL Content

Table 7-30 Get a Guest User Main Characteristics

Description Retrieve the specified Guest User

Synopsis GET /ers/config/guestuser/{id}


QueryString n/a



Response Message Body Resource of type GuestUser

Response Status 200, 400, 401, 403, 404, 415, 500


OL-26134-01


Get a Guest User by ID Example

RequestGET https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/3333

Content-Type - application/vnd.com.cisco.ise.identity.guestuser.2.0+xmlAccept - application/vnd.com.cisco.ise.identity.guestuser.2.0+xmlAuthorization - 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> <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>[email protected]</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>[email protected]</personBeingVisited> <reasonForVisit>Interview</reasonForVisit> <sponsorUserName>SponsoredUser1</sponsorUserName> <status>Awaiting Initial Login</status></ns3:guestuser>

Related Topics

See Response Error Messages, page 6-7 for details on password visibility in the API.

Filter by Usernames that Start with “ilucky” Example

RequestGET 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">


OL-26134-01


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:* 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>* Server auth using Basic with user 'username'

GET Guest User by ID Request> GET /ers/config/guestuser/444Authorization: Basic xxxxxxxxxxxxxxxxUser-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.6Host: <ISE-ADMIN-NODE>:9060Pragma: no-cacheACCEPT: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>[email protected]</emailAddress><firstName>John</firstName><lastName>Doe</lastName><notificationLanguage>English</notificationLanguage><phoneNumber>9999998877</phoneNumber><smsServiceProvider>Global Default</smsServiceProvider>


OL-26134-01


<userName>user1</userName></guestInfo><guestType>Daily (default)</guestType><personBeingVisited>[email protected]</personBeingVisited><portalId>ff2d99e0-2101-11e4-b5cf-005056bf2f0a</portalId><reasonForVisit>Interview</reasonForVisit></ns3:guestuser>

Related Topics


Get All Guest UsersYou 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.

Related Topics

Filtering Parameters, page 6-9

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.

RequestGET https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/?page=0&size=10&sortasc=name&filter=name.STARTSW.ilu&filter=firstName.STARTSW.b


ResponseHTTP/1.1 200 OK;Date:Sat, 15 Dec 2012 21:55:05 GMT;Content-Length:1439;

Table 7-31 Get All Guest Users Main Characteristics

Description Retrieve a collection of Guest Users

Synopsis GET /ers/config/guestuser/


QueryString page, size, sortasc, sortdsc, filter




Response Status 200, 400, 401, 403, 404, 415, 500


OL-26134-01


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-000c290fcf9a" 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-000c290fcf9a" rel="self"/> </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-000c290fcf9a" 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-000c290fcf9a" 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-000c290fcf9a" 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-000c290fcf9a" rel="self"/> </ns2:resource> </resources></ns2:searchResult>

Create a Guest UserYou 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-32 Create a Guest User Main Characteristics

Description Create the specified Internal User

Synopsis POST /ers/config/guestuser/


QueryString n/a

Request Message Body GuestUser



Response Status 201, 400, 401, 403, 415, 500


OL-26134-01


Guest User XML Structure

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns3:guestuser name="guestUser" id="123456789" description="ERS Example user " xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com"> <customFields> <entry> <key>some key</key> <value>some value</value> </entry> <entry> <key>another key</key> <value>and its value</value> </entry> </customFields> <guestInfo> <emailAddress>[email protected]</emailAddress> <enabled>true</enabled> <password>asdlkj324ew</password> <phoneNumber>3211239034</phoneNumber> <smsServiceProvider>GLobal Default</smsServiceProvider> <userName>DS3ewdsa34wWE</userName> </guestInfo> <guestType>Contractor</guestType> <portalId>23423432523</portalId> <sponsorUserName>Mr Spons</sponsorUserName></ns3:guestuser>

Create a Guest User Example

Request POST https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/


<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:guestuser xmlns:ns2="identity.ers.ise.cisco.com"> <guestAccessInfo> <fromDate>08/08/2014 08:15</fromDate> <toDate>08/09/2014 08:15</toDate> <validDays>1</validDays> </guestAccessInfo> <guestInfo> <company>New Company</company> <emailAddress>[email protected]</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>[email protected]</personBeingVisited> <portalId>ff2d99e0-2101-11e4-b5cf-005056bf2f0a</portalId> <reasonForVisit>Interview</reasonForVisit></ns2:guestuser>


OL-26134-01


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-000c29c56fc6;Set-Cookie:JSESSIONID=28CF43F1ACCC7448BED7255DC7B787EE; Path=/ers; Secure;JSESSIONIDSSO=DB6D6900088D1863CA84863570392E4C; Path=/; Secure;Content-Type:application/xml;

Related Topics


Update a Guest UserUpdating 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.

Update User Example

RequestPUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/name/ilucky101


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

ResponseStatus: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>

Table 7-33 Update a Guest User Main Characteristics

Description Update the specified Guest User

Synopsis PUT /ers/config/guestuser/{id}


QueryString n/a

Request Message Body GuestUser



Response Status 200, 400, 401, 403, 404, 415, 500


OL-26134-01


</updatedField> <updatedField field="validDays"> <newValue>0</newValue> <oldValue>1</oldValue> </updatedField></ns2:updatedFields>

Delete a Guest UserYou 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.

Delete a Guest User Example

RequestDELETE https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/3333


ResponseHTTP/1.1 200 OK Date: Thu, 12 Jul 2012 23:59:59 GMT

Suspend a Guest UserUse 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-34 Delete a Guest User Main Characteristics

Description Delete the specified Guest User

Synopsis DELETE /ers/config/guestuser/{id}


QueryString n/a




Response Status 204, 400, 401, 403, 404, 415, 500

Table 7-35 Suspend a Guest User Main Characteristics

Description Suspend the specified Guest User

Synopsis PUT /ers/config/guestuser/suspend/{id}


QueryString n/a


OL-26134-01


Suspend a Guest User by ID Example

Request

PUT https:/<ISE-ADMIN-NODE>:9060/ers/config/guestuser/suspend/3333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xmlContent-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>

ResponseHTTP/1.1 204 No Content Sat, 15 Dec 2012 10:14:38 GMT

Reinstate a Guest UserUse the PUT operation to reinstate a suspended guest’s user account.

Reinstate Guest User Example

RequestPUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/reinstate/33 Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

Request Message Body reason



Response Status 204, 400, 401, 403, 404, 415, 500

Table 7-35 Suspend a Guest User Main Characteristics

Table 7-36 Reinstate a Guest User Main Characteristics

Description Reinstate the specified Guest User

Synopsis PUT /ers/config/guestuser/reinstate/{id}


QueryString n/a




Response Status 204, 400, 401, 403, 404, 415, 500


OL-26134-01


ResponseHTTP/1.1 204 OK Date: Sat, 15 Dec 2012 10:20:48 GMT

Send an Email to a Guest UserUse 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.

Send an Email to a Guest User Example

RequestPUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/email/4444/portalId/ff2d99e0-2101-11e4-b5cf-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>


Send an SMS Text to a Guest UserUse 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.

Table 7-37 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}


QueryString n/a

Request Message Body senderEmail



Response Status 204, 400, 401, 403, 404, 415, 500


OL-26134-01


The request requires a portal ID because the portal configuration contains information needed for the text body.

Send an SMS Example

RequestPUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/sms/444/portalId/ff2d99e0-2101-11e4-b5cf-005056bf2f0a Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml


Approve a Guest UserThis operation allows you to approve a guest user account. This requires using the guest account ID.

Table 7-38 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}


QueryString n/a




Response Status 204, 400, 401, 403, 404, 415, 500

Table 7-39 Get API Version Main Characteristics

Description Approve the specified Guest User

Synopsis PUT /ers/config/guestuser/approve/{id}


QueryString n/a



Response Message Body API version

Response Status 200, 400, 401, 403, 404, 415, 500


OL-26134-01


Approve a Guest User Example

RequestPUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/approve/3333 Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml


Deny Approval for a Guest User AccountThis operation allows you to deny approval for a guest user account. This requires using the guest account ID.

Deny a Guest User’s Approval Example

RequestPUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/deny/7777 Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml


Reset Password for a Guest User AccountThis operation allows you to reset the password for a guest user account. This requires using the guest account ID. This operation returns a new, generated password. You cannot specify your own password using the REST API.


Description Deny the specified Guest User

Synopsis PUT /ers/config/guestuser/deny/{id}


QueryString n/a




Response Status 200, 400, 401, 403, 404, 415, 500


OL-26134-01


Reset a Guest User’s Password Example

RequestPUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/resetpassword/7777 Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

ResponseHTTP/1.1 204 OK Date: Sat, 15 Dec 2014 10:20:48 GMT<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:operationResult xmlns:ns2="ers.ise.cisco.com"> <attributesList> <attribute value="DdsAASDs%$##@ssds12" name="password"/> </attributesList>

</ns2:operationResult>

Start Bulk Execution for Guest UsersA 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.

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.


Description Reset password for the specified Guest User

Synopsis PUT /ers/config/guestuser/resetpassword/{id}


QueryString n/a



Response Message Body New password

Response Status 200, 400, 401, 403, 404, 415, 500

Table 7-42 Start Bulk Execution Main Characteristics

Description Start Execute

Synopsis PUT /ers/config/guestuser/bulk


QueryString n/a

Request Message Body BulkRequest


OL-26134-01


Create Guest Bulk Example

RequestPUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/bulkAuthorization: BasicContent-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>[email protected]</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>[email protected]</personBeingVisited>

</resource>

...

<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>[email protected]</emailAddress> <enabled>true</enabled> <firstName>Mary</firstName>



Response Status 202, 400, 401, 403, 404, 415, 500

Table 7-42 Start Bulk Execution Main Characteristics


OL-26134-01


<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>[email protected]</personBeingVisited>

</resource></resourcesList>

</ns3:bulkRequest>

ResponseHTTP/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 UsersIf 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.

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

ResponseHTTP/1.1 200 OKDate: Thu Mar 07 18:17:35 IST 2013 GMTContent-Type: application/vnd.com.cisco.ise.ers.guestuserbulkrequest.1.0+xml Content-Length: 16347


Description Monitor the specified bulk execution progress

Synopsis GET /ers/config/guestuser/bulk/{bulkid}


QueryString n/a



Response Message Body BulkStatus

Response Status 200, 400, 401, 403, 404, 415, 500


OL-26134-01


{<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><resourceStatusstatus = "SUCCUESS"description = "created by bulk request"id = "23d068d0-873a-11e2-bad4-00215edbb2a8"/>

...

<resourceStatusstatus = "SUCCUESS"description = "created by bulk request"id = "23cfa580-873a-11e2-bad4-00215edbb2a8"/>

</resourcesStatus></ns2:bulkStatus>}

Change a Sponsor’s PasswordThis operation allows you to change the password of the sponsor who is currently logged in. This requires using the portal ID.

Change a Sponsor’s Password Example

RequestPUT https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/changeSponsorPassword/88888 Host: cisco.com Authorization: Basic xxxxxxxxxxxxxxxxxxxContent-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml


Description Update the logged-in sponsor’s password

Synopsis PUT /ers/config/guestuser/changeSponsorPassword/{portalId}


QueryString n/a




Response Status 200, 400, 401, 403, 404, 415, 500


OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Portals

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


External RESTful Services APIs for PortalsThe following table lists the External RESTful Services APIs for Portals:

Get All PortalsThe following table lists the main characteristics of the Get All Portals API call:

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

Table 7-45 APIs Available for Portals


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

Table 7-46 Main Characteristics of Get All Portals API Call

Description Retrieve a collection of portals

Synopsis GET /ers/config/portal






Response Status 200, 400, 401, 403, 404, 415,500


OL-26134-01


Sample Response for Get All Portals Call

HTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-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 IDThe following table lists the main characteristics of the Get Portal by ID API call:

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 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-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">

Table 7-47 Main Characteristics of Get Portal by ID API Call

Description Retrieve the specified portal

Synopsis GET /ers/config/portal/{id}


QueryString N/A



Response Message Body Resource of type Portal

Response Status 200, 400, 401,403, 404, 415, 500


OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Profiles

<dictionaryLabelKey>ui_last_name_label</dictionaryLabelKey> <labelName>Last name</labelName>

<required>true</required> </GuestUserField> </GuestUserFieldList></ns3:portal>}

External RESTful Services APIs for ProfilesThe following table lists the External RESTful Services APIs for Profiles:

Get All ProfilesThe following table lists the main characteristics of the Get All Portals API call:

Sample Request for Get All Profiles Call

GET https://<ISE-ADMIN-NODE>:9060/ers/config/profilerprofile Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/vnd.com.cisco.ise.identity.profilerprofile.1.0+xml

Sample Response for Get All Profiles Call

HTTP/1.1 200 OKDate: Thu, 12 Jul 2014 23:59:59 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>



Get All Profiles GET /ers/config/profilerprofile n/a Page, Size, sortacs or sortdsn, Filter

Get Profile by ID GET /ers/config/profilerprofile/{id}

n/a

Table 7-49 Main Characteristics of Get All Portals API Call

Description Retrieve a collection of profiles

Synopsis GET /ers/config/profilerprofile






Response Status 200, 400, 401, 403, 404, 415,500


OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Network Devices

<ns2:searchResult total="2" xmlns:ns2="ers.ise.cisco.com"> <nextPage type="application/xml" href="link-to-next-page" rel="next"/> <previousPage type="application/xml" href="link-to-previous-page" rel="previous"/> <resources> <resource name="name1" id="id1" description="description1"/> <resource name="name2" id="id2" description="description2"/> </resources></ns2:searchResult>

Get Portal by IDThe following table lists the main characteristics of the Get Profile by ID API call:

Sample Request for Get Portal by ID Call

GET https://<ISE-ADMIN-NODE>:9060/ers/config/profilerprofile/333 Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/vnd.com.cisco.ise.identity.profilerprofile.1.0+xml

Sample Response for Get Portal by ID Call


<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns3:profilerprofile name="name" id="id" description="description" xmlns:ns2="ers.ise.cisco.com" xmlns:ns3="identity.ers.ise.cisco.com"/

External RESTful Services APIs for Network DevicesThe following table lists the External RESTful Services APIs for Network Devices:

Table 7-50 Main Characteristics of Get Portal by ID API Call

Description Retrieve the specified profile

Synopsis GET /ers/config/profilerprofile/{id}


QueryString N/A



Response Message Body Resource of type Profile

Response Status 200, 400, 401,403, 404, 415, 500


OL-26134-01


Get All Network DevicesThe following table lists the main characteristics of the Get All Network Devices API call:

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 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-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>



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 networkdevice

Update Network Device PUT /ers/config/networkdevice/{id}

networkdevice

Delete Network Device DELETE /ers/config/networkdevice/{id}

n/a

Get Network Device Resource Version Info

GET /ers/config/ networkdevice /versioninfo

n/a

Table 7-52 Main Characteristics of Get All Network Devices API Call

Description Retrieve a collection of network device resources

Synopsis GET /ers/config/networkdevice






Response Status 200, 400, 401, 403, 404, 415, 500


OL-26134-01


<resource 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"/> </resource> </resources> </ns2:searchResult>}

Get Network Device by IDThe following table lists the main characteristics of the Get Network Device by ID API call:

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 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-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>

Table 7-53 Main Characteristics of Get Network Device by ID API Call

Description Retrieve the specified network device

Synopsis GET /ers/config/networkdevice/{id}


QueryString N/A



Response Message Body Resource of type Network Device

Response Status 200, 400, 401, 403, 404, 415, 500


OL-26134-01


<mask>32</mask> </NetworkDeviceIP> </NetworkDeviceIPList> <modelName>Unknown</modelName> <NetworkDeviceGroupList> <NetworkDeviceGroup>1d8c62b0-2539-11e3-84ad-00215edbb2a8</NetworkDeviceGroup> <NetworkDeviceGroup>37053aa0-2539-11e3-84ad-00215edbb2a8</NetworkDeviceGroup> </NetworkDeviceGroupList> <softwareVersion>Unknown</softwareVersion></ns3:networkdevice>}

Create Network DeviceThe following table lists the main characteristics of the Create Network Device API call:

Sample Request for Create Network Device Call

POST https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevice/ Authorization: Basic xxxxxxxxxxxxxxxxxxxContent-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-84ad- 00215edbb2a8</NetworkDeviceGroup> <NetworkDeviceGroup>37053aa0-2539-11e3-84ad-

Table 7-54 Main Characteristics of Create Network Device API Call

Description Create a specified network device

Synopsis POST /ers/config/networkdevice/


QueryString N/A

Request Message Body NetworkDevice



Response Status 200, 400, 401, 403, 415, 500


OL-26134-01


00215edbb2a8</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 GMTContent-Type: application/vnd.com.cisco.ise.network.networkdevice.1.0+xmlLocation: https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevice/444

Update Network DeviceThe following table lists the main characteristics of the Update Network Device API call:

Sample Request for Update Network Device Call

PUT https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevice/333 Authorization: Basic xxxxxxxxxxxxxxxxxxxContent-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 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-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">

Table 7-55 Main Characteristics of Update Network Device API Call

Description Update a specified network device

Synopsis PUT /ers/config/networkdevice/{id}


QueryString N/A

Request Message Body NetworkDevice



Response Status 200, 400, 401, 403, 415, 500


OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for Network Device Groups

<updatedField field="name"> <newValue>nd2_updated</newValue> <oldValue>nd2</oldValue> </updatedField> <updatedField field="enableKeywrap"> <newValue>true</newValue> <oldValue>false</oldValue> </updatedField></ns2:updatedFields>}

Delete Network DeviceThe following table lists the main characteristics of the Delete Network Device API call:

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


External RESTful Services APIs for Network Device GroupsThe following table lists the External RESTful Services APIs for Network Device Groups:

Table 7-56 Main Characteristics of Delete Network Device API Call

Description Delete a specified network device

Synopsis DELETE /ers/config/networkdevice/{id}


QueryString N/A




Response Status 200, 204, 400, 401, 403, 404, 415, 500

Table 7-57 APIs Available for SGTs


Get All Network Device Groups

GET /ers/config/networkdevicegroup

n/a page, size, sortacs or sortdsn, filter


OL-26134-01


Get All Network Device GroupsThe following table lists the main characteristics of the Get All Network Device Groups API call:

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 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-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-00215edbb2a8" rel="self"/> </resource>

Get Network Device Group

GET /ers/config/networkdevicegroup/{id}

n/a

Get Network Device Group Resource Version Info

GET /ers/config/networkdevicegroup/versioninfo

n/a

Table 7-57 APIs Available for SGTs (continued)


Table 7-58 Main Characteristics of Get All Network Device Groups API Call

Description Retrieve a collection of Network Device Groups resources

Synopsis GET /ers/config/networkdevicegroup






Response Status 200, 400, 401, 403, 404, 415, 500


OL-26134-01


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

Get Network Device GroupThe following table lists the main characteristics of the Get Network Device Groups API call:

Sample Request for Get Network Device Group API Call

GET https://<ISE-ADMIN-NODE>:9060/ers/config/networkdevicegroup/333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.network.networkdevicegroup.1.0+xml

Sample Response for Get Network Device Group API Call

HTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.network.networkdevicegroup.1.0 +xmlContent-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>}

Table 7-59 Main Characteristics of Get Network Device Group API Call

Description Retrieve the specified Network Device group

Synopsis GET /ers/config/networkdevicegroup/{id}


QueryString N/A



Response Message Body Resource of type NetworkDeviceGroup

Response Status 200, 400, 401, 403, 404, 415, 429, 500


OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for SGTs

External RESTful Services APIs for SGTsThe following table lists the External RESTful Services APIs for SGTs:

Get All SGTsThe following table lists the main characteristics of the Get All SGTs API call:

Sample Request for Get All SGTs API Call

GET https://<ISE-ADMIN-NODE>:9060/ers/config/sgt?page=0&size=20&sortacs=nameAuthorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.sga.sgt.1.0+xml

Sample Response for Get All SGTs API Call

HTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.ers.searchresult.1.0+xmlContent-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"/>

Table 7-60 APIs Available for SGTs


Get All SGTs GET /ers/config/sgt n/a page, size, sortacs or sortdsn, filter

Get SGT GET /ers/config/sgt/{id1}

1. The SGT ID is the UUID type as stored in the Cisco ISE database.

n/a

Get GST Resource Version Info

GET /ers/config/sgt/versioninfo n/a

Table 7-61 Main Characteristics of Get All SGTs API Call

Description Retrieve a collection of SGT resources

Synopsis GET /ers/config/sgt






Response Status 200, 400, 401, 403, 404, 415, 429, 500


OL-26134-01

Chapter 7 External RESTful Services API Operations External RESTful Services APIs for SGTs

</resource> </resources></ns2:searchResult>}

Get SGT by IDThe following table lists the main characteristics of the Get SGT by ID API call:

Sample Request for Get SGT by ID API Call

GET https://<ISE-ADMIN-NODE>:9060/ers/config/sgt/333Authorization: Basic xxxxxxxxxxxxxxxxxxxAccept: application/vnd.com.cisco.ise.sga.sgt.1.0+xml

Sample Response for Get SGT by ID API Call

HTTP/1.1 200 OKDate: Thu, 12 Jul 2012 23:59:59 GMTContent-Type: application/vnd.com.cisco.ise.sga.sgt.1.0+xmlContent-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>}

Table 7-62 Main Characteristics of Get SGTs API Call

Description Retrieve the specified SGT

Synopsis GET /ers/config/sgt/{id}


QueryString N/A




Response Status 200, 400, 401, 403, 404, 415, 429, 500


OL-26134-01

Chapter 7 External RESTful Services API Operations REST API Client

REST API ClientThe 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.

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


OL-26134-01

https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en

https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en

https://github.com/a85/POSTMan-Chrome-Extension/wiki



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.

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

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


OL-26134-01




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 For more information on the Accept Header, see Accept Header, page 7-58.

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


URI

The POST method sends the URI to the Cisco ISE server. A typical URI must adhere to the following format:





Note The URI is not the request body; it is just a URL. This URL is sent to the server using the POST method.


OL-26134-01


Content-Type Header

The Content-Type Header must adhere to the following format:






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

Making the POST Request Using POSTMAN

Procedure




Step 3 From the drop-down menu, choose POST.

Step 4 In the URI bar, enter the URI.






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


OL-26134-01




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

Step 12 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 MethodRequests 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


URI

The PUT method sends the URI to the Cisco ISE server. A typical URI must adhere to the following format:






OL-26134-01


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:






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

Making the PUT Request Using POSTMAN

Procedure




Step 3 From the drop-down menu, choose PUT.

Step 4 In the URI bar, enter the URI.







OL-26134-01




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

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

Step 12 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 MethodDeletes 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


URI

The DELETE method sends the URI to the Cisco ISE server. A typical URI must adhere to the following format:



OL-26134-01





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:






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

Making the DELETE Request Using POSTMAN

Procedure




Step 3 From the drop-down menu, choose DELETE.

Step 4 In the URL bar, enter the URI.



OL-26134-01








Step 7 Add an accept 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 Accept Header, page 7-64.

Step 8 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.


OL-26134-01



OL-26134-01

Cisco Identity ServicOL-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.

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

A-1es Engine API Reference Guide, Release 1.4

Appendix A Cisco ISE Failure Reasons Report Viewing Failure Reasons

A-2Cisco Identity Services Engine API Reference Guide, Release 1.4

OL-26134-01

Cisco Identity Services Engine API Reference Guide, Release 1 · United States and certain other...

Documents

Transcript of Cisco Identity Services Engine API Reference Guide, Release 1 · United States and certain other...