<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="OpenLink Virtuoso Universal Server: Documentation" />
<meta name="dc.subject" content="OpenLink Virtuoso Universal Server: Documentation" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href=".html" title="Chapter Contents" />
<link rel="prev" href="index.html" title="Home" />
<link rel="next" href="contents.html" title="Contents" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>OpenLink Virtuoso Universal Server: Documentation</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="vc_login" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>OpenLink Virtuoso Universal Server: Documentation - login</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="functions.html">Chapter Contents</a> | <a class="link" href="index.html" title="Home">Prev</a> | <a class="link" href="contents.html" title="Contents">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div>
<a href="overview.html">Overview</a>
</div>
<div>
<a href="installation.html">Installation Guide</a>
</div>
<div>
<a href="quicktours.html">Quick Start & Tours</a>
</div>
<div>
<a href="sampleapps.html">Sample ODBC & JDBC Applications</a>
</div>
<div>
<a href="concepts.html">Conceptual Overview</a>
</div>
<div>
<a href="server.html">Administration</a>
</div>
<div>
<a href="accessinterfaces.html">Data Access Interfaces</a>
</div>
<div>
<a href="sqlreference.html">SQL Reference</a>
</div>
<div>
<a href="sqlprocedures.html">SQL Procedure Language Guide</a>
</div>
<div>
<a href="hooks.html">Database Event Hooks</a>
</div>
<div>
<a href="repl.html">Data Replication, Synchronization and Transformation Services</a>
</div>
<div>
<a href="webappdevelopment.html">Web Application Development</a>
</div>
<div>
<a href="webandxml.html">XML Support</a>
</div>
<div>
<a href="rdfandsparql.html">RDF Data Access and Data Management</a>
</div>
<div>
<a href="webservices.html">Web Services</a>
</div>
<div>
<a href="runtimehosting.html">Runtime Hosting</a>
</div>
<div>
<a href="internetservices.html">Internet Services</a>
</div>
<div>
<a href="freetext.html">Free Text Search</a>
</div>
<div>
<a href="tpcc.html">TPC C Benchmark Kit</a>
</div>
<div>
<a href="xa.html">Using Virtuoso with Tuxedo</a>
</div>
<div>
<a href="appendixa.html">Appendix</a>
</div>
<div>
<a href="functions.html">Virtuoso Functions Guide</a>
</div>
<br />
</div>
<div id="text">
<h2>login</h2>
<div class="refpurpose">Authentication parameters of a page.</div>
<div class="funcsynopsis">
<span class="funcdef">
<<a href="vc_login.html">
<span class="function">login</span>
</a>
name (required)
annotation (optional)
initial-enable (optional)
enabled (optional)
instantiate (optional)
control-udt (optional)
xsd-stub-xhtml (optional)
width (optional)
height (optional)
realm (required)
mode (required)
user-password (optional)
user-password-check (optional)
debug-srcfile (optional)
debug-srcline (optional)
debug-log (optional)
/></span>
</div>
<div class="refsect1">
<div class="refsect1title">Description</div>
<p>
<p>The login control controls authentication for its page.
Depending on options this may or may not be visible.
This works together with a login-form and logout-button controls. The storage of passwords and user names is left to the application, which can specify functions called by these widgets.
The server keeps login information in the following table:</p>
<span class="computeroutput">
create table VSPX_SESSION (VS_REALM varchar, VS_SID varchar, VS_UID varchar, VS_STATE long varchar,
primary key (VS_REALM, VS_SID));
</span>
<p> This table is shared between all vspx applications, each with their login differentiated by realm.
The state is an array of name value pairs which will be accessed through connection_get and connection_set inside the page code.</p>
<p>
There are three methods of keeping session state:URL-poisoning, digest authentication and Cookies.The URL-poisoning scheme presents a login dialog form and sets a session ID as hidden form element.
Digest authentication uses an opaque value as session id and is available only for browsers that support standard HTTP 1.1 digest authentication. The Cookie is an analogue of URL poisoning, but in that case session ID is kept as a Cookie, thus cookies must be enabled on the browser.
</p>
<p>
The login control is mandatory when using a persistent page variables (see persist="session" attribute of 'variable' control). This is because HTTP protocol is state-less; therefore value of such variables have to be stored in a table and restored on next hit with same session ID (and realm). Hence as login control maintains a session state (via some mechanism, see notes above), this capability is used to maintain persistent page variables.
Note also that persistent page variables can be used between different pages, in that case all of those pages need to have login control (in most cases it is invisible).
</p>
</p>
</div>
<div class="refsect1">
<div class="refsect1title">Attributes</div>
<div class="formalpara">
<strong>name = <a href="vc_type_SqlName.html">SqlName</a>
</strong>
<p>A page level unique name identifying a control.</p>
</div>
<div class="formalpara">
<strong>annotation</strong>
<p>A human readable comment.</p>
</div>
<div class="formalpara">
<strong>initial-enable = <a href="vc_type_CalculateableValue.html">CalculateableValue</a>
</strong>
<p>Determines whether a control is initially visible. True by default. Could be data-bound to an SQL expression.</p>
</div>
<div class="formalpara">
<strong>enabled = <a href="vc_type_CalculateableValue.html">CalculateableValue</a>
</strong>
<p>Determines whether a control is visible. True by default. Could be data-bound to an SQL expression.</p>
</div>
<div class="formalpara">
<strong>instantiate = <a href="vc_type_CalculateableValue.html">CalculateableValue</a>
</strong>
<p>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling 'on-init' event handler of the control; other values are calculated before calling 'before-data-bind' event handler.</p>
</div>
<div class="formalpara">
<strong>control-udt = <a href="vc_type_SqlName.html">SqlName</a>
</strong>
<p>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of 'control-udt' attribute should be equal to the name of the desired target UDT.</p>
</div>
<div class="formalpara">
<strong>xsd-stub-xhtml</strong>
<p>This attribute is for internal use only. It has no effect if added to the source VSPX file.</p>
</div>
<div class="formalpara">
<strong>width</strong>
<p>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</p>
</div>
<div class="formalpara">
<strong>height</strong>
<p>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</p>
</div>
<div class="formalpara">
<strong>realm</strong>
<p>This is the authentication realm name.</p>
</div>
<div class="formalpara">
<strong>mode</strong>
<p>This specifies the preferred mode of keeping session and login information.
In the case of url and cookie the name and password will have to be supplied in a form submit. The vspx:login-form control provides a convenient way of doing this. If passwords are transmitted in a form submit, it is best for security to have the login page accessed via SSL only. Many values may be separated by spaces. This is the order of preference. The system will use the first available depending on the user agent.</p>
<table class="data">
<caption>Table: 12.4.9.1. Allowed values of the 'mode' attribute</caption>
<tr>
<td class="data">digest</td>
<td class="data">
<p>HTTP digest authentication is used and the session id will travel as the opaque data in the digest headers.</p>
</td>
</tr>
<tr>
<td class="data">url</td>
<td class="data">
<p>The url mode means that URL poisoning is used and that the session id passes with the links, posts etc. Some automation is offered for this by the vspx:url and vspx:form and derived controls.</p>
</td>
</tr>
<tr>
<td class="data">cookie</td>
<td class="data">
<p>The session id is set in a cookie on browser.</p>
</td>
</tr>
</table>
<br />
</div>
<div class="formalpara">
<strong>user-password</strong>
<p>The name of a SQL function which will retrieve the password given a user name. If digest authentication is to be possible, this function must be specified. Example:
</p>
<div>
<pre class="programlisting">
create procedure
sql_user_password (in name varchar)
{
declare pass varchar;
pass := NULL;
whenever not found goto none;
select pwd_magic_calc (U_NAME, U_PASSWORD, 1) into pass
from SYS_USERS where U_NAME = name and U_SQL_ENABLE = 1 and U_IS_ROLE = 0;
none:
return pass;
}
;</pre>
</div>
</div>
<div class="formalpara">
<strong>user-password-check</strong>
<p>This is a function which takes the user name and password (unencrypted) and returns true if these match, false otherwise.</p>
<p>
If the application will keep a session state which will automatically be extracted from the application's user repository upon login, then either of these functions may set this using connection_set. This will persist in the session if the login is successful and will be discarded otherwise. An example of such information is a user privilege class, real name, email or such.
These functions may be called one or more times during the session, but no more than one call at the start is guaranteed.</p>
<p>Example:</p>
<div>
<pre class="programlisting">
create procedure
sql_user_password_check (in name varchar, in pass varchar)
{
if (exists (select 1 from SYS_USERS where U_NAME = name and U_SQL_ENABLE = 1 and U_IS_ROLE = 0 and
pwd_magic_calc (U_NAME, U_PASSWORD, 1) = pass))
return 1;
return 0;
}
;</pre>
</div>
<p>Note: when the mode is digest the login control will only call user_password and in other modes it will only call user_password_check.</p>
</div>
<div class="formalpara">
<strong>debug-srcfile</strong>
<p>URI of the source document where the tag comes from.</p>
</div>
<div class="formalpara">
<strong>debug-srcline</strong>
<p>Line number in the source document where the tag comes from.</p>
</div>
<div class="formalpara">
<strong>debug-log</strong>
<p>This defines what sort of data are saved to the debugging log.
</p>
</div>
</div>
<div class="refsect1">
<div class="refsect1title">Declaration of type vspx_login</div>
<p>
</p>
<div>
<pre class="screen">
create type vspx_login under vspx_form
as (
vl_realm varchar,
vl_mode varchar,
vl_pwd_get varchar,
vl_usr_check varchar,
vl_authenticated int default 0,
vl_user varchar,
vl_sid varchar,
vl_no_login_redirect varchar,
vl_logout_in_progress int default 0
)
temporary self as ref
overriding method vc_view_state (stream any, n int) returns any,
overriding method vc_set_view_state (e vspx_event) returns any,
constructor method vspx_login (name varchar, parent vspx_control)
</pre>
</div>
</div>
<div class="refsect1">
<div class="refsect1title">Examples</div>
<a name="vc_ex_login__0" />
<div class="example">
<div class="exampletitle">
Simple login dialog
</div>
<p>
<?xml version="1.0"?>
<!--
-
- $Id: login__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2006 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
This example will show simltaniously 'not-autneticated' message and
a simple post counter.
</p>
<div>
<pre class="screen">
<v:page name="login__0" xmlns:v="http://www.openlinksw.com/vspx/">
<html>
<body>
<v:variable name="ctr" type="int" persist="session" default="0"/>
<v:login name="lc1" realm="vspx" mode="url" user-password-check="sql_user_password_check">
<v:template type="if-no-login">You are not logged in</v:template>
<v:login-form name="f1" required="1" title="Login" user-title="User Name" password-title="Password" submit-title="Login"/>
<v:template type="if-login">
Posted #: <v:label name="l1" value="--self.ctr" format="%d"/>
<v:button name="b1" action="simple" value="Reload">
<v:on-post>
self.ctr := self.ctr + 1;
self.l1.vc_data_bind (e);
</v:on-post>
</v:button>
<v:button name="b2" action="logout" value="Logout"/>
</v:template>
</v:login>
</body>
</html>
</v:page>
</pre>
</div>
</div>
</div>
<div class="tip">
<div class="tiptitle">See Also: Reference Material in the Tutorial:</div>
<p>
<a href="/tutorial/web/vx_s_6/login.vspx">VX-S-6</a>
</p>
</div>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
939
