VAL
Virtuoso Authentication Layer
VAL Authentication API Tools

Functions

 VAL.DBA.add_sid_to_url (varchar url, varchar service=null, varchar serviceId=null, varchar realm=null, varchar sidParamName="sid", varchar cookieSidName="sid", any options=null, varchar sid=null)
 
 VAL.DBA.create_login_page_url (varchar url, varchar deniedService=null, varchar deniedServiceId=null, varchar realm=null)
 
 VAL.DBA.default_smtp_server ()
 Reads the default smpt server from the Virtuoso configuration. More...
 
 VAL.DBA.email_address_for_service_id (varchar serviceId)
 Find an email address for the given service id. More...
 
 VAL.DBA.get_connection_realm (varchar fallback=null)
 Get the realm for the current http connection. More...
 
 VAL.DBA.get_default_realm ()
 The default application realm. More...
 
 VAL.DBA.get_profile_name (varchar serviceId)
 Get the full name for the given profile URI. More...
 
 VAL.DBA.get_profile_url (varchar serviceId, varchar service=null)
 Get a profile URL for a given service ID. More...
 
 VAL.DBA.http_to_https_uri (varchar uri, int checkForVhost=0)
 Convert an HTTP URI into its HTTPS counterpart. More...
 
 VAL.DBA.is_admin_user (varchar uname)
 Check if a given SQL user is dba or in the admin group (role) More...
 
 VAL.DBA.new_user_session (varchar uname, varchar realm=null, int checkDeactivated=0, any options=null)
 
 VAL.DBA.remove_user_online_mapping (varchar service, varchar serviceId)
 
 VAL.DBA.service_from_profile_uri (varchar url)
 Extract service name from online account URI. More...
 
 VAL.DBA.session_id_for_connection (varchar sid, varchar serviceId, varchar realm=null, varchar sidParamName="sid")
 
 VAL.DBA.smtp_server_available ()
 Check if a valid SMTP server has been configured. More...
 
 VAL.DBA.thirdparty_services ()
 A simple map of all supported third-party authentication services, their labels, and oauth apikey urls. More...
 
 VAL.DBA.thirdparty_supported_services ()
 A simple map of all the supported authentication services that can be used in thirdparty_authentication_url. More...
 
 VAL.DBA.update_user_online_mapping (varchar service=null, varchar serviceId, varchar oauthSid=null, any uname)
 
 VAL.DBA.user_personal_uri (varchar uname)
 An SQL user's personal URI. More...
 
 VAL.DBA.username_for_online_account (varchar service=null, varchar serviceId, any cert=null, varchar webidGraph=null, varchar realm=null)
 

Detailed Description

The Authentication Tools API contains a set of convinience procedures which make working with VAL is vsp pages much simpler.

Function Documentation

VAL.DBA.add_sid_to_url ( varchar  url,
varchar  service = null,
varchar  serviceId = null,
varchar  realm = null,
varchar  sidParamName = "sid",
varchar  cookieSidName = "sid",
any  options = null,
varchar  sid = null 
)

Create a new session and add the session id to the given URL for the given service and serviceId. Be aware that the serviceId should have been authenticated before calling this method.

This method is used by VAL.DBA.thirdparty_authentication_default_callback() and in the default authenticate.vsp page to handle BrowserID authentication redirection.

This procedure will also write a cookie header unless cookieSidName is set to null.

Parameters
urlThe URL to add the sid parameter to.
serviceThe authentication service that was used.
serviceIdThe authenticated id, can be a WebID, a Facebook uri, etc..
realmThe application realm the new session should live in. See VAL.DBA.get_default_realm() for the default realm.
sidParamNameThe parameter name used for the session id. Example: ...com/path?sid=6649987677. If null no parameters will be added to the URL.
cookieSidNameThe name used for the session id cookie. If null no cookie will be written. Setting both sidParamName and cookieSidName to null is useless.
optionsAn optional vector of options which is directly passed to VAL.DBA.new_user_session().
sidThe optional session id to use. If null then a new session will be created.
Returns
A copy of url with an optionally added session id parameter.
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.create_login_page_url ( varchar  url,
varchar  deniedService = null,
varchar  deniedServiceId = null,
varchar  realm = null 
)

Creates a URL which allows to authenticate via any of the supported methods.

TODO: add an optional hint to the URI the resource was shared with

Parameters
urlThe URI of the resource to access.
deniedServiceIn case of a previous authentication attempt this is set to the service which was used. Can be any of the supported services like webid, openid, browserid, facebook, dropbox, etc...
deniedServiceIdIn case of a previous authentication attempt this is set to the service id which the user authenticated with but which was not permitted to access the resource.
realmThe optional application realm to use.
VAL.DBA.default_smtp_server ( )

Reads the default smpt server from the Virtuoso configuration.

VAL.DBA.email_address_for_service_id ( varchar  serviceId)

Find an email address for the given service id.

This procedure supports email addresses stored in the profile graph, sql account email addresses and browser id embedded email addresses.

Returns
An email address for serviceId or null if none could be determined.
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_connection_realm ( varchar  fallback = null)

Get the realm for the current http connection.

VAL allows to configure the application realm in the virtual dir options. This procedure will check for that option.

Warning
Be aware that authentication sessions have their own realm information which will override the virtual dir option in VAL.DBA.get_authentication_details_for_connection().
Returns
The application realm configured in the virtual dir or fallback if none was found.
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_default_realm ( )

The default application realm.

Authentication information in VAL is typically connected to an application realm. If none is specified the default one is used as returned by this procedure.

Returns
The URI of the default application realm.
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_profile_name ( varchar  serviceId)

Get the full name for the given profile URI.

Be aware that this procedure returns possibly private information and should only be shown to authorized people (like the one identified by the given serviceId itself).

Returns
The fullname of the given serviceId or null if none was found.
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_profile_url ( varchar  serviceId,
varchar  service = null 
)

Get a profile URL for a given service ID.

Not each service provides a deferenceble URL. This procedure tries hard to return a URL which people can visit to get information about the given serviceId.

Returns
A profile URL or null if none coudl be determined.
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.http_to_https_uri ( varchar  uri,
int  checkForVhost = 0 
)

Convert an HTTP URI into its HTTPS counterpart.

Parameters
uriThe URI to convert to HTTPS. If this is already an HTTPS URI, it will be returned unaltered.
checkForVhostIf 1 then an additional check will be performed, ensuring that the HTTPS URI does actually exists, i.e. a corresponding virtual host exists.
Returns
The HTTPS URL or null if SSL is not configured.
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.is_admin_user ( varchar  uname)

Check if a given SQL user is dba or in the admin group (role)

Returns
1 If the given uname is an admin user, 0 otherwise.
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.new_user_session ( varchar  uname,
varchar  realm = null,
int  checkDeactivated = 0,
any  options = null 
)

Create a new user session for the given user in the given realm. If checkDeactivated is 1 then no session will be created if the given user account has been disabled.

Parameters
unameThe name to accociate the session with. This can be a SQL user account but also some VAL-supported service id like a WebID or a Facebook URI.
realmThe application realm to use. Defaults to VAL.DBA.get_default_realm ().
checkDeactivatedIf 1 the procedure will not create sessions for deactivated SQL accounts. Does nothing when creating a session for anything but a sql user account.
optionsAn optional vector of settings to save with the session in VS_STATE.
Returns
The new session id as a varchar.
VAL.DBA.remove_user_online_mapping ( varchar  service,
varchar  serviceId 
)

Delete a user account mapping that has been created via VAL.DBA.update_user_online_mapping().

Be aware that triggers take care of removing temporary user accounts and such.

See also
VAL.DBA.update_user_online_mapping(), VAL.DBA.username_for_online_account()
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.service_from_profile_uri ( varchar  url)

Extract service name from online account URI.

Example: "http://www.facebook.com/...." -> "facebook"

The extracted value may then be used to load a small icon from /val/img/social16/NAME.png

