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

◆ add_sid_to_url()

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().

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

Parameters

url	The URL to add the sid parameter to.
service	The authentication service that was used.
serviceId	The authenticated id, can be a WebID, a Facebook uri, etc..
realm	The application realm the new session should live in. See VAL.DBA.get_default_realm() for the default realm.
sidParamName	The parameter name used for the session id. Example: `...com/path?sid=6649987677`. If `null` no parameters will be added to the URL.
cookieSidName	The name used for the session id cookie. If `null` no cookie will be written. Setting both `sidParamName` and cookieSidName to `null` is useless.
options	An optional vector of options which is directly passed to VAL.DBA.new_user_session().
sid	The 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;

◆ create_login_page_url()

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

url	The URI of the resource to access.
deniedService	In 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`, `facebook`, `dropbox`, etc...
deniedServiceId	In 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.
realm	The optional application realm to use.

◆ default_smtp_server()

VAL.DBA.default_smtp_server ( )

Reads the default smpt server from the Virtuoso configuration.

◆ email_address_for_service_id()

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 and sql account 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;

◆ get_connection_realm()

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;

◆ get_default_realm()

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;

◆ get_profile_name()

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;

◆ get_profile_url()

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;

◆ http_to_https_uri()

VAL.DBA.http_to_https_uri	(	varchar	uri,
		int	checkForVhost = `0`
	)

Convert an HTTP URI into its HTTPS counterpart.

Parameters

uri	The URI to convert to HTTPS. If this is already an HTTPS URI, it will be returned unaltered.
checkForVhost	If `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;

◆ is_admin_user()

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;

◆ new_user_session()

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

uname	The 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.
realm	The application realm to use. Defaults to VAL.DBA.get_default_realm ().
checkDeactivated	If `1` the procedure will not create sessions for deactivated SQL accounts. Does nothing when creating a session for anything but a sql user account.
options	An optional vector of settings to save with the session in VS_STATE.

Returns: The new session id as a varchar.

◆ remove_user_online_mapping()

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;

◆ service_from_profile_uri()

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

◆ session_id_for_connection()

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]	sid	The session id if a valid one was found.
[out]	serviceId	The service id or username for which the session was created.
[in,out]	realm	The 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.
	sidParamName	By 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;

◆ smtp_server_available()

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;

◆ thirdparty_services()

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;

◆ thirdparty_supported_services()

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;

◆ update_user_online_mapping()

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

service	The 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.
serviceId	The service id of the online account. This can be any of the supported types like WebID, Facebook URL, etc..
oauthSid	The 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.
uname	The 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;

◆ user_personal_uri()

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;

◆ username_for_online_account()

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

service	The 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.
serviceId	The service id of the online account. This can be any of the supported types like WebID, Facebook URL, etc..
cert	The optional certificate for mapping WebIDs to SQL accounts via old-school ACLs.
webidGraph	The optional graph containing the details of the imported WebID profile.
realm	The 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;

Functions

Detailed Description

Function Documentation

◆ add_sid_to_url()

◆ create_login_page_url()

◆ default_smtp_server()

◆ email_address_for_service_id()

◆ get_connection_realm()

◆ get_default_realm()

◆ get_profile_name()

◆ get_profile_url()

◆ http_to_https_uri()

◆ is_admin_user()

◆ new_user_session()

◆ remove_user_online_mapping()

◆ service_from_profile_uri()

◆ session_id_for_connection()

◆ smtp_server_available()

◆ thirdparty_services()

◆ thirdparty_supported_services()

◆ update_user_online_mapping()

◆ user_personal_uri()

◆ username_for_online_account()