CGE User Authentication

Apache Shiro configuration

The server relies upon Apache Shiro to provide the authentication layer, this allows for a wide range of configurations that can be tailored to your requirements. Note that authentication does not imply authorisation, it is perfectly possible to create A configuration where a user can authenticate themselves but does not have the authorisation to actually perform actions against the database.

In order to enable authentication you must provide a valid Shiro configuration file, which is beyond the scope of this publication.

For more information, see Generate a Shiro Configuration Template Using the generate shiro Command and visit http://shiro.apache.org/configuration.html and http://shiro.apache.org/web.html. As many users may not be familiar with this framework the command line interface includes a helper command that will generate templates for the most common configurations.

Enabling user authentication

$ cge-cli fe --security example.ini

User Authorization

$ cat ~/.ssh/id_rsa.pub | sed 's/my-name/other-user/'>> /my/db/authorized_keys

In this example the user is authorizing their public key to be used by other-user. This does not grant that user the ability to connect to the database directly with this key as they would not have access to the corresponding private key. Essentially, the user delegates the ability for a process owned by themselves to use a key pair owned by themselves, on behalf of another user.

Login Mechanisms

Apache Shiro supports two login mechanisms which can be used as desired. Firstly it supports HTTP Basic authentication, in this mode any attempt to access the server that requires authentication Will send a HTTP authentication challenge back to the client. In a web browser this will typically result in the browser presenting a login prompt to the user. When the user enters their credentials this is submitted back to server for the server to verify against the configured authentication realm. In this mode every request to the server requires credentials to be presented, however most browsers will remember credentials for the life of the browser session and automatically submit them with subsequent requests.

Secondly it supports forms authentication, in this mode any attempts to access the server that requires authentication will redirect the user to the login page. The server provides a login page at /login so Shiro configurations should use that as the login URL. The user can then enter their credentials in a form in the browser before submitting them back to the server for the verification. In this mode the server will use cookies to identify the user, it checks the cookie against its record of logged in users to determine if the user has previously authenticated. This means that the user need only present their credentials once and thereafter need only present the cookie.

Which login mechanism is selected to be sued will depend on how the user intends to use the server. If you primarily use the server to provide SPARQL endpoints for access by SPARQL tools and libraries then you are better off using basic authentication as many tools and libraries do not support forms authentication. On the other hand if you are primarily using the server for the browser interface then forms authentication is more user-friendly.

LDAP Integration

$ cge-cli generate shiro ldap > example.ini

[main]
# Define a LDAP realm
ldapRealm = org.apache.shiro.realm.ldap.JndiLdapRealm
 
# Configure the template for User lookups
# You will need to ask a system administrator what the format should be here
# The following is the default on Urika-GX systems as shipped but your system
# administrator may have
ldapRealm.userDnTemplate = uid={0},ou=People,ou=external,dc=local
 
# Configure to point to LDAP server of choice
# The LDAP server resides on the login1 node on Urika-GX systems as shipped
# 389 is the normal default port for LDAP servers
ldapRealm.contextFactory.url = ldap://host-login1:389
 
# Only uncomment and change this if your server needs a specific auth mechanism.
# By default the client should negotiate this automatically with the server
#ldapRealm.contextFactory.authenticationMechanism = DIGEST-MD5
 
# If your LDAP server needs credentials to access it set them here
# In most cases this should be unecessary
#ldapRealm.contextFactory.systemUsername = ldap-admin
#ldapRealm.contextFactory.systemPassword = ldap-admin-password
 
# Associate the realm with the security manager
securityManager.realms = $ldapRealm
 
# Enable auth caching, reduces load on the LDAP server
# Comment this out to disable caching
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager
 
# Configure the login page, /login is the page provided by the CGE SPARQL Server
authc.loginUrl = /login
 
[urls]
# Enable logouts
/logout = logout
 
# Require authentication for all paths, comment this out and uncomment the subsequent line
# if you prefer to use HTTP Basic Authentication rather than Forms Authentication
/** = authc
#/** = authcBasic

ldapRealm.contextFactory.url = ldap://host-login1:389

To use the system LDAP server provided on a Urika-GX System this should be set to the login1 node of the system. For example if your system was named machine then the URL should be ldap://machine-login1:389. If it is required to use a central LDAP server, contact the IT department to determine the correct URL to use.

ldapRealm.userDnTemplate = uid={0},ou=People,ou=external,dc=local

The example given here is the distinguished name format used by default on Urika-GX Systems. However your system administrator and/or IT department may use a very different format. If this setting is incorrect, all attempts to authenticate will fail. Please contact the system administrator and/or IT department to determine the correct distinguished name format.

There are a variety of other LDAP related settings seen in the generated template but these are all commented out as they should not be needed for most common LDAP setups. If the two aforementioned settings are correctly configured and you are still unable to authenticate successfully please contact the System administrator and/or IT department to enquire whether any advanced settings are needed.

Configuration properties

Once the preferred configuration has been put in place, it may be helpful to specify all the relevant options directly in the cge.properties file, instead of having to remember all the command line options. Doing this will help specify a default configuration, which is automatically picked up and applied. The following table details all the available properties that can be used to change the configuration of the SPARQL server.