目录

简介

先决条件

要求

使用的组件

背景信息

配置

在ISE上启用ERS

为ERS设置管理员和发起人帐户

创建访客帐户

读取、更新、删除访客数据

验证

故障排除

简介

本文档介绍如何使用具象状态传输(REST)API功能在身份服务引擎(ISE)上执行与访客相关的任务。 思科访客API是一组基于REST的操作，提供安全的HTTPS和经过身份验证的访问以管理思科访客用户。使用API，您可以创建、读取、更新、删除和搜索访客用户。

先决条件

要求

思科建议您了解以下主题：

- ISE

- 外部RESTful服务

- REST客户，如失眠、SREED等

使用的组件

本文档中的信息基于以下软件和硬件版本：

- 思科ISE版本2.6

- 失眠REST客户端v7.1.1

本文档中的信息都是基于特定实验室环境中的设备编写的。本文档中使用的所有设备最初均采用原始（默认）配置。如果您的网络处于活动状态，请确保您了解所有命令的潜在影响。

注意：其他ISE版本的过程类似或相同。除非另有说明，否则您可以在所有2.x ISE软件版本上使用这些步骤。

背景信息

要使用API，需要在ISE中设置启用外部RESTful服务(ERS)和保证人身份验证。ERS支持基本身份验证，并在端口9060上运行。身份验证凭证是加密的，是请求报头的一部分。ERS要求ISE管理员为用户分配特殊权限以执行操作。

本文档将介绍以下配置步骤：

1.在ISE上启用ERS

2.为ERS设置管理员和发起人帐户

3.创建访客帐户

4.读取、更新、删除访客数据

配置

在ISE上启用ERS

要在ISE上使用REST API功能，必须启用ERS。

导航至管理>System >设置> ERS设置>启用ERS进行读/写，如图所示。

与ERS相关的所有信息都可作为ISE的HTTPS端口9060上的软件开发套件(SDK)提供。在您启用ERS并使用具有“ERS-Admin”或“ERS-Operator”权限的管理员帐户登录后，可以访问此帐户。

为ERS设置管理员和发起人帐户

为了使用ERS，ISE需要具有ERS管理员或ERS操作员权限的管理员帐户。管理员帐户需要创建并添加到相应的组。或者，ERS访问也适用于超级管理员帐户。

为了将API用于访客功能，ERS管理员需要门户的原始数据，如门户ID、访客身份组等。但是，要读取/创建/更新或删除任何访客数据，需要启用ERS访问权限的保证人帐户。

- 在本文档中，内部ISE用户帐户用作保证人。

- 导航至管理>身份管理>身份，然后添加网络访问用户，如图所示。

- 此用户帐户必须添加到其中一个发起人组。

- 示例帐户映射到名为ALL_ACCOUNTS的默认保证人组。

- 要允许此发起人组的ERS访问，请转到工作中心>访客访问>门户和组件>发起人组并打开分配的发起人组。

- 启用选项： 使用编程接口（访客REST API）访问思科ISE访客帐户，如图所示。

创建访客帐户

要通过API创建访客帐户，必须将API调用作为保证人并通过其识别的赞助门户对ISE进行。

步骤1.要获取ISE上预配置的所有发起人门户的门户ID，请使用任何REST客户端，并提供以下信息：

方法

GET

URL

https://<ISE-IP>:9060/ers/config/sponsorportal

凭证

使用ERS管理员凭证

信头

内容类型:应用/xml

接受：应用/xml

预期输出：

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<ns3:searchResult total="1"

xmlns:ns5="ers.ise.cisco.com"

xmlns:ers-v2="ers-v2"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:ns3="v2.ers.ise.cisco.com">

<ns3:resources>

<ns5:resource description="Default portal used by sponsors to create and manage accounts for authorized visitors to securely access the network"

id="274a95f0-2e58-11e9-98fb-0050568775a3" name="Sponsor Portal (default)">

<link rel="self" href="https://10.127.197.186:9060/ers/config/sponsorportal/274a95f0-2e58-11e9-98fb-0050568775a3" type="application/xml"/>

</ns5:resource>

</ns3:resources>

</ns3:searchResult>

感兴趣的值是发起人门户的门户ID，用于创建访客用户。本例中的ID为“274a95f0-2e58-11e9-98fb-0050568775a3”。

步骤2.使用此API调用创建访客帐户。此处的portalID值是从步骤1获取的值。

方法

POST

URL

https://<ISE-IP>:9060/ers/config/guestuser/

凭证

使用保证人帐户凭据

信头

内容类型:application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

接受：application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

正文

<?xml version="1.0" encoding="UTF-8"?>

<ns2:guestuser xmlns:ns2="identity.ers.ise.cisco.com"

<customFields>

</customFields>

<guestAccessInfo>

<fromDate>04/25/2020 18:55</fromDate>

<location>德里</location>

<toDate>04/28/2020 19:55</toDate>

<validDays>3</validDays>

</guestAccessInfo>

<guestInfo>

<company>思科</company>

<emailAddress>abcd@cisco.com</emailAddress>

<firstName>John</firstName>

<lastName>Doe</lastName>

<notificationLanguage>英语</notificationLanguage>

<password>9618</password>

<phoneNumber>9999998877</phoneNumber>

<smsServiceProvider>全局默认</smsServiceProvider>

<userName>johndoe</userName>

</guestInfo>

<guestType>承包商（默认）</guestType>

