JBoss.orgCommunity Documentation

Chapter 7. Overlord S-RAMP Implementation

7.1. Overview
7.2. Server
7.2.1. Description
7.2.2. Configuring
7.2.3. Configuring (EAP)
7.2.4. Security (Authentication)
7.2.5. Security (Authorization)
7.2.6. Extending: Custom Deriver
7.3. Client
7.3.1. Basic Usage
7.3.2. Extended Feature: Ontologies
7.3.3. Extended Feature: Auditing
7.3.4. Extending: Custom Expander

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.

Overlord S-RAMP also provides a Java based client library that consumers can use to integrate their own applications with an S-RAMP compliant server.

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:


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


The relevant section looks something like this:

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

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

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 Overlord S-RAMP implementation includes Artifact Derivers 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 Artifact Derivers for their own artifact types. This is done by performing the following steps:

  1. Write a custom Deriver Java class - it must implement ArtifactDeriver
  2. Create a DeriverProvider (a class that implements DeriverProvider) - used to map artifact types to implementations of ArtifactDeriver
  3. Provide a text file named org.overlord.sramp.common.derived.DeriverProvider 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
  4. Package everything up into a JAR and make it available either on the classpath or in an external directory configured by setting property sramp.derivers.customDir.

The Overlord S-RAMP distribution comes with an example of how to write and package a custom deriver - the demo is named s-ramp-demos-custom-deriver.

As mentioned, the Overlord S-RAMP implementation also provides a Java client library that can be used to integrate with S-RAMP compliant servers. This section of the guide describes how to use this library.

The S-RAMP client is a simple Java based client library and can be included in a Maven project by including the following pom.xml dependency:


Once the library is included in your project, you can use the client by instantiating the SrampAtomApiClient class. Note that the client class supports pluggable authentication mechanisms, although BASIC auth is a simple matter of including the username and password upon construction of the client.

Please refer to the javadoc of that class for details, but here are some usage examples to help you get started (code simplified for readability):

Upload an XSD document to S-RAMP

SrampAtomApiClient client = new SrampAtomApiClient(urlToSramp);
String artifactFileName = getXSDArtifactName();
InputStream is = getXSDArtifactContentStream();
ArtifactType type = ArtifactType.XsdDocument();
BaseArtifactType artifact = client.uploadArtifact(ArtifactType.XsdDocument(), is, artifactFileName);

Create a custom artifact in S-RAMP (meta-data only, no file content)

SrampAtomApiClient client = new SrampAtomApiClient(urlToSramp);
ExtendedArtifactType artifact = new ExtendedArtifactType();
artifact.setName("My Test Artifact #1");
artifact.setDescription("Description of my test artifact.");
BaseArtifactType createdArtifact = client.createArtifact(artifact);

Retrieve full meta-data for an XSD artifact by its UUID

SrampAtomApiClient client = new SrampAtomApiClient(urlToSramp);
String uuid = getArtifactUUID();
BaseArtifactType metaData = client.getArtifactMetaData(ArtifactType.XsdDocument(), uuid);

Retrieve artifact content

SrampAtomApiClient client = new SrampAtomApiClient(urlToSramp);
String uuid = getArtifactUUID();
InputStream content = client.getArtifactContent(ArtifactType.XsdDocument(), uuid);

Query the S-RAMP repository (by artifact name)

SrampAtomApiClient client = new SrampAtomApiClient(urlToSramp);
String artifactName = getArtifactName();
QueryResultSet rset = client.buildQuery("/s-ramp/xsd/XsdDocument[@name = ?]")