REST API를 사용하여 ISE 게스트 계정 구성
목차
소개
이 문서에서는 REST(Representational State Transfer) API 기능을 사용하여 ISE(Identity Services Engine)에서 게스트 관련 작업을 수행하는 방법에 대해 설명합니다. Cisco 게스트 API는 Cisco 게스트 사용자를 관리하기 위한 보안 HTTPS 및 인증된 액세스를 제공하는 REST 기반 작업 집합입니다.API를 사용하면 게스트 사용자를 생성, 읽기, 업데이트, 삭제 및 검색할 수 있습니다.
사전 요구 사항
요구 사항
Cisco에서는 다음 주제에 대해 숙지할 것을 권장합니다.
- ISE
- 외부 RESTful 서비스
- 불면증, REST 등의 REST 클라이언트
사용되는 구성 요소
이 문서의 정보는 다음 소프트웨어 및 하드웨어 버전을 기반으로 합니다.
- Cisco ISE, 릴리스 2.6
- Insurinfence 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(Software Development Kit)로 사용할 수 있습니다.ERS를 활성화하고 "ERS-Admin" 또는 "ERS-Operator" 권한을 가진 관리자 계정으로 로그인한 후에 액세스할 수 있습니다.
ERS에 대한 관리자 및 스폰서 계정 설정
ERS를 사용하려면 ISE에 ERS-Admin 또는 ERS-operator의 권한이 할당된 관리자 계정이 필요합니다.관리자 계정을 생성하여 각 그룹에 추가해야 합니다.또는 ERS 액세스는 Super-Admin 어카운트에서도 작동합니다.
게스트 기능에 API를 사용하려면 ERS 관리자가 포털 ID, 게스트 ID 그룹 등과 같은 포털의 원시 데이터를 필요로 합니다.그러나 게스트 데이터를 읽기/생성/업데이트 또는 삭제하려면 ERS 액세스가 활성화된 스폰서 계정이 필요합니다.
- 이 문서에서는 내부 ISE 사용자 계정을 스폰서로 사용합니다.
- Administration(관리) > Identity Management(ID 관리) > Identities(ID)로 이동하고 이미지에 표시된 대로 네트워크 액세스 사용자를 추가합니다.
- 이 사용자 계정은 스폰서 그룹 중 하나에 추가해야 합니다.
- 예제 어카운트는 ALL_ACCOUNTS라는 기본 스폰서 그룹에 매핑됩니다.
- 이 스폰서 그룹에 대한 ERS 액세스를 허용하려면 Work Centers(작업 센터) > Guest Access(게스트 액세스) > Portal & Components(포털 및 구성 요소) > Sponsor Groups(스폰서 그룹)로 이동하여 할당된 스폰서 그룹을 엽니다.
- 옵션을 활성화합니다.
게스트 계정 생성
API를 통해 게스트 어카운트를 생성하려면 API 호출이 ISE에 스폰서로서 그리고 스폰서 포털에서 인식하는 포털을 통해 이루어져야 합니다.
1단계. ISE에 사전 구성된 모든 스폰서 포털의 포털 ID를 가져오려면 여기에 제공된 정보와 함께 모든 REST 클라이언트를 사용합니다.
| 메서드 | 다운로드 |
| URL | https://<ISE-IP>:9060/ers/config/sponsorportal |
| 자격 증명 | ERS 관리자 자격 증명 사용 |
| 헤더 | Content-Type:애플리케이션/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-005056877a3"입니다.
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에서 사용할 수 있습니다.
- 이름으로 게스트 사용자 계정 세부 정보 가져오기:
| 메서드 | 다운로드 |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/name/{name} |
| 자격 증명 | 스폰서 계정 자격 증명 사용 |
| 헤더 | Content-Type:애플리케이션/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-aaaafe-7289dc971d1"입니다.
| 메서드 | PUT |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/resetpassword/{id} |
| 자격 증명 | 스폰서 계정 자격 증명 사용 |
| 헤더 | Content-Type:애플리케이션/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>
- 이름으로 게스트 계정 삭제:
| 메서드 | 삭제 |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/name/{name} |
| 자격 증명 | 스폰서 계정 자격 증명 사용 |
| 헤더 | Content-Type:애플리케이션/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)를 사용하여 Cisco 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에 없거나 잘못되었습니다.스폰서 포털에 대한 'Get' 통화에서 포털의 올바른 포털 ID를 가져옵니다.
- API 응답 코드 및 가능한 의미:
200(확인):REST API가 원하는 작업을 성공적으로 수행했음을 나타냅니다.
201(생성됨):컬렉션 내에서 리소스가 생성되었음을 나타냅니다.
204(콘텐츠 없음):일반적으로 PUT, POST 또는 DELETE 요청에 대한 응답으로 전송됩니다.
400(잘못된 요청):잘못된 형식의 요청 구문, 잘못된 매개 변수 등과 같은 문제에 대한 일반 오류 코드입니다.가능한 경우 메시지 세부 정보를 읽고 원인을 파악합니다.
401(승인되지 않음):이는 작업이 잘못된 자격 증명으로 수행되었거나 자격 증명이 없거나 이 작업을 수행할 권한이 없는 계정임을 나타냅니다.
500(내부 서버 오류):서버 측의 문제를 나타냅니다.ISE에 로그온하면 원인을 이해하는 데 도움이 될 수 있습니다.
ISE의 REST API 사용에 대한 자세한 내용은 게스트 REST API를 참조하십시오.
피드백