Create ISE Network Devices Using ERS API

Introduction

This document describes the process for creating network access devices (NADs) on ISE via ERS API using PostMan as the REST Client.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• ISE (Identity Services Engine)
• ERS (External RESTful Services)
• REST clients like Postman, RESTED, Insomnia, and so on.

Components Used

The information in this document is based on these software versions:

• Cisco ISE (Identity Services Engine) 3.1 patch 6
• Postman REST client v10.17.4

Note: The procedure is similar or identical for other ISE versions and REST Clients. You can use these steps on all 2.x and 3.x ISE Software Releases unless stated otherwise.

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

Configure

Enable ERS (Port 9060)

ERS APIs are HTTPS-only REST APIs that operate over port 443 and port 9060. Port 9060 is closed by default, so it needs to be opened first. A timeout from the server is presented if clients trying to access this port do not enable ERS first. Therefore, the first requirement is to enable ERS from the Cisco ISE admin UI.

Navigate to Administration > Settings > API Settings and enable the ERS (Read/Write) toggle button.

Note: The ERS APIs support TLS 1.1 and TLS 1.2. ERS APIs do not support TLS 1.0 regardless of enabling TLS 1.0 in the Security Settings window of the Cisco ISE GUI (Administration > System > Settings > Security Settings). Enabling TLS 1.0 in the Security Settings window is related to the EAP protocol only and does not impact ERS APIs.

Create ERS Admin

Create a Cisco ISE Administrator, assign a password, and add the user to the admin group as ERS Admin. You can leave the rest of the configuration empty.

Set up Postman

Download or use the the online version of Postman.

1. Create a user and create a workspace by clicking Create Workspace under the Workspaces tab.

2. Select Blank Workspace and assign a name to the workspace. You can add a description and make it public. For this example, Personalis selected.

Once you have created the workspace, you can now configure API calls.

ISE SDK and Basic Postman Authorization

To configure any call, first access the ISE ERS SDK (Software Developer Kit). This tool compiles the whole list of API calls ISE can perform:

1. Navigate to https://{ise-ip}/ers/sdk.
2. Log in using your ISE Admin credentials.
3. Expand the API Documentation.
4. Scroll down until you find Network Device and click it.
5. Under this option, you can now find all the available operations you can perform for Network Devices on ISE. Select Create.

6. You can now see the configuration required to perform the API call using XML or JSON on any Rest Client as well as an expected response example. 

7.Back to Postman configure basic authentication to ISE. Under the Authorization tab, select Basic Auth as the authentication type and add the ISE ERS User credentials previously created on ISE.

Note: The password is shown as clear text unless variables are configured on Postman.

Create NAD Using XML

Create TESTNAD1 with RADIUS TACACS, SNMP and TrustSec settings using XML.

1. On the SDK, under Create, are the headers and the templates required to perform the call as well as the expected response.

2. Move to the Headers tab and configure the needed headers for the API call as seen in the SDK. The header configuration must look like this:

3. Move to the Body header and select raw. This allows you to paste the XML template needed for creating the NAD. 

4.  The XML template looks like this (change the values as required):