Returns
The name of the service or null.
See also
http://localhost:8890/odsdox/group__ods__module__user.html#gac71c825dde239393bfc6124c7238153a
VAL.DBA.session_id_for_connection ( varchar  sid,
varchar  serviceId,
varchar  realm = null,
varchar  sidParamName = "sid" 
)

Check if the current HTTP session contains a valid session id. The session id can either be in the URL as parameter "sid" or in a cookie.

Parameters
[out]sidThe session id if a valid one was found.
[out]serviceIdThe service id or username for which the session was created.
[in,out]realmThe realm of the session. If provided only session ids from the given realm will be returned. Caution: make sure to actually initialize the variable to null if it has no input value.
sidParamNameBy default the session ID is stored in a cookie with name sid. The name can be changed via this parameter.
Returns
1 if a valid session id was found, 0 otherwise.
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.smtp_server_available ( )

Check if a valid SMTP server has been configured.

This function does a very dumb check: it tries to connect to the configured address and if that works, assumes it is an SMTP server.

Returns
1 if mails can be sent via VAL.DBA.send_notification_email() or smtp_send() in general, 0 if not.
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_services ( )

A simple map of all supported third-party authentication services, their labels, and oauth apikey urls.

Returns
A vector of key/value pairs where each key maps to a vector containing a label and an keyurl. This includes the ODS instances from ODS_OAUTH_INSTANCES.
See also
VAL.DBA.thirdparty_supported_services()
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_supported_services ( )

A simple map of all the supported authentication services that can be used in thirdparty_authentication_url.

A vector of key/value pairs where each key maps to a supported service and each value is either 0 or 1, depending on whether that service is usable (in other words: for which service a client key and secret is installed in OAUTH..APP_REG.)

vector('openid', 1, 'facebook', 1, 'twitter', 0, ....)
See also
VAL.DBA.thirdparty_service_labels()
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.update_user_online_mapping ( varchar  service = null,
varchar  serviceId,
varchar  oauthSid = null,
any  uname 
)

Create or update a mapping of an online account to a user. Clients should only use this to store "fixed" mappings. For temporary user accounts use VAL.DBA.username_for_online_account() instead. For mapping two service ids use VAL.DBA.add_same_as_relation().

Caution: Only call this procedure for mappings that are authenticated. Otherwise security might be breached when the wrong user names are suddenly related to an online account.

Parameters
serviceThe service type. This parameter is optional and when not provided will be ignored. Its only point is to improve accuracy for clients having the service type available.
serviceIdThe service id of the online account. This can be any of the supported types like WebID, Facebook URL, etc..
oauthSidThe OAuth session which references OAUTH..CLI_SESSIONS. This allows to reuse an OAuth access token for subsequent API calls. If this is null and a mapping is updated the existing value is used.
unameThe user to map the account to (can also be uid).

Throws a signal on error.

See also
VAL.DBA.username_for_online_account(), VAL.DBA.remove_user_online_mapping(), VAL.DBA.add_same_as_relation()
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.user_personal_uri ( varchar  uname)

An SQL user's personal URI.

The profile URI of a given SQL user is the same as used by ODS for convinience.

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.username_for_online_account ( varchar  service = null,
varchar  serviceId,
any  cert = null,
varchar  webidGraph = null,
varchar  realm = null 
)

Get a mapped user account for the given online service id.

Parameters
serviceThe service type. This parameter is optional and when not provided will be ignored. Its only point is to improve accuracy for clients having the service type available.
serviceIdThe service id of the online account. This can be any of the supported types like WebID, Facebook URL, etc..
certThe optional certificate for mapping WebIDs to SQL accounts via old-school ACLs.
webidGraphThe optional graph containing the details of the imported WebID profile.
realmThe optional application realm for checking ACLs.
Returns
The name of the user account the given service id is mapped to.

Throws a signal in the case of an error.

See also
VAL.DBA.update_user_online_mapping(), VAL.DBA.remove_user_online_mapping()
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;