The Cisco Identity Services Engine API Reference Guide, provides you with guidelines and examples for using the three supported categories of representational state transfer (REST) APIs and related API calls. The REST APIs and calls allow you to gather session and node-specific information by using Cisco Monitoring ISE nodes in your network. A session is defined as the duration between when you start accessing the desired node and completing the set of tasks or operations needed to gather information.
The supported categories of Monitoring REST APIs that are available to users in Cisco ISE, Release 1.1.x are as follows:
– Session Management
Change of Authorization (CoA)
Note You can use only these supported REST API categories to gather information about endpoints being monitored by the Monitoring persona. Monitoring is one of three supported personas that an ISE node type can perform in your Cisco ISE Release 1.1 deployment. For the remainder of this guide, “Monitoring ISE node” will be used to describe the Monitoring persona of a Cisco ISE node.
The REST API calls provide the means for you to locate, monitor, and accumulate important real-time session-based information stored in individual endpoints in your network that you can access through a Cisco Monitoring ISE node.
The real-time session-based information that you gather can prove useful to understand Cisco ISE operations, assist in diagnosing conditions or issues, or be used to troubleshoot error conditions or activity or behavior that you suspect may be affecting your monitoring operations. The role that the REST APIs play in a Cisco ISE distributed deployment is shown in Figure 1-1.
As shown in Figure 1-1, the REST (HTTPS) API calls are used by supported client types: remote Java, browser-based, or PHP (hypertext preprocessor), and for the purpose of accessing the Cisco Monitoring ISE node and retrieving important session-based information that is stored in the Cisco ISE deployment endpoints.
Figure 1-1 Cisco ISE Distributed Deployment and REST APIs
Verifying a Cisco Monitoring ISE Node
Before you can successfully invoke the API calls on a Cisco Monitoring ISE node, you first need to verify that the node you want to monitor is a valid Cisco Monitoring ISE node. To verify this, you need to successfully log into and be authenticated by the Cisco ISE network.
Note To be able to use the public REST APIs, you must first authenticate with Cisco ISE using valid credentials for any of the supported Cisco ISE admin roles (Helpdesk Admin, Identity Admin, Monitoring Admin, Network Device Admin, Policy Admin, RBAC Admin, Super Admin, or System Admin).
To login and be authenticated, complete the following steps:
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 shows its type as a Cisco Monitoring ISE node.
Supported API Calls
This section introduces the REST APIs, which provide an interface for programmatically issuing calls that retrieve and display the node-specific or session-specific information. The following tables list the API category, type of API call, and provide a brief description and an example of the API call format:
Table 1-1—defines the query API calls for session management.
Table 1-2—defines the query API calls for troubleshooting.
Note Before you can perform any of the API calls described in this guide, you first need to log into and be authenticated by the Cisco ISE network. The authentication requirement for using the public REST APIs is explained in Verifying a Cisco Monitoring ISE Node.
If you intend to use a generic programmatic interface to authenticate with the REST API supported by Cisco ISE, you would need to first create a REST-based client that bridges between Cisco ISE and the specific tool you use. You would then use this REST client to perform authentication with the Cisco ISE REST APIs, marshal and submit the API requests to the Monitoring ISE nodes, and unmarshal the API responses and pass these responses on to the specified tool.
Table 1-1 Cisco ISE Query API Calls - Session Management
Cisco ISE API Call Category
Cisco ISE API Call Description and Example
Active sessions counter
Lists the number of currently active sessions:
Posture sessions counter
Lists the number of currently active Posture service sessions:
Note Profiler is a service that aids in identifying, locating, and determining the capabilities of all attached endpoints on your Cisco ISE network.
Simple Session List
Note A simple session list includes the MAC address, network access switch (NAS) IP address, user name, and session ID information associated with a session.The Cisco Identity Services Engine, Release 1.1.x, is not compliant with IPv6.
Note The level of support for IPv6 in Cisco ISE is only as it relates to the node being addressed on an IPv6 network (for example, IPv6 stateless auto-configuration and DHPv6). However, none of the Cisco ISE, Release 1.1.x, protocol stacks (such as runtime or mgmt) supports IPv6.
Active sessions list
Lists all currently active sessions:
Note In this release of Cisco ISE, the maximum number of active authenticated endpoint sessions that can be displayed is limited to 100,000.
Authenticated sessions list
Lists all currently active authenticated sessions:
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.
User name session search
Searches the database for the latest session that contains the specified user name:
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 use case for which the FailureReasons API call is designed addresses the need for it to be called only once to gather the information from the Monitoring ISE 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 you own file system or database.
Reauth type can be any of the following values (0-2): REAUTH_TYPE_DEFAULT = 0 REAUTH_TYPE_LAST = 1 REAUTH_TYPE_RERUN = 2
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.
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 types
Sends a session disconnect command and port option type:
Note Port option type can be any of the following values (0-2): DYNAMIC_AUTHZ_PORT_DEFAULT = 0 DYNAMIC_AUTHZ_PORT_BOUNCE = 1 DYNAMIC_AUTHZ_PORT_SHUTDOWN = 2
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.
Similar to a Get Session Auth Status API call in Table 1-2, there is an HTTP PUT version of a REST API implemented that allows clients to retrieve account status. The REST APIs support both HTTP PUT and HTTP GET calls, with the examples in this guide documenting HTTP GET calls. The HTTP PUT version addresses the need for APIs that require parameter inputs. The following schema file example is a request for account status: