OSDB - Using Protected Services
Contents
- Supported Security Schemes
- WebID-TLS Protected Services
- Describing a WebID-TLS-Protected Service
- OSDB Server WebID-TLS Configuration
- API Key Protected Services
- OpenID Connect and OAuth2 Protected Services
- IdP Registration
See Also
Supported Security Schemes
Most publicly accessible web services now employ some form of authorization to limit or monitor access. To use these protected services, OSDB supports a number of security schemes:
- WebID-TLS
- API key
- HTTP (Basic and Bearer)
- OAuth2
- OpenID Connect
The security scheme used by the target web service is described in the imported service description using the OpenLink Security Schemes ontology. When OSDB executes one of the service’s actions, it follows the appropriate security protocol in its role as a proxy client while interacting with the service.
WebID-TLS Protected Services
In order to use a service protected by WebID-TLS, OSDB must authenticate against that service. OSDB can either use its own identity or that of an OSDB user/client. To use the latter, the user must be logged into OSDB. The choice of whether the OSDB server’s own webID, or the OSDB user’s webID, is used to authenticate is based on whether the target service supports WebID-TLS delegation. If the service allows delegation, the OSDB user’s webID is used, if not, the OSDB server’s webID is used.
When accessing the service as a user, rather than as the OSDB server itself, WebID-TLS delegation is required because OSDB cannot act as a simple proxy for the logged-in user. When a user logs into OSDB, OSDB has access only to the user’s certificate, not to their private key and any accompanying CA certificate. So, OSDB cannot use the user’s X509 credentials to authenticate against the service. However, OSDB can use WebID-TLS delegation, acting as an agent for a user. If an OSDB user is not logged in, OSDB can still use the target service if the service allows access to OSDB’s own WebID.
OSDB will act as a delegate (aka agent) if:
- the service description sets the delegationHeader property, and
- the OSDB user is logged into OSDB
If delegation fails the agent authenticated by the service typically falls back to the delegate (OSDB) rather than the delegator (OSDB user). OSDB itself can then use the target service if it has the necessary permissions.
Describing a WebID-TLS-Protected Service
OSDB requires details of a protected service’s security scheme if it is to be able to access it. The service description should detail the security scheme using terms from the OpenLink Security Schemes ontology.
Service Security Scheme Description
By way of example, an RDF description of Virtuoso’s /describe service is listed below.
Virtuoso /describe service description:
@prefix oplsec: <http://www.openlinksw.com/ontology/securityschemes#> .
@prefix oplwebsrv: <http://www.openlinksw.com/ontology/webservices#> .
@prefix schema: <http://schema.org/> .
@prefix wdrs: <http://www.w3.org/2007/05/powder-s#> .
<#this>
a schema:CreativeWork ;
schema:name "Description of Virtuoso Describe Service" ;
schema:mainEntity <#DescribeService> ;
schema:about <#DescribeService> .
<#DescribeService>
schema:mainEntityOfPage <#this> ;
a schema:WebApplication ;
schema:name "describe_svc" ;
schema:description "Virtuoso /describe service" ;
schema:potentialAction
<#DescribeAction> ;
wdrs:describedby <#this> .
<#DescribeAction>
a schema:Action ;
oplwebsrv:hasActionWord "describe" ;
#schema:name "describe" ;
schema:description "Virtuoso Describe service — describe entity" ;
schema:target <#DescribeEntryPoint> ;
wdrs:describedby <#this> .
<#DescribeEntryPoint>
a schema:EntryPoint ;
schema:contentType "text/html" ;
schema:httpMethod "GET" ;
schema:url <https://localhost:4433/describe/> ;
oplwebsrv:hasParameter <#DescribeActionParamEntityUrl> ;
oplsec:securityScheme <#DescribeSecurityScheme> ;
wdrs:describedby <#this> .
<#DescribeActionParamEntityUrl>
a oplwebsrv:WebServiceParameter ;
schema:name "Entity URL" ;
oplwebsrv:shortDescription "The URL of the entity to be described. The entity description must be held in the RDF store.";
oplwebsrv:parameterName "url" ;
oplwebsrv:parameterType "query" ;
oplwebsrv:parameterExampleValue "http://localhost:8896/ski_resorts#Les_Arcs" ;
oplwebsrv:isRequired true ;
wdrs:describedby <#this> .
<#DescribeSecurityScheme>
a oplsec:SecurityScheme , oplsec:WebIdSecurityScheme ;
oplsec:delegationHeader "On-Behalf-Of" ;
# oplsec:sessionAuthorizationUrl "https://localhost:4433/val/api/ogin?service=webid" ;
# oplsec:sessionReleaseUrl "https://localhost:4433/val/api/logout" ;
# oplsec:sessionKeyLocation "cookie" ;
# oplsec:sessionKeyName "sid" ;
# oplsec:sessionKeyReceiptLocation "cookie" ;
# oplsec:sessionKeyReceiptName "sid" ;
wdrs:describedby <#this> .
The service oplwebsrv:EntryPoint has a oplsec:SecurityScheme associated with it, in this case a oplsec:WebIdSecurityScheme. The Security Schemes ontology defines a number of SecurityScheme subclasses, one for each scheme supported by OSDB: ApiKeySecurityScheme, HttpSecurityScheme, OAuth2SecurityScheme, OpenIdConnectSecurityScheme and WebIdSecurityScheme.
OSDB does not assume the triple store acting as the Service Registry supports subclass inferencing. (Though available in Virtuoso, opting to not require it allows OSDB to use other triple stores). Therefore, the SecurityScheme entity must be defined as both a oplsec:SecurityScheme and one of its subclasses. If the WebID-TLS implementation of the target service supports delegation, the only other requirement for the service definition is that it sets the oplsec:delegationHeader property to identify the HTTP header used to trigger delegation.
WebID-TLS Session Support
Note: This section describes a possible future feature.
The remaining, commented out, properties declared on the <#DescribeSecurityScheme> entity relate to WebID-TLS sessions. This is an extension to WebID-TLS supported by the VAL (Virtuoso Authentication Layer). For more information, refer to the VAL API documentation:
These session related properties are not required when invoking the target
service (i.e. /describe) through https (see the EntryPoint’s schema.url above).
If no VAL login is performed, VAL will authenticate the client using the certificate,
if any, supplied by OSDB. This per-service-call authentication uses any WebID in the
certificate, or just the certificate fingerprint if no WebID is present. Per-service-call
authentication does not establish a session.
These session related properties would be required if invoking the target service
through http. Any service request from OSDB will then not be accompanied by
a certificate; so a VAL login session must have been established beforehand.
(Note: At the present time, OSDB does not support invocation of a VAL+WebID-TLS protected
service through http. Only invocation via https is supported.)
The session properties could in principle be used with https to establish a session
prior to any service requests. This would eliminate per-service-call authentication
in favour of a single login call which, when used from a client making multiple
service requests, is more efficient. However there is currently no efficiency gain to be
had with OSDB - if login/logout endpoints were defined in the service description,
(using sessionAuthorizationUrl/sessionReleaseUrl) each service request would need
to be wrapped by login and logout calls as, in the current implementation, OSDB does not know when
a client has finished with a service and so would have to close any session after each request, nullifying the benefit.
Service Access Control
The oplsec:SecurityScheme entity in the service description enables an OSDB user to authenticate. Depending on the service, this may be sufficient to gain access. In the case of Virtuoso services protected by VAL, VAL makes the distinction between authentication and authorization. Once VAL has authenticated a user, it will only authorize access for that user if the VAL ACL rules for the service allow so.
The following SQL script configures VAL ACLs for the /describe and /sparql endpoints on a test Virtuoso server. Rule <#AclRdefaultSdescribeMsTdescribe171130_describesvc1> controls access to /describe.
VAL ACL Rules for the Virtuoso /describe service:
--
-- Example ACL rules setup
--
-- RuleID format: #AclR{realm}S{scope}M{access mode}T{rule tag}
-- Deny public access by default
-- DB.DBA.RDF_DEFAULT_USER_PERMS_SET ('nobody', 0);
-- ==========================================================================
-- Scope setup
-- ==========================================================================
-- Note:
-- VAL scopes can also be enabled/disabled using the VAL Configuration UI
-- in the Virtuoso Conductor.
-- Enable Query scope for the Default (HTTP) realm.
--
-- Enforces WebID-TLS authentication for /sparql logins.
-- Enables evaluation of SPARQL ACL rules in the default realm
-- for services: /sparql, /describe and /about.
sparql
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
WITH <urn:virtuoso:val:config>
DELETE
{ oplacl:DefaultRealm oplacl:hasDisabledAclScope oplacl:Query }
INSERT
{ oplacl:DefaultRealm oplacl:hasEnabledAclScope oplacl:Query }
;
-- Disable Query scope for the SQL realm
sparql
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
WITH <urn:virtuoso:val:config>
DELETE
{ oplacl:SqlRealm oplacl:hasEnabledAclScope oplacl:Query }
INSERT
{ oplacl:SqlRealm oplacl:hasDisabledAclScope oplacl:Query }
;
-- Disable PrivateGraphs scope for the Default (HTTP) realm
sparql
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
WITH <urn:virtuoso:val:config>
DELETE
{ oplacl:DefaultRealm oplacl:hasEnabledAclScope oplacl:PrivateGraphs }
INSERT
{ oplacl:DefaultRealm oplacl:hasDisabledAclScope oplacl:PrivateGraphs }
;
-- Disable PrivateGraphs scope for the SQL realm
sparql
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
WITH <urn:virtuoso:val:config>
DELETE
{ oplacl:SqlRealm oplacl:hasEnabledAclScope oplacl:PrivateGraphs }
INSERT
{ oplacl:SqlRealm oplacl:hasDisabledAclScope oplacl:PrivateGraphs }
;
-- ==========================================================================
-- SPARQL query processor ACLs setup
-- ==========================================================================
-- Cleanup
SPARQL
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX acl: <http://www.w3.org/ns/auth/acl#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
WITH GRAPH <http://localhost:8896/acl/graph/rules/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm>
DELETE
{
<#AclRdefaultSqueryMsTdescribe171130_sparqlprocessor1> ?p ?o .
}
WHERE
{
<#AclRdefaultSqueryMsTdescribe171130_sparqlprocessor1> ?p ?o .
}
;
-- ACL Definition
-- Enables use of SPARQL query processor accessed through default realm (e.g. through /sparql).
-- Enables general Sponger use (specific cartridges may be disabled through Cartridge ACLs).
SPARQL
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX acl: <http://www.w3.org/ns/auth/acl#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
WITH GRAPH <http://localhost:8896/acl/graph/rules/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm>
INSERT
{
<#AclRdefaultSqueryMsTdescribe171130_sparqlprocessor1> a acl:Authorization ;
foaf:maker <urn:id:cblakeley> ;
rdfs:label "ACL (Default realm) for SPARQL processor" ;
oplacl:hasRealm oplacl:DefaultRealm ;
oplacl:hasScope oplacl:Query ;
acl:accessTo <urn:virtuoso:access:sparql> ;
oplacl:hasAccessMode oplacl:Read, oplacl:Write, oplacl:Sponge ;
acl:agent
<http://ods-qa.openlinksw.com/DAV/home/nobody/YouID/Carl_Blakeley_WebDAV/profile.ttl#identity> ,
<http://ods-qa.openlinksw.com/DAV/home/nobody/cmsb_handcrafted_webid_170223.ttl#identity> .
}
;
-- ==========================================================================
-- /describe service ACLs setup
-- ==========================================================================
-- Cleanup
SPARQL
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX acl: <http://www.w3.org/ns/auth/acl#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
WITH GRAPH <http://localhost:8896/acl/graph/rules/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm>
DELETE
{
<#AclRdefaultSdescribeMsTdescribe171130_describesvc1> ?p ?o .
}
WHERE
{
<#AclRdefaultSdescribeMsTdescribe171130_describesvc1> ?p ?o .
}
;
-- ACL Definition
-- Enables use of /describe in the Default realm.
-- Enables optional use of the Sponger via /describe (specific cartridges may be disabled through Cartridge ACLs).
SPARQL
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX acl: <http://www.w3.org/ns/auth/acl#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
WITH GRAPH <http://localhost:8896/acl/graph/rules/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm>
INSERT
{
<#AclRdefaultSdescribeMsTdescribe171130_describesvc1> a acl:Authorization ;
foaf:maker <urn:id:cblakeley> ;
rdfs:label "ACL (Default realm) for describe service" ;
oplacl:hasRealm oplacl:DefaultRealm ;
oplacl:hasScope <urn:virtuoso:val:scopes:sponger:describe> ;
acl:accessTo <urn:virtuoso:access:sponger:describe> ;
oplacl:hasAccessMode oplacl:Read, oplacl:Write, oplacl:Sponge ;
acl:agent
<http://ods-qa.openlinksw.com/DAV/home/nobody/YouID/Carl_Blakeley_WebDAV/profile.ttl#identity> ,
<http://ods-qa.openlinksw.com/DAV/home/nobody/cmsb_handcrafted_webid_170223.ttl#identity> .
}
;
OSDB Server WebID-TLS Configuration
The OSDB server requires its own X509 credentials and WebID to authenticate against WebID-TLS-protected services. This applies whether or not the server uses WebID-TLS delegation.
The X509 certificate used to run OSDB over https need not be the one used to
provide the OSDB server’s webID. A separate key/certificate pair can be configured for
supplying OSDB’s webID to target services. The key and certificate to be used
are defined under the “agentCredentials” key in OSDB’s JSON configuration file.
An extract from an OSDB configuration file is shown below. By default, OSDB uses file default/config.json. An alternate startup config file can be specified by setting the NODE_ENV environment variable. e.g.
NODE_ENV=osdb_dev osdb_server -r http://localhost:8896/sparql
Note that a different key/certificate pair is specified by serverKey/serverCertificate for running OSDB over https.
Extract from OSDB server configuration file osdb/config/osdb_dev.json:
{
"serverURL": "https://localhost:8000",
"serverKey": "config/server.key",
"serverCertificate": "config/server.crt",
...
"agentCredentials": {
"agentKey" : "config/osdb_software_agent.key.pem",
"agentKeyPassphraseProtected" : true,
"agentCertificate" : "config/osdb_software_agent.crt.pem",
"agentCACertificate" : ""
}
}
Details of how to configure WebID+TLS+Delegation (WTD) can be found in the Virtuoso WTD Configuration Guide. Configuring OSDB to act as a WTD software agent follows the same process. The only slight difference is that OSDB uses separate key and certificate PEMs (a node.js requirement) rather than combining them in a P12. The key and certificate can be extracted from the P12 into separate PEMS using openssl.
openssl pkcs12 -in osdb_software_agent.p12 -out osdb_software_agent.key.pem -nocerts
openssl pkcs12 -in osdb_software_agent.p12 -out osdb_software_agent.crt.pem -nokeys
The key PEM file is normally protected by a passphrase (openssl insists on this). When the configuration key agentKeyPassphraseProtected is set true, OSDB will prompt for the passphrase on the command line when the server is started.
API Key Protected Services
An OSDB service using an API key security scheme must declare an oplsec:securityScheme property on the service EntryPoint which references an ApiKeySecurityScheme entity. The extracts below, from an example service description for Uber, illustrate the key properties.
Extract from Uber service description:
<#UberProductsEntryPoint>
a schema:EntryPoint ;
schema:name "Products — Uber products at a given location" ;
schema:description """
The Products endpoint returns information about the Uber products offered at a given location.
""" ;
schema:contentType "application/json" ;
schema:httpMethod "GET" ;
schema:url <https://sandbox-api.uber.com/v1/products> ;
schema:urlTemplate "https://sandbox-api.uber.com/v1/products(?latitude,longitude)" ;
oplwebsrv:isEntryPointOf <#UberProductsAction> ;
oplwebsrv:hasParameter
<#UberProductsParamLatitude> ,
<#UberProductsParamLongitude> ;
oplwebsrv:usageExample
"""curl -H 'Authorization: Token sT1eIxxxx' 'https://sandbox-api.uber.com/v1/products?latitude=37.7759792&longitude=-122.41823'""" ;
oplsec:securityScheme <#UberProductsSecurityScheme> ;
...
wdrs:describedby <#this> .
...
<#UberProductsSecurityScheme>
a oplsec:SecurityScheme , oplsec:ApiKeySecurityScheme ;
oplsec:apiKeyName "Authorization" ;
oplsec:apiKeyLocation "header" ;
wdrs:describedby <#this> .
The Uber API security uses an ‘Authorization’ header to receive a client’s API key. The API key itself is held in the OSDB server’s configuration file under the ‘securityDefinitions’ key. Each API key listed is keyed on the URI of a SecurityScheme entity defined in the corresponding service definition.
Extract from OSDB server configuration file osdb/config/osdb_dev.json:
{
"serverURL": "https://localhost:8000",
"serverKey": "config/server.key",
"serverCertificate": "config/server.crt",
"securityDefinitions": [
{
"securitySchemeURL": "http://{service description host}/uber_svc.ttl#UberProductsSecurityScheme",
"apiKey": "Token sT1eIxxxx"
}
],
OpenID Connect and OAuth2 Protected Services
OSDB can use OpenID Connect (OIDC), or the WebID variant WebID OIDC for authentication and authorization. As part of the authentication process, OIDC provides an OAuth2 access token which can be used to access protected APIs belonging to the identity provider (IdP) service.
Describing an OIDC Service to OSDB
The service description below is for the UserInfo endpoint belonging to the Google OpenID Connect service. Use of this endpoint requires that the user has authenticated beforehand to obtain an OAuth access token. The OAuth token grants the OSDB server (the Relying Party) access to the user’s profile information. An example response from the ‘userfinfo’ action follows:
{
"sub": "114...",
"name": "Carl Blakeley",
"given_name": "Carl",
"family_name": "Blakeley",
"profile": "https://plus.google.com/+CarlBlakeley",
"picture": "https://lh5.googleusercontent.com/.../photo.jpg",
"email": "...@...",
"email_verified": true,
"gender": "male",
"locale": "en-GB"
}
In the course of executing the ‘userinfo’ action to obtain this profile data, OSDB supplies the bearer access token in an Authorization header, as required by OAuth2 authenticated requests. The service description relies on the OpenLink Security Schemes ontology which defines classes for HTTP security schemes used by web services, including WebID-TLS, OAuth2, HTTP (Basic and Digest) and OpenID Connect.
#
# Service description for testing OSDB support for OIDC authentication and OAuth 2 protected services
# Access to the Google User Info endpoint requires an OAuth2 access token granted via OpenID Connect authentication.
#
@prefix oplwebsrv: <http://www.openlinksw.com/ontology/webservices#> .
@prefix oplsec: <http://www.openlinksw.com/ontology/securityschemes#> .
@prefix schema: <http://schema.org/> .
@prefix wdrs: <http://www.w3.org/2007/05/powder-s#> .
<#this>
a schema:CreativeWork ;
schema:name "Description of Google UserInfo Endpoint" ;
schema:mainEntity <#GoogleUserInfoService> ;
schema:about <#GoogleUserInfoService> .
<#GoogleUserInfoService>
schema:mainEntityOfPage <#this> ;
a schema:WebApplication ;
schema:name "google_userinfo" ;
schema:description "Google UserInfo Service" ;
schema:potentialAction
<#UserInfoAction> ;
wdrs:describedby <#this> .
# -- API: Get User Info --
<#UserInfoAction>
a schema:Action ;
schema:name "userinfo" ;
schema:description "Return user profile information" ;
schema:target <#UserInfoEntryPoint> ;
wdrs:describedby <#this> .
<#UserInfoEntryPoint>
a schema:EntryPoint ;
schema:name "Google OpenID Connect UserInfo endpoint" ;
schema:url <https://www.googleapis.com/oauth2/v3/userinfo> ;
schema:contentType "application/json" ;
schema:httpMethod "GET" ;
oplsec:securityScheme <#UserInfoOidcSecurityScheme> ;
wdrs:describedby <#this> .
# Bearer access tokens accompanying authenticated requests are sent in an Authorization
# request header. The other methods of sending bearer access tokens described by RFC 6750
# (form-encoded body parameter or URI query parameter) are not supported by OSDB because
# of the security risks.
<#UserInfoOidcSecurityScheme>
a oplsec:SecurityScheme , oplsec:OpenIdConnectSecurityScheme ;
oplsec:openIdConnectUrl <https://accounts.google.com> ;
wdrs:describedby <#this> .
The next service description, ‘YouTube Subscriptions API’, takes the use of OAuth2 access tokens a step further. Again the access token is granted in the course of authenticating using OIDC, but the service description takes advantage of the fact that Google’s OIDC implementation allows a client application to request additional scopes, beyond the standard OIDC set. (See: Google: OpenID Connect, section “Advanced topics” > “Access to other Google APIs”.) In this case, in order to list a YouTube user’s subscriptions, a client must provide an access token with the necessary YouTube-specific scopes.
#
# Service description for testing OSDB support for OIDC authentication and OAuth 2 protected services.
# Access to a YouTube user's subscriptions listing requires an OAuth2 access token, in OSDB's case
# granted via OpenID Connect authentication but with additional YouTube-specific scopes requested.
#
# See https://developers.google.com/youtube/v3/docs/subscriptions/list
#
@prefix oplwebsrv: <http://www.openlinksw.com/ontology/webservices#> .
@prefix oplsec: <http://www.openlinksw.com/ontology/securityschemes#> .
@prefix schema: <http://schema.org/> .
@prefix wdrs: <http://www.w3.org/2007/05/powder-s#> .
<#this>
a schema:CreativeWork ;
schema:name "Description of YouTube Subscriptions API" ;
schema:mainEntity <#YouTubeSubscriptionsAPI> ;
schema:about <#YouTubeSubscriptionsAPI> .
<#YouTubeSubscriptionsAPI>
schema:mainEntityOfPage <#this> ;
a schema:WebApplication ;
schema:name "youtube_subscriptions" ;
schema:description "YouTube Subscriptions API" ;
schema:potentialAction
<#YouTubeSubsAction> ;
wdrs:describedby <#this> .
# -- API: Get User Subscriptions --
<#YouTubeSubsAction>
a schema:Action ;
schema:name "user_subscriptions" ;
schema:description "Lists a user's YouTube subscriptions" ;
schema:target <#YouTubeSubsEntryPoint> ;
wdrs:describedby <#this> .
<#YouTubeSubsEntryPoint>
a schema:EntryPoint ;
schema:name "YouTube subscriptions endpoint" ;
schema:url <https://www.googleapis.com/youtube/v3/subscriptions/?mine=true&part=snippet%2CcontentDetails> ;
schema:contentType "application/json" ;
schema:httpMethod "GET" ;
oplsec:securityScheme <#YouTubeSubsSecurityScheme> ;
wdrs:describedby <#this> .
# The Google OpenID Connect implementation allows an application to get permission to use other Google APIs,
# such as YouTube, at the same time as authenticating the user. To do this, the application includes the other
# scopes that are needed in the authentication request sent to Google.
#
# See https://developers.google.com/identity/protocols/OpenIDConnect, section "Advanced topics" > "Access to other Google APIs"
#
# YouTube OAuth 2.0 scopes are described at:
# https://developers.google.com/identity/protocols/googlescopes#youtubev3
<#YouTubeSubsSecurityScheme>
a oplsec:SecurityScheme , oplsec:OpenIdConnectSecurityScheme ;
oplsec:openIdConnectUrl <https://accounts.google.com> ;
oplsec:hasOAuth2Scopes <#YouTubeSubsManageScope>, <#YouTubeSubsViewScope> ;
wdrs:describedby <#this> .
<#YouTubeSubsManageScope>
a oplsec:OAuth2Scope ;
oplsec:scopeName "https://www.googleapis.com/auth/youtube" ;
oplsec:scopeDescription "Manage your YouTube account" ;
wdrs:describedby <#this> .
<#YouTubeSubsViewScope>
a oplsec:OAuth2Scope ;
oplsec:scopeName "https://www.googleapis.com/auth/youtube.readonly" ;
oplsec:scopeDescription "View your YouTube account" ;
wdrs:describedby <#this> .
Below is a snippet of the response received by OSDB:
{
"kind": "youtube#subscriptionListResponse",
"etag": "\"ZG3FIn5B5vcHjQiQ9nDOCWdxwWo/1JglNA_veZLTSA1Rh_dvdu3eM-4\"",
"pageInfo": {
"totalResults": 3,
"resultsPerPage": 5
},
"items": [
{
"kind": "youtube#subscription",
"etag": "\"ZG3FIn5B5vcHjQiQ9nDOCWdxwWo/Pz2Ml5R-dN0OuI1zXEfgPVXxk2g\"",
"id": "Ee6cUOVYYyM...",
"snippet": {
"publishedAt": "2017-01-07T18:32:02.000Z",
"title": "Learn French With Alexa",
"description": "Alexa Polidoro, from https://learnfrenchwithalexa.com, is a real French teacher with many years' experience of teaching French to adults and children at all levels ...",
"resourceId": {
"kind": "youtube#channel",
"channelId": "UCK6TzBHhEUCKa6dgjlsVHEw"
},
"channelId": "UCYyfVUl9FCLToA_ELOgChDQ",
"thumbnails": {
...
}
},
"contentDetails": {
"totalItemCount": 415,
"newItemCount": 9,
"activityType": "all"
}
},
...
]
}
User Authentication and Authorization
If an OSDB action uses OpenID Connect or OAuth2 security, the user must be logged in before they can execute the action, so that OSDB can retrieve an access token for the action.
Because OIDC and OAuth require a user to authenticate using a username and password, as opposed to providing an X509 certificate for a WebID-TLS login, OSDB actions which use OAuth can only be executed through the OSDB UI, not via the OSDB REST API. When a user attempts to execute such an action through the Action Console, OSDB will prompt them to login into the IdP associated with the action, if they have not already done so. The user is also logged into OSDB as a result of logging into the third-party IdP.
If the user is already logged into OSDB, but using a different IdP to that required by the action, OSDB will prompt the user to switch to the required login through a ‘Change Login’ screen. A logged-in user may also be asked to re-authenticate in the unlikely event that the action they are trying to execute was registered with OSDB after they logged into their current session. The user will only need to re-authenticate if the newly registered action uses the same IdP as they used to login, but also requires more OAuth2 scopes (see below) than their initial login granted.
Access Tokens and Scopes
When a user logs into OSDB using an OIDC or WebID-OIDC IdP, the user session receives an access token on successful authentication. The access token is destroyed when the user logs out. The access token grants OSDB access to the user’s profile data available from the OIDC IdP’s UserInfo endpoint. This access token can then also be used to access protected data from other API endpoints supported by the IdP, provided the access token grants the necessary permissions (scopes) required by the target API. The OSDB service description described earlier for the YouTube action ‘user_subscriptions’ illustrates this approach.
OSDB notes all the OAuth2 scopes (beyond the standard OIDC scopes) used by actions associated with a particular IdP. The required scopes must be requested when the user authenticates, not when the user executes the action. At the point a user is authenticating using OIDC, OSDB knows the set of OAuth2 scopes required by all registered actions using services belonging to the target IdP and requests all these scopes at the same time through the user consent screen presented to the user by the IdP in the course of authenticating. (Depending on the IdP, this consent screen may be displayed only once, when consenting for the first time, then again only if the scopes being requested change). Requesting the scopes needed for all OSDB actions supported by the IdP in one go ensures the user doesn’t have
to reauthenticate when switching between different actions of the same IdP which require different scopes.
OSDB also notes the scopes granted with the user’s current access token. If a new action requiring more scopes is registered with OSDB during the user’s session, OSDB can detect if re-authentication is needed, to obtain a fresh access token, before the action can be executed.
IdP Registration
OIDC and WebID-OIDC identity providers to be used by OSDB must first be registered in the OSDB config/osdb.json configuration file. The extract below shows three IdPs, a Solid WebID-OIDC provider, an OpenLink Data Spaces WebID-OIDC provider and the Google OIDC IdP, configured for OSDB. The OSDB login dialog presents these IdPs as login buttons, each labelled {displayName}, alongside the default OSDB WebID-TLS login button.
"IdPs": {
"webid_oidc" : [
...
{
"id" : "solid_opl",
"url": "https://solid.openlinksw.com:8444",
"displayName": "Solid (OpenLink)",
"icon_id": "solid"
},
{
"id": "ods_qa",
"url": "https://ods-qa.openlinksw.com",
"displayName": "OpenLink Data Spaces (QA Server)",
"icon_id": "openlink"
}
],
"oidc": [
{
"id": "google",
"url": "https://accounts.google.com",
"displayName": "Google",
"icon_id": "google",
"registration": {
"client_id": "251...apps.googleusercontent.com",
"client_secret": "y3I..."
}
}
]
}
OSDB login dialog
Each IdP must have a unique id. Property IdPs:webid_oidc|oidc:url is the authorization endpoint of the IdP. Any action which uses this IdP must specify the same URL in the oplsec:openIdConnectUrl property of the oplsec:OpenIdConnectSecurityScheme entity in the service/action description imported by OSDB. Property icon_id identifies an icon for the IdP in the OSDB source tree (osdb/public/img/{icon_id}_24x24.png).
OSDB will work with IdPs which support OpenID Connect dynamic registration, in which case only the url property is needed. Support for dynamic registration is optional. For OIDC IdPs which don’t, the OSDB configuration must include an OAuth client_id and client_secret. In the absence of dynamic registration, the client_id and client_secret credentials are typically obtained through some out-of-band pre-registration form, as with Google’s registration process.
The screenshots below show the login and OIDC scope authorization dialogs presented when the OpenLink Data Spaces server in the above login dialog is selected.
ODS login dialog
ODS WebID-OIDC authorization dialog