CloudStack Integration UI and API Customization and Integration CloudStack Developer On Ramp May 3, 2012
What you will learn • How to customize the CloudStack 3.0.x user interface ᵒ Showcase changes specific in the CSS to alter the look and feel of CloudStack ᵒ Showcase an example of how to add your own side navigation ᵒ Dealing with Cross Site Request Forgery (CSRF) ᵒ Simple Single Signon ᵒ Localization 2
What you will learn • Working with the API ᵒ Session Based Auth vs API Key Auth ᵒ How to sign a request with apiKey/secretKey ᵒ Asynchronous commands ᵒ Response Format ᵒ Pagination • Q&A
Customizing the CloudStack User Interface Editing the CSS Localization
Adding navigation buttons and functionality 4. Open /ui/index.jsp. Create HTML 5. Enclose a function in 'testSection', somewhere in the 'template' div to which returns a jQuery object contain your HTML content, which will be containing your template code, and drawn in the browser pane: whatever other content you wish to
Adding navigation buttons and functionality 7. (optional) Add an icon for your new section in the CSS, either at the bottom of /ui/css/cloudstack3.css or in your own CSS file under /ui/css folder. Make sure the size of the icon is ~32x32 pixels:
Cross Site Request Forgery (CSRF) • Type of malicious exploit of a website whereby unauthorized commands are transmitted from a user that the website trusts. Unlike cross-site scripting (XSS), which exploits the trust a user has for a particular site, CSRF exploits the trust that a site has in a user's browse • What does CS do to prevent this? ᵒ After execution of the login command you will get two session variables • JSESSIONID – default cookie • SESSIONKEY – random token that is passed along every API request - http://<API URL>?sessionkey=<SESSIONKEY>&…
Simple Single Signon http://<api_url>? command=login&username=XXX&domainid=NNN×tamp=YYY&signature= <secure-hash> • You do not need to pass in the API Key • The four parameters that must be passed in for the login command are domainId, username, timestamp, and signature • security.singlesignon.key • security.singlesignon.tolerance.millis • SAML?
Localization ᵒ Support for Japanese and Simplified Chinese ᵒ Takes advantage of the Java ResourceBundle to do localization ᵒ Simply create a /WEB-INF/classes/resources/messages_<language code>.properties ᵒ Server side vs Client side processing
Session-based Auth vs API Key Auth • CloudStack supports two ways of authenticating via the API. • Session-based Auth ᵒ Uses default Java Servlet cookie based sessions ᵒ Use the “login” API to get a JSESSIONID cookie and a SESSIONKEY token ᵒ All API commands require both cookie and token to authenticate ᵒ Has a timeout as configured within Tomcat • API Key Auth ᵒ Works similarly to AWS API ᵒ Requires a bit more coding to generate the signature ᵒ All API commands require a signature hash
SIGNING REQUEST WITH API KEY / SECRET KEY Step 1: commandString = command name + parameters + api key URL encode each field-value pair within the commandstring Step 2: Lower case the entire commandString and sort it alphabetical y via the field for each field-value pair. sortedCommandString : apiKey=vmwij … &command=createvolume&diskofferingid=1&name=smallvolume=zoneid=1 Step 3: Take the sortedCommandString and run it through the HMAC SHA-1 hashing algorithm (most programming languages offer a utility method to do this) with the user’s Secret Key. Base64 encode the resulting byte array in UTF-8 so that it can be safely transmitted via HTTP. The final string produced after Base64 encoding should be SyjAz5bggPk08I1DE34lnH9x%2f4%3D
Asynchronous Commands ᵒ Starting with 3.0, in your standard CRUD (Create, Read, Update, Delete) of any first class objects in CloudStack, CUD are automatically asynchronous. R is synchronous. ᵒ Rather than returning a response object, it will return a job ID. ᵒ If it is a “Create” command, it will also return the object ID. ᵒ With the job ID, you can query the async job status via the queryAsyncJobResult command. ᵒ The queryAsyncJobResult response will return the following possible job status code: • 0 - Job is still in progress. Continue to periodically poll for any status changes. • 1 - Job has successfully completed. The job wil return any successful response values associated with command that was originally executed. • 2 - Job has failed to complete. Please check the <jobresultcode> tag for failure reason code and <jobresult> for the failure reason.
RESPONSE FORMAT CloudStack supports two formats as the response to an API cal . The default response is XML. If you would like the response to be in JSON, add &response=json to the Command String.
Pagination • Using the page and pagesize parameter • page defines the current cursor to the list • pagesize defines the number of items per request • Pagesize is limited by the administrator • Sample: • listVirtualMachines&page=1&pagesize=500 • listVirtualMachines&page=2&pagesize=500