ISE Guest Sponsor API Tips & Tricks

This guide will list Tips and Tricks around using Guest API calls working with Sponsors and guests

 

For other related API see this document- ISE API for working with portal settings and elements

 

Other integration notes:

ISE custom sponsor portal using API to filter pending accounts requiring approval to the person being visited

ISE Guest REST - Sponsor account initialization requirement

 

Where can I find information about the API?

Introduction to External RESTful Services API

https://<ISE-ADMIN-NODE>:9060/ers/sdk (requires a user setup to access (see guide above))

 

Cisco Identity Services Engine API Reference Guide, Release 2.x - Cisco

 

CSCvd48557 - Ability to set the sponsor user with the guest API


When you create a guest account it sets the sponsor user to that of the sponsor calling the API. There is no way to override this.

API called using apisponsor

Example: Joe visits Jason but uses a visitor management system to create the account.

When looking at Sponsor Portal > Manage accounts screen Joe is not listed. Jason will need access to all accounts or Jason and apisponsor would need to belong to same GROUP accounts. If jason sponsor group has setting to filter accounts on person being visited then it won't show in his filtered list either.

 

Getting started

 

Setup access permissions

 

To work with the APIs they must be enabled.

Administration > System > Settings > ERS Settings

 

You will need 2 different types of accounts to fully work with the Guest APIs. One for sponsor actions and one for changes of portal settings (if needed)

 

In order to work with guest accounts you need to setup a Sponsor that is able to use the API. 

Sponsor accounts are needed to perform CRUD operations guest accounts.

Administration > Identity Management > Identities > Users > Create an account for a Sponsor part of ALL_ACCOUNTS

This sponsor will have visibility of ALL Guests in the system. If you wanted to limit it then you could use different group.

 

Note the sponsor account should not be part of any of the ERS groups (as shown below)

api.png

 

Give Sponsor group access to the API

Under the sponsor group (ALL_ACCOUNTS) add ERS API access permission

Work Centers > Guest Access > Configure > Sponsor Groups > ALL_ACCOUNTS

Sponsor Permisions - Access Cisco ISE guest accounts using the programmatic interface

 

If you want to perform perform operations on portal settings and elements you will need to have an ERS Admin account

