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.

Introduction

Cisco Identity Services Engine (ISE) is a security policy management platform that provides secure access to network resources. Cisco ISE allows enterprises to gather real-time contextual information from networks, users, and devices. An administrator can then use this information to make proactive governance decisions by creating access control policies for the various network elements, including access switches, Cisco Wireless Controllers, Virtual Private Network (VPN) gateways, and data center switches. Cisco ISE acts as the policy manager in the Cisco TrustSec solution and supports TrustSec software-defined segmentation.

Cisco ISE is available on Secure Network Server appliances with different performance characterizations, and also as software that can be run on a virtual machine (VM). Note that you can add more appliances to a deployment for better performance.

Cisco ISE has a scalable architecture that supports standalone and distributed deployments, but with centralized configuration and management. It also enables the configuration and management of distinct personas and services, thereby giving you the ability to create and apply services where needed, in a network, but operate the Cisco ISE deployment as a complete and coordinated system.

Use Cases

A Cisco ISE administrator can gather real-time contextual data for a network, including users and user groups (who?), device type (what?), access time (when?), access location (where?), access type (wired, wireless, or VPN) (how?), and network threats and vulnerabilities.

For more information about the features that are supported by Cisco ISE, see the Cisco Identity Services Engine Administrator Guide.

To access documentation on cisco.com, go to End-User Documentation.

Cisco ISE API Service

The Cisco ISE API service provides a framework for developing and deploying web applications in the Cisco ISE environment. This feature documents the REST APIs, that can be used to generate code in different languages as well as share them across users for understanding the APIs. The Cisco ISE API service is based on OpenAPI specification, which is a broadly accepted industry standard for describing REST APIs.

The API Gateway must be enabled for accessing an API service. All API service requests enter Cisco ISE through the API Gateway in both standalone and distributed Cisco ISE deployments. The API Gateway receives API service requests through port 443.

In the standalone Cisco ISE node, after receiving the API request, the API Gateway forwards the request to the API service.

In a distributed environment, the read requests are forwarded to either a PSN or a primary PAN, but the write requests are forwarded only to the primary PAN. The primary PAN is the only node that has the write authority in the deployment environment.

You must assign special privileges to a user operating on API services. API service users can be either internal users or belong to an external Microsoft Active Directory group. The internal users or the Active Directory group to which the external users belong must be mapped to either ERS Admin or ERS Operator groups:

  • ERS Admin: These users can create, read, update, and delete ERS API requests. They have full access to all ERS APIs (GET, POST, DELETE, and PUT).
  • ERS Operator: These users have read-only access (GET requests only).

Note: A user with the role Super Admin can access all API services.

Cisco ISE allows API access to manage Cisco ISE nodes through two sets of API formats:

  • External Restful Services (ERS) APIs
  • Open APIs

  1. ERS APIs are REST APIs that are based on the HTTPS protocol and operate over the standard HTTPS port 443 (port 9060 can also be used). The ERS APIs support basic authentication. The authentication credentials are encrypted and are part of the request header. You can use any REST client such as JAVA, cURL Linux command, Python, or any other client to invoke ERS' API calls.

    Note:

    • ERS APIs support TLS 1.1, TLS 1.2, and TLS 1.3, but not TLS 1.0 even if TLS 1.0 has been enabled in the Security Settings window (Administration > System > Settings > Security Settings). Enabling TLS 1.0 in the Security Settings window is related to only the EAP protocol and does not impact ERS APIs.

    • ERS session idle timeout is 60 sec. If several requests are sent during this period, the same session is used with the same Cross-Site Request Forgery (CSRF) token. If the session has been idle for more than 60 sec, the session is reset and a new CSRF token is used.

    For more information on Cisco ISE ERS APIs, go to https://{ise-ip}/ers/sdk.

    The ERS service is enabled by default when the Amazon Machine Image (AMI) version of Cisco ISE is deployed in the VMware Cloud environment. This helps in easy integration of Cisco ISE with other Cisco products and third-party applications, without the need to enable the ERS service from the Cisco ISE GUI.

    Open API specification for ERS: The Open API specification (JSON file) for ERS APIs is available for download in the Cisco ISE GUI, in the Overview section of the API Settings window (Administration > SystemSettings > API Settings > Overview). This Open API JSON file can be used for auto-generation of API client code using any programming language such as Python, JAVA and so on. For additional information about Open API specifications and tools, see https://openapi.tools/.

  2. Open APIs are REST APIs based on HTTPS, operating in port 443. From Cisco ISE Release 3.1, newer APIs are available in the Open API format. For more information on Cisco ISE Open APIs, go to https://{ise-ip}/api/swagger-ui/index.html.

    The following Open APIs have been introduced in Cisco ISE, Release 3.1:

    • Repository: These APIs provide the ability to manage the repositories. You can create, retrieve, update, and delete the repository configuration and list the files from the configured repositories.

    • Configuration Data Backup and Restore: These APIs provide the ability to manage the backup and restore operations. They enable you to create, cancel, update, and restore the configuration backup, and also list the status of the last backup. Users can create and edit the backup schedule as well.

    • Certificate: These APIs provide the ability to manage certificates. They enable you to create, retrieve, update, and delete system certificates, and trusted certificates, create Certificate Signing Requests (CSRs), and export and import certificates.

    • Policy : These APIs provide the ability to manage policies. They are of two types:

      • RADIUS Policy : These APIs provide the ability to manage RADIUS policies. They enable you to get lists of all the required boundaries (Authorization Profile, SecurityGroup, IdentityStores, Profiles) and the Discovery Dictionary Filter Helper. These APIs allow Dictionaries and Attributes management, Conditions management (Library, Network, Time, and Date Conditions), and Policy Set management, including AuthN rules, Authz rules, Exception rules, and Global Exception rules.
      • TACACS+ Policy: These APIs provide the ability to manage TACACS+ Policies. They enable you to get lists of all the required boundaries (Command Sets, TACACS Profiles, IdentityStores, ServiceNames) and Discovery of Dictionary related to TACACS Helper. These APIs allow Conditions management (Library, Network, Time and Date Conditions), and Policy Set management including AuthN rules, Authz rules, Exception rules, and Global Exception rules.

    • TrustSec: These APIs provide the ability to manage TrustSec related operations such as Virtual Networks(VNs), Security Group - Virtual Network mappings(SG-VN mappings), and VN-VLAN mappings.

    • Task Service: These APIs provide the ability to monitor the status of various tasks carried out in Cisco ISE.

    • Deployment: These APIs provide the ability to configure the Cisco ISE nodes and set up the deployment.

    • Patch and Hot Patch: These APIs provide the ability to carry out patch related operations such as installing a patch, removing a patch, listing all the installed patches and so on. Note This API works only when primary PAN services are up. If the primary PAN services are down, the API call on the secondary PAN fails.

    • License: These APIs provide the ability to register, enable and manage smart licensing.

