使用REST API配置ISE访客帐户
简介
本文档介绍如何使用具象状态传输(REST)API功能在身份服务引擎(ISE)上执行与访客相关的任务。 思科访客API是一组基于REST的操作，提供安全的HTTPS和经过身份验证的访问以管理思科访客用户。使用API，您可以创建、读取、更新、删除和搜索访客用户。
先决条件
要求
思科建议您了解以下主题：
- ISE
- 外部RESTful服务
- REST客户，如失眠、SREED等
使用的组件
本文档中的信息基于以下软件和硬件版本：
- 思科ISE版本2.6
- 失眠REST客户端v7.1.1
本文档中的信息都是基于特定实验室环境中的设备编写的。本文档中使用的所有设备最初均采用原始（默认）配置。如果您的网络处于活动状态，请确保您了解所有命令的潜在影响。
背景信息
要使用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访问，请转到工作中心>访客访问>门户和组件>发起人组并打开分配的发起人组。
- 启用选项：
创建访客帐户
要通过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"?> |
预期输出：
导航至ISE GUI > Master GuestReport以验证帐户是否已创建：
读取、更新、删除访客数据
以下是对访客数据执行各种操作的一些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。
反馈