WebIDTLSDelegationWhatWhyHow

WebIDTLSDelegationWhatWhyHow WebID+TLS+Delegation Usage Guide 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: HTTP URI (Hyperlink) based Entity Identifiers (Names) TLS based data transmission RDF Language based Statements representing Entity Relationships and Entity Relationship Types Ontology of terms from shared vocabularies such as <http://www.w3.org/ns/auth/acl#Authorization> <http://www.openlinksw.com/ontology/acl#> <http://www.openlinksw.com/ontology/restrictions#> <http://www.openlinksw.com/schemas/cert#> and others Entity Relationship Type Semantics — including the nature of relationships that exist between Software Applications and their Users via <http://www.openlinksw.com/schemas/cert#onBehalfOf> Primary Features Collectively, the components above enable: Unambiguous Naming for Software Applications (Agents or Bots) and their Users Identity Claims Construction Identity Claims Verification Resource Access Rules (Authorizations) Creation & Evaluation Resource Access Rate Rules (Restrictions) Creation & Evaluation . 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: URIs — Entity Denotation HTTP — Data Access Protocol HTTP URIs — Entity Identification (Denotation & Connotation via in-built interpretation using Denotation->Connotation redirection) RDF Language Statements — enabling construction of Profile Documents using machine- and human-comprehensible sentences/statements X.509 — Identity Cards (Certificates) that include references to Profile Documents via Subject Alternative Name field TLS — Data Encryption and Basic Identity Verification that scales to the Internet and Web. 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: Configuring Virtuoso Server HTTPS Listener Endpoint Configuring Virtuoso Server SQL TLS/SSL Listener Port Additional Virtuoso Components to be installed The following Virtuoso application should be installed from the System Admin -> Packages tab of the Conductor: Sponger Cartridge VAD - To enable querying of remote resource URIs Faceted Browser VAD - To provide human readable form of Web ID Profile documents and ACLs Virtuoso Authentication Layer (VAL) VAD - To enable ACLs for be setup and enforced URIQA DefaultHost in INI file must be set to valid hostname to be used by VAL 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 Add oplcert:onBehalfOf relations to the Agent's WebID-Profile Document that associates it with authorized Users Add an entry in the WebID-Profile doc of each User that associates them with the Agent Load WebID-Profile Documents into Virtuoso's Quad Store (using the various options it supports: Sponger, SPARQL Load, ODS-Briefcase, etc.) 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 http://kingsley.idehen.net/DAV/home/kidehen/agent-profile-document.ttl -- WebID-Profile Document http://kingsley.idehen.net/DAV/home/kidehen/profile.ttl -- User WebID-Profile Sample WebID-Profile Document TTL snippet — @prefix oplacl: <http://www.openlinksw.com/ontology/acl#> ## User Credentials (OnBehalfOf relation participants) <{your-webid}> oplacl:hasIdentityDelegate <http://kingsley.idehen.net/DAV/home/kidehen/agent-profile-document.ttl#i> . <http://kingsley.idehen.net/DAV/home/kidehen/agent-profile-document.ttl#i> cert:key [ cert:exponent "65537"^^xsd:integer ; cert:modulus "b1d61bb0e90d226f60c428f59ddee81159017adbb64f82436834bec1177ee1a2ef45002a14d04473eb14784d054416333156c124c9363c38553437c570e047703cf1bb5ed37ff662b31ff52dc3ef3f0de88b36780214f59304d51587b9c7350be7f29451a9f2ecb0df8409244c1513f68ac2bc40751ffdb5bb67981bc16c619dc0b753f1f73e3fa0190a44166463258c1d505d4db913dd69f0a32ee9102ce6713a31764ed907a5eb82f19fe4d3ce560a571c4bd64519a3a0e24dba90bc6684f447af0224efccefbdc6aef73eabb6b41bc26240ac6571739c570c9aa3345c4210da0b4151148c17d451753cd0a44572007059ef209f636ed116f61e3febc76809"^^xsd:hexBinary ] . 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: HTTP Realm ACLs HTTP Realm Restrictions SQL Realm ACLS SQL Realm Restrictions 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. Open the ODBC Administrator and create an ODBC DSN for the OpenLink Virtuoso Driver.

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

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.

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: Start the CPPDemo application.

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

Choose the DSN created previously from the list presented.

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

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

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}

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: An X.509 Certificate is only created for the software agent (e.g., cURL, Web Browser, ODBC compliant app, etc.) used to access the protected document Document access controls are scoped to the application user, as opposed to software being used. Sample Resources <OpenPermID-bulk-assetClass-20151111_095807.ttl.gz> — Protected Named Graph accessible to any NetID (which includes WebIDs) via HTTP Realm scoped ACLs <OpenPermID-bulk-industry-20151111_095806.ttl.gz> — Protected Named Graph accessible to a specific WebID list via SQL or HTTP Realm scoped ACLs Certificates and their Subjects LODConnectivity Cert — required for WebID+TLS testing using our setup on URIBurner Sample LODConnectivity Cert — https://download3.openlinksw.com/certificates/software_agent.p12 CA Certificate Bundle for verifying Certs issued by YouID and URIBurner (requested via Shop Agent re. LOD Connectivity Certs) Sample CA Certificate Bundle — https://download3.openlinksw.com/certificates/ca_list_shop_2016.pem WebID for which access has been granted to the resource identified by <OpenPermID-bulk-industry-20151111_095806.ttl.gz> 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 isql linkeddata.uriburner.com:1113 "" 1234 -X VirtuosoLODConnectivity.p12 -T ca_list_shop_2016.pem 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 SPARQL SELECT COUNT (*) FROM <OpenPermID-bulk-assetClass-20151111_095807.ttl.gz> WHERE {?s ?p ?o}; 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) 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" 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 SPARQL SELECT COUNT (*) FROM <OpenPermID-bulk-assetClass-20151111_095807.ttl.gz> WHRE {?s ?p ?o}; 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) 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" 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 Go to the http://linkeddata.uriburner.com/sparql SPARQL Endpoint and click on the Login link.

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

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

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 Go to the Faceted Browser, http://linkeddata.uriburner.com/fct, and click on the Login link.

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

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

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.

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 Virtuoso WebID+TLS+Delegation Step by Step Configuration Guide Virtuoso Authentication Layer (VAL) - What, Why and How Virtuoso Authentication Layer - ACL System QuickStart Guide Using X509 Certificates With ODBC Connection