Chapter 11. Overlord S-RAMP Implementation

The Overlord S-RAMP implementation strives to be a fully compliant reference implementation of the S-RAMP specification. This chapter describes the overall architecture of the implementation and also provides some information about how to configure it.

11.2. Server

11.2.1. Description

The server implementation is a conventional Java web application (WAR). The following technologies are used to provide the various components that make up the server implementation:

JCR (ModeShape) - used as the persistence engine, where all S-RAMP data is stored. Artifacts and ontologies are both stored as nodes in a JCR tree. All S-RAMP queries are mapped to JCRSQL2 queries for processing by the JCR API. The ModeShape JCR implementation is used by default. However, the persistence layer is pluggable allowing alternative providers to be implemented in the future.
JAX-RS (RESTEasy) - used to provide the S-RAMP Atom based REST API. The S-RAMP specification documents an Atom based REST API that implementations should make available. The Overlord S-RAMP implementation uses JAX-RS (specifically RESTEasy) to expose all of the REST endpoints defined by the specification.
JAXB - used to expose a Java data model based on the S-RAMP data structures defined by the specification (S-RAMP XSD schemas).

11.2.2. Configuring

Configuration of the server can be done by providing a configuration file to the server on startup. The configuration file can be provided in a number of ways:

sramp.properties - an external file can be provided in the JBoss application server’s configuration directory. An alernative location is the home directory of the user running the application server.
custom external file - a custom location for an sramp.properties file can be specified by starting the application server with the sramp.config.file.name system property set. This is typically done using -Dsramp.config.file.name=<pathToFile> on the application server’s command line startup script (often in JAVA_OPTS).
on the classpath - if no external file is found, the classpath is used to lookup a default configuration.

The configuration file is a simple Java properties file, with the following properties available to be set:

# The base URL of the S-RAMP server - can be useful in some advanced configurations where
# the incoming Request URL is not the canonical server address.
sramp.config.baseurl
# Turn on/off auditing of changes to S-RAMP artifacts
sramp.config.auditing.enabled
# Turn on/off auditing of changes to derived S-RAMP artifacts
sramp.config.auditing.enabled-derived

11.2.3. Configuring (EAP)

When running in JBoss EAP this same configuration information is instead stored in the JBOSS/standalone/configuration/standalone.xml file under the urn:jboss:domain:overlord-configuration:1.0 subsystem. For example:

    <subsystem xmlns="urn:jboss:domain:overlord-configuration:1.0">
      <configurations>
        <configuration name="sramp">
          <properties>
            <property name="sramp.config.auditing.enabled" value="true" />
            <property name="sramp.config.auditing.enabled-derived" value="true" />
          </properties>
        </configuration>
      </configurations>
    </subsystem>

11.2.4. Security (Authentication)

The S-RAMP repository Atom API is protected using standard web application security and JAAS on the backend. When deploying to an application server, security should be configured according to the specifics of the container. Typically the API would be protected by a simple BASIC authentication scheme, but in some more advanced configurations it would be appropriate to use OAuth or SAML Bearer Token authentication mechanisms.

When deploying into JBoss, the S-RAMP distribution adds a JBoss security domain named "overlord-jaxrs". This security domain is configured to accept either a username and password (standard BASIC authentication) or a SAML Assertion (bearer token auth). If invoking the Atom API directly, then typically BASIC authentication would be used. When invoking the Atom API from an application that has already authenticated the user in some way, then it is appropriate to use SAML. For example, the S-RAMP CLI application uses BASIC authentication when invoking the S-RAMP Atom API. The S-RAMP Browser (a web application) requires the user be authenticated into it, and thus is able to use SAML rather than propagate user credentials.

When using simple BASIC authentication, the security domain must be configured with a source of users and passwords. For example, in JBoss EAP this information can be configured by modifying the following files:

jboss-eap-6.x/standalone/configuration/application-users.properties

Alternative mechanisms can be used by making changes to the security domains configured in the JBoss configuration. For example:

jboss-eap-6.x/standalone/configuration/standalone.xml

The relevant section looks something like this:

<security-domain name="overlord-jaxrs" cache-type="default">
  <authentication>
    <login-module code="RealmDirect" flag="required">
      <module-option name="password-stacking" value="useFirstPass"/>
    </login-module>
  </authentication>
</security-domain>

For example, the RealmDirect (which passes through the authentication to the Application Realm) login module could be replaced with a LDAP login module.

11.2.5. Security (Authorization)

When accessing the S-RAMP Atom API, the authenticated user must have certain roles. Because the implementation leverages ModeShape as its persistence store by default, the authenticated user must have the following JAAS role, which is required by ModeShape:

admin.sramp

Additionally, the S-RAMP Atom API web application requires that the user has the following role:

overlorduser

11.2.6. Extending: Custom ArtifactBuilder

As mentioned earlier in this guide, part of the S-RAMP specification is the concept of derived content. This happens when an artifact of a certain type is added to the S-RAMP repository. The server is responsible for creating relevant and interesting derived artifacts from it. For example, when an XML Schema (XSD) document is added to the repository, the server is responsible for automatically creating an artifact for every top level Element, Complex Type, Simple Type, and Attribute declaration found in the XSD.

The ArtifactBuilder contract allows integrations to define custom properties on the primary artifact, generate derived artifacts, and resolve relationships between the whole set. The Overlord S-RAMP implementation includes ArtifactBuilders for all of the logical models defined by the S-RAMP specification (e.g. WSDL, XSD, Policy). However, it also provides a mechanism that allows users to provide ArtifactBuilders for their own artifact types. This is done by performing the following steps:

Write a custom ArtifactBuilder Java class - it must implement ArtifactBuilder
Create an ArtifactBuilderProvider (a class that implements ArtifactBuilderProvider) - used to map artifact types to implementations of ArtifactDeriver
Provide a text file named org.overlord.sramp.common.artifactbuilder.ArtifactBuilderProvider in the following location: META-INF/services. The content of that file should simply be one line containing the fully qualified classname of the class defined in #2
Package everything up into a JAR and make it available either on the classpath or in an external directory configured by setting property sramp.extension.customDir.

The Overlord S-RAMP distribution comes with an example of how to write and package a custom builder - the demo is named s-ramp-demos-custom-artifact-builder. Also, see the Javadocs for the relevant classes.