External RESTful Services is based on HTTPS and REST methodology and uses port 9060. This chapter provides guidelines and examples for using the External RESTful Services application programming interface (API) supported by Cisco ISE as well as related API calls used to perform Create, Read, Update, Delete (CRUD) operations.
These APIs provide an interface to the ISE configuration data by enabling users, endpoints, endpoint groups, identity groups and SGTs to perform CRUD operations on the ISE data.
The HTTPS port 9060 is closed by default. The first requirement to use the API is to enable External RESTful Services from the ISE CLI.
Note If you try to invoke External RESTful Services API calls prior to enabling from the CLI, you will receive a response status as 403- “forbidden”.
External RESTful Services has a debug logging category, which you can enable in Cisco ISE on the debug logging page. For more information, see the Debug Log Configuration Options section of Cisco Identity Services Engine User Guide, Release 1.2 .
All Representational State Transfer (REST) operations are audited and logged in the system.
Enabling the External RESTful Services API
CRUD data sent to the server is validated with the same validation rules that Cisco ISE has for the GUI. All validation is centralized in a validation layer. All XML data being posted is validated against the schema.
Two types of validation occur: data validation and structural validation. Data validation validates the data to be Cisco ISE compliant, for example, mandatory fields, field length, types, and so on. While structural validation validates the schema. For example, fields order, names, and so on.
You should maintain strict namespaces within resources names and Uniform Resource Identifiers (URIs), including:
The Accept/Content-Type headers should contain the following namespace:
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 following namespace definition:
For example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
Note A hard reboot or reload disables the ERS API in Cisco ISE 1.2. You will need to use the following instructions to re-enable the ERS API.
Step 1 Run the command application configure ise .
Step 2 The following options are displayed on the screen:
Step 3 Enter 6 and press Enter .
The following message appears:
Current External RESTful Services State: disabled
By proceeding, External RESTful Services port 9060 will be opened and External RESTful Services API will be enabled
Are you sure you want to proceed? y/n [n]:
Step 4 Enter y and press Enter .
The following message appears:
Enabling External RESTful Services port 9060...
External RESTful Services API enabled
Step 5 Verify if the External RESTful Services API is enabled by accessing the External RESTful Services SDK page at the following URL: https://<ipaddress>:9060/ers/sdk. You should always add the port number as 9060 to access the SDK.
You must create an ISE Administrator with the External RESTful Services Admin group in order to use the APIs. For more information on creating admin users, refer to the following section in the Cisco Identity Services User Guide, Release 1.2:
http://www.cisco.com/en/US/docs/security/ise/1.2/user_guide/ise_man_admin.html#wp1579129
To Use the External RESTful Services API, an HTTPS client is required. You can use a curl command to post requests to the server, write your own Python scripts or Java clients. You can also use any HTTP posting tool such as the POSTMAN plugin from Chrome browser. Now External RESTful Services is enabled and ready, you can start using it.
In External RESTful Services, resource representations and request bodies are normally encoded in XML (as specified in RFC4267). Each type of resource has its own media-type, which matches the following pattern:
application/vnd.com.cisco.ise.xxx.yyy.version+xml;charset=UTF-8
Where "xxx" represents the namespace, "yyy" the resource, and version specifies the resource version used by the client. (RFC 3023). For example, the MediaType for Internal User resource with schema version 1.0 is represented as follows:
application/vnd.com.cisco.ise.identity.internaluser.1.0+xml;charset=UTF-8
The External RESTful Services API must provide representations of all resources available in XML. Whenever the requested media type is not supported by the Cisco ISE server, status 415 will be returned with a list of causes such as "Resource version is no longer supported".
In requests made to External RESTful Services, several specific HTTP headers are used as described in Table 5-1 .
In responses returned by the External RESTful Services, several specific HTTP headers are used as described in Table 5-2 .
External RESTful Services returns common HTTP response codes as described in Table 5-3 . In addition to the status codes returned in the response header, each request might have additional XML content according to the nature of the request.
The External RESTful Services API provides backward compatibility with previous Cisco ISE versions through a versioning mechanism. Because Cisco ISE, Release 1.2, is the first External RESTful Services release, all resources are 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:
After authenticating and authorizing the request, a version-match check is performed with one of the following matching results:
The server adds a response warning message describing the versions gap and proceeds processing the request. |
|
The server returns status 415 with a corresponding error message. |
In addition, each resource has an API to retrieve a list of server-supported versions.
The search results by default are paged to 20 resources per page. Page numbering starts at page number 0. The maximum number of resources per page cannot exceed 100. You can override the defaults by using the paging parameters. Paging parameter are passed in the URI using query parameters.
For example, to get the first 50 records of an internal user sorted in ascending order by the “name” field, the following request is passed:
By default, the search results are sorted according to the column name in an ascending order. You can override the default sort settings by specifying the sorting parameters. You can pass the sorting parameters in the URI using query parameters. You can specify 'sortasc' (ascending order) or 'sortdsc' (descending order) parameters to override the default settings.
For example, to sort the first 50 records of an internal user in a descending order by the “name” field, the following request is passed:
GET /ers/config/internaluser?filter=name.STARTW.a&filter=identityGroup.EQ.Finance&size=50&page=0&sortdsc=name
You can perform simple filtering operations through the filter query string parameter. You can send more than one filter. The logical operator common to all filter criteria is AND by default. 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 a first name starting with ‘a’ and belonging to the ‘Finance’ identity group, the following request is passed:
The following filter parameters are available:
External RESTful Services data model defines the representations of the RESTful resources that the External RESTful Services API operates up on. The representations are made up of fields, each with a name and value, encoded using an XML dictionary. The values are numeric or string literals, lists, or dictionaries, each of which are represented in XML.
Each type of resource contains its own internet media type. The internal media type must conform to the following pattern:
application/vnd.com.cisco.ise.resource.version+xml;charset=UTF-8
The media type corresponding to each RESTful resource is included in square brackets in the section header.
In the resource model descriptions, fields annotated with [POST] are included in a POST request that is used to create new resources. Similarly, fields annotated with [PUT] are included in a PUT request that is used to update properties of existing resources. You must not include fields that are not annotated in the request body of the PUT or POST requests. Such requests are ignored by the server.
Each resource contains a base representation that constitutes a set of attributes or fields mentioned in the following table:
The internet media type for the internal user must conform to the following format:
application/vnd.com.cisco.ise.identity.internaluser.1.0+xml
An internal user data model contains the set of attributes or fields mentioned in the following table:
The internet media type for the internal user must conform to the following format:
application/vnd.com.cisco.ise.identity.endpoint.1.0+xml
An Endpoint data model contains the set of attributes or fields mentioned in the following table:
The internet media type for the Endpoint identity group must conform to the following format:
application/vnd.com.cisco.ise.identity.endpointgroup.1.0+xm
An Endpoint identity group data model contains the set of attributes or fields mentioned in the following table:
The internet media type for the identity group must conform to the following format:
application/vnd.com.cisco.ise.identity.identitygroup.1.0+xml
An identity group data model contains the set of attributes or fields mentioned in the following table:
The internet media type for the SGTs must conform to the following format:
application/vnd.com.cisco.ise.sga.sgt.1.0+xml
An SGT data model contains the set of attributes or fields mentioned in the following table:
The internet media type for the VersionInfo data model must conform to the following format:
application/vnd.com.cisco.ise.ers.versioninfo.1.0+xml
A VersionInfo data model contains the set of attributes or fields mentioned in the following table:
The internet media type for the SearchResult data model must conform to the following format:
application/vnd.com.cisco.ise.ers.searchresult.1.0+xml
A SearchResult data model contains the set of attributes or fields mentioned in the following table:
The internet media type for the External RESTful Services Response data model must conform to the following format:
application/vnd.com.cisco.ise.ersresponse.1.0+xml
An External RESTful Service Response data model contains the set of attributes or fields mentioned in the following table:
The internet media type for the Response message data model must conform to the following format:
application/vnd.com.cisco.ise.ersresponse.1.0+xml
A Response message data model contains the set of attributes or fields mentioned in the following table:
When ever the request fails, a HTTP error status and response content is returned back to client in order to describe the problem. The following table describes possible errors:
The External RESTful Services API is disabled by default and a user with administrative privileges must explicitly enabled it. The External RESTful Services API supports only HTTPS access (using port 9060) and basic HTTP authentication. Plain HTTP access is not supported. The External RESTful Services API implementation employs a mechanism to thwart brute force attacks on the passwords.
The External RESTful Services API runs over HTTPS only and supports basic authentication. The authentication credentials are encrypted and are part of the request header. Authentication is implemented using the basic authentication mechanism corresponding to the Tomcat server.
Note As External RESTful Services applications are completely stateless, no session is managed.
External RESTful Services API provides read-only and full-access level authorization. An administrator must assign special privileges to a user to perform operations using the External RESTful Services. The following two roles can be assigned
If you do not have the required permissions and still try to perform External RESTful Services operations, you will receive an error response.
The External RESTful Services web application is secured against all kinds of injection attacks including Cross Side Scripting, SQL/HQL Injection, Shell Injection, and filename manipulation attacks. Sufficient input validation is also performed.
All External RESTful Services requests are valid only for the primary node. Secondary nodes have only read-access (GET requests).
You can use the External RESTful Services software developer’s kit (SDK) page to build your own tools. You access the page from the following URL: https://<ipaddress>:9060/ers/sdk
The External RESTful Services SDK page can be accessed by Admin users only. It contains the following information:
See Figure 5-1 for all the functions available.
Figure 5-1 External RESTful Services SDK
External RESTful Services SDK is shipped with the following XSD schema files that are supported on the External RESTful Services API:
Step 1 Log in to the External RESTful Services SDK page with the following URL:
https://<ipaddress>:9060/ers/sdk
Step 2 Log in as an External RESTful Services Admin.
Step 3 Click Schema Files available under Downloads .
You can use the files with available tools such as JAXB to generate schema classes.
You can develop HTTP client code or use any third-party HTTP client code and integrate it with the schema classes that are generated from the XSD files.
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.
Common External RESTful Services flows always consist of an HTTPS request sent from a client and an HTTPS response from the server. The flows differ by request types, URIs, request headers, response headers, and response contents.
Common flows will always consist of HTTPS requests sent from the client and an HTTPS response from the ISE server. The flows differ by request types, URI's, request headers, response headers and response contents. Successful requests will generally return an HTTP status code of 200 (OK), 201 (Created), or 204 (No Content), to indicate that the requested action has been successfully performed. In addition, they might include a response message body (with an appropriate media type) containing a representation of the requested information. However, it is possible for a number of things to go wrong. The various underlying causes are described by various HTTP status codes in the range 400-499 (for client side errors) or 500-599 (for server side problems). The description of each request type SHOULD list the possible status codes returned by that request type.
The following figure shows an example of an External RESTful Services success flow.
Figure 5-2 External RESTful Services Success Flow Sequence
It is possible for a number of things to go wrong during the request processing. The various underlying causes are described by various HTTP status codes in the range 400-499 (for client side errors) or 500-599 (for server side problems). The description of each request type SHOULD list the possible status codes returned by that request type. If a response is returned with an error status code (400-499 or 500-599), the server SHOULD also return a response message body containing a messages data model, containing zero or more message data models, describing what went wrong. The text values of such messages might be used, for example, to communicate with a human user of the client side application.
In failed flow, the response content will contain a list of the error messages that caused the failure.
The following figure shows an example of an External RESTful Services failure flow.
Figure 5-3 External RESTful Services Failure Flow Sequence