Note:

  • In a Cisco ISE cloud setup, the firewall rule should be opened using iptables to access the API documentation page in AWS cloud.
  • The IP address present in the OpenAPI requests, and coming from a subnet is expected to be shown as a remote IP address from that network.

Enable API Service

API services are disabled by default. If you evoke any API calls before you enable the API services in Cisco ISE, you receive an error message. Enable the Cisco ISE REST API feature for the applications developed for a Cisco ISE REST API to be able to access Cisco ISE. The ERS APIs use the standard HTTPS port 443 (port 9060 can also be used) and the Open APIs use the HTTPS port 9070. Both these ports are disabled by default. If the API services are not enabled in the Cisco ISE administration server, the client application receives a timeout error from the server for any guest REST API requests.

  1. In the Cisco ISE GUI, click the Menu icon and choose Administration > System > Settings > API Settings > API Service Settings.

  2. In the API Service Settings for Primary Administration Node area, click the ERS (Read/Write) toggle button to enable ERS on the Primary Administration node (PAN), or click the Open API (Read/Write) toggle button to enable Open API services on the PAN.

  3. In the API Service Settings for All Other Nodes area, click the ERS (Read) toggle button to enable the ERS on all other nodes, or click the Open API (Read) toggle button to enable Open API service.

  4. In the CSRF Check area, click the radio button for one of the following options:

  • Use CSRF Check for Enhanced Security: If this option is enabled, the ERS client must send a GET request to fetch the CSRF token from Cisco ISE and include the CSRF token in the requests that are sent to Cisco ISE. Cisco ISE will validate a CSRF token when a request is received from the ERS client. Cisco ISE processes the request only if the token is valid. This option is not applicable for ERS clients earlier than Cisco ISE Release 2.3.

  • Disable CSRF for ERS Request: If this option is enabled, CSRF validation is not performed. This option can be used for ERS clients earlier than Cisco ISE Release 2.3.

  1. Click Save.

Cisco ISE API Gateway

The Cisco ISE API Gateway is an API management solution that acts as a single entry point to multiple Cisco ISE service APIs to provide better security and traffic management. API requests from external clients are routed to the API Gateway in Cisco ISE. The requests are forwarded to the Cisco ISE nodes where service APIs are running, based on an internal algorithm.

api-gateway

From Cisco ISE Release 3.1 onwards, the MnT (Monitoring) APIs, the ERS APIs and the Open APIs all are routed through the API Gateway. The following ports need to opened between the API gateway node and all other nodes in the deployment for the respective APIs.

  • MnT APIs: 9443
  • Open APIs: 9070
  • ERS APIs: standard HTTPS port 443 (port 9060 can also be used)

You can choose the Cisco ISE nodes on which you want to enable the API Gateway. We recommend that you run the API Gateway on at least two nodes in your Cisco ISE deployment.

The API Gateway is enabled by default in case of a standalone deployment. In case of a distributed deployment, the API Gateway is enabled by default on the primary PAN, provided the API Gateway is not enabled on any other node in the deployment.

  1. Log in to the primary PAN.

  2. In the Cisco ISE GUI, click the Menu icon and choose Administration > System > Settings > API Settings > API.

  3. In the ISE API Gateway Nodes List area, check the check boxes next to the nodes on which you want to enable the API Gateway.

  4. Click Enable.

Cisco ISE provides different APIs for GET and UPDATE operations for the API Gateway. In the examples below, we have considered only 2 Cisco ISE nodes. The code can be modified based on the number of nodes in the deployment.

  1. GET
  • URL: https://<ise-node>/admin/API/apiGateway/get
  • Response: [ { "id": "1234", "hostname": "<ise-node1>", "isEnabled": true }, { "id": "5678", "hostname": "<ise-node2>", "isEnabled": false } ]
  1. UPDATE
  • Request Type: POST
  • URL: https://<ise-node>/admin/API/apiGateway/update
  • Request Body: [{"hostname": "<ise-node1>","isEnabled": "true"},{"hostname": "<ise-node2>","isEnabled": "false"}]