VAL
Virtuoso Authentication Layer
VAL Authentication API

Functions

 VAL.DBA.browserid_verify_assertion (varchar assertion, varchar audience, varchar browserid)
 Verify a BrowserID assertion. More...
 
 VAL.DBA.digest_authentication (varchar uname, varchar nonce, varchar pwdHash)
 
 VAL.DBA.get_authentication_details_for_connection (varchar sid, varchar serviceId, varchar uname, int isRealUser, varchar realm=null, varchar sidParamName="sid", any cert, varchar webidGraph=null)
 Checks for existing authentication information in the current connection. More...
 
 VAL.DBA.logout (varchar sid=null, varchar sidParamName="sid")
 Clear authentication information. More...
 
 VAL.DBA.oauth_refresh_token (varchar service=null, varchar serviceId=null, int force=0, varchar oauthSid=null, varchar scope=null)
 Refresh an OAuth access token based on service type and service id. More...
 
 VAL.DBA.request_login_nonce ()
 
 VAL.DBA.thirdparty_authentication_url (varchar service, varchar data, varchar callback, varchar successProc=null, varchar errorProc=null, any params=null, varchar scope="basic", varchar clientIp=null, varchar realm=null)
 Create an authentication URL for any supported 3rd-party service. More...
 

Detailed Description

The VAL Authentication API provides a set of procedures to easily integrate authentication functionality into vsp pages.

Function Documentation

VAL.DBA.browserid_verify_assertion ( varchar  assertion,
varchar  audience,
varchar  browserid 
)

Verify a BrowserID assertion.

This procedure will verify a BrowserID assertion.

Parameters
assertionThe assertion to verify.
[out]browseridWill be set to the BrowserID corresponding to the assertion on success.
Returns
1 on successful verification, 0 on failure. Normally there is no need to check the return value as the procedure will throw a signal on error which the calling procedure should catch.
Special SQL Execute Permissions
This procedure can be executed by role VAL_AUTH. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_AUTH role:
grant VAL_AUTH to myuser;
VAL.DBA.digest_authentication ( varchar  uname,
varchar  nonce,
varchar  pwdHash 
)

Perform digest authentication in a slightly more secure way than plain pwds. The pwdHash uses a nonce as generated via VAL.DBA.request_login_nonce() in combination with the password like so:

pwdHash := md5 (pwd || nonce);
Special SQL Execute Permissions
This procedure can be executed by role VAL_AUTH. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_AUTH role:
grant VAL_AUTH to myuser;
VAL.DBA.get_authentication_details_for_connection ( varchar  sid,
varchar  serviceId,
varchar  uname,
int  isRealUser,
varchar  realm = null,
varchar  sidParamName = "sid",
any  cert,
varchar  webidGraph = null 
)

Checks for existing authentication information in the current connection.

This procedure checks for authentication information like a session ID, a WebID client certificate, or basic HTTP authentication and fills the output parameters accordingly. The following authentication mechanisms are checked:

  • A Session ID which can either be given as a URL parameter to the requested URL or as a Cookie. The default VAL callback handler for VAL.DBA.thirdparty_authentication_url() creates such session ids.
  • A client certificate with an optionally embedded WebID.
  • Basic HTTP authentication

Afterwards the 3rd-party service ID or WebID is mapped to an existing SQL user account by the following means:

  • ODS online account mapping (if ODS is installed)
  • SPARQL ACL rules mapping service ids to SQL users

If successful the SPARQLUserId is set to the authenticated SQL user for the benetif of the SPARQL engine.

Parameters
[out]sidWill be set to the session id if one has been found, null otherwise. Be aware that an empty session does not mean "no authentication information". HTTP digest auth or WebID does not result in a session id.
[out]serviceIdWill be set to the 3rd-party serviceID connected to the session, the WebID embedded in the client certificate. If the session maps to an actual SQL user the serviceId will be set to their profile URI (VAL.DBA.user_personal_uri()).
[out]unameWill be set to the SQL username if the authentication information could be mapped to one, null otherwise.
[out]isRealUserWill be set to 1 if uname refers to an actual user, 0 if uname refers to a dummy SPARQL ACL rule user account which is only used for mapping. This is useful only for UIs which want to display the correct login identifier. If isRealUser is 1 then the UI should show that name, otherwise it should show the serviceID instead.
[in,out]realmThe optional application realm to be used. If provided only authentication information matching the realm will be returned. If null then the realm from the virtual directory will be used instead (see also Virtual Host Specific Realm). Should the realm not be set in the virtual dir options it will be set to the realm of the found authentication information, falling back to the default for authentication information without a realm.
sidParamNameThe name of the URL parameter and cookie used to store the session id. Default to sid.
[out]certThe optional client certificate which was used for authentication. Will be non-null for WebID and client cert authentication. Use this in calls to procedures like VAL.DBA.check_acls_for_resource() and friends.
webidGraphThe optional graph URI to use for storing the WebID profile details. If null then a tmp graph will be created and cleared after the checks are finished. If the profile details are required after the authentication checks for something like authorization then providing a graph URI is a good idea.
Returns
0 if no useful authentication information could be found, otherwise one of the following:
  • 1 - In case of authentication via a session id
  • 2 - In case of authentication via WebID or a client certificate
  • 3 - In case of HTTP authentication
  • 4 - In case of OAuth authentication
See also
Supported Authentication Methods
Special SQL Execute Permissions
This procedure can be executed by role VAL_AUTH. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_AUTH role:
grant VAL_AUTH to myuser;
VAL.DBA.logout ( varchar  sid = null,
varchar  sidParamName = "sid" 
)

