Cisco Identity Services Engine API Reference Guide, Release 1.1
Using the Change of Authorization REST APIs
Downloads: This chapterpdf (PDF - 92.0KB) The complete bookPDF (PDF - 1.43MB) | Feedback

Using the Change of Authorization REST APIs

Table Of Contents

Using the Change of Authorization REST APIs

Using the CoA Session Management API Calls

Session Reauthentication API Call

Reauth API Output Schema

Invoking the Reauth API Call

Sample Data Returned from the Reauth API Call

Session Disconnect API Call

Disconnect API Output Schema

Invoking the Disconnect API Call

Sample Data Returned from the Disconnect API Call


Using the 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. The CoA API calls provide the means for sending session authentication and session disconnect commands to a specified Cisco Monitoring ISE node in your Cisco ISE deployment.

The following sections provide API output schema file examples, procedures for issuing each API call, and a sample of the data returned by each API call:

Session Reauthentication API Call

Session Disconnect API Call

Using the CoA Session Management API Calls

The CoA session management API calls allow you to send reauthentication and disconnect commands to a specified session on a target Cisco Monitoring ISE node in your Cisco ISE deployment:

Session reauthentication (Reauth)

Session disconnection (Disconnect)

Session Reauthentication API Call

This section provides a schema file output example, a procedure for sending a session reauthentication command and Reauth type by invoking the Reauth API call, and a sample of the data returned after this API call is issued. The reauth types can be any of the following:

REAUTH_TYPE_DEFAULT = 0

REAUTH_TYPE_LAST = 1

REAUTH_TYPE_RERUN = 2

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


Note Make sure that you have verified that the target node to which you are issuing an API call is a valid Cisco Monitoring ISE node. To verify the persona of a Cisco ISE node, see Verifying a Cisco Monitoring ISE Node.


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


Step 1 Log into the target Cisco Monitoring ISE node.

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 2 Enter the Reauth API call in the URL Address field of the target node by replacing the "/admin/" component with the API call component (/ise/mnt/api/CoA/<specific-api-call>/<macaddress>/
<reauthtype>/<nasipaddress>/<destinationipaddress>):

https://acme123/ise/mnt/api/CoA/Reauth/server12/00:26:82:7B:D2:51/2/10.10.10.10

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.


Step 3 Press Enter to issue the API call.


Sample Data Returned from the Reauth API Call

The following example illustrates the data returned when you invoke a Reauth API call on a target Cisco Monitoring ISE node. Two possible results can be returned from invoking this command:

True indicates that the command was successfully executed.

False means that the command was not executed (due to a variety of conditions).

This XML file does not appear to have any style information associated with it. The 
document tree is shown below.
 
   
-
<remoteCoA requestType="reauth">
<results>true</results>
</remoteCoA>

Session Disconnect API Call

This section provides a schema file output example, a procedure for sending a session disconnect command and a port option type by invoking the Disconnect API, and a sample of the data returned after this API call is issued. The disconnect port option types can be any of the following:

DYNAMIC_AUTHZ_PORT_DEFAULT = 0

DYNAMIC_AUTHZ_PORT_BOUNCE = 1

DYNAMIC_AUTHZ_PORT_SHUTDOWN = 2

Disconnect API Output Schema

This sample schema file is the output of the Disconnect API call after sending it to a specified session on the target Cisco Monitoring ISE node:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 
   
  <xs:element name="remoteCoA" type="coAResult"/>
 
   
  <xs:complexType name="coAResult">
    <xs:sequence>
      <xs:element name="results" type="xs:boolean" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="requestType" type="xs:string"/>
  </xs:complexType>
</xs:schema>

Invoking the Disconnect API Call


Note Make sure that you have verified that the target node to which you are issuing an API call is a valid Cisco Monitoring ISE node. To verify the persona of a Cisco ISE node, see Verifying a Cisco Monitoring ISE Node.


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


Step 1 Log into the target Cisco Monitoring ISE node.

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 2 Enter the Disconnect API call in the URL Address field of the target node by replacing the "/admin/" component with the API call component (/ise/mnt/api/CoA/<Disconnect>/<serverhostname>/
<macaddress>/<portoptiontype>/<nasipaddress>/<destinationipaddress>):

https://acme123/ise/mnt/api/CoA/Disconnect/server12/ 
00:26:82:7B:D2:51/2/10.10.10.10

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.


Step 3 Press Enter to issue the API call.


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 from invoking this command:

True indicates that the command was successfully executed.

False means that the command was not executed (due to a variety of conditions).

This XML file does not appear to have any style information associated with it. The 
document tree is shown below.
 
   
-
<remoteCoA requestType="reauth">
<results>true</results>
</remoteCoA>