7.5 goobi_rest.xml

The authentication of the REST API is configured in the configuration file goobi_rest.xml. The file is usually located here:

/opt/digiverso/goobi/config/goobi_rest.xml

A sample configuration could look like this:

<?xml version='1.0' encoding='UTF-8'?>
<config>
<endpoint path="/seterrorstep.*">
<method name="post">
<allow netmask="0:0:0:0:0:0:0:1/128" token="CHANGEME"/>
<allow netmask="127.0.0.0/8" token="CHANGEME"/>
</method>
</endpoint>
<endpoint path="/addtoprocesslog.*">
<method name="post">
<allow netmask="0:0:0:0:0:0:0:1/128" token="CHANGEME"/>
<allow netmask="127.0.0.0/8" token="CHANGEME"/>
</method>
</endpoint>
<endpoint path="/closestep.*">
<method name="post">
<allow netmask="0:0:0:0:0:0:0:1/128" token="CHANGEME"/>
<allow netmask="127.0.0.0/8" token="CHANGEME"/>
</method>
</endpoint>
<endpoint path="/process/check.*">
<method name="get">
<allow netmask="127.0.0.0/8" token="CHANGEME"/>
</method>
</endpoint>
<endpoint path="/processes/search">
<method name="get">
<allow netmask="127.0.0.0/8" token="CHANGEME"/>
</method>
<method name="post">
<allow netmask="127.0.0.0/8" token="CHANGEME"/>
</method>
</endpoint>
<endpoint path="/vocabulary/.*">
<cors>
<method>GET</method>
<origin>https://intranda.com</origin>
</cors>
<method name="get">
<allow />
</method>
<method name="post">
<allow />
</method>
</endpoint>
<endpoint path="/mails/disable/.*">
<method name="get">
<allow />
</method>
</endpoint>
</config>

General structure

A configuration consists of several rules for endpoints. These are the <endpoint> elements. An endpoint always has the attribute path, which is used to configure the path of the API endpoint for which the subordinate rules are to apply. This attribute allows wildcards with regular expressions. The sub-elements of <endpoint> are <method> or <cors> elements.

Allow access to API methods

Activation of individual API endpoints with associated HTTP method works with the <method> elements below the endpoints. A method has only one attribute with the name of the HTTP method to which the child elements are to apply. The child elements of the <method> elements are <allow> elements. These elements can be used to control access to the endpoints with the respective HTTP method. They allow IP addresses to be unlocked using IPv4 and IPv6 netmasks and tokens. If the token or netmask attribute is omitted, access is allowed without token or with any IP. If both are omitted, any IP can access the endpoint without a token. This can be useful if you want an endpoint to be completely public or authenticated by other methods (for example, JSON web tokens).

When checking a request, Goobi proceeds according to document sequence and checks the first <endpoint>/<method> pair that matches the request. If no <allow> rule is found that matches the request, Goobi returns status code 401 and refuses to process the request. This also implies that the order of the rules in this configuration file should be observed. If Goobi returns a message with the status code 401, this may be because an endpoint further up has been formulated too generally and Goobi does not advance to a rule further down, as processing is refused on the basis of the rule further up in the document.

CORS

The configuration also allows the activation of cross-origin requests. For this purpose, a <cors> element can be created below an endpoint, in which the allowed methods are configured with <method> elements and the allowed origins with <origin> elements. If a <cors> element is configured below an endpoint, Goobi automatically handles any preflight requests sent by the browser.