CLARIN Federated Content Search (CLARIN-FCS) - AAI 1.0

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as in RFC2119.

The following typographic conventions for XML fragments will be used throughout this specification:

Endpoints and Clients MUST adhere to the XML-Namespaces specification. The CLARIN-FCS interface specification generally does not dictate whether XML elements should be serialized in their prefixed or non-prefixed syntax, but Endpoints MUST ensure that the correct XML namespace is used for elements and that XML namespaces are declared correctly. Clients MUST be agnostic regarding syntax for serializing the XML elements, i.e. if the prefixed or un-prefixed variant was used, and SHOULD operate solely on expanded names, i.e. pairs of namespace name and local name.

The aggregator allows an optional login via Shibboleth. Authentication of search queries which are sent to an FCS endpoint is implemented using authentication headers with JSON Web Token (JWT). User information (e.g. mail address or similar) is encoded in the token as claims.

JWTs include an RSA signed token which SHOULD be checked by the respective endpoint. In case of missing or insufficient authorization when accessing restricted resources, the endpoint MUST rise an error using SRU diagnostic "Authentication error" (info:srw/diagnostic/1/3).

The aggregator owns a single common RSA key for all endpoints. For all endpoints with restricted resources its public key has to be manually transferred and included in their configuration. Communication between aggregator and endpoints is only allowed via SSL. Claims iss, sub and aud SHOULD be encoded in the JWT. The endpoint MUST check aud to see if it is the correct recipient and MAY check the fields iss and exp.

The availability and nature of a personal identifier attribute in the aggregator itself, is not guaranteed for a successful login. In SAML this is limited by the configuration of the external IdP selected by the user. When available, one of three SAML attributes is used as user personal identifier: email, eduPersonPrincipalName or eduPersonTargetedID. These attributes are mapped by the aggregator to userID in the same order of preference. userID is then passed to the endpoint. The aggregator issues this information to JWTs and sends it to the appropriate endpoints. The endpoints alone announces which authentication information is required (see next section) and decides at runtime whether the information provided is sufficient for access. While the aggregator front end can inform and guide the user in advance, in case authentication information is still missing.

In order to announce restricted resources the endpoint needs to explain in the <Resources> section of the <EndpointDescription> that it does support the aforementioned procedure for a resource. This is done via a dedicated element <AvailabilityRestriction>:

The <AvailabilityRestriction> is defined in the top-level <Resource> element and the restriction is valid for its complete sub-tree hierarchy of <Resource> elements. From the backwards compatibility perspective this means that if you do not define the <AvailabilityRestriction> element all resources will be available for searching through the endpoint.

The text node requirementName in <RestrictionRequirement> is either of authOnly or personalIdentifier. authOnly does not require any attributes except for the authentication via home institution. If personalIdentifier is stated eduPersonPrincipalName or eduPersonTargetedID or email is passed to the endpoint as userID using the procedure described above.