Buy or Renew
Buy or Renew
cancel
Turn on suggestions
Showing results for 
Search instead for 
Did you mean: 
cancel
Create a new article
Bookmark
|
Subscribe
|
33410
Views
4
Helpful
7
Comments

ISE Guest Sponsor API Tips & Tricks

Jason Kunst
Cisco Employee
Cisco Employee

on ‎03-14-2017 10:41 AM - edited on ‎08-16-2023 07:21 AM by Cisco Employee

 

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

 

ISE REST API Information

For other related API information, see 

 

Which ISE Node(s) are Used for Guest APIs?

Use the Primary Policy Administration Node (PAN) on port 9060 for ISE < 3.1 unless using the sponsor portal URL.

ISE 3.1 and later may use the ISE API Gateway feature and use HTTPS on port 443 normally

 

Known Caveats with ISE Guest API

If you try to do any CRUD operations (Create, Read, Update, Delete) with the ISE REST APIs for guests, you will likely receive an HTTP Status 401 – Unauthorized error message. This is a known issue:

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

The only way to create, read, update or delete Guest users is with a Sponsor account. 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. We will show you how to workaround this problem below. See the related TechZone article How to create guest accounts with API .

 

Enable ISE REST APIs

  1. In ISE, navigtat to Administration > System > Settings > ERS Settings
  2. Check Enable ERS for Read/Write
  3. You may optionally check Enable ERS for Read if you will be doing REST APIs actions beyond the guest functions
  4. Disable CSRF
  5. Save the settings

    Screen Shot 2018-04-12 at 4.33.23 PM.png

  6. You should now be able to login to the SDK using the link https://YOUR-PAN-NAME:9060/ers/sdk :

    Screen Shot 2018-04-12 at 5.10.18 PM.png

 

Access Permissions

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). To simply look at the SDK you will need an admin account (this has nothing to do with the sponsor account used to query or work with guest accounts).

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.

  1. In ISE, go to Administration > Identity Management > Identities > Users
  2. Click +Add to add a new sponsor-api user for ALL_ACCOUNTS :

    Screen Shot 2018-04-12 at 4.36.14 PM.png

    This sponsor will have visibility of ALL Guests in the system.  If you wanted to limit it then you could use different group.
  3. Click on Submit to save the new account

 

Give Sponsor Group Access to the API

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

  1. In ISE, go to Work Centers > Guest Access > Portals & Components > Sponsor Groups > ALL_ACCOUNTS
  2. Under Sponsor Can Create, check the box for Access Cisco ISE guest accounts using the programmatic interface (Guest REST API)
  3. Scroll to the top and click Save

If you need to setup an admin account that is able to work with the guest portal actions (changing portal settings) or looking at the SDK then follow these steps:

  1. Cisco Identity Services Engine API Reference Guide, Release 2.x - Introduction to External RESTful Services API [Cisco I…
  2. Administration > System > Admin Access > Administrators > Admin Users
  3. Make sure you give them access to ERS admin and operator
    api.png

 

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. Also see ISE Guest Types do i really need locations and timezones?

 

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

 

Sponsor Validation

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 that you receive an HTTP Status 401 Unauthorized or not.

 

Find Guest by Email

https://<ISE-ADMIN-NODE>:9060/ers/config/guestuser?filter=emailAddress.EQ.username@domain.org

 

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

 

Is there a way we can always create a user with the maximum duration without changing the API call?

The maximum duration comes from the guest type and the self-registration portal being used. The way to set an account with max duration is to fill out the three fields ( fromDate, toDate and validDays ) are properly filled. If longer than the “Maximum access duration” then API will throw error.

 

Create a Guest User

Username and password are optional and can be dynamically generated.

techzone note

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>

 

Creating a GuestUser without Username and Password

{
   "GuestUser": {
       "guestType": "Contractor (default)",
       "portalId": "6b93b3f0-26dd-11e8-a836-005056872c7f",
       "guestAccessInfo": {
           "validDays": 91,
           "fromDate": "03/19/2018 17:47",
           "toDate": "06/17/2018 17:47",
           "location": "San Jose"
       },
       "customFields": {}
   }
}

 

Bulk operations

At present, please use XML instead of JSON for bulk operations, as JSON not supported for bulk.

List bulk users

Create Bulk Users

https://psnip:9060/ers/config/guestuser/bulk/submit

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 \
  --header "Content-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml; charset=utf-8" \
  --user $ISE_REST_USERNAME:$ISE_REST_PASSWORD \
  'https://ise-pan.domain.com:9060/ers/config/guestuserers-password@ise-pan.domain.com:9060/ers/config/guestuser'

 

List Guest Users

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

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

 

Get Guest Username+Password using the Guest API

Query with the ID generated for the Guest account:

curl --insecure --location \
--header 'Accept: application/json' \
--user $ISE_REST_USERNAME:$ISE_REST_PASSWORD \
--request GET https://$ISE_HOSTNAME:9060/ers/config/guestuser/{id}

 

Send an Email to the Guest

Use the sponsor portal:

curl -X PUT -k  -i \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --user $ISE_SPONSOR_USERNAME:$ISE_SPONSOR_PASSWORD \

  'https://ise:9060/ers/config/guestuser/email/11c276c0-05b4-11e9-a436-005056abd9c7/portalId/{portal-id}' \
  --data '
{
  "OperationAdditionalData" : {
    "additionalData" : [ {
      "name" : "senderEmail",
      "value" : "sponsor@demo.local"
    } ]
  }
}
'

 

FAQ

Can I use the Guest API to create web pages or guest approval flow? No you would have to do this via your own system

 

 

Comments
lopezra@cpchem.com
Level 1
Level 1
‎03-16-2020 01:05 PM

anyone else getting 401 Unauthorized for guest user/sponsor api calls? I followed all the steps but when i run the following, get a 401: 

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

 

ERSAdmin account works fine when getting portal ID. 

 

Here is a screenshot of postman:

401postman.jpg

Thanks,

Rey

Jason Kunst
Cisco Employee
Cisco Employee
‎03-17-2020 08:10 AM
Are you doing the calls as a sponsors account like the community page says?
lopezra@cpchem.com
Level 1
Level 1
‎03-17-2020 08:51 AM
Yes I created "sponsor-api' and added him to all accounts group(this group has checkbox for allowing API). Doing sponsor calls using it. I tested my credentials by logging into sponsor portal successfully. Im still getting 401.
kimqv
Level 1
Level 1
‎04-27-2020 03:30 AM

Hi ,

I need help for creating on REST API-  Guest account - daily change username /password, and publish to Intranet.

 

Riccardo Atzeni
Level 1
Level 1
‎01-24-2023 10:39 AM

Hello Everyone,
I'm facing a strange error using the APIs: I'm trying to create a user on ISE 3.1, the user is created if I get a look via GUI to the sponsor portal but every time I'm receiving the following error:

{
  "ERSResponse" : {
    "operation" : "POST-create-guestuser",
    "messages" : [ {
      "title" : "Creating GuestUser failed due to com.cisco.cpm.guestaccess.exception.GuestAccessSystemException: java.util.concurrent.TimeoutException",
      "type" : "ERROR",
      "code" : "CRUD operation exception"
    } ],
    "link" : {
      "rel" : "related",
      "href" : "https://<IPADDRESS>:<PORT>/ers/config/guestuser",
      "type" : "application/xml"
    }
  }
}


Can you help me to understand what is happening?

Peter Koltl
Level 7
Level 7
‎09-12-2023 02:48 AM

Is it a requirement for the sponsor API that the Sponsor Portal authentication is set to Sponsor_Portal_Sequence or similar basic authorization? If the Sponsor Portal is set to SAML authentication, can the method above used for API?

 

Gioacchino
Level 1
Level 1
‎03-26-2024 03:49 AM

I'm taking for granted that the data shown in the section

Creating a GuestUser without Username and Password

are the minimum for the user to be created.
I wonder if in the dict ""guestAccessInfo", the three fields "validDays", "fromDate", and "toDate" are all mandatory and what happens if there is an inconsistency among them.

Regards,

Gio

Getting Started

Find answers to your questions by entering keywords or phrases in the Search bar above. New here? Use these resources to familiarize yourself with the community:

Top