WebID+TLS+Delegation Usage Guide

What is it?

WebID+TLS+Delegation is an open standards based multi-protocol authentication layer that provides fine-grained attributed-based access controls (ABAC) to protected resources (HTTP-accessible documents, folders, services [via their endpoints], and SPARQL named graphs). In a nutshell, this solution uses logic expressed in the nature of entity relationships to address issues such as identity, authorization, and restriction.





Key Components

The key components of this solution are:

Primary Features

Collectively, the components above enable:

Why is it important?

Explicitly distinguishing the identity of an user and an application is a fundamental requirement for practical attribute-based access controls that leverage open standards such as:

How do I use it?

Server Setup

A Virtuoso Server instance with the WebID+TLS+Delegation feature available needs to be installed on any OS it is available for. Once installed the Virtuoso server needs to be configured to Listen on Secure SSL HTTP (i.e., https) and SQL ports using your own as detailed at:

Additional Virtuoso Components to be installed

The following Virtuoso application should be installed from the System Admin -> Packages tab of the Conductor:

Software Agent Certificate Generation

A Software agent server certificate needs to be generated or provided and associated with a suitable WebID as its SAN (Subject Alternate Name). The OpenLink YouID Certificate Generation service can be used for the create of such certificates, or any other suitable external service can be used.

Software Agent PKCS#12 generation

A PKCS#12 binary format certificate needs to to generated storing the server certificate, any intermediate certificates, and the private key into a single encrypt able password protected file. If intermediary file to complete the chain of trust are not included in the PKCS#12 file then them must either be registered in the Operating System Key store/chain or public keys passed with the -T param during connection.

Software Agents and Users Web IDs generation and uploading

WebID profile documents need to be generate for the software agent and user connections are to be delegated on behalf of and accessible from suitably accessible URI.

Web ID Profile Document Entries

Note: In situations where there are massive numbers of users and a single agent, a single Turtle document can hold data from points 1&2 above.

Example documents

Virtuoso Authentication Layer (VAL) ACL Setup

VAL, the Virtuoso Authentication Layer, is an open-standards-based, multi-protocol authentication layer, that provides fine-grained, attributed-based access controls (ABAC) to protected resources (HTTP-accessible documents, folders, services [via their endpoints], and SPARQL named graphs).

Virtuoso provides access to data across two distinct (but interlinked) functionality realms: HTTP and SQL. Thus, configuring VAL requires creation of Authorization and Restrictions rules that target each of the aforementioned realms, individually.

VAL Authorizations apply to HTTP and/or SQL realms distinctly. Basically, you have an ACL Scope by Virtuoso Realms matrix per basic unit of ABAC functionality.

ABAC ACLs are created by writing a collection of RDF language statements to a special VAL system named graph. These statements describe an instance of an authorization, and where additional restrictions apply they are also used to describe resource usage rate restrictions.

The VAL documentation details how the ABAC ACLs in the various functional Realms can be created. Typically these are created in the following forms:

Examples of such ACLs are detailed in the Sample ACL Script used for the live QA demo below.

Client Application Setup

To use the generated software agent certificate the CA certificate need to be registered with Operating System Keystore or use of PEM file based CA Root Cert bundle passed as part of the client application connection string.

ODBC Connection

An ODBC WebID+TLS+Delegation DSN can be configured as detailed below. In this test scenario the WebID of the user (identified by value of AppUser parameter) is the only identity to which protected resource access has been granted.

  1. Open the ODBC Administrator and create an ODBC DSN for the OpenLink Virtuoso Driver.



  2. Chose and name for the ODBC DSN , enter the hostname & SSL SQL port the Virtuoso server is running on and select the This server requires secure connection (SSL) check box option



  3. Select the Public key authentication protocol of the Authentication Method drop down list box; set the name of the p12 certificate of the software agent to be used and password; set the AppUser to the name of the WebID profile document of the used the connection delegation is to be on behalf of.



  4. For SPARQL request the option in the dialog below can be left blank, or can be set if making SQL requests. Click the Finish button to complete the DSN creation.



