使用REST API配置ISE訪客帳戶
簡介
本文說明如何使用表示狀態傳輸(REST)API功能在身份服務引擎(ISE)上執行訪客相關任務。 思科訪客API是一組基於REST的操作，提供安全的HTTPS和經過身份驗證的訪問來管理思科訪客使用者。藉助API，您可以建立、讀取、更新、刪除和搜尋訪客使用者。
必要條件
需求
思科建議您瞭解以下主題：
- ISE
- 外部RESTful服務
- 休息的客戶如失眠、休息等。
採用元件
本文中的資訊係根據以下軟體和硬體版本：
- Cisco 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。
導覽至Administration > System > Settings > ERS settings > Enable ERS for read/write，如下圖所示。
所有與ERS相關的資訊都在ISE的HTTPS埠9060上作為軟體開發套件(SDK)提供。啟用ERS並使用具有「ERS-Admin」或「ERS-Operator」許可權的管理員帳戶登入後，可以訪問此功能。
為ERS設定管理員和保證人帳戶
為了使用ERS，ISE需要具有為其分配的ERS-Admin或ERS-operator許可權的管理帳戶。需要建立管理員帳戶並將其新增到各自的組中。或者，ERS訪問也適用於超級管理員帳戶。
為了將API用於訪客功能，ERS管理員需要門戶的原始資料，如門戶ID、訪客身份組等。但是，為了讀取/建立/更新或刪除任何訪客資料，需要啟用ERS訪問許可權的發起人帳戶。
- 在本檔案中，使用內部ISE使用者帳戶作為發起人。
- 導覽至Administration > Identity Management > Identities，然後新增網路存取使用者，如下圖所示。
- 必須將此使用者帳戶新增到其中一個發起人組。
- 示例帳戶對映到名為ALL_ACCOUNTS的預設發起人組。
- 若要允許此發起組的ERS訪問，請轉到工作中心>訪客訪問>門戶和元件>發起人組，然後開啟分配的發起人組。
- 啟用選項：
建立訪客帳戶
為了通過API建立訪客帳戶，必須將API呼叫作為發起人並通過其識別的發起門戶進行ISE。
步驟1。若要獲取在ISE上預配置的所有發起人門戶的門戶ID，請使用具有此處提供的資訊的任何REST客戶端：
| 方法 | GET |
| URL | https://<ISE-IP>:9060/ers/config/sponsorportal |
| 憑證 | 使用ERS管理員憑據 |
| 標頭 | Content-Type:application/xml 接受:application/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/ |
| 憑證 | 使用發起人帳戶憑據 |
| 標頭 | Content-Type: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} |
| 憑證 | 使用發起人帳戶憑據 |
| 標頭 | Content-Type:application/xml 接受:application/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。在此示例中，訪客ID為「3b967932-86f8-11ea-aafe-72889dc971d1」。
| 方法 | PUT |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/resetpassword/{id} |
| 憑證 | 使用發起人帳戶憑據 |
| 標頭 | Content-Type:application/xml 接受:application/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>
- 按名稱刪除訪客帳戶：
| 方法 | 刪除 |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/name/{name} |
| 憑證 | 使用發起人帳戶憑據 |
| 標頭 | Content-Type:application/xml 接受:application/xml |
預期輸出：
驗證
目前沒有適用於此組態的驗證程序。
疑難排解
本節提供的資訊可用於對組態進行疑難排解。
一些常見錯誤及其可能的原因：
- 訪客帳戶建立失敗，錯誤為：
401 Unauthorized
<message type="ERROR" code="CRUD operation exception">
<title>Sponsor does not have permission to access REST Apis</title>
</message>
修正:這意味著用於使訪客帳戶的發起人帳戶對映到未啟用ERS訪問的發起人組。編輯與此對應的發起人組並使用程式設計介面(Guest 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>
修正:在ISE上輸入的門戶ID不存在或不正確。從發起人門戶的「Get」呼叫獲取該門戶的正確門戶ID。
- API響應代碼及其可能的含義：
200（確定）：指示REST API成功執行了所需的操作。
201（建立）：表示在集合內建立了資源。
204（無內容）：這通常作為對PUT、POST或DELETE請求的響應傳送。
400（錯誤請求）：用於請求語法格式錯誤、引數無效等問題的通用錯誤代碼。閱讀消息詳細資訊（如果可用）以瞭解原因。
401（未授權）：這表示執行操作所使用的憑據錯誤、沒有憑據或帳戶無權執行此操作。
500（內部伺服器錯誤）：指示伺服器端的問題。登入ISE可幫助瞭解原因。
有關ISE的REST API用法的詳細資訊，請參閱Guest REST API。
意見