Cisco Identity Services Engine API Reference Guide, Release 2.x - Introduction to External RESTful Services API [Cisco I…

 

 

Guest types

Its recommend to create a new guest for your API interactions. Also use FromFirstLogin type accounts (unless needing to activate accounts at a certain time/date)

ISE Guest Types do i really need locations and timezones?

 

Bulk calls can only be done with XML and not JSON

 

Misc setup details

 

Query ERS API for Portal ID

(A PortalId is necessary to create user)

GET /ers/config/portal HTTP/1.1

Host: <ise_admin_ip>:9060

Authorization: Basic XXXXX

Content-Type: application/vnd.com.cisco.ise.identity.portal.2.0+xml

Accept: application/vnd.com.cisco.ise.identity.portal.2.0+xml

 

How can I validate that a sponsor is valid?

When I am setting up my systems (example visitor management) and configuring a sponsor account to use. I want to send a call to ISE Guest API to validate this.

https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser/versioninfo

Validate 401 or not

 

Common Calls


Finding guest based off email-address

https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser?filter=emailAddress.EQ.vpetla@cisco.com


How do I update guest user info?

To update guest user, we need to use only updateById.


How do I move from suspended to active account?

Re-instantiate to move suspended guest to active account

 

Create Guest User

(username is optional and can be dynamically generated)

POST /ers/config/guestuser HTTP/1.1

Host: <ise_admin_ip>:9060

Authorization: Basic XXXXX

Content-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

Accept: 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">

<guestAccessInfo>

<fromDate>06/01/2016 00:01</fromDate>

<toDate>06/02/2016 23:59</toDate>

<validDays>1</validDays>

<location>San Jose</location>

  </guestAccessInfo>

  <guestInfo>

<firstName>John</firstName>

<lastName>Jones</lastName>

    <userName>john</userName>

  </guestInfo>

<guestType>Daily</guestType>

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

  <portalId>76c18c50-2a34-11e5-82cb-005056bf2f0a</portalId>

</ns2:guestuser>

 

 

Note: portalId needs to be replaced with one found on your ISE using ERS API for “portal”

Required: fromDate, location, toDate, validDays, and portalId

 

Submit the XML file above using cURL :

 

curl -v --tlsv1 -d @add_guest_user.xml -k -H "Content-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml; charset=utf-8" 'https://ers-admin:ers-password@ise-pan.domain.com:9060/ers/config/guestuserers-password@ise-pan.domain.com:9060/ers/config/guestuser'


List Guest Users

(to get generated password and maybe username – filters in green optional)

GET /ers/config/guestuser/?filter=firstName.EQ.Vish&filter=lastName.EQ.JonesHTTP/1.1

Host: <ise_admin_ip>:9060

Authorization: Basic XXXXX

Content-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

 

 

Examples of usage

 

Get Sponsor Portal ID using the portal API query

 

use non-sponsor admin that has access to the ERS APIs

 

Headers:

GET /ers/config/portal

Host: <ise_admin_ip>:9060

Accept: application/vnd.com.cisco.ise.identity.portal.2.0+xml

Authorization: Basic YXBpOkFwcGxlMTIz

 

Response:

Content-Type: application/vnd.com.cisco.ise.ers.searchresult.2.0+xml;charset=utf-8

 

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

<ns3:searchResult total="4" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:ns3="ers.ise.cisco.com">

  <resources>

    <resource description="Default portal used by sponsors to create and manage accounts for authorized visitors to securely access the network" id="a6f50970-2230-11e6-99ab-005056bf55e0" name="sponsor">

      <link rel="self" href="https://<ise_admin_ip>:9060/ers/config/portal/a6f50970-2230-11e6-99ab-005056bf55e0" type="application/xml"/>

    </resource>

    <resource description="Guests are allowed to create their own accounts and access the network using their assigned username and password" id="a692c530-2230-11e6-99ab-005056bf55e0" name="Self-Registered Guest Portal (default)">

      <link rel="self" href="https://10.0.0.121:9060/ers/config/portal/a692c530-2230-11e6-99ab-005056bf55e0" type="application/xml"/>

    </resource>

    <resource description="Sponsors create guest accounts, and guests access the network using their assigned username and password" id="a65b8890-2230-11e6-99ab-005056bf55e0" name="Sponsored Guest Portal (default)">

      <link rel="self" href="https://<ise_admin_ip>:9060/ers/config/portal/a65b8890-2230-11e6-99ab-005056bf55e0" type="application/xml"/>

    </resource>

  </resources>

</ns3:searchResult>

 

Create the Guest user using the guest API query. Obtain Guest ID from the POST response “Location”:

 

Headers:

POST /ers/config/guestuser

Host: <ise_admin_ip>:9060

Content-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

Authorization: Basic YXBpOkFwcGxlMTIz

 

Payload - must follow this template, changing only the parameters in yellow:

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

<ns4:guestuser xmlns:ers="ers.ise.cisco.com" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:ns4="identity.ers.ise.cisco.com">

    <customFields>

        <entry>

<key>ui_sponsorname_text_label</key>

            <value>John Jones</value>

        </entry>

    </customFields>

    <guestAccessInfo>

        <fromDate>09/01/2016 09:49</fromDate>

        <location>San Jose</location>

        <toDate>09/01/2016 17:48</toDate>

        <validDays>1</validDays>

    </guestAccessInfo>

    <guestInfo>

        <enabled>true</enabled>

        <firstName>Susan</firstName>

        <lastName>Storm</lastName>

        <notificationLanguage>English</notificationLanguage>

    </guestInfo>

    <guestType>APIGuestType</guestType>

<portalId>72317030-5a8d-11e6-87e1-000c292eb29b</portalId>

</ns4:guestuser>

 

Response:

Content-Type: application/xml;charset=utf-8

Location: https://10.0.0.121:9060/ers/config/guestuser/f4705ee2-748b-11e6-9e5e-000c2958a9f6

 

Obtain the Guest username and password using the Guest API query with the ID generated for the Guest account:

Headers:

GET /ers/config/guestuser/f4705ee2-748b-11e6-9e5e-000c2958a9f6

Host: <ise_admin_ip>:9060

Accept: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml

Authorization: Basic YXBpOkFwcGxlMTIz

 

Response:

Content-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml;charset=utf-8

 

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

<ns4:guestuser id="f4705ee2-748b-11e6-9e5e-000c2958a9f6" name="gsharma377" 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.0.0.121:9060/ers/config/guestuser/f4705ee2-748b-11e6-9e5e-000c2958a9f6" type="application/xml"/>

  <customFields>

    <entry>

      <key>ui_sponsorname_text_label</key>

      <value>Victor Value</value>

    </entry>

  </customFields>

  <guestAccessInfo>

    <fromDate>09/06/2016 16:23</fromDate>

    <location>San Jose</location><toDate>09/07/2016 00:42</toDate>

    <validDays>1</validDays>

  </guestAccessInfo>

  <guestInfo>

    <creationTime>09/06/2016 23:45</creationTime>

    <enabled>false</enabled>

    <firstName>Gaurva</firstName>

    <lastName>Sharma</lastName>

    <notificationLanguage>English</notificationLanguage>

    <password>2063</password>

    <userName>vvalue123</userName>

  </guestInfo>

  <guestType>Daily (default)</guestType>

  <sponsorUserName>MasterSponsor</sponsorUserName>

  <status>AWAITING_INITIAL_LOGIN</status>

</ns4:guestuser>