vcommander REST API Draft Proposal v1.1 1. Client Authentication vcommander will use SSL and session-based authentication to secure REST web services. 1. All REST API calls must take place over HTTPS 2. All REST API calls must have a security token (access token) in the http header of each API call a. This token is provided when client authenticate with the vcommander service Login Operation: POST /sessions Description: To authenticate to the API service, POST a request to its login URL. The request body must contain a MIME Base64 encoding of the client credentials in the form: user@organization:password (domain credential) or user:password (local user) Output: A HTTP response is return along with a security token in the header. The security token is in this format: securitytoken: token Notes: This security token is required in all subsequent API requests to the service. This security token must be transmitted to the service via the HTTP header. This security token has an expiry date that is configurable within vcommander. As long as requests are made within this time frame, the expiry date of this security token will be extended. Expired security token requires the client to re-authenticate. Example: Request HTTP 1.1 POST / webservices/services/ VCommanderRestV10/sessions Response Body: PZQkW0HUSFQVeNyZO5uu/TzQie6YYXQdEifBhdL05A
HTTP/1.1 200 OK Headers: securitytoken : DCFyZO0HUSF5uuS0HUSFDGSGif0HUSFBhD=!bob Logout Operation: DELETE /sessions/{securitytoken} Description: To logout and terminate vcommander REST API session, delete the session you created when you logged in. Output: A HTTP response (200 OK) if successful. Notes: This request, like all other authenticated requests, must include the security token in the HTTP header. Example: Request HTTP 1.1 DELETE / webservices/services/ VCommanderRestV10/sessions/ DCFyZO0HUSF5uuS0HUSFDGSGif0HUSFBhD=!bob Response HTTP/1.1 200 OK
A session overview Supplemental Details 1. The above approach is secure enough when using HTTPS. If we wish, we could go future by sending in the username and password encoded with a MD5 digest 2. Query Authentication with additional signature parameters : APIs calls can be authenticated but this make the URL less concise and harder to debug (see Reference #2 below) 3. A session managed on the server is not truly stateless, but this is where purist REST is not what we want.
2. API Version vcommander REST service versioning is in the URL itself. For example, /webservices/services/vcommanderrestv10 (version 1.0) /webservices/services/ VCommanderRestV11 (version 1.1) /webservices/services/ VCommanderRestV20 (version 2) vcommander can update version as API evolves. Sample APIs The following are API samples; other APIs follow the same pattern. Operation POST /session DELETE /session/{securitytoken} GET /catalog/{id} PUT /catalog/{id} POST /catalog/{id}/action/publish POST /catalog/{id}/action/unpublish DELETE /catalog/{id} GET /vm/{remoteid} DELETE /vm/{remoteid} Description Create a session object (login) Delete a session object (logout) Retrieves a service catalog Modifies a service catalog Publish a service catalog Un-publish a service catalog Deletes a catalog Retrieve a Virtual Machine Deletes a Virtual Machine
In-depth Details 1. The current unified SOAP webservice layer delegates all the bulk of the work to the vcommander service layer. We leverage the same architecture for REST. It will just be a unified interface that delegates to the vcommander layer. 2. Both SOAP and REST have an inbound interceptor (our code) that inspects incoming messages. This is where we extract security token from SOAP header or HTTP header (REST) and use this token to authenticate against the vcommander security model. 3. REST unified interface: It uses JAXB to convert vcommander DTO (ie. WSVirtualMachine) to XML and back. 4. To get JAXB to do this, we annotate our DTOs with certain annotation Difference between SOAP and REST: an implementation perspective 1. The inbound security interceptor for SOAP and REST extracts security token from SOAP header and HTTP header respectively 2. The REST service layer needs to be implemented. ie. GET /vm/{remoteid}
Client Reference Implementations The user can use any REST client to communicate with vcommander REST service. We will create a reference client implementation for internal use. 1. Java usage example: RestClient client = new RestClient("https://localhost/webservices/services/"); client.login("superuser", "secret"); WSVirtualMachine vm = client.getvmbyremoteid(wsvirtualmachine.class, "vm-3457"); System.out.println("VM name: "+vm.getname()); System.out.println("Config file: "+vm.getconfigfile()); client.logout(); client.close(); 2. PowerShell Powershell 3.0 has a number of Cmdlets for working with web services. With these Cmdlets, there is no need to use.net Framework object and wrapping them for used in Powershell. This implies that the customer needs to have Powershell 3.0 installed. # Import the module Import-Module VCommanderRestClient #Initialize the global variables Initialize-Configuration #Connect the client Connect-Client #Retrieve a list of Virtual machine $vms = Get=VMs max 10
References 1. http://www.vmware.com/support/vcd/doc/rest-api-doc-1.5-html/ 2. http://broadcast.oreilly.com/2009/12/principles-for-standardizedrest-authentication.html 3. https://www.owasp.org/index.php/rest_security_cheat_sheet