<?xml version="1.0" encoding="UTF-8"?> <ns0:networkdevice xmlns:ns0="network.ers.ise.cisco.com" xmlns:xs="Schema XML File" xmlns:ns1="ers.ise.cisco.com" xmlns:ers="ers.ise.cisco.com" description="This NAD was added via ERS API" name="TESTNAD1"> <authenticationSettings> <dtlsRequired>true</dtlsRequired> <enableKeyWrap>true</enableKeyWrap> <keyEncryptionKey>1234567890123456</keyEncryptionKey> <keyInputFormat>ASCII</keyInputFormat> <messageAuthenticatorCodeKey>12345678901234567890</messageAuthenticatorCodeKey> <radiusSharedSecret>cisco123</radiusSharedSecret> </authenticationSettings> <coaPort>1700</coaPort> <dtlsDnsName>Domain</dtlsDnsName> <NetworkDeviceIPList> <NetworkDeviceIP> <ipaddress>NAD IP Address</ipaddress> <mask>32</mask> </NetworkDeviceIP> </NetworkDeviceIPList> <NetworkDeviceGroupList> <NetworkDeviceGroup>Location#All Locations#LAB</NetworkDeviceGroup> <NetworkDeviceGroup>Device Type#All Device Types#Access-Layer</NetworkDeviceGroup> </NetworkDeviceGroupList> <profileName>Cisco</profileName> <snmpsettings> <linkTrapQuery>true</linkTrapQuery> <macTrapQuery>true</macTrapQuery> <originatingPolicyServicesNode>Auto</originatingPolicyServicesNode> <pollingInterval>3600</pollingInterval> <roCommunity>aaa</roCommunity> <version>ONE</version> </snmpsettings> <tacacsSettings> <connectModeOptions>ON_LEGACY</connectModeOptions> <sharedSecret>cisco123</sharedSecret> </tacacsSettings> <trustsecsettings> <deviceAuthenticationSettings> <sgaDeviceId>TESTNAD1</sgaDeviceId> <sgaDevicePassword>cisco123</sgaDevicePassword> </deviceAuthenticationSettings> <deviceConfigurationDeployment> <enableModePassword>cisco123</enableModePassword> <execModePassword>cisco123</execModePassword> <execModeUsername>Admin</execModeUsername> <includeWhenDeployingSGTUpdates>true</includeWhenDeployingSGTUpdates> </deviceConfigurationDeployment> <pushIdSupport>false</pushIdSupport> <sgaNotificationAndUpdates> <coaSourceHost>ise3-1test</coaSourceHost> <downlaodEnvironmentDataEveryXSeconds>86400</downlaodEnvironmentDataEveryXSeconds> <downlaodPeerAuthorizationPolicyEveryXSeconds>86400</downlaodPeerAuthorizationPolicyEveryXSeconds> <downloadSGACLListsEveryXSeconds>86400</downloadSGACLListsEveryXSeconds> <otherSGADevicesToTrustThisDevice>false</otherSGADevicesToTrustThisDevice> <reAuthenticationEveryXSeconds>86400</reAuthenticationEveryXSeconds> <sendConfigurationToDevice>false</sendConfigurationToDevice> <sendConfigurationToDeviceUsing>ENABLE_USING_COA</sendConfigurationToDeviceUsing> </sgaNotificationAndUpdates> </trustsecsettings> </ns0:networkdevice>  

Note: It is important to note that the next lines are required only if <enableKeyWrap>{false|true}</enableKeyWrap> is set to true. Otherwise, the same can be deleted from the XML template:

<keyEncryptionKey>1234567890123456</keyEncryptionKey> <keyInputFormat>ASCII</keyInputFormat> <messageAuthenticatorCodeKey>12345678901234567890</messageAuthenticatorCodeKey>

You can remove the configuration you do not require from the template and just leave the data you actually need to be added during the creation of the NAD. As an example, here is the same template but only with the TACACS configuration. Regardless of the required configuration, make sure that the template ends with </ns0:networkdevice>. 

<?xml version="1.0" encoding="UTF-8"?> <ns0:networkdevice xmlns:ns0="network.ers.ise.cisco.com" xmlns:xs="Schema XML File" xmlns:ns1="ers.ise.cisco.com" xmlns:ers="ers.ise.cisco.com" description="This NAD was added via ERS API" name="TESTNAD1"> <NetworkDeviceIPList> <NetworkDeviceIP> <ipaddress>NAD IP Address</ipaddress> <mask>32</mask> </NetworkDeviceIP> </NetworkDeviceIPList> <NetworkDeviceGroupList> <NetworkDeviceGroup>Location#All Locations#LAB</NetworkDeviceGroup> <NetworkDeviceGroup>Device Type#All Device Types#Access-Layer</NetworkDeviceGroup> </NetworkDeviceGroupList> <profileName>Cisco</profileName> <tacacsSettings> <connectModeOptions>ON_LEGACY</connectModeOptions> <sharedSecret>cisco123</sharedSecret> </tacacsSettings> </ns0:networkdevice> 

5.  Paste the XML template for raw under the Body header.

6.  Select POST as the method, paste https://{ISE-ip}/ers/config/networkdevice and click Send. If everything was correctly configured, you must see a 201 Created message and the result empty. 

7. Confirm if the NAD was created by performing a GET call for the NAD, or by checking the ISE NAD list. 

Create NAD Using JSON

Create TESTNAD2with RADIUS TACACS, SNMP and TrustSec settings using JSON.

1. On the SDK, under Create, are the headers and the templates required to perform the call as well as the expected response.

2. Move to the Headers tab and configure the needed headers for the API call as seen in the SDK. The header configuration must look like this:

3. Move to the Body header and select raw. This allows you to paste the JSON template needed for creating the NAD. 

4.  The JSON template must look like this (change the values as required):

{ "NetworkDevice": { "name": "TESTNAD2", "description": "This NAD was added via ERS API", "authenticationSettings": { "radiusSharedSecret": "cisco123", "enableKeyWrap": true, "dtlsRequired": true, "keyEncryptionKey": "1234567890123456", "messageAuthenticatorCodeKey": "12345678901234567890", "keyInputFormat": "ASCII" }, "snmpsettings": { "version": "ONE", "roCommunity": "aaa", "pollingInterval": 3600, "linkTrapQuery": true, "macTrapQuery": true, "originatingPolicyServicesNode": "Auto" }, "trustsecsettings": { "deviceAuthenticationSettings": { "sgaDeviceId": "TESTNAD2", "sgaDevicePassword": "cisco123" }, "sgaNotificationAndUpdates": { "downlaodEnvironmentDataEveryXSeconds": 86400, "downlaodPeerAuthorizationPolicyEveryXSeconds": 86400, "reAuthenticationEveryXSeconds": 86400, "downloadSGACLListsEveryXSeconds": 86400, "otherSGADevicesToTrustThisDevice": false, "sendConfigurationToDevice": false, "sendConfigurationToDeviceUsing": "ENABLE_USING_COA", "coaSourceHost": "ise3-1test" }, "deviceConfigurationDeployment": { "includeWhenDeployingSGTUpdates": true, "enableModePassword": "cisco123", "execModePassword": "cisco123", "execModeUsername": "Admin" }, "pushIdSupport": "false" }, "tacacsSettings": { "sharedSecret": "cisco123", "connectModeOptions": "ON_LEGACY" }, "profileName": "Cisco", "coaPort": 1700, "dtlsDnsName": "Domain", "NetworkDeviceIPList": [ { "ipaddress": "NAD IP Adress", "mask": 32 } ], "NetworkDeviceGroupList": [ "Location#All Locations", "Device Type#All Device Types" ] } }

Note: It is important to note that the next lines are required only if enableKeyWrap":{false|true}, is set to true. Otherwise, the same can be deleted from the JSON template:

"keyEncryptionKey": "1234567890123456", "messageAuthenticatorCodeKey": "12345678901234567890", "keyInputFormat": "ASCII" You can also remove the configuration you dont require from the template, and just leave the data you actually need to be added during the creation of the NAD. 

5.  Paste the JSON template for raw under the Body header.

6.  Select POST as the method, paste https://{ISE-ip}/ers/config/networkdevice and click Send. If everything was correctly configured, you must see a 201 Created message and the result empty. 

7. Confirm if the NAD was created by performing a GET call for the NAD, or by checking the ISE NAD list. 

Verify

 If you are able to access the API service GUI page, for example, https://{iseip}:{port}/api/swagger-ui/index.html or https://{iseip}:9060/ers/sdk, it means the API service is working as expected.

Troubleshoot

• All REST operations are audited and the logs are logged in the system logs.
• To troubleshoot issues that are related to the Open APIs, set the Log Level for the apiservice component to DEBUG in the Debug Log Configuration window.
• To troubleshoot issues relating to the ERS APIs, set the Log Level for the ers component to DEBUG in the Debug Log Configuration window. To view this window, navigate to the Cisco ISE GUI, click the Menu icon and choose Operations > Troubleshoot > Debug Wizard > Debug Log Configuration.
• You can download the logs from the Download Logs window. To view this window, navigate to the Cisco ISE GUI, click the Menu icon and choose Operations > Troubleshoot > Download Logs.
• You can choose to download either a support bundle from the Support Bundle tab by clicking the Download button under the tab, or download the api-service debug logs from the Debug Logs tab by clicking the Log File value for the api-service debug log.