Sample Client Application Usage

WebID+TLS+Delegation connections can be tested with various client application to verify the ACLs applied are being enforced.

Virtuoso Interactive SQL (isql)

In this scenario the identity of the software user and the software (application/agent/bot) are distinct, i.e., you have a WebID for the software and a WebID for the software user. In this test scenario the WebID of the user (identified by value of -W parameter) is the only identity to which protected resource access has been granted. 


./isql {virtuoso-hostname}:{SSL-SQL-Port#} "" {app-or-agent-pkcs-file-access-pwd} -X {app-or-agent-pkcs-file} -T {ca-cert-bundle} -W {user-webid}

For example: 


$ ./isql uriburner.com:1113 "" 1234 -X software_agent.p12 -T ca_list_shop_2016.pem -W http://kingsley.idehen.net/public_home/kidehen/profile.ttl#i
Connected to OpenLink Virtuoso
Driver: 07.20.3217 OpenLink Virtuoso ODBC Driver
OpenLink Interactive SQL (Virtuoso), version 07.20.3217.
Type HELP; for help and EXIT; to exit.
SQL> sparql SELECT COUNT (*) FROM <OpenPermID-bulk-assetClass-20151111_095807.ttl.gz> WHERE {?s ?p ?o};
callret-0
INTEGER
_______________________________________________________________________________

5454

1 Rows. -- 819 msec.
SQL>

ODBC CPPDemo Interactive SQL Application

The CPPDemo application bundle the the Virtuoso Client Connectivity Kit can be used for testing and ODBC connection using the DSN created previously:

  1. Start the CPPDemo application.



  2. The CPPDemo sample ODBC interactive SQL application can be used for testing the ODBC connection. Select the Open Connection item under the Environment menu.



  3. Choose the DSN created previously from the list presented.



  4. Enter the password of the p12 certificate for the software agent in the login dialog present and click the OK button to connect.



  5. Select the Execute SQL item of the SQL menu to load text windows to enter query to run.



  6. Enter the query to be executed and click on the OK button; example: 

    sparql SELECT COUNT (*) FROM <OpenPermID-bulk-assetClass-20151111_095807.ttl.gz> WHERE {?s ?p ?o}





  7. The query result set will be returned.



HTTP connection using cURL

In this usage scenario we make use of the "OnBehalfOf?:" custom HTTP request header. The value of this header takes the form of a WebID that identifies the user of an application/agent/bot accessing a protected resource via the HTTP protocol. 


curl -iLk --cert-type P12 --cert {app-or-agent-pkcs-file}:{pkcs-file-access-pwd} --cacert {ca-cert-bundle} -H "OnBehalfOf: {user-webid}" "{uri-for-accessing-protected-resource}"

For example: 


curl -iLk --cert-type P12 --cert VirtuosoLODConnectivity.p12:1234 --cacert ca_list_shop_2016.pem -H "On-Behalf-Of: http://kingsley.idehen.net/public_home/kidehen/profile.ttl#i" "https://linkeddata.uriburner.com/sparql/?default-graph-uri=&query=select+distinct+*+from+%3COpenPermID-bulk-industry-20151111_095806.ttl.gz%3E++where+%7B%5B%5D+a+%3FEntityType%7D+limit+50&should-sponge=&format=text%2Fcsv%2Btr&CXML_redir_for_subjs=121&CXML_redir_for_hrefs=&timeout=30000000"

Note, to protect the certificate password from possible Bash History Exploit Vulnerability, the P12 certificate can be converted to a password protected PEM file with the command: 


openssl app-or-agent-pkcs-file -out app-or-agent-pem-file

and the PEM file (app-or-agent-pem-file) specified instead instead of the P12 file with the {pkcs-file-access-pwd} removed, in which case curl will prompt for the password, which would then not be part of the users bash history.

Sample Use case against Virtuoso Live URIBurner service

The OpenLink URIBurner services has been set up with WebID+TLS+Delegation support enabled, with a number of ACLs in place to control access to resources by software agents and there associated delegated users.

Assuming the following scenario:

A publisher of a document seeks to constrain its access to a specific user or group of users. As part of this effort, the following are desired with regards to user experience:

Sample Resources

Certificates and their Subjects

ACL Definitions Example Script

See sample, below.

Web ID+TLS ISQL/ODBC using TLS Connection Tests

Template ACL for Web ID+TLS ISQL/ODBC using TLS


./isql linkeddata.uriburner.com:1113 "" {app-or-agent-pkcs-file-access-pwd} -X {app-or-agent-pkcs-file} -T {ca-cert-bundle}

Sample ACLs for Web ID+TLS ISQL/ODBC using TLS



  1. isql linkeddata.uriburner.com:1113 "" 1234 -X VirtuosoLODConnectivity.p12 -T ca_list_shop_2016.pem




  2. isql linkeddata.uriburner.com:1113 "" 1234 -X kidehen_dot_net.p12 -T ca_list_shop_2016.pem

ACL Test Queries for Web ID+TLS ISQL/ODBC using TLS



  1. SPARQL 
SELECT COUNT (*) 
FROM <OpenPermID-bulk-assetClass-20151111_095807.ttl.gz> 
WHERE {?s ?p ?o};




  2. SPARQL 
SELECT COUNT (*) 
FROM <OpenPermID-bulk-industry-20151111_095806.ttl.gz> 
WHERE {?s ?p ?o};

Results

You will have count of "0" as the solution for queries performed by identities that fail protected resource ACL test.

Web ID+TLS via HTTP (using cURL) Connection Tests

ACL Template for Web ID+TLS via HTTP (using cURL)


curl -iLk --cert-type P12 --cert {app-or-agent-pkcs-file}:{app-or-agent-pkcs-file-access-pwd} "https://linkeddata.uriburner.com/sparql/?default-graph-uri=&query=select+distinct+*+from+%3COpenPermID-bulk-assetClass-20151111_095807.ttl.gz%3E++where+%7B%5B%5D+a+%3FEntityType%7D+limit+50&should-sponge=&format=text%2Fcsv%2Btr&CXML_redir_for_subjs=121&CXML_redir_for_hrefs=&timeout=30000000"

Sample ACLs for Web ID+TLS via HTTP (using cURL)



  1. curl -iLk --cert-type P12 --cert VirtuosoLODConnectivity.p12:1234 "https://linkeddata.uriburner.com/sparql/?default-graph-uri=&query=select+distinct+*+from+%3COpenPermID-bulk-assetClass-20151111_095807.ttl.gz%3E++where+%7B%5B%5D+a+%3FEntityType%7D+limit+50&should-sponge=&format=text%2Fcsv%2Btr&CXML_redir_for_subjs=121&CXML_redir_for_hrefs=&timeout=30000000"




  2. curl -iLk --cert-type P12 --cert VirtuosoLODConnectivity.p12:1234 "https://linkeddata.uriburner.com/sparql/?default-graph-uri=&query=select+distinct+*+from+%3COpenPermID-bulk-industry-20151111_095806.ttl.gz%3E++where+%7B%5B%5D+a+%3FEntityType%7D+limit+50&should-sponge=&format=text%2Fcsv%2Btr&CXML_redir_for_subjs=121&CXML_redir_for_hrefs=&timeout=30000000"

Results

You will have empty solutions for queries performed by identities that fail protected resource ACL tests.

Web ID+TLS+Delegation ISQL/ODBC/JDBC using TLS Connection Tests

In this scenario the identity of the software user and the software (application/agent/bot) are distinct, i.e., you have a WebID for the software and a WebID for the software user. In this test scenario, the WebID of the user (identified by value of the -W parameter) is the only identity to which protected resource access has been granted.

ACL Template for Web ID+TLS+Delegation ISQL/ODBC/JDBC using TLS


./isql linkeddata.uriburner.com:1113 "" {app-or-agent-pkcs-file-access-pwd} -X {app-or-agent-pkcs-file} -T {ca-cert-bundle} -W {user-webid}



iodbctest "Driver={OpenLink Virtuoso ODBC Driver};HOST=linkeddata.uriburner.com:1113;UID=;PWD={app-or-agent-pkcs-file-access-pwd};ENCRYPT={app-or-agent-pkcs-file};SERVERCERT={ca-cert-bundle};Delegate={user-webid}"



ConnectString url = "jdbc:virtuoso://linkeddata.uriburner.com:1113/charset=UTF-8/SSL/kpass={app-or-agent-pkcs-file-access-pwd}/kpath={app-or-agent-pkcs-file}/ts={ca-cert-bundle}/delegate='{user-webid}'"

Sample ACLs for Web ID+TLS+Delegation ISQL/ODBC/JDBC using TLS

1 . 


isql linkeddata.uriburner.com:1113 "" 1234 -X VirtuosoLODConnectivity.p12 -T ca_list_shop_2016.pem -W http://kingsley.idehen.net/public_home/kidehen/profile.ttl#i

2. 


iodbctest "Driver={OpenLink Virtuoso ODBC Driver};HOST=linkeddata.uriburner.com:1113;UID=;PWD=1234;ENCRYPT=VirtuosoLODConnectivity.p12;SERVERCERT=ca_list_shop_2016.pem;Delegate=http://kingsley.idehen.net/public_home/kidehen/profile.ttl#i"

3. 


ConnectString url = "jdbc:virtuoso://linkeddata.uriburner.com:1113/charset=UTF-8/SSL/kpass=1234/kpath=VirtuosoLODConnectivity.p12/ts=ca_list_shop_2016.pem/delegate='http://kingsley.idehen.net/public_home/kidehen/profile.ttl#i'"

ACL Test Queries



  1. SPARQL 
SELECT COUNT (*) 
FROM <OpenPermID-bulk-assetClass-20151111_095807.ttl.gz> 
WHRE {?s ?p ?o};




  2. SPARQL 
SELECT COUNT (*) 
FROM <OpenPermID-bulk-industry-20151111_095806.ttl.gz> 
WHERE {?s ?p ?o};

Results

You will have count of "0" as the solution for queries performed by identities that fail protected resource ACL test.

Web ID+TLS+Delegate via HTTPS (using cURL) Connection Tests

In this usage scenario we make use of the "OnBehalfOf:" custom HTTP request header. The value of this header takes the form of a WebID that identifies the user of an application/agent/bot accessing a protected resource via the HTTP protocol.

ACL Template for Web ID+TLS+Delegate via HTTPS (using cURL)


curl -iLk --cert-type P12 --cert {app-or-agent-pkcs-file}:{pkcs-file-access-pwd} --cacert {ca-cert-bundle} -H "OnBehalfOf: {user-webid}" "{uri-for-accessing-protected-resource}"

Sample ACLs for Web ID+TLS+Delegate via HTTPS (using cURL)



  1. curl -iLk --cert-type P12 --cert VirtuosoLODConnectivity.p12:1234 --cacert ca_list_shop_2016.pem -H "On-Behalf-Of: http://kingsley.idehen.net/public_home/kidehen/profile.ttl#i" "https://linkeddata.uriburner.com/sparql/?default-graph-uri=&query=select+distinct+*+from+%3COpenPermID-bulk-industry-20151111_095806.ttl.gz%3E++where+%7B%5B%5D+a+%3FEntityType%7D+limit+50&should-sponge=&format=text%2Fcsv%2Btr&CXML_redir_for_subjs=121&CXML_redir_for_hrefs=&timeout=30000000"




  2. curl -iLk --cert-type P12 --cert VirtuosoLODConnectivity.p12:1234 --cacert ca_list_shop_2016.pem -H "On-Behalf-Of: http://kingsley.idehen.net/public_home/kidehen/profile.ttl#i" "https://linkeddata.uriburner.com/sparql/?default-graph-uri=&query=select+distinct+*+from+%3COpenPermID-bulk-assetClass-20151111_095807.ttl.gz%3E++where+%7B%5B%5D+a+%3FEntityType%7D+limit+50&should-sponge=&format=text%2Fcsv%2Btr&CXML_redir_for_subjs=121&CXML_redir_for_hrefs=&timeout=30000000"

Results

You will have empty solutions for queries performed by identities that fail protected resource ACL tests.

Web ID+TLS+Delegate to SPARQL Endpoint and Faceted Browser UI's using OSDS Connection Tests

The OpenLink Structured Data Sniffer (OSDS) version 2.10.8+ can be used as a vehicle for injecting On-Behalf-Of: request header with the value from the configured and selected WebID into HTTP requests. The is passed by setting the Preferred User ID value in the Options configuration dialog of OSDS as indicated in the following dialog:





In this example the Preferred User ID is set to http://kingsley.idehen.net/public_home/kidehen/profile.ttl#i.

Import the Software Agent certificate (p12 file) into the Chrome or FireFox? Browser, supported by OSDS, that is to be used.

Web ID+TLS+Delegate to SPARQL Endpoint UI

  1. Go to the http://linkeddata.uriburner.com/sparql SPARQL Endpoint and click on the Login link.



  2. From the presented VAL Login Dialog select the WebID-TLS icon to make a WebID login.



  3. From the presented certificates select the software agent certificate for the connection



  4. When logged in the http://kingsley.idehen.net/public_home/kidehen/profile.ttl#i delegated user is presented as the logged in user. At this point, a query can be executed, depending on the ACLs in place.



    • SPARQL Query Results page where the query targets entity relationships in a protected database (a/k/a Named Graph or Document) that's only accessible to specific Users authenticated via any of the presented protocols, i.e., NetIDs? Condition Group ACL for <OpenPermID?-bulk-assetClass-20151111_095807.ttl.gz>. Returns the following based on the ACLs in place:



    • SPARQL Query Results page where the query targets entity relationships in a protected database (a/k/a Named Graph or Document) that's only accessible to specific Users identified by a WebID (HTTP URI or Hyperlink that identifies a Person, Organization, or Software Agent), i.e., specific WebID ACL for <OpenPermID?-bulk-assetClass-20151111_095806.ttl.gz>. Returns no results as the ACLs do not allow it.

Web ID+TLS+Delegate to Faceted Browser UI

  1. Go to the Faceted Browser, http://linkeddata.uriburner.com/fct, and click on the Login link.



  2. From the presented VAL Login Dialog, select the WebID-TLS icon to make a WebID login.



  3. From the presented certificates select the software agent certificate for the connection



  4. When logged in, the delegated user, http://kingsley.idehen.net/public_home/kidehen/profile.ttl#i, is presented as the logged in user. At which point a query can be executed and depending on the ACLs in place.



    1. SPARQL Query Results page where the query targets entity relationships in a protected database (a/k/a Named Graph or Document) that's only accessible to specific Users authenticated via any of the presented protocols, i.e., NetIDs? Condition Group ACL for <OpenPermID?-bulk-assetClass-20151111_095807.ttl.gz>. Returns the following based on the ACLs in place:



    2. SPARQL Query Results page where the query targets entity relationships in a protected database (a/k/a Named Graph or Document) that's only accessible to specific Users identified by a WebID (HTTP URI or Hyperlink that identifies a Person, Organization, or Software Agent), i.e., specific WebID ACL for <OpenPermID?-bulk-assetClass-20151111_095806.ttl.gz>. Returns no results, as the ACLs do not allow it.

Related