. . . "

Create an authentication URL to log into or register with ODS through a third party service or WebID.

" . . . . . "GET" . "

ODS supports a variety of third-party services for login and registration including Twitter, Facebook, or Google. ODS clients can use this method to easily expose this functionality to their users. Clients can either start authentication, registration or the connection of an ODS account with a third-party service account.

\nClient Workflow\n

The workflow for a client is always the same irrespective of the service type:\n

The client requests an authentication URL via this method, specifying the service type (see below for Supported Services, the action to take, and a callback URL.

The client navigates to the returned URL allowing the user to authenticate with the 3rd party service.

The 3rd party service redirects to ODS which concludes the action and performs the final redirect to the callback URL provided by the client. The callback URL contains one the following:\n

A new ODS session ID in the userSession.sid parameter and a flag (0 or 1) to indicate if a new account has been registered user.new. See also Authentication via Session Id.

An authentication confirmation session consisting of the parameters confirmSession.cid, confirmSession.reason.code, confirmSession.reason.msg, user.name, user.email, onlineAccount.service, and onlineAccount.uid. See Authentication Confirmation Mode for details.

In the case of a workflow error an error messages in the error.msg parameter. Errors include such conditions as a failed 3rd party service authentication or a missing detail in the profile for registration (ODS for example requires an email address for account creation).

\n

\n

Clients can use server.getInfo() to retrieve the enabled services. A service is available if it is enabled in the ODS configuration (all are enabled by default) and if the ODS instance contains an application ID. Application IDs are typically created through the third-party service's web interface and can be added by the ODS administrator via admin.apikeys.new(). (See below for links to the respective admin pages and the required callback links.)

For security reasons the callback URL needs to match one of the configures clients URLs. See admin.clients.new() for details.

\n\nAuthentication Action Types\n

Clients can initiate three different types of actions revolving around third-party service accounts with this methods. The actions are as follows:

\n

authenticate A basic authentication workflow which, if succesful results in the client being authenticated with the ODS account which is connected to the 3rd-party service account the user logged into.

register The creation of a new ODS account which will be connected to the 3rd-party service account the user logged into. The new ODS account will have a random password set which can later be changed via user.password.change() to allow authentication with classical username digest information. Should the 3rd-party service not provide enough information to create an account, ODS will continue based on the value of confirm as detailed in Authentication Confirmation Mode.

connect Connect an existing ODS account with a third-party service account.

auto In automatic mode ODS tries to choose the best fitting action. Should an ODS account be connected to the 3rd-party service account the user logged into authenticate will be chosen. Otherwise ODS will try to create a new account like with register (Should the 3rd-party service not provide enough information to create an account, ODS will continue based on the value of confirm as detailed in Authentication Confirmation Mode). Should the client provide authentication information according to ODS Authentication ODS will try to connect the 3rd-party service account the user logged into with the authenticated ODS account.

\n

\n\nAuthentication Confirmation Mode\n

ODS allows to create accounts by simply connecting them to third-party online accounts. Clients can either ask the user to confirm the creation of the new account or have it done automatically. ODS supports three modes for registration confirmation:\n

always ODS will always ask the client to confirm the creation of the new account.

never ODS will never ask the client for confirmation. If certain details like the email are missing for account creation it will simply fail.

auto ODS will decide based on the available profile detail. If both username and email address are available, valid, and not yet in user the new account will be created without confirmation. Otherwise ODS will request confirmation through a confirmation session.

\n

A verified and completed confirmation request can be confirmed to create the final account via user.authenticate.confirm().

\n\nSupported Services\n

ODS supports the following services for authentication and registration. Except for OpenID each service uses one flavor of OAuth and requires a client ID and secret to be registered with ODS. Client IDs are managed via admin.apikeys.new(). (An easy way to install new client keys is via the ODS Console which can easily be installed on any instance of Virtuoso running ODS.)

Most services require that a callback URL is stored with the client ID. The following list contains details on the values to add for ODS. Keep in mind that both ODS and Virtuoso support OAuth workflows in other situations like Briefcase external web drive mounting. These use different callback URLs which needs to be taken into account when configuring certain services like Google.

\n

facebook - Create a login link for Facebook. Client IDs (App ID/API key and App Secret) can be created at https://developers.facebook.com/apps . The Facebook client app should be configured as \"Website with Facebook login\" with a site URL matching the host of the ODS installation. Example: if ODS runs at http://myhost.com/ods/api then the URL in the Facebook app should be http://myhost.com/ or https://myhost.com/ if SSL endpoints have been configured.

google - Create a login link for Google. Client ID and Client secret can be created at https://code.google.com/apis/console/ under \"API Access\". The redirect urls need to contain http[s]://HOST[:PORT]/val/api/thirdparty_callback (an https URL when ODS SSL endpoints have been configured).

twitter - Create a login link for Twitter. Consumer key and secret can be created at https://dev.twitter.com/apps . The Twitter Callback URL should be set to the host of the ODS installation. See facebook above for an example.

linkedin - Create a login link for LinkedIn. OAuth User Token and Secret can be created at https://www.linkedin.com/secure/developer . There is no need to specify a callback URL.

windowslive - Create a login link for Windows Live. Client ID and secret can be created at https://account.live.com/developers/applications . The redirect urls need to contain http[s]://HOST[:PORT]/val/api/thirdparty_callback (an https URL when ODS SSL endpoints have been configured).

wordpress - Create a login link for Wordpress. Client ID and Secret can be created at https://developer.wordpress.com/apps/ . The redirect URL of the configured OAuth application needs to match the host of the ODS installation. See facebook above for an example.

yahoo - Create a login link for Yahoo. Consumer key and secret can be created at https://developer.apps.yahoo.com/dashboard/createKey.html. The application needs a Web-based one with access to private user data: read/write permissions for the Social Directory scope. The application domain needs to match the domain of the ODS installation. Example: if ODS runs at http://myhost.com/ods/api then the domain should be http://myhost.com/.

tumblr - Create a login link for Tumblr. OAuth Consumer Key and Secret Key can be created at http://www.tumblr.com/oauth/apps . The redirect URL of the configured OAuth application needs to match the host of the ODS installation. See facebook above for an example.

disqus - Create a login link for Disqus. Public Key and Secret Key can be created at http://disqus.com/api/applications/. ODS only requires the created application to have read access. The redirect URL of the configured OAuth application needs to match the host of the ODS installation. See facebook above for an example.

instagram - Create a login link for Instagram. Client IDs including API key and secret can be created at http://instagram.com/developer/clients/manage/ . The redirect uri needs to be http[s]://HOST[:PORT]/val/api/thirdparty_callback (an https URL when ODS SSL endpoints have been configured).

bitly - Create a login link for Bitly. Client ID and Secret can be created at https://bitly.com/a/oauth_apps by registering an OAuth 2 application. The application link should be set to the host of the ODS installation. See facebook above for an example.

foursquare - Create a login link for Foursquare. Client ID and Client Secret can be created at https://foursquare.com/developers/apps . The application link should be set to the host of the ODS installation. See facebook above for an example.

dropbox - Create a login link for DropBox. App key and app secret can be created at https://www.dropbox.com/developers/apps . No callback URL needs to be configured.

github - Create a login link for GitHub. Client ID and secret can be created at https://github.com/settings/applications/new . The callback URL should be set to the host of the ODS installation. See facebook above for an example.

meetup - Create a login link for MeetUp. Key and Secret can be created at http://www.meetup.com/meetup_api/oauth_consumers/create/ . The callback URL should be set to the host of the ODS installation. See facebook above for an example. There is no need to set a revocation URL.

flickr - Create a login link for Flickr. Key and Secret can be created at http://www.flickr.com/services/apps . There is no need to configure a callback URL.

salesforce - Create a login link for SalesForce. Client IDs including API key and secret can be created by logging into http://salesforce.com/ and navigating to Setup | Develop | Remote Access. The callback URL needs to be https://myhost.com/val/api/thirdparty_callback where myhost.com refers to the client's actual host. Salesforce requires the callback URL to be an https URL. Thus, in order to use it the instance of Virtuoso requires setting up an SSL-protected virtual host for /val/api. Caution: Settings on Salesforce remote access may take several minutes to take effect.

boxnet - Create a login link for Box.NET. OAuth2 client_id and client_secret can be created at https://www.box.com/developers/services/edit/ . The redirect_uri should be set to the host of the ODS installation. See facebook above for an example.

xing - Create a login link for Xing. An OAuth consumer key and secret can be created by visiting http://dev.xing.com and following the steps after clicking \"Register your app\".

amazon - Create a login link for Amazon. OAuth Client ID and Secret can be created by visiting https://login.amazon.com/manageApps and setting up an account to create a new application. The Allowed Return URLs should contain the full callback URL as used by ODS: http[s]://HOST[:PORT]/val/api/thirdparty_callback (an https URL when ODS SSL endpoints have been configured).

soundcloud Create a login link for SoundCloud. OAuth Client ID and Secret can be created at http://soundcloud.com/you/apps . The redirect uri needs to be http[s]://HOST[:PORT]/val/api/thirdparty_callback (an https URL when ODS SSL endpoints have been configured).

beatport - Create a login link for Beatport. OAuth API Key and Secret an be created at https://accounts.beatport.com/developer/request-api-key . The provided values are not important.

spotify - Create a login link for Spotify. OAuth Client ID and Secret can be created at https://developer.spotify.com/my-applications . Add a Redirect URI value of http[s]://HOST[:PORT]/val/api/thirdparty_callback (an https URL when ODS SSL endpoints have been configured).

paypal - Create a login link for PayPal. OAuth Client ID and Secret can be created at https://developer.paypal.com/webapps/developer/applications/myapps . The redirect uri needs to be http[s]://HOST[:PORT]/val/api/thirdparty_callback (an https URL when ODS SSL endpoints have been configured).

openid - (The actual OpenID is specified in data)

webid - Authenticate via WebID. The method will return an https URL which requests a client certificate.

Any ODS instances which has been installed as OAuth provider via admin.oauth.odshosts.new() can also be used here. API Key and API Secret can be created at http://HOST/oauth/oauth_apps.vspx where HOST matches the configured ODS instances hostname. The callback URL should be set to the host of the client ODS installation. See facebook above for an example.

\n

  • \n\nservice\n\n\n

    The type of service to authenticate with. See the list above for Supported Services. An example would be google. Available and enabled (ODS allows to disable certain services for login or registration) can be retrieved via server.getInfo(). Here it is important to skip the service types that are handled by other functions - namely digest (handled by user.authenticate()).

    \n
    • \n
  • \n\ncallback\n\n\n

    The client callback URL. Once the login is complete the user will be redirected here. ODS will add parameters to the URL as detailed in Client Workflow.

    \n
    • \n
  • \n\naction\n\n\n

    The action that should be taken. Can be one of authenticate, register, connect, or auto. See Authentication Action Types for details.

    \n
    • \n
  • \n\nconfirm\n\n\n

    The confirmation mode. Can be one of always, never, or auto. See Authentication Confirmation Mode for details.

    \n
    • \n
  • \n\ndata\n\n\n

    Optional data only required for openid login.

    \n
    • \n
  • \n\nscope\n\n\n

    The scope of the authentication. ODS 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.\n

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

    \n

    \n
    • \n
  • \n\nclient_ip\n\n\n

    The IP address of the authenticated client. Normally there is no need to specify this since ODS will simply determine it. However, if the ODS instance is hidden behind a proxy this is required since otherwise OAuth authentication with certain services will fail.

    \n
    • \n\n

    A URL pointing to the third-party's login page which will result in a redirection to ODS. Clients need to point their users to this URL. In the case of an error like missing input or a disabled service this method will return with a 4xx HTTP error code.

    \n

    user.authenticate(), user.authenticate.webid()

    \nAuthentication

    This function will provide additional information if authentication via one of the supported methods as described in ODS Authentication is used.

    \n

    " . "text/xml" . . "EntryPoint - user_authenticate_authenticationUrl" . . . .