XSA API Developer Guide

What Is XSA?

The XSA (XLcloud Stack Agent) is a Java application that can be run on XLcloud stack instances. It is used to create a RESTful servlet for a stack, providing business logic. E.g. a SLURM stack can provide methods to submit and monitor HPC jobs. XSA consists of a core module and various extensions (such as the aforementioned HPC extension). The core module is responsible for:

  • setup and configuration of the RESTful servlet,
  • XSA extensions lookup and validation on application startup,
  • user authorization in OpenAM.

Installation and configuration of XSA should be handled by Chef using a proper cookbook. An "xsa" cookbook is available in the default "XLcloud Cookbooks" repository. To deploy XSA, Java and GlassFish need to be available on the target instance.

More information on XSA and extension development can be found here: M5-kickoff-XSA-deepdive.odp

User Authorization

Using the XSA API requires user authorization with the "Authorization" header, just like the XMS API does. The same access tokens can be used, that the are normally passed to XMS.

Whenever a user accesses an XSA API resource, XSA validates whether the user has appropriate entitlements. It is done by sending a GET request on xmsApiUri/entitlements, e.g. http://toolcloud:8090/xlcloud-xms/entitlements. The request sent there is identical to the one that would be sent to OpenAM, with the only difference being the resource entitlements for which we want to validate. The resource is prepended with the XSA endpoint URI. E.g. if we want to validate entitlements for resource applications/osu_latency/jobs, the resource that will be sent in the request will be Based on the XSA endpoint URI, XMS will then be able to determine which stack the request is coming from, and send an actual request to OpenAM, prefixing the requested resource with accounts/{account_id}/stacks/{stack_id}/. So, in the given example, the entitlement that would be validated in the end could be accounts/105/stacks/2/applications/osu_latency/jobs.

The described flow (for resource applications) is illustrated in the diagram below.


This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 5.4.6 - Documentation - Legal Notice

Site maintained by