{toc}
Controlling access to a GraphDB repository and assigning user accounts to roles with specified access permissions is achieved with a combination of HTTP authentication and the Sesame server's deployment descriptor. Sesame and GraphDB have no separate access control mechanisms, therefore to control access, GraphDB must be deployed using the Sesame HTTP server.
Using this technique will allow an administrator to:
* Create security constraints on operations (reading statements, writing statements, modifying named graphs, changing namespace definitions, etc.);
* Group security constraints in to security roles;
* Manage user accounts and assign these to specific security roles.
h1. Operations
The Sesame HTTP server is a servlet-based Web application deployed to any standard servlet container - for the remainder of this section it is assumed that Tomcat is being used.
The Sesame server exposes its functionality using a [RESTful|http://en.wikipedia.org/wiki/Representational_state_transfer] API that is an extension of the [SPARQL protocol for RDF|http://www.w3.org/TR/sparql11-protocol/]. This protocol defines exactly what operations can be achieved using specific URL patterns and HTTP methods (GET, POST, PUT, DELETE). Each combination of URL pattern and HTTP method can be associated with a set of user roles, thus giving very fine-grained control.
The following diagram shows the URL patterns associated with groups of operations on a Sesame HTTP server.
{noformat}
<SESAME_URL>
/protocol : protocol version (GET)
/repositories : overview of available repositories (GET)
/<REP_ID> : query evaluation on a repository (GET/POST)
/statements : repository statements (GET/POST/PUT/DELETE)
/contexts : context overview (GET)
/size : count of statements in repository (GET)
/namespaces : overview of namespace definitions (GET/DELETE)
/<PREFIX> : namespace-prefix definition (GET/PUT/DELETE)
/rdf-graphs : overview of named graphs (GET)
/<NAME> : directly named graph (GET/POST/PUT/DELETE)
/service : indirectly named graph (GET/POST/PUT/DELETE)
{noformat}
_This diagram is copied (with modifications) from chapter 4 of the [online Sesame 2 system guide|http://openrdf.callimachus.net/sesame/2.7/docs/system.docbook?view#chapter-http-protocol]._
In general, read operations are effected using GET and with PUT, POST and DELETE for write operations. The exception to this is that POST is allowed for SPARQL queries. This is for practical reasons, because some HTTP servers have limits on the length of parameter values for GET requests.
h1. Security constraints and roles
The association between operations and security roles is specified using security constraints in the Sesame server's deployment descriptor - a file called {{web.xml}} that can be found in the {{.../webapps/openrdf-sesame/WEB-INF}} directory.
{note}
{{web.xml}} will be present immediately after installation without any security roles defined. If this file is edited, then care must be taken to create a backup - if the Sesame HTTP server is redeployed, then it will overwrite {{web.xml}} with the default version. In particular, do not edit this file while Tomcat is running.
{note}
The deployment descriptor defines:
* authentication mechanism/configuration;
* security constraints in terms of operations (URL pattern plus HTTP method);
* security roles associated with security constraints.
To enable authentication, add the following XML element to {{web.xml}} inside the {{<web-app>}} element:
{noformat}
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>Sesame</realm-name>
</login-config>
{noformat}
Security constraints associate operations (URL pattern plus HTTP method) with security roles. Both security constraints and security roles are nested in the {{<web-app>}} element.
A security constraint minimally consists of a collection of web resources (defined in terms of URL patterns and HTTP methods) and an authorisation constraint (the role name that has access to the resource collection). Some example security constraints are shown below:
{noformat}
<security-constraint>
<web-resource-collection>
<web-resource-name>SPARQL query access to the 'test' repository</web-resource-name>
<url-pattern>/repositories/test</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>viewer</role-name>
<role-name>editor</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>
Read access to 'test' repository's namespaces, size, contexts, etc
</web-resource-name>
<url-pattern>/repositories/test/*</url-pattern>
<http-method>GET</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>viewer</role-name>
<role-name>editor</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>Write access</web-resource-name>
<url-pattern>/repositories/test/*</url-pattern>
<http-method>POST</http-method>
<http-method>PUT</http-method>
<http-method>DELETE</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>editor</role-name>
</auth-constraint>
</security-constraint>
{noformat}
The ability to create and delete repositories requires access to the SYSTEM repository. An administrator security constraint for this would look like the following:
{noformat}
<security-constraint>
<web-resource-collection>
<web-resource-name>Administrator access to SYSTEM</web-resource-name>
<url-pattern>/repositories/SYSTEM/</url-pattern>
<url-pattern>/repositories/SYSTEM/*/</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
<http-method>PUT</http-method>
<http-method>DELETE</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>administrator</role-name>
</auth-constraint>
</security-constraint>
{noformat}
Also nested inside the {{<web-app>}} element are definitions of security roles. The format is best shown by example:
{noformat}
<security-role>
<description>
Read only access to repository data
</description>
<role-name>viewer</role-name>
</security-role>
<security-role>
<description>
Read/write access to repository data
</description>
<role-name>editor</role-name>
</security-role>
<security-role>
<description>
Full control over the repository, as well as creating/deleting repositories
</description>
<role-name>administrator</role-name>
</security-role>
{noformat}
h1. User accounts
Tomcat has a number of ways to manage user accounts. The different techniques are called 'realms' and the default one is called 'UserDatabaseRealm'. This is the simplest one to manage, but also the least secure, because usernames and passwords are stored in plain text.
For the default security realm, usernames and passwords are stored in the file {{tomcat-users.xml}} in the Tomcat configuration directory, usually {{/etc/tomcat6/tomcat-users.xml}} on Linux systems. To add user accounts, {{<user>}} elemеnts must be added inside the {{<tomcat-users>}} element, for example:
{noformat}
<user username="adam" password="secret" roles="viewer" />
<user username="eve" password="password" roles="viewer,editor,administrator" />
{noformat}
h1. Programmatic authentication
To use a remote repository where authentication has been enabled, it is necessary to provide the username and password to the Sesame API. Remote repositories will usually be accessed via the {{org.openrdf.repository.manager.RemoteRepositoryManager}} class. Before attempting access, it is necessary to tell the repository manager the security credentials using the following method:
{noformat}
void setUsernameAndPassword(String username, String password)
{noformat}
Alternatively, that can be passed in the factory method:
{noformat}
static RemoteRepositoryManager getInstance(String serverURL, String username, String password)
{noformat}
Controlling access to a GraphDB repository and assigning user accounts to roles with specified access permissions is achieved with a combination of HTTP authentication and the Sesame server's deployment descriptor. Sesame and GraphDB have no separate access control mechanisms, therefore to control access, GraphDB must be deployed using the Sesame HTTP server.
Using this technique will allow an administrator to:
* Create security constraints on operations (reading statements, writing statements, modifying named graphs, changing namespace definitions, etc.);
* Group security constraints in to security roles;
* Manage user accounts and assign these to specific security roles.
h1. Operations
The Sesame HTTP server is a servlet-based Web application deployed to any standard servlet container - for the remainder of this section it is assumed that Tomcat is being used.
The Sesame server exposes its functionality using a [RESTful|http://en.wikipedia.org/wiki/Representational_state_transfer] API that is an extension of the [SPARQL protocol for RDF|http://www.w3.org/TR/sparql11-protocol/]. This protocol defines exactly what operations can be achieved using specific URL patterns and HTTP methods (GET, POST, PUT, DELETE). Each combination of URL pattern and HTTP method can be associated with a set of user roles, thus giving very fine-grained control.
The following diagram shows the URL patterns associated with groups of operations on a Sesame HTTP server.
{noformat}
<SESAME_URL>
/protocol : protocol version (GET)
/repositories : overview of available repositories (GET)
/<REP_ID> : query evaluation on a repository (GET/POST)
/statements : repository statements (GET/POST/PUT/DELETE)
/contexts : context overview (GET)
/size : count of statements in repository (GET)
/namespaces : overview of namespace definitions (GET/DELETE)
/<PREFIX> : namespace-prefix definition (GET/PUT/DELETE)
/rdf-graphs : overview of named graphs (GET)
/<NAME> : directly named graph (GET/POST/PUT/DELETE)
/service : indirectly named graph (GET/POST/PUT/DELETE)
{noformat}
_This diagram is copied (with modifications) from chapter 4 of the [online Sesame 2 system guide|http://openrdf.callimachus.net/sesame/2.7/docs/system.docbook?view#chapter-http-protocol]._
In general, read operations are effected using GET and with PUT, POST and DELETE for write operations. The exception to this is that POST is allowed for SPARQL queries. This is for practical reasons, because some HTTP servers have limits on the length of parameter values for GET requests.
h1. Security constraints and roles
The association between operations and security roles is specified using security constraints in the Sesame server's deployment descriptor - a file called {{web.xml}} that can be found in the {{.../webapps/openrdf-sesame/WEB-INF}} directory.
{note}
{{web.xml}} will be present immediately after installation without any security roles defined. If this file is edited, then care must be taken to create a backup - if the Sesame HTTP server is redeployed, then it will overwrite {{web.xml}} with the default version. In particular, do not edit this file while Tomcat is running.
{note}
The deployment descriptor defines:
* authentication mechanism/configuration;
* security constraints in terms of operations (URL pattern plus HTTP method);
* security roles associated with security constraints.
To enable authentication, add the following XML element to {{web.xml}} inside the {{<web-app>}} element:
{noformat}
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>Sesame</realm-name>
</login-config>
{noformat}
Security constraints associate operations (URL pattern plus HTTP method) with security roles. Both security constraints and security roles are nested in the {{<web-app>}} element.
A security constraint minimally consists of a collection of web resources (defined in terms of URL patterns and HTTP methods) and an authorisation constraint (the role name that has access to the resource collection). Some example security constraints are shown below:
{noformat}
<security-constraint>
<web-resource-collection>
<web-resource-name>SPARQL query access to the 'test' repository</web-resource-name>
<url-pattern>/repositories/test</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>viewer</role-name>
<role-name>editor</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>
Read access to 'test' repository's namespaces, size, contexts, etc
</web-resource-name>
<url-pattern>/repositories/test/*</url-pattern>
<http-method>GET</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>viewer</role-name>
<role-name>editor</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>Write access</web-resource-name>
<url-pattern>/repositories/test/*</url-pattern>
<http-method>POST</http-method>
<http-method>PUT</http-method>
<http-method>DELETE</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>editor</role-name>
</auth-constraint>
</security-constraint>
{noformat}
The ability to create and delete repositories requires access to the SYSTEM repository. An administrator security constraint for this would look like the following:
{noformat}
<security-constraint>
<web-resource-collection>
<web-resource-name>Administrator access to SYSTEM</web-resource-name>
<url-pattern>/repositories/SYSTEM/</url-pattern>
<url-pattern>/repositories/SYSTEM/*/</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
<http-method>PUT</http-method>
<http-method>DELETE</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>administrator</role-name>
</auth-constraint>
</security-constraint>
{noformat}
Also nested inside the {{<web-app>}} element are definitions of security roles. The format is best shown by example:
{noformat}
<security-role>
<description>
Read only access to repository data
</description>
<role-name>viewer</role-name>
</security-role>
<security-role>
<description>
Read/write access to repository data
</description>
<role-name>editor</role-name>
</security-role>
<security-role>
<description>
Full control over the repository, as well as creating/deleting repositories
</description>
<role-name>administrator</role-name>
</security-role>
{noformat}
h1. User accounts
Tomcat has a number of ways to manage user accounts. The different techniques are called 'realms' and the default one is called 'UserDatabaseRealm'. This is the simplest one to manage, but also the least secure, because usernames and passwords are stored in plain text.
For the default security realm, usernames and passwords are stored in the file {{tomcat-users.xml}} in the Tomcat configuration directory, usually {{/etc/tomcat6/tomcat-users.xml}} on Linux systems. To add user accounts, {{<user>}} elemеnts must be added inside the {{<tomcat-users>}} element, for example:
{noformat}
<user username="adam" password="secret" roles="viewer" />
<user username="eve" password="password" roles="viewer,editor,administrator" />
{noformat}
h1. Programmatic authentication
To use a remote repository where authentication has been enabled, it is necessary to provide the username and password to the Sesame API. Remote repositories will usually be accessed via the {{org.openrdf.repository.manager.RemoteRepositoryManager}} class. Before attempting access, it is necessary to tell the repository manager the security credentials using the following method:
{noformat}
void setUsernameAndPassword(String username, String password)
{noformat}
Alternatively, that can be passed in the factory method:
{noformat}
static RemoteRepositoryManager getInstance(String serverURL, String username, String password)
{noformat}