Clear authentication information.

This procedure performs a full VAL logout: it invalidates the session, removes the session cookie and resets the SPARQLUserId.

If no session id is given it is determined using VAL.DBA.session_id_for_connection()

Returns
1 if logout was performed, 0 if no session id was found and nothing was done.
Special SQL Execute Permissions
This procedure can be executed by role VAL_AUTH. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_AUTH role:
grant VAL_AUTH to myuser;
VAL.DBA.oauth_refresh_token ( varchar  service = null,
varchar  serviceId = null,
int  force = 0,
varchar  oauthSid = null,
varchar  scope = null 
)

Refresh an OAuth access token based on service type and service id.

Parameters
serviceThe type of service. One of the supported types. See the ODS API documentation for details.
serviceIdThe service ID. In most cases this is a profile URI. See the ODS API documentation for details.
forceIf 1 the token will always be refreshed even if the expiration time is not reached yet. FIXME: does this at all make sense? If the token is revoken manually then we need to re-authenticate via UI anyway!
oauthSidOptional sid to identify the exact session to update. If this is null then the latest valid session is updated.
scopeOptional Update the token with the given scope. Either 'profile' or 'basic'. Defaults to null in which case the first matching token is used, independant of its scope.
VAL.DBA.request_login_nonce ( )

Public HTTP API method which allows clients such as authenticate.vsp to request a nonce for slightly safer digest login without https. The nonce will be tied to the client IP and can only be used once.

Special SQL Execute Permissions
This procedure can be executed by role VAL_AUTH. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_AUTH role:
grant VAL_AUTH to myuser;
VAL.DBA.thirdparty_authentication_url ( varchar  service,
varchar  data,
varchar  callback,
varchar  successProc = null,
varchar  errorProc = null,
any  params = null,
varchar  scope = "basic",
varchar  clientIp = null,
varchar  realm = null 
)

Create an authentication URL for any supported 3rd-party service.

The user should be directed to the returned URL to log into the service and approve the sharing of information.

Parameters
serviceThe service to authenticate with. This can be any supported OAuth service or openid. See also Supported 3rd Party Services.
dataOptional information required for login. Thus far only openid requires the actual OpenID URL.
callbackThe callback URL. Be aware that the third-party service will never see this URL since we use an internal callback URL which will handle the further processing based on the value of this URL and successProc.
successProcThe name of a procedure to call for custom processing of the authentication data. Defaults to thirdparty_authentication_default_callback(). This procedure needs to return the final redirection URL based on the url parameter described below. The generic authentication callback procedure will, once authentication was successful, call this procedure with the following parameters:
  • Callback URL (matches callback)
  • The custom parameters (matches params).
  • Service name (matches service)
  • Service ID as returned by the service. This is typically a profile URL as used to identify 3rd-party accounts internally. In case of OpenID this is the authenticated OpenID URL.
  • A vector containing a map of profile details from the service. This map can contain the following values:
    • username A username extracted from the 3rd-party service account. This username might be constructed. It is mainly useful if a new account should be created based on this information (for example ODS).
    • email - An email address extracted from the 3rd-party service account. Can be null.
    • fullname - The full name extracted from the 3rd-party service account. Can be null.
    • image - The URL to the profle image extracted from the 3rd-party service account. Can be null.
  • A vector containing a map of OAuth information from the authentication process. This is a copy of the OAuth session data that is also accessible via the oauth session id (see below) from OAUTH.DBA.CLI_SESSIONS. It can contain the following information:
    • access_token - The optional OAuth access token. This is required to perform calls to the 3rd-party service.
    • refresh_token - The optional OAuth refresh token.
    • expire - The optional access token expiration time. This is an actual datetime value indicating the time the access token will expire. If this value is null then the access token will never expire.
  • The internal OAuth sid which allows to identify this OAuth session in OAUTH.DBA.CLI_SESSIONS. null for openid.
errorProcThe name of a procedure to call in case of an error. Like successProc this procedure needs to return the redirection URL, however containing optional error information constructed from the parameters below. If not specified the plain url as provided in callback is used with additional parameter error.msg. Customizing this is typically not required. The procedure needs to handle the following parameters:
  • Callback URL (matches callback)
  • The custom parameters (matches params).
  • Service name (matches service)
  • The error state (varchar)
  • The error message (varchar)
paramsA vector of custom paramers which will be forwared to the callback procedure. This is a means to have state without persisting it.
scopeThe scope of the authentication. VAL currently supports three meta-scopes which are mapped to the service-dependent scope values if applicable. The scopes can also be combined by comma-separation.
  • basic - This will just request basic profile information like username and email
  • profile - This will request read access to the full profile including friend lists, posts, etc.
  • dav - This will request read/write access to a service's filesystem (GDrive, DropBox, etc.)
  • post - This will request permisions to create new posts like status updates or Tweets or Blog entries.
clientIpForce the IP address of the client to a different value. Some OAuth services enforce the client IP be the same for all steps but allow to set it once in the beginning. This is normally not required as it is figured out by default. However, if an ODS proxy is in use the automatically determined client IP will differ from the one of the client. In that case this should be set to the actual client which will also perform the authentication step with the 3rd party service.
realmThe optional application realm in which authentication should be performed. This falls back to the default realm (VAL.DBA.get_default_realm()).
Returns
A new authentication URL to which the client should navigate. On error a signal is thrown.
Special SQL Execute Permissions
This procedure can be executed by role VAL_AUTH. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_AUTH role:
grant VAL_AUTH to myuser;