Artificer Implementation
------------------------

Overview
~~~~~~~~
The Artificer 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.


Server
~~~~~~
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:

1. JPA (Hibernate) + Hibernate Search + RDBMS - used as the persistence engine, where all Artificer data is stored.  Artifacts
and ontologies are both stored as typical JPA entities.  All Artificer queries are mapped to JSQL
queries for processing by the JPA API.  Performant searching is provided by Hibernate Search, while the backing
storage utilizes H2 (by default).  Note that all of this is fully configurable and replaceable!

2. JAX-RS (RESTEasy) - used to provide the Artificer Atom based REST API.  The S-RAMP specification
documents an Atom based REST API that implementations should make available.  The Artificer
implementation uses JAX-RS (specifically RESTEasy) to expose all of the REST endpoints defined
by the specification.

3. JAXB - used to expose a Java data model based on the S-RAMP data structures defined by the
specification (S-RAMP XSD schemas).


Security
^^^^^^^^
The Artificer Browser is protected using web application security mechanisms
configured in the WARs' web.xml.

By default, the UI uses single-sign-on (SSO) as the actual authentication
mechanism.  The SSO is provided via integration with the Keycloak framework.
The actual web.xml configuration uses a standard basic security-context, but SSO
is provided under-the-hood.

The security domain is configured to accept either a username
and password (standard BASIC authentication) or a bearer token.
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 the bearer token as a request header ("Authorization", "Bearer " + bearerToken).
For example, the Artificer CLI
application uses BASIC authentication when invoking the Artificer Atom API.  The Artificer
Browser (a web application) requires the user be authenticated into it, and thus is
able to use the bearer tokens rather than propagate user credentials.

The app uses a Keycloak realm named *artificer*, which you'll see used in *standalone-full.xml*'s Keycloak subsystem
resources.  See *Getting Started* for more info.