Authentication Support in HeFQUIN

Basic Authentication

HeFQUIN supports HTTP Basic authentication. The username and password are supplied separately through environment variables and are used to construct the HTTP Authorization: Basic <credentials> header. See RFC 7617 for more information.

The following is an abbreviated example of a federation member using HTTP Basic authentication, with the username and password supplied through environment variables:

PREFIX xsd:    <http://www.w3.org/2001/XMLSchema#>
PREFIX fd:     <http://w3id.org/hefquin/feddesc#>
PREFIX ex:     <http://example.org/>
PREFIX td:     <https://www.w3.org/2019/wot/td#>
PREFIX wotsec: <https://www.w3.org/2019/wot/security#>

ex:MyEndpoint a fd:RDFBasedFederationMember ;
      fd:serviceURI "http://example.org/sparql"^^xsd:anyURI ;
      fd:interface [ a                         fd:FixedEndpointInterface ;
                     fd:supportedProtocol      fd:SPARQLProtocol ;
                     fd:endpointAddress        "http://example.org/sparql"^^xsd:anyURI ;

                     td:hasSecurityConfiguration [ a                wotsec:BasicSecurityScheme ;
                                                   fd:envarForUsername "usernameEnvVarName" ;
                                                   fd:envarForPassword "passwordEnvVarName"
                   ] .
            

Bearer Authentication

Bearer authentication uses the Authorization: Bearer <token> HTTP header. It can be configured using the predefined wotsec:BearerSecurityScheme security scheme, with the token value supplied separately through an environment variable. Alternatively, Bearer authentication can also be represented using HeFQUIN's fd:TokenBasedSecurityScheme by setting wotsec:name to "Bearer". The Bearer authentication scheme is defined in RFC 6750.

The following is an abbreviated example of a federation member using the predefined Bearer security scheme:

PREFIX fd:     <http://w3id.org/hefquin/feddesc#>
PREFIX ex:     <http://example.org/>
PREFIX td:     <https://www.w3.org/2019/wot/td#>
PREFIX wotsec: <https://www.w3.org/2019/wot/security#>

ex:MyEndpoint a fd:RDFBasedFederationMember ;
      # ...
      fd:interface [ a                         fd:FixedEndpointInterface ;
                     # ...
                     td:hasSecurityConfiguration [ a                wotsec:BearerSecurityScheme ;
                                                   fd:envarForToken "tokenEnvVarName"
                   ] .
            

Generic Token-based Authentication with a Custom Authentication Scheme

Generic token-based authentication can be used if a federation member expects a token in the HTTP Authorization header. The authentication scheme can be specified using wotsec:name, with the token value supplied separately through an environment variable. For example, GraphDB uses the GDB authentication scheme, resulting in an Authorization: GDB <token> header. See the GraphDB access control documentation for more information.

The following is an abbreviated example of a federation member configured to use the generic token-based security scheme with GDB as the custom authentication scheme:

PREFIX fd:     <http://w3id.org/hefquin/feddesc#>
PREFIX ex:     <http://example.org/>
PREFIX td:     <https://www.w3.org/2019/wot/td#>
PREFIX wotsec: <https://www.w3.org/2019/wot/security#>

ex:MyEndpoint a fd:RDFBasedFederationMember ;
      # ...
      fd:interface [ a                         fd:FixedEndpointInterface ;
                     # ...
                     td:hasSecurityConfiguration [ a                fd:TokenBasedSecurityScheme ;
                                                   wotsec:name      "GDB" ;
                                                   fd:envarForToken "tokenEnvVarName" ]
                   ] .
            

fd:TokenBasedSecurityScheme uses the fd prefix instead of wotsec. That is because the generic token-based security scheme is a HeFQUIN-specific security scheme for token-based authentication with a custom Authorization scheme. The Web of Things security vocabulary provides predefined security schemes, such as wotsec:BearerSecurityScheme and wotsec:BasicSecurityScheme, each with a specific, predefined meaning. These schemes can therefore not be used to represent an arbitrary authentication scheme.

Supplying Credentials through Environment Variables

The values of fd:envarForToken, fd:envarForUsername, and fd:envarForPassword are names of environment variables, not the actual authentication credentials. Credentials and other secrets should not be written directly into the federation description. Instead, HeFQUIN reads the corresponding values from the environment at runtime.

For example, if the federation description contains:

fd:envarForToken "tokenEnvVarName"

open a terminal and set the corresponding environment variable using the export command, before starting HeFQUIN. For example:

export tokenEnvVarName="your-token"

Similarly, Basic authentication can be configured by setting the username and password environment variables in the terminal:

export usernameEnvVarName="your-username"
export passwordEnvVarName="your-password"

HeFQUIN will then read these values when it is started from the same terminal and use them when constructing requests to the corresponding federation member.