This HTML5 document contains 16 embedded RDF statements represented using HTML+Microdata notation.

The embedded RDF content will be recognized by any processor of HTML5 Microdata.

Subject Item

n2:authenticationUrl

rdf:type

schema:EntryPoint

schema:httpMethod

GET

schema:contentType

text/xml

n3:isWebServiceOf

n6:this_ODSUserModuleAPI

n3:endPointURL

n7:authenticationUrl

schema:shortDescription

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

n3:hasParameter

n4:_scope n4:_client_ip n4:_confirm n4:_data n4:_callback n4:_action n4:_service

schema:name

EntryPoint - user_authenticate_authenticationUrl

schema:description

<p>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.</p><sect1 id="group__ods__module__user_1ods_authentication_url_workflow"> <title>Client Workflow</title> <p>The workflow for a client is always the same irrespective of the service type:<orderedlist> <listitem><p>The client requests an authentication URL via this method, specifying the <computeroutput>service</computeroutput> type (see below for <ref kindref="member" refid="group__ods__module__user_1ods_authentication_url_services">Supported Services</ref>, the <computeroutput>action</computeroutput> to take, and a callback URL.</p></listitem><listitem><p>The client navigates to the returned URL allowing the user to authenticate with the 3rd party service.</p></listitem><listitem><p>The 3rd party service redirects to ODS which concludes the action and performs the final redirect to the <computeroutput>callback</computeroutput> URL provided by the client. The <computeroutput>callback</computeroutput> URL contains one the following:<orderedlist> <listitem><p>A new ODS session ID in the <computeroutput>userSession.sid</computeroutput> parameter and a flag (<computeroutput>0</computeroutput> or <computeroutput>1</computeroutput>) to indicate if a new account has been registered <computeroutput>user.new</computeroutput>. See also <ref kindref="member" refid="ods_authentication_1ods_authentication_session_id">Authentication via Session Id</ref>.</p></listitem><listitem><p>An authentication confirmation session consisting of the parameters <computeroutput>confirmSession.cid</computeroutput>, <computeroutput>confirmSession.reason.code</computeroutput>, <computeroutput>confirmSession.reason.msg</computeroutput>, <computeroutput>user.name</computeroutput>, <computeroutput>user.email</computeroutput>, <computeroutput>onlineAccount.service</computeroutput>, and <computeroutput>onlineAccount.uid</computeroutput>. See <ref kindref="member" refid="group__ods__module__user_1ods_authentication_url_confirm">Authentication Confirmation Mode</ref> for details.</p></listitem><listitem><p>In the case of a workflow error an error messages in the <computeroutput>error.msg</computeroutput> 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).</p></listitem></orderedlist> </p></listitem></orderedlist> </p><p>Clients can use <ref kindref="member" refid="group__ods__module__misc_1ga694da38279997cafbe2f2012dfe30c47">server.getInfo()</ref> 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 <ref kindref="member" refid="group__ods__module__admin_1ga92ef7d74e1103210380902488e90e2a7">admin.apikeys.new()</ref>. (See below for links to the respective admin pages and the required callback links.)</p><p>For security reasons the <computeroutput>callback</computeroutput> URL needs to match one of the configures clients URLs. See <ref kindref="member" refid="group__ods__module__admin_1ga675af873f023acb812a8d7694a1d3b9f">admin.clients.new()</ref> for details.</p></sect1> <sect1 id="group__ods__module__user_1ods_authentication_url_action"> <title>Authentication Action Types</title> <p>Clients can initiate three different types of actions revolving around third-party service accounts with this methods. The actions are as follows:</p><p><itemizedlist> <listitem><p><computeroutput>authenticate</computeroutput> 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.</p></listitem><listitem><p><computeroutput>register</computeroutput> 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 <ref kindref="member" refid="group__ods__module__user_1ga454e9821088a774ba245ffcef0f16965">user.password.change()</ref> 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 <computeroutput>confirm</computeroutput> as detailed in <ref kindref="member" refid="group__ods__module__user_1ods_authentication_url_confirm">Authentication Confirmation Mode</ref>.</p></listitem><listitem><p><computeroutput>connect</computeroutput> Connect an existing ODS account with a third-party service account.</p></listitem><listitem><p><computeroutput>auto</computeroutput> 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 <computeroutput>authenticate</computeroutput> will be chosen. Otherwise ODS will try to create a new account like with <computeroutput>register</computeroutput> (Should the 3rd-party service not provide enough information to create an account, ODS will continue based on the value of <computeroutput>confirm</computeroutput> as detailed in <ref kindref="member" refid="group__ods__module__user_1ods_authentication_url_confirm">Authentication Confirmation Mode</ref>). Should the client provide authentication information according to <ref kindref="compound" refid="ods_authentication">ODS Authentication</ref> ODS will try to connect the 3rd-party service account the user logged into with the authenticated ODS account.</p></listitem></itemizedlist> </p></sect1> <sect1 id="group__ods__module__user_1ods_authentication_url_confirm"> <title>Authentication Confirmation Mode</title> <p>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:<itemizedlist> <listitem><p><computeroutput>always</computeroutput> ODS will always ask the client to confirm the creation of the new account.</p></listitem><listitem><p><computeroutput>never</computeroutput> ODS will never ask the client for confirmation. If certain details like the email are missing for account creation it will simply fail.</p></listitem><listitem><p><computeroutput>auto</computeroutput> 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.</p></listitem></itemizedlist> </p><p>A verified and completed confirmation request can be confirmed to create the final account via <ref kindref="member" refid="group__ods__module__user_1gae57c8caea0f528b4fedf05cb34656540">user.authenticate.confirm()</ref>.</p></sect1> <sect1 id="group__ods__module__user_1ods_authentication_url_services"> <title>Supported Services</title> <p>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 <ref kindref="member" refid="group__ods__module__admin_1ga92ef7d74e1103210380902488e90e2a7">admin.apikeys.new()</ref>. (An easy way to install new client keys is via the <ref kindref="compound" refid="ods_console">ODS Console</ref> which can easily be installed on any instance of Virtuoso running ODS.)</p><p>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.</p><p><itemizedlist> <listitem><p><computeroutput>facebook</computeroutput> - Create a login link for Facebook. Client IDs (App ID/API key and App Secret) can be created at <ulink url="https://developers.facebook.com/apps">https://developers.facebook.com/apps</ulink> . 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 <computeroutput><ulink url="http://myhost.com/ods/api">http://myhost.com/ods/api</ulink></computeroutput> then the URL in the Facebook app should be <computeroutput><ulink url="http://myhost.com/">http://myhost.com/</ulink></computeroutput> or <computeroutput><ulink url="https://myhost.com/">https://myhost.com/</ulink></computeroutput> if SSL endpoints have been configured.</p></listitem><listitem><p><computeroutput>google</computeroutput> - Create a login link for Google. Client ID and Client secret can be created at <ulink url="https://code.google.com/apis/console/">https://code.google.com/apis/console/</ulink> under "API Access". The redirect urls need to contain <computeroutput>http[s]://HOST[:PORT]/val/api/thirdparty_callback</computeroutput> (an https URL when ODS SSL endpoints have been configured).</p></listitem><listitem><p><computeroutput>twitter</computeroutput> - Create a login link for Twitter. Consumer key and secret can be created at <ulink url="https://dev.twitter.com/apps">https://dev.twitter.com/apps</ulink> . The Twitter Callback URL should be set to the host of the ODS installation. See <computeroutput>facebook</computeroutput> above for an example.</p></listitem><listitem><p><computeroutput>linkedin</computeroutput> - Create a login link for LinkedIn. OAuth User Token and Secret can be created at <ulink url="https://www.linkedin.com/secure/developer">https://www.linkedin.com/secure/developer</ulink> . There is no need to specify a callback URL.</p></listitem><listitem><p><computeroutput>windowslive</computeroutput> - Create a login link for Windows Live. Client ID and secret can be created at <ulink url="https://account.live.com/developers/applications">https://account.live.com/developers/applications</ulink> . The redirect urls need to contain <computeroutput>http[s]://HOST[:PORT]/val/api/thirdparty_callback</computeroutput> (an https URL when ODS SSL endpoints have been configured).</p></listitem><listitem><p><computeroutput>wordpress</computeroutput> - Create a login link for Wordpress. Client ID and Secret can be created at <ulink url="https://developer.wordpress.com/apps/">https://developer.wordpress.com/apps/</ulink> . The redirect URL of the configured OAuth application needs to match the host of the ODS installation. See <computeroutput>facebook</computeroutput> above for an example.</p></listitem><listitem><p><computeroutput>yahoo</computeroutput> - Create a login link for Yahoo. Consumer key and secret can be created at <ulink url="https://developer.apps.yahoo.com/dashboard/createKey.html.">https://developer.apps.yahoo.com/dashboard/createKey.html.</ulink> The application needs a Web-based one with access to private user data: read/write permissions for the <emphasis>Social Directory</emphasis> scope. The application domain needs to match the domain of the ODS installation. Example: if ODS runs at <computeroutput><ulink url="http://myhost.com/ods/api">http://myhost.com/ods/api</ulink></computeroutput> then the domain should be <computeroutput><ulink url="http://myhost.com/">http://myhost.com/</ulink></computeroutput>.</p></listitem><listitem><p><computeroutput>tumblr</computeroutput> - Create a login link for Tumblr. OAuth Consumer Key and Secret Key can be created at <ulink url="http://www.tumblr.com/oauth/apps">http://www.tumblr.com/oauth/apps</ulink> . The redirect URL of the configured OAuth application needs to match the host of the ODS installation. See <computeroutput>facebook</computeroutput> above for an example.</p></listitem><listitem><p><computeroutput>disqus</computeroutput> - Create a login link for Disqus. Public Key and Secret Key can be created at <ulink url="http://disqus.com/api/applications/.">http://disqus.com/api/applications/.</ulink> 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 <computeroutput>facebook</computeroutput> above for an example.</p></listitem><listitem><p><computeroutput>instagram</computeroutput> - Create a login link for Instagram. Client IDs including API key and secret can be created at <ulink url="http://instagram.com/developer/clients/manage/">http://instagram.com/developer/clients/manage/</ulink> . The redirect uri needs to be <computeroutput>http[s]://HOST[:PORT]/val/api/thirdparty_callback</computeroutput> (an https URL when ODS SSL endpoints have been configured).</p></listitem><listitem><p><computeroutput>bitly</computeroutput> - Create a login link for Bitly. Client ID and Secret can be created at <ulink url="https://bitly.com/a/oauth_apps">https://bitly.com/a/oauth_apps</ulink> by registering an OAuth 2 application. The application link should be set to the host of the ODS installation. See <computeroutput>facebook</computeroutput> above for an example.</p></listitem><listitem><p><computeroutput>foursquare</computeroutput> - Create a login link for Foursquare. Client ID and Client Secret can be created at <ulink url="https://foursquare.com/developers/apps">https://foursquare.com/developers/apps</ulink> . The application link should be set to the host of the ODS installation. See <computeroutput>facebook</computeroutput> above for an example.</p></listitem><listitem><p><computeroutput>dropbox</computeroutput> - Create a login link for DropBox. App key and app secret can be created at <ulink url="https://www.dropbox.com/developers/apps">https://www.dropbox.com/developers/apps</ulink> . No callback URL needs to be configured.</p></listitem><listitem><p><computeroutput>github</computeroutput> - Create a login link for GitHub. Client ID and secret can be created at <ulink url="https://github.com/settings/applications/new">https://github.com/settings/applications/new</ulink> . The callback URL should be set to the host of the ODS installation. See <computeroutput>facebook</computeroutput> above for an example.</p></listitem><listitem><p><computeroutput>meetup</computeroutput> - Create a login link for MeetUp. Key and Secret can be created at <ulink url="http://www.meetup.com/meetup_api/oauth_consumers/create/">http://www.meetup.com/meetup_api/oauth_consumers/create/</ulink> . The callback URL should be set to the host of the ODS installation. See <computeroutput>facebook</computeroutput> above for an example. There is no need to set a revocation URL.</p></listitem><listitem><p><computeroutput>flickr</computeroutput> - Create a login link for Flickr. Key and Secret can be created at <ulink url="http://www.flickr.com/services/apps">http://www.flickr.com/services/apps</ulink> . There is no need to configure a callback URL.</p></listitem><listitem><p><computeroutput>salesforce</computeroutput> - Create a login link for SalesForce. Client IDs including API key and secret can be created by logging into <ulink url="http://salesforce.com/">http://salesforce.com/</ulink> and navigating to Setup | Develop | Remote Access. The callback URL needs to be <computeroutput><ulink url="https://myhost.com/val/api/thirdparty_callback">https://myhost.com/val/api/thirdparty_callback</ulink></computeroutput> where <computeroutput>myhost.com</computeroutput> 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. <bold>Caution:</bold> Settings on Salesforce remote access may take several minutes to take effect.</p></listitem><listitem><p><computeroutput>boxnet</computeroutput> - Create a login link for Box.NET. OAuth2 client_id and client_secret can be created at <ulink url="https://www.box.com/developers/services/edit/">https://www.box.com/developers/services/edit/</ulink> . The redirect_uri should be set to the host of the ODS installation. See <computeroutput>facebook</computeroutput> above for an example.</p></listitem><listitem><p><computeroutput>xing</computeroutput> - Create a login link for Xing. An OAuth consumer key and secret can be created by visiting <ulink url="http://dev.xing.com">http://dev.xing.com</ulink> and following the steps after clicking "Register your app".</p></listitem><listitem><p><computeroutput>amazon</computeroutput> - Create a login link for Amazon. OAuth Client ID and Secret can be created by visiting <ulink url="https://login.amazon.com/manageApps">https://login.amazon.com/manageApps</ulink> and setting up an account to create a new application. The <emphasis>Allowed Return URLs</emphasis> should contain the full callback URL as used by ODS: <computeroutput>http[s]://HOST[:PORT]/val/api/thirdparty_callback</computeroutput> (an https URL when ODS SSL endpoints have been configured).</p></listitem><listitem><p><computeroutput>soundcloud</computeroutput> Create a login link for SoundCloud. OAuth Client ID and Secret can be created at <ulink url="http://soundcloud.com/you/apps">http://soundcloud.com/you/apps</ulink> . The redirect uri needs to be <computeroutput>http[s]://HOST[:PORT]/val/api/thirdparty_callback</computeroutput> (an https URL when ODS SSL endpoints have been configured).</p></listitem><listitem><p><computeroutput>beatport</computeroutput> - Create a login link for Beatport. OAuth API Key and Secret an be created at <ulink url="https://accounts.beatport.com/developer/request-api-key">https://accounts.beatport.com/developer/request-api-key</ulink> . The provided values are not important.</p></listitem><listitem><p><computeroutput>spotify</computeroutput> - Create a login link for Spotify. OAuth Client ID and Secret can be created at <ulink url="https://developer.spotify.com/my-applications">https://developer.spotify.com/my-applications</ulink> . Add a Redirect URI value of <computeroutput>http[s]://HOST[:PORT]/val/api/thirdparty_callback</computeroutput> (an https URL when ODS SSL endpoints have been configured).</p></listitem><listitem><p><computeroutput>paypal</computeroutput> - Create a login link for PayPal. OAuth Client ID and Secret can be created at <ulink url="https://developer.paypal.com/webapps/developer/applications/myapps">https://developer.paypal.com/webapps/developer/applications/myapps</ulink> . The redirect uri needs to be <computeroutput>http[s]://HOST[:PORT]/val/api/thirdparty_callback</computeroutput> (an https URL when ODS SSL endpoints have been configured).</p></listitem><listitem><p><computeroutput>openid</computeroutput> - (The actual OpenID is specified in <computeroutput>data</computeroutput>)</p></listitem><listitem><p><computeroutput>webid</computeroutput> - Authenticate via WebID. The method will return an https URL which requests a client certificate.</p></listitem><listitem><p>Any ODS instances which has been installed as OAuth provider via <ref kindref="member" refid="group__ods__module__admin_1gafb92fea83f401240d25d502c48d8acab">admin.oauth.odshosts.new()</ref> can also be used here. API Key and API Secret can be created at <ulink url="http://HOST/oauth/oauth_apps.vspx">http://HOST/oauth/oauth_apps.vspx</ulink> where <computeroutput>HOST</computeroutput> matches the configured ODS instances hostname. The callback URL should be set to the host of the client ODS installation. See <computeroutput>facebook</computeroutput> above for an example.</p></listitem></itemizedlist> </p><p><parameterlist kind="param"><li> <parameternamelist> <parametername>service</parametername> </parameternamelist> <parameterdescription> <p>The type of service to authenticate with. See the list above for <ref kindref="member" refid="group__ods__module__user_1ods_authentication_url_services">Supported Services</ref>. An example would be <computeroutput>google</computeroutput>. Available and enabled (ODS allows to disable certain services for login or registration) can be retrieved via <ref kindref="member" refid="group__ods__module__misc_1ga694da38279997cafbe2f2012dfe30c47">server.getInfo()</ref>. Here it is important to skip the service types that are handled by other functions - namely <computeroutput>digest</computeroutput> (handled by <ref kindref="member" refid="group__ods__module__user_1ga6238a5b780bc6a2811d977bfdc2a9f96">user.authenticate()</ref>). </p></parameterdescription> </li> <li> <parameternamelist> <parametername>callback</parametername> </parameternamelist> <parameterdescription> <p>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 <ref kindref="member" refid="group__ods__module__user_1ods_authentication_url_workflow">Client Workflow</ref>. </p></parameterdescription> </li> <li> <parameternamelist> <parametername>action</parametername> </parameternamelist> <parameterdescription> <p>The action that should be taken. Can be one of <computeroutput>authenticate</computeroutput>, <computeroutput>register</computeroutput>, <computeroutput>connect</computeroutput>, or <computeroutput>auto</computeroutput>. See <ref kindref="member" refid="group__ods__module__user_1ods_authentication_url_action">Authentication Action Types</ref> for details. </p></parameterdescription> </li> <li> <parameternamelist> <parametername>confirm</parametername> </parameternamelist> <parameterdescription> <p>The confirmation mode. Can be one of <computeroutput>always</computeroutput>, <computeroutput>never</computeroutput>, or <computeroutput>auto</computeroutput>. See <ref kindref="member" refid="group__ods__module__user_1ods_authentication_url_confirm">Authentication Confirmation Mode</ref> for details. </p></parameterdescription> </li> <li> <parameternamelist> <parametername>data</parametername> </parameternamelist> <parameterdescription> <p>Optional data only required for <computeroutput>openid</computeroutput> login. </p></parameterdescription> </li> <li> <parameternamelist> <parametername>scope</parametername> </parameternamelist> <parameterdescription> <p>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.<itemizedlist> <listitem><p><computeroutput>basic</computeroutput> - This will just request basic profile information like username and email</p></listitem><listitem><p><computeroutput>profile</computeroutput> - This will request read access to the full profile including friend lists, posts, etc.</p></listitem><listitem><p><computeroutput>dav</computeroutput> - This will request read/write access to a service's filesystem (GDrive, DropBox, etc.) </p></listitem></itemizedlist> </p></parameterdescription> </li> <li> <parameternamelist> <parametername>client_ip</parametername> </parameternamelist> <parameterdescription> <p>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.</p></parameterdescription> </li> </ul> <simplesect kind="return"><p>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.</p></simplesect> <simplesect kind="see"><p><ref kindref="member" refid="group__ods__module__user_1ga6238a5b780bc6a2811d977bfdc2a9f96">user.authenticate()</ref>, <ref kindref="member" refid="group__ods__module__user_1ga974f604be99696e368122af579e4a670">user.authenticate.webid()</ref></p></simplesect> <simplesect kind="par"><title>Authentication</title><p>This function will provide additional information if authentication via one of the supported methods as described in <ref kindref="compound" refid="ods_authentication">ODS Authentication</ref> is used. </p></simplesect> </p></sect1>

schema:url

n7:authenticationUrl