<personBeingVisited>abcd3@cisco.com</personBeingVisited>

<portalId>274a95f0-2e58-11e9-98fb-0050568775a3</portalId>

<reasonForVisit>从会计部访问Bob</reasonForVisit>

</ns2:guestuser>

注意：此处显示的正文内容可用作模板（SDK中也提供）。 确保fromDate、toDate与validDays对应。位置、访客类型和其他值必须有效，才能引用使用的ISE，只有到此时呼叫才会成功。

注意：进行此呼叫时使用的凭证必须是映射到保证人组的有效保证人帐户。此处的ERS管理员凭据将不起作用。有关详细信息，请参阅本指南的上一部分。

预期输出：

导航至ISE GUI > Master GuestReport以验证帐户是否已创建：

注意：没有选项可以从发起人门户为每个访客帐户指定自定义用户名和密码组合。此API方法可用于满足该要求。

读取、更新、删除访客数据

以下是对访客数据执行各种操作的一些API调用示例。SDK中提供所有可用选项及其格式。

- 按名称获取访客用户帐户详细信息：

方法

GET

URL

https://<ISE-IP>:9060/ers/config/guestuser/name/{name}

凭证

使用保证人帐户凭据

信头

内容类型:应用/xml

接受：应用/xml

预期输出：

200 OK

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<ns4:guestuser id="3b967932-86f8-11ea-aafe-72889dc971d1" name="johndoe"

xmlns:ers="ers.ise.cisco.com"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:ns4="identity.ers.ise.cisco.com">

<link rel="self" href="https://10.127.197.186:9060/ers/config/guestuser/name/johndoe" type="application/xml"/>

<customFields/>

<guestAccessInfo>

<fromDate>04/25/2020 18:55</fromDate>

<location>Delhi</location>

<toDate>04/28/2020 19:55</toDate>

<validDays>3</validDays>

</guestAccessInfo>

<guestInfo>

<company>Cisco</company>

<creationTime>04/25/2020 18:55</creationTime>

<emailAddress>abcd@cisco.com</emailAddress>

<enabled>false</enabled>

<firstName>John</firstName>

<lastName>Doe</lastName>

<notificationLanguage>English</notificationLanguage>

<password>9618</password>

<phoneNumber>9999998877</phoneNumber>

<smsServiceProvider>Global Default</smsServiceProvider>

<userName>johndoe</userName>

</guestInfo>

<guestType>Contractor (default)</guestType>

<personBeingVisited>abcd3@cisco.com</personBeingVisited>

<reasonForVisit>Visiting Bob from Accounting</reasonForVisit>

<sponsorUserId>1f7627f0-86f8-11ea-aafe-72889dc971d1</sponsorUserId>

<sponsorUserName>Sponsor_ERS</sponsorUserName>

<status>AWAITING_INITIAL_LOGIN</status>

</ns4:guestuser>

- 重置访客用户密码：

这需要先从呼叫获取访客ID，然后在此API中使用。本例中的访客用户ID为“3b967932-86f8-11ea-aafe-72889dc971d1”。

方法

PUT

URL

https://<ISE-IP>:9060/ers/config/guestuser/resetpassword/{id}

凭证

使用保证人帐户凭据

信头

内容类型:应用/xml

接受：应用/xml

此方法不允许指定新密码。ISE将返回带有新自动生成密码的输出。

预期输出：

200 OK

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<ns3:operationResult

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:ns3="ers.ise.cisco.com">

<attributesList>

<attribute name="password" value="2557"/>

</attributesList>

</ns3:operationResult>

- 按名称删除访客帐户：

方法

DELETE

URL

https://<ISE-IP>:9060/ers/config/guestuser/name/{name}

凭证

使用保证人帐户凭据

信头

内容类型:应用/xml

接受：应用/xml

预期输出：

验证

当前没有可用于此配置的验证过程。

故障排除

本部分提供了可用于对配置进行故障排除的信息。

一些常见错误及其可能原因：

- 访客帐户创建失败，出现错误：

401 Unauthorized

<message type="ERROR" code="CRUD operation exception">

<title>Sponsor does not have permission to access REST Apis</title>

</message>

修复程序:这意味着用于使访客帐户的发起人帐户映射到未启用ERS访问的发起人组。编辑与此对应的保证人组，并使用编程接口（访客REST API）启用访问思科ISE访客帐户。

400 Bad Request

<message type="ERROR" code="CRUD operation exception">

<title>Creating GuestUser failed due to com.cisco.cpm.guestaccess.validation.GuestAccessValidationException: Portal not found for portal session e1fc15a7-a170-4d6a-b02c-0ab7b0bc54ff</title>

修复程序:在呼叫中输入的门户ID在ISE上不存在或不正确。从发起人门户的“获取”呼叫中，获取门户的正确门户ID。

- API响应代码及其可能含义：

200(OK):表示REST API成功执行了所需操作。

201（已创建）：表示已在集合内创建资源。

204（无内容）：这通常作为对PUT、POST或DELETE请求的响应发送。

400（错误请求）：有关错误请求语法、无效参数等问题的通用错误代码。阅读消息详细信息（如果可用），了解原因。

401（未授权）：这表示操作是使用错误的凭据执行的，没有凭据或帐户无权执行此操作。

500（内部服务器错误）：表示服务器端出现问题。登录ISE可能有助于了解原因。

有关ISE的REST API使用的详细信息，请参阅访客REST API。