WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration

Transcription

1 WCS SOAP Based North Bound Application Program Interfaces (APIs) for Guest User Administration Introduction The goal of this document is to describe the Cisco Wireless Control System (WCS) interface and how client systems can use it. The intended audience for this document is application developers, system integrators, or customers looking to develop solutions using this technology. This document details the APIs exposed by WCS for the creation, deletion, and administration of guest users on wireless LAN controllers using WCS. System High Level, page 2 Zip File Contents, page 2 Requirements for Use of Zip File Programs, page 3 Configuration APIs, page 4 WCS Notifications, page 8 Appendix, page 10 Americas Headquarters: Cisco Systems, Inc., 170 West Tasman Drive, San Jose, CA USA 2007 Cisco Systems, Inc. All rights reserved.

2 System High Level System High Level As shown below, the third party applications interact with the WCS server by way of SOAP/XML over HTTP/S. The WCS server performs operations including the creation or deletion of guest users by interacting with the wireless LAN controllers. Figure 1 Third Party Applications Interact with WCS Server Third party applications SOAP/XML SOAP/XML WCS Server SNMP SNMP LWAPP LWAPP LWAPP LWAPP W S N E W S N E W S N E W S N E A zip file is provided to access the availabe north bound APIs. Zip File Contents A zip file provides all of the files needed to use the North Bound Interface APIs. This zip file contains the following: Client Side Jar file for SOAP APIs Java Test Program to use the APIs JavaDoc for the APIs Sample scripts to compile and run the sample test program Extract the zip file onto the machine from which you want to access the APIs. 2

3 Requirements for Use of Zip File Programs Requirements for Use of Zip File Programs The following actions are required to use the zip file programs: Install Java 1.5.x and ensure that the JAVA_HOME variable is set correctly. Modify the samplerun script to point to the java location. Create a user which has the required permissions to access "North Bound APIs" in WCS using WCS GUI. Compile and run the sample test program. The samplecompile and samplerun scripts are provided. For UNIX platforms, the samplecompile and samplerun scripts can be run directly after 'ConfigTemplateTest' is changed to 'GuestUserTest'. The sample test program provides a command line option that can be used to exercise each of the above APIs. To run the test program, include the following path: c:\>java GuestUserTest <Service URL> <NBAPI username> <NBAPI password> For example: c:\>java GuestUserTest wsuser wcs.1234 This process opens a connection to WCS and enable you to perform operations such as creating or deleting guest users using the command line options provided by the sample test program. Once the sample program (included in the zip file) is compiled and run, you can perform the following guest-user-related operations: List existing guest user templates Create new guest templates Delete existing guest templates Update existing guest templates Apply guest templates to controllers List guest users on controllers Show details of a guest user List controllers with profiles List logged in guest users on controllers List user roles on controllers The sample test program code is also included in the Appendix and can be used as a reference by other application developers. A guest user name can be up to 24 characters long and the name is case sensitive. 3

4 Configuration APIs Configuration APIs Before accessing the north bound APIs from a third party application, the administrator needs to create a user on WCS who has the permissions to access north bound APIs. The following WCS Soap based APIs are provided for the north bound functionality. See API Usage Sequence to determine in which order the APIs should be called to create or remove guest users. createguestusertemplate This API creates a Guest User Account Template in the WCS database. Creating a guest user template object in the WCS database is the first step towards creating a guest user on the WLC. void createguestusertemplate(guestusertemplatews guestusertemplatews) throws java.rmi.remoteexception, This API does not automatically create the guest user on the controller. This API creates the template that is stored in the WCS database. To create the guest user on a controller, use the applyguestusertemplatetocontrollers. Parameters: guestusertemplatews Template Object containing parameters (described below after the API signatures). Throws: WSException If the template already exists or if the input parameters are null. java.rmi.remoteexception For all other conditions. updateguestusertemplate This API updates a guest user template object present in the WCS database. The modified template must be applied to the controller for the changes to take effect. void updateguestusertemplate(guestusertemplatews guestusertemplatews) throws java.rmi.remoteexception, This can be used to modify the lifetime, password, user role, or description for the guest user. Once the template is modified, you can apply it to the guest user. Parameters: 4

5 Configuration APIs guestusertemplatews Template Object containing parameters. Throws: WSException If the template is not found or if the input parameters are null. java.rmi.remoteexception For all other conditions. deleteguestusertemplate This API deletes the guest user from the WLC and also removes the guest user template object from the WCS database. void deleteguestusertemplate(java.lang.string templatename) throws java.rmi.remoteexception, Parameters: templatename Name of the template that needs to be deleted Throws: WSException If the template is not found or if the input parameter is null. java.rmi.remoteexception For all other conditions. getguestusertemplates This API returns all of the guest user template objects stored in the WCS database. GuestUserTemplateWs[] getguestusertemplates() throws java.rmi.remoteexception, Throws: java.rmi.remoteexception For all other conditions. applyguestusertemplatetocontrollers This API applies a guest user template to the list of specified controllers. For example, it creates the given guest user on the list of specified controllers. If no controller IP is provided, the Guest User Template is applied to all controllers currently being managed by the WCS. Prior to using this API, create the template in the WCS database by using the createguestusertemplate API. void applyguestusertemplatetocontrollers(java.lang.string templatename, java.lang. String[] controllers) throws java.rmi.remoteexception, Parameters: templatename Name of the template which needs to be applied to controllers. 5

6 Configuration APIs controllers String array containing IP addresses of the controllers to which the template needs to be applied. Throws: WSException If the template is not found, if the controller with IP is not found, or if the input parameters are null. java.rmi.remoteexception For all other conditions. listguestusersoncontroller This API returns a list of all guest users that exist on a controller. String[] listguestusersoncontroller(string controller) throws java.rmi.remoteexception, Parameters: controllers String containing the IP address of the controller from which the guest users are to be retrieved. Throws: WSException If the controller with IP is not found or if the input parameter is null. java.rmi.remoteexception For all other conditions. listloggedinguestusersoncontroller This API returns a list of currently logged in guest users on a controller. String[] listloggedinguestusersoncontroller(string controller) throws java.rmi.remoteexception, Parameters: controllers String containing the IP address of the controller from which the logged in guest users are to be retrieved. Throws: WSException If the controller with IP is not found or if the input parameter is null. java.rmi.remoteexception For all other conditions. getguestuserdetails This API provides the details of a created guest user given the username and the controller IP on which the user was created. Map getguestuserdetails(java.lang.string username, java.lang.string controllers) throws java.rmi.remoteexception, Map<String,String> contains the following name value pairs: user name password lifetime 6

7 Configuration APIs description User role Profile name WLAN ID Remaining Lifetime Parameters: username Name of the user whose details are sought. controller String containing the IP address of the controller from where the guest user details are to be retrieved. Throws: WSException If the user name is not found, if the controller with IP is not found, or if the input parameters are null. java.rmi.remoteexception For all other conditions. getcontrollerwithprofile This API provides a list of controllers which have the wlan profile name configured. This API can be used by third party applications to get the list of controllers known to WCS on which a given profile name exists. String[] controllers getcontrollerswithprofile(java.lang.string profilename) throws java.rmi.remoteexception, Returns controllers A list of all controllers IP addresses on which the given profile name exists. Parameters: profilename Name of the profile to be checked. Throws: WSException If the user name is not found, if the controller with IP is not found, or if the input parameters are null. java.rmi.remoteexception For all other conditions. getuserrolesoncontroller This API lists all of the user roles that have been configured on the controller. User roles are bandwidth contract templates provisioned on the device. The default user role is default. String[] getuserrolesoncntroller (java.lang.string Controllerip) throws java.rmi.remoteexception, Parameters: controllers String containing IP addresses of the controller from which the user roles are to be fetched. 7

8 WCS Notifications Throws: WSException If the controller with IP is not found or if the input parameter is null. java.rmi.remoteexception For all other conditions. GuestUserTemplateWs object contains the following: Template name (same as Guest user name) Profile id (wlan on the controller) Guest User Password Guest User Lifetime Description for Guest User Remaining lifetime of guest user User role In addition to the above APIs, two additional APIs are provided for third party applications to programmatically log into WCS prior to using the above APIs and log out of WCS. These APIs are detailed below: String login(string in0, String in1) throws java.rmi.remoteexception, ; returns http session id. boolean logout() throws java.rmi.remoteexception; true if successfully logged out, false otherwise. Refer to the sample test program in the Appendix for more details on their usage. API Usage Sequence To create a guest user, follow these steps: Step 1 Step 2 Create the Guest User template by providing all input parameters. Apply the template to the desired WCS-managed controller. To remove a guest user created from WCS and the controller, use the Delete Guest User Template API. To modify a guest user s parameters, follow these steps: Step 1 Step 2 Update the template object. Apply the template to the desired controller. WCS Notifications WCS can also send guest-user-related notifications to a north bound system. WCS currently supports notification through an SNMP trap for north bound notifications. 8

9 WCS Notifications WCS acts as a trap generator to send guest user related traps to third party applications. To receive notifications from WCS, the third party application needs to be added as a notification receiver to WCS. This screen is accessible from Adminsitration > Settings > Notification Receivers and is shown below. Figure 2 Notification Receivers Screen Cisco Device Exeption Reporting In the following conditions, north bound SNMP traps from WCS are provided: guestuserloggedin When WCS receives the trap clwaguestuserloggedin from a wireless LAN controller, it sends a trap north bound. guestuserloggedout When WCS receives the trap clwaguestuserloggedout from a wireless LAN controller, it sends a trap north bound. guestuseradded When WCS receives a trap from a wireless LAN controller notifying that a guest user has been added, it sends a trap north bound. guestuserremoved When WCS receives a trap from a wireless LAN controller notifying that a guest user has been removed from the controller, it sends a trap north bound. The Cisco Device Exception Reporting defines a notification that is used by WCS to send the traps to a third party. This notification is described below: 9

10 cdermonitoredexceptionevent NOTIFICATION-TYPE OBJECTS { cderexcepid, cderexcephostaddresstype, cderexcephostaddress, cderexcepprioritydescription, cderexceptime, cderexcepdata, cderexcepreportedby STATUS current DESCRIPTION "This notification is sent when an exception is detected on the managed device. " ::= { cdermibnotifications 1 This notification is defined as a part of the Cisco mib: CISCO-DEVICE-EXCEPTION-REPORTING-MIB In all of the above conditions, the generated trap is the same but the cderexcepdata defines what type of event has taken place. For example, when a guest user is added, the data field resembles the following: Guest user 'g45' created on the Controller ' ' Appendix The following sample test program code can be used as a reference by other application developers. Sample test program: /** * */ package com.cisco.ws.test; import java.io.ioexception; import java.net.url; import java.rmi.remoteexception; import java.util.hashmap; import java.util.iterator; import java.util.set; import java.util.stringtokenizer; import com.cisco.ws.api.clientapi; import com.cisco.ws.api.clientapiservicelocator; import com.cisco.ws.api.configtemplateapi; 10

11 import com.cisco.ws.api.configtemplateapiservicelocator; import com.cisco.ws.api.configtemplateapistub; import com.cisco.ws.api.guestusertemplatews; import ; import com.cisco.ws.api.clientapistub; public class GuestUserTest { public static void main(string[] args) throws Exception{ System.out.println("Please make sure that user is precreated on WCS and has NorthBoundAPI group assigned to it"); if (args.length!= 3) { printusage(); System.exit(0); System.out.println("WCS IP: " + args[0]); System.out.println("User Name: " + args[1]); System.out.println("Password: " + args[2]); String choice = "1"; ConfigTemplateApi configapi = null; ConfigTemplateApiServiceLocator servicelocator = new ConfigTemplateApiServiceLocator(); ClientApiServiceLocator clientservicelocator = new ClientApiServiceLocator(); URL serviceurl = new URL(args[0] + "/ConfigTemplateApi"); URL clientserviceurl = new URL(args[0] + "/ClientApi"); ClientApi clientapi = null; configapi = servicelocator.getconfigtemplateapi(serviceurl); clientapi = clientservicelocator.getclientapi(clientserviceurl); if (configapi == null ) return; ((ConfigTemplateApiStub) configapi).setmaintainsession(true); configapi.login(args[1], args[2]); System.out.println("\nUser " + args[1] + " successfully logged in "); while (!choice.equals("0")) { System.out.println("\nYou have the following options\n\n" + "1. List Existing Guest User templates\n" + "2. Create NEW Guest Template\n" + "3. Delete existing Guest template\n"+ "4. Update existing Guest template\n" + "5. Apply Guest template to controllers\n" + "6. List Guest Users on controller\n" + "7. Show details of a guest user\n" + "8. List controllers with profile\n" + "9. List Logged in Guest Users on controller\n" + "a. List User Roles on controller\n" + 11

12 "0. Exit program\n\n" + "Enter your choice [0-9]-> "); choice = readinputstring(); System.out.println("Choice is: " + choice); try { char [] cho= choice.tochararray(); switch (cho[0]) { //LIST case '1': listguestusers(configapi); break; //CREATE case '2': createguestuser(configapi); break; case '3': //DELETE deleteguestuser(configapi); break; //UPDATE case '4': updateguestuser(configapi); break; //APPLY TO CONTRLR case '5': applyguestuser(configapi); break; //LIST USERS ON CONTROLLER case '6': ((ClientApiStub) clientapi).setmaintainsession(true); clientapi.login(args[1], args[2]); System.out.println("-Enter the IP address of the controller-"); String controllerip = readinputstring(); String[] gusers = clientapi.listguestusersoncontroller(controllerip); if(gusers.length == 0){ System.out.println("Thre are no Guest users on controller "+controllerip); else{ System.out.println("The controller "+controllerip+ " has the following Guest Users-"); for(int i=0; i<gusers.length; i++){ System.out.println(gUsers[i]); 12

13 clientapi.logout(); break; //SHOW GUEST DETAILS case '7': ((ClientApiStub) clientapi).setmaintainsession(true); clientapi.login(args[1], args[2]); System.out.println("-Enter Guest User name-"); String guser1 = readinputstring(); System.out.println("-Enter the IP address of the controller-"); String controllerip1 = readinputstring(); HashMap detailshashmap = clientapi.getguestuserdetails(guser1, controllerip1); if(!detailshashmap.isempty()){ Set properties = detailshashmap.keyset(); Iterator It = properties.iterator(); while (It.hasNext()) { String property = (String)(It.next()); System.out.println(property + " - " + detailshashmap.get(property)); else { System.out.println("Error in getting properties!"); clientapi.logout(); break; //GET CONTROLLERS WITH PROFILE case '8': ((ClientApiStub) clientapi).setmaintainsession(true); clientapi.login(args[1], args[2]); System.out.println("-Enter Profile name-"); String profile = readinputstring(); String [] controllerips =clientapi.getcontrollerswithprofile(profile); if(controllerips.length == 0){ System.out.println("Thre are no controllers with profile-> "+profile); else{ System.out.println("The following cotrollers have the profile \""+profile+"\" configured "); for(int i=0; i<controllerips.length; i++){ System.out.println(controllerIps[i]); clientapi.logout(); break; //GET LOGGED IN GUESTS case '9' : 13

14 ((ClientApiStub) clientapi).setmaintainsession(true); clientapi.login(args[1], args[2]); System.out.println("-Enter controller IP-"); String controip = readinputstring(); String[] loggedguests = clientapi.listloggedinguestusersoncontroller(controip); if(loggedguests.length == 0){ System.out.println("Thre are no Guest users Logged into controller "+controip); else{ System.out.println("The controller "+controip+ " has the following Guest Users-"); for(int i=0; i<loggedguests.length; i++){ System.out.println(loggedGuests[i]); clientapi.logout(); break; //GET USER ROLES case 'a' : ((ClientApiStub) clientapi).setmaintainsession(true); clientapi.login(args[1], args[2]); System.out.println("-Enter controller IP-"); String switchip = readinputstring(); String[] userroles = clientapi.getuserrolesoncontroller(switchip); if(userroles.length == 0){ System.out.println("Thre are no Guest users Logged into controller "+switchip); else{ System.out.println("The controller "+switchip+ " has the following User Roles-"); for(int i=0; i<userroles.length; i++){ System.out.println(userRoles[i]); clientapi.logout(); break; default : break; catch (WSException e) { System.out.println("Error " + e.getmessage()); configapi.logout(); System.out.println("User " + args[1] + " successfully logged out"); 14

15 private static void applyguestuser(configtemplateapi configapi) throws WSException, RemoteException { System.out.println("Enter Guest User name"); String guser = readinputstring(); System.out.println("Guest User name is: " + guser); System.out.println("Enter comma separated Controller IP addresses..default is all controllers"); String ip = readinputstring(); System.out.println("-- applying Guest User template to controllers -- "); StringTokenizer st = new StringTokenizer(ip, ","); String[] controllers = new String[st.countTokens()]; int i = 0; while (st.hasmoretokens()) { controllers[i++] = (String) st.nexttoken(); if (ip.equalsignorecase("")) { configapi.applyguestusertemplatetocontrollers(guser); else { configapi.applyguestusertemplatetocontrollers(guser, controllers); private static void updateguestuser(configtemplateapi configapi) throws WSException, RemoteException { System.out.println("-Steps to Update an existing guest user-"); GuestUserTemplateWs guestusertemplatews = new GuestUserTemplateWs(); System.out.println("-Enter Guest User Name, you would like to update-"); String guname = readinputstring(); guestusertemplatews.settemplatename(guname); guestusertemplatews.setguestusername(guname); guestusertemplatews.setisguestuser(true); System.out.println("-Enter Guest User password-"); String passwd = readinputstring(); guestusertemplatews.setuserpassword(passwd); System.out.println("-Enter Profile to connect-"); String profile = readinputstring(); guestusertemplatews.setprofile(profile); System.out.println("-Enter Guest User Description-"); String desc = readinputstring(); guestusertemplatews.setdescription(desc); System.out.println("-Enter Guest Lifetime in timeticks(100th of a sec)-"); 15

16 String lifetimestr = readinputstring(); guestusertemplatews.setlifetime(integer.valueof(lifetimestr)); System.out.println("-Enter Guest Role; Default role is 'default'-"); String rolestr = readinputstring(); guestusertemplatews.setuserrole(rolestr); System.out.println("-- Updating Guest User template -- "); configapi.updateguestusertemplate(guestusertemplatews); System.out.println("\nSuccessfully updated Guest User Template "); private static void deleteguestuser(configtemplateapi configapi) throws WSException, RemoteException { System.out.println("--Enter the name of the guest template you wish to delete --"); String deletetemplate = readinputstring(); configapi.deleteguestusertemplate(deletetemplate); System.out.println("Guest Template deleted successfully!"); private static void listguestusers(configtemplateapi configapi) throws WSException, RemoteException { System.out.println("-- Listing Guest user templates -- "); GuestUserTemplateWs[] guestuserarray = configapi.getguestusertemplates(); if (guestuserarray!= null && guestuserarray.length > 0) { for (int i = 0; i < guestuserarray.length; i++) { GuestUserTemplateWs guestuser = (GuestUserTemplateWs) guestuserarray[i]; System.out.println("\nGuest User Template Name -> " + guestuser.gettemplatename()); else { System.out.println("No Guest User config templates found."); private static void createguestuser(configtemplateapi configapi) throws WSException, RemoteException { System.out.println("-Steps to create new guest user-"); GuestUserTemplateWs guestusertemplatews = new GuestUserTemplateWs(); System.out.println("-Enter Guest User Name-"); String guname = readinputstring(); guestusertemplatews.settemplatename(guname); guestusertemplatews.setguestusername(guname); guestusertemplatews.setisguestuser(true); System.out.println("-Enter Guest User password-"); String passwd = readinputstring(); 16

17 guestusertemplatews.setuserpassword(passwd); System.out.println("-Enter Profile to connect-"); String profile = readinputstring(); guestusertemplatews.setprofile(profile); System.out.println("-Enter Guest User Description-"); String desc = readinputstring(); guestusertemplatews.setdescription(desc); System.out.println("-Enter Guest Lifetime in timeticks(100th of a sec)-"); String lifetimestr = readinputstring(); guestusertemplatews.setlifetime(integer.valueof(lifetimestr)); System.out.println("-Enter Guest Role; Default role is 'default'-"); String rolestr = readinputstring(); guestusertemplatews.setuserrole(rolestr); guestusertemplatews.set id(""); guestusertemplatews.setbuilding(""); guestusertemplatews.setcampus(""); guestusertemplatews.setconfiggroup(""); guestusertemplatews.setoutdoorarea(""); guestusertemplatews.setfloorarea(""); System.out.println("-- Creating Guest User template -- "); configapi.createguestusertemplate(guestusertemplatews); System.out.println("\nSuccessfully created Guest User Template "); public static String readinputstring() { String inputstring = ""; while (true) { try { int tmp = System.in.read(); if (tmp == -1 tmp == 10) return inputstring.trim(); char c = (char) tmp; inputstring = inputstring + c; catch (IOException e) { 17

18 public static void printusage() { System.out.println("Usage: Guest user <IP-address of WCS Host> <User Name> <Password>"); CCVP, the Cisco logo, and Welcome to the Human Network are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and Learn is a service mark of Cisco Systems, Inc.; and Access Registrar, Aironet, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Enterprise/Solver, EtherChannel, EtherFast, EtherSwitch, Fast Step, Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient, IOS, iphone, IP/TV, iq Expertise, the iq logo, iq Net Readiness Scorecard, iquick Study, LightStream, Linksys, MeetingPlace, MGX, Networkers, Networking Academy, Network Registrar, PIX, ProConnect, ScriptShare, SMARTnet, StackWise, The Fastest Way to Increase Your Internet Quotient, and TransPath are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries. All other trademarks mentioned in this document or Website are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0711R) 18

19 2007 Cisco Systems, Inc. All rights reserved. 19

20 20