Introduction to the Monitoring REST API

Note: The documentation set for this product strives to use bias-free language. For purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product.

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.

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 the following image, 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.

Monitoring REST API Calls in a Distributed Deployment

To perform operations using the Monitoring REST APIs, the users must be assigned to one of the following Admin Groups and must be authenticated against the credentials stored in the Cisco ISE internal database (internal admin users):

  • Super Admin
  • System Admin
  • MnT Admin

Monitoring REST APIs are only supported for internal users. Communication with the external ID stores is not supported for the following reasons:

  • It can be seen as a DoS attack from Cisco ISE to the RADIUS token server (sending unnecessary requests) as Monitoring REST APIs have a high call frequency.
  • There is delay in the API response, since the API first authenticates with the external ID store and then goes for the internal users.
  • The user accounts can get locked on the RADIUS token server due to excessive failed logins.

The following Monitoring REST API categories are supported:

  • Session Management
  • Troubleshooting
  • Change of Authorization (CoA)

You can use these APIs to gather information about endpoints being monitored by the Monitoring persona. 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.

Verifying a Monitoring Node

Before you Begin

Before you can successfully invoke the API calls on a Monitoring node, you need to verify that the node you want to monitor is valid.

To be able to use a public Monitoring REST API, you must first authenticate with Cisco ISE using valid credentials.

  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.

  2. Choose Administration > System > Deployment.

    The Deployment Nodes page appears, which lists all configured nodes that are deployed.

  3. In the Roles column of the Deployment Nodes page, verify that the role for the target node that you want to monitor is listed as a Monitoring node.

Supported API Calls

The following tables describe the different types of API calls and provide an example of the API call format:

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.

 

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

  • You must add the HTTP authorization header with the authorization credentials to view the number of active sessions.

PostureCount

Lists the number of Postured endpoints.

https://<ISEhost>/admin/API/mnt/Session/PostureCount

  • 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

  • Profiler is a service that aids in identifying, locating, and determining the capabilities of all attached endpoints on a Cisco ISE network.

Session List

  • A session list includes the MAC address, network access device (NAD) IP address, username, and session ID information associated with a session.

ActiveList

Lists all active sessions.

https://<ISEhost>/admin/API/mnt/Session/ActiveList

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

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
  • Every Cisco ISE node is configured with a time zone. Recommended time zone is UTC.

See Sample Data Returned from the AuthList API Call, for samples that show all four parameter options.

Session Attributes

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

  • Make sure that you specify the MAC address using the XX:XX:XX:XX:XX:XX format. The MAC address input is case sensitive. Only uppercase characters are accepted for the MAC address input.
  • 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>

  • 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.
  • Cisco ISE Monitoring REST API doesn't work when username contains a domain. The workaround is to change the API method from GET to POST. For example:
    curl -X POST -k \
    -H 'Accept: application/xml' \
    -H 'Content-Type: application/xml' \
    -i 'https://ise31.securitydemo.net/admin/API/mnt/Session/UserName' \
    --data 'employee1@demo.local'

IPAddress

Searches the database for the latest session that contains the specified NAS IP address (IPv4 or IPv6 address).

https://<ISEhost>/admin/API/mnt/Session/IPAddress/<nasipaddress>

  • xxx.xxx.xxx.xxx is the NAS IP address format (for example, 10.10.10.10)

or

https://<ISEhost>/admin/API/mnt/Session/IPAddress/<nasipv6address>

  • xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx is the NAS IPv6 address format (for example, 2001:cdba:0:0:0:0:3247:9651)

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

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

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

 

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

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

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

AuthStatus

Lists the authentication status for all sessions.

https://<ISEhost>/admin/API/mnt/AuthStatus/MACAddress/<macaddress>/<numberofseconds>/<numberofrecordspermacaddress>/All

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

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

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

 

Cisco ISE Change of Authorization API Calls

API Call

Description and Example

Reauth

Sends a session reauthentication command and type.

https://<ISEhost>/admin/API/mnt/CoA/Reauth/<serverhostname>/
<macaddress>/<reauthtype>/<nasipaddress>/
<destinationipaddress>

Where <ISEhost> denotes the IP address of the Cisco ISE MnT node to which the call is sent, <serverhostname> denotes the Cisco ISE PSN that owns the endpoint session, <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

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

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

x-bbedit-document:///untitled%20text%208?93 0—DYNAMIC_AUTHZ_PORT_DEFAULT

1—DYNAMIC_AUTHZ_PORT_BOUNCE

2—DYNAMIC_AUTHZ_PORT_SHUTDOWN

  • If you do not know the NAS IP address, enter the required values up to that point and the API will use these values in its search query. However, you must know the MAC address to perform this API call, but you can leave other parameters as null.

For details about Cisco ISE Change of Authorization API calls, see Change of Authorization REST APIs.

HTTP PUT API Calls

Similar to AuthStatus API call, 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>

</xs:schema>