doc/book/devrepo/repo/sessions.rst
author Sylvain Thénault <sylvain.thenault@logilab.fr>
Fri, 30 Sep 2016 17:04:42 +0200
changeset 11761 78c8a2bb04ff
parent 10496 e95b559a06a2
child 12815 a49f134db02e
permissions -rw-r--r--
[json] Stop serializing cw_source into default json representation of an entity Related to #15538288
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     2
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     3
Sessions
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     4
========
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     5
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
     6
Sessions are objects linked to an authenticated user.  The `Session.new_cnx`
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
     7
method returns a new Connection linked to that session.
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
     8
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
     9
Connections
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    10
===========
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
    11
10333
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    12
Connections provide the `.execute` method to query the data sources, along with
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    13
`.commit` and `.rollback` methods for transaction management.
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
    14
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    15
Kinds of connections
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    16
--------------------
2112
df86450ca65d [doc] a note on sessions
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    17
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    18
There are two kinds of connections.
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    19
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    20
* `normal connections` are the most common: they are related to users and
2112
df86450ca65d [doc] a note on sessions
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    21
  carry security checks coming with user credentials
df86450ca65d [doc] a note on sessions
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    22
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    23
* `internal connections` have all the powers; they are also used in only a
2112
df86450ca65d [doc] a note on sessions
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    24
  few situations where you don't already have an adequate session at
df86450ca65d [doc] a note on sessions
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    25
  hand, like: user authentication, data synchronisation in
df86450ca65d [doc] a note on sessions
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    26
  multi-source contexts
df86450ca65d [doc] a note on sessions
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    27
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    28
Normal connections are typically named `_cw` in most appobjects or
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
    29
sometimes just `session`.
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
    30
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    31
Internal connections are available from the `Repository` object and are
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
    32
to be used like this:
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
    33
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
    34
.. sourcecode:: python
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
    35
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    36
   with self.repo.internal_cnx() as cnx:
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    37
       do_stuff_with(cnx)
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    38
       cnx.commit()
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
    39
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
    40
Connections should always be used as context managers, to avoid leaks.
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
    41
10333
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    42
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    43
Python/RQL API
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    44
~~~~~~~~~~~~~~
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    45
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    46
The Python API developped to interface with RQL is inspired from the standard db-api,
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    47
but since `execute` returns its results directly, there is no `cursor` concept.
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    48
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    49
.. sourcecode:: python
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    50
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    51
   execute(rqlstring, args=None, build_descr=True)
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    52
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    53
:rqlstring: the RQL query to execute (unicode)
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    54
:args: if the query contains substitutions, a dictionary containing the values to use
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    55
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    56
The `Connection` object owns the methods `commit` and `rollback`. You
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    57
*should never need to use them* during the development of the web
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    58
interface based on the *CubicWeb* framework as it determines the end
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    59
of the transaction depending on the query execution success. They are
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    60
however useful in other contexts such as tests or custom controllers.
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    61
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    62
.. note::
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    63
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    64
  If a query generates an error related to security (:exc:`Unauthorized`) or to
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    65
  integrity (:exc:`ValidationError`), the transaction can still continue but you
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    66
  won't be able to commit it, a rollback will be necessary to start a new
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    67
  transaction.
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    68
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    69
  Also, a rollback is automatically done if an error occurs during commit.
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    70
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    71
.. note::
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    72
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    73
   A :exc:`ValidationError` has a `entity` attribute. In CubicWeb,
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    74
   this atttribute is set to the entity's eid (not a reference to the
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    75
   entity itself).
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    76
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    77
Executing RQL queries from a view or a hook
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    78
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    79
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    80
When you're within code of the web interface, the Connection is handled by the
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    81
request object. You should not have to access it directly, but use the
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    82
`execute` method directly available on the request, eg:
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    83
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    84
.. sourcecode:: python
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    85
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    86
   rset = self._cw.execute(rqlstring, kwargs)
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    87
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    88
Similarly, on the server side (eg in hooks), there is no request object (since
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    89
you're directly inside the data-server), so you'll have to use the execute method
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    90
of the Connection object.
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    91
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    92
Proper usage of `.execute`
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    93
~~~~~~~~~~~~~~~~~~~~~~~~~~
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    94
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    95
Let's say you want to get T which is in configuration C, this translates to:
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    96
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    97
.. sourcecode:: python
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    98
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
    99
   self._cw.execute('Any T WHERE T in_conf C, C eid %s' % entity.eid)
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   100
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   101
But it must be written in a syntax that will benefit from the use
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   102
of a cache on the RQL server side:
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   103
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   104
.. sourcecode:: python
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   105
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   106
   self._cw.execute('Any T WHERE T in_conf C, C eid %(x)s', {'x': entity.eid})
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   107
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   108
The syntax tree is built once for the "generic" RQL and can be re-used
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   109
with a number of different eids.  The rql IN operator is an exception
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   110
to this rule.
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   111
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   112
.. sourcecode:: python
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   113
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   114
   self._cw.execute('Any T WHERE T in_conf C, C name IN (%s)'
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   115
                    % ','.join(['foo', 'bar']))
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   116
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   117
Alternatively, some of the common data related to an entity can be
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   118
obtained from the `entity.related()` method (which is used under the
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   119
hood by the ORM when you use attribute access notation on an entity to
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   120
get a relation. The initial request would then be translated to:
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   121
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   122
.. sourcecode:: python
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   123
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   124
   entity.related('in_conf', 'object')
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   125
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   126
Additionally this benefits from the fetch_attrs policy (see :ref:`FetchAttrs`)
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   127
optionally defined on the class element, which says which attributes must be
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   128
also loaded when the entity is loaded through the ORM.
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   129
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   130
.. _resultset:
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   131
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   132
The `ResultSet` API
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   133
~~~~~~~~~~~~~~~~~~~
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   134
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   135
ResultSet instances are a very commonly manipulated object. They have
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   136
a rich API as seen below, but we would like to highlight a bunch of
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   137
methods that are quite useful in day-to-day practice:
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   138
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   139
* `__str__()` (applied by `print`) gives a very useful overview of both
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   140
  the underlying RQL expression and the data inside; unavoidable for
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   141
  debugging purposes
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   142
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   143
* `printable_rql()` returns a well formed RQL expression as a
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   144
  string; it is very useful to build views
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   145
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   146
* `entities()` returns a generator on all entities of the result set
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   147
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   148
* `get_entity(row, col)` gets the entity at row, col coordinates; one
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   149
  of the most used result set methods
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   150
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   151
.. autoclass:: cubicweb.rset.ResultSet
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   152
   :members:
10496
e95b559a06a2 [doc] more fixes of warnings/errors in doc build
David Douard <david.douard@logilab.fr>
parents: 10491
diff changeset
   153
   :noindex:
10333
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   154
569324f890d7 [book] remove dbapi documentation
Julien Cristau <julien.cristau@logilab.fr>
parents: 9580
diff changeset
   155
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   156
Authentication and management of sessions
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   157
-----------------------------------------
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   158
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   159
The authentication process is a ballet involving a few dancers:
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   160
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
   161
* through its `get_session` method the top-level application object (the
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   162
  `CubicWebPublisher`) will open a session whenever a web request
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   163
  comes in; it asks the `session manager` to open a session (giving
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   164
  the web request object as context) using `open_session`
2112
df86450ca65d [doc] a note on sessions
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   165
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   166
  * the session manager asks its authentication manager (which is a
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   167
    `component`) to authenticate the request (using `authenticate`)
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   168
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   169
    * the authentication manager asks, in order, to its authentication
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   170
      information retrievers, a login and an opaque object containing
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   171
      other credentials elements (calling `authentication_information`),
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   172
      giving the request object each time
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   173
9175
a7412e884d7b fix typos in docstring, doc and comments
Julien Cristau <julien.cristau@logilab.fr>
parents: 8760
diff changeset
   174
      * the default retriever (named `LoginPasswordRetriever`)
7751
50f89f05ae0a [doc/book] fix ref to trustedauth cube
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6320
diff changeset
   175
        will in turn defer login and password fetching to the request
50f89f05ae0a [doc/book] fix ref to trustedauth cube
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6320
diff changeset
   176
        object (which, depending on the authentication mode (`cookie`
50f89f05ae0a [doc/book] fix ref to trustedauth cube
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6320
diff changeset
   177
        or `http`), will do the appropriate things and return a login
50f89f05ae0a [doc/book] fix ref to trustedauth cube
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6320
diff changeset
   178
        and a password)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   179
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   180
    * the authentication manager, on success, asks the `Repository`
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   181
      object to connect with the found credentials (using `connect`)
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   182
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   183
      * the repository object asks authentication to all of its
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   184
        sources which support the `CWUser` entity with the given
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   185
        credentials; when successful it can build the cwuser entity,
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   186
        from which a regular `Session` object is made; it returns the
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   187
        session id
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   188
7751
50f89f05ae0a [doc/book] fix ref to trustedauth cube
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6320
diff changeset
   189
        * the source in turn will delegate work to an authentifier
50f89f05ae0a [doc/book] fix ref to trustedauth cube
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6320
diff changeset
   190
          class that defines the ultimate `authenticate` method (for
50f89f05ae0a [doc/book] fix ref to trustedauth cube
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6320
diff changeset
   191
          instance the native source will query the database against
50f89f05ae0a [doc/book] fix ref to trustedauth cube
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6320
diff changeset
   192
          the provided credentials)
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   193
6311
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   194
    * the authentication manager, on success, will call back _all_
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   195
      retrievers with `authenticated` and return its authentication
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   196
      data (on failure, it will try the anonymous login or, if the
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   197
      configuration forbids it, raise an `AuthenticationError`)
afd6a9e45489 [doc/book] tell a more complete story on sessions and the authentication process
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6298
diff changeset
   198
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   199
Writing authentication plugins
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   200
------------------------------
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   201
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   202
Sometimes CubicWeb's out-of-the-box authentication schemes (cookie and
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
   203
http) are not sufficient. Nowadays there is a plethora of such schemes
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   204
and the framework cannot provide them all, but as the sequence above
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   205
shows, it is extensible.
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   206
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   207
Two levels have to be considered when writing an authentication
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   208
plugin: the web client and the repository.
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   209
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   210
We invented a scenario where it makes sense to have a new plugin in
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   211
each side: some middleware will do pre-authentication and under the
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   212
right circumstances add a new HTTP `x-foo-user` header to the query
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   213
before it reaches the CubicWeb instance. For a concrete example of
7751
50f89f05ae0a [doc/book] fix ref to trustedauth cube
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6320
diff changeset
   214
this, see the `trustedauth`_ cube.
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   215
7751
50f89f05ae0a [doc/book] fix ref to trustedauth cube
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6320
diff changeset
   216
.. _`trustedauth`: http://www.cubicweb.org/project/cubicweb-trustedauth
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   217
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   218
Repository authentication plugins
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   219
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   220
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   221
On the repository side, it is possible to register a source
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   222
authentifier using the following kind of code:
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   223
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   224
.. sourcecode:: python
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   225
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   226
 from cubicweb.server.sources import native
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   227
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   228
 class FooAuthentifier(native.LoginPasswordAuthentifier):
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   229
     """ a source authentifier plugin
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   230
     if 'foo' in authentication information, no need to check
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   231
     password
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   232
     """
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   233
     auth_rql = 'Any X WHERE X is CWUser, X login %(login)s'
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   234
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   235
     def authenticate(self, session, login, **kwargs):
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   236
         """return CWUser eid for the given login
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   237
         if this account is defined in this source,
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   238
         else raise `AuthenticationError`
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   239
         """
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   240
         session.debug('authentication by %s', self.__class__.__name__)
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   241
         if 'foo' not in kwargs:
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   242
             return super(FooAuthentifier, self).authenticate(session, login, **kwargs)
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   243
         try:
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   244
             rset = session.execute(self.auth_rql, {'login': login})
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   245
             return rset[0][0]
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   246
         except Exception, exc:
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   247
             session.debug('authentication failure (%s)', exc)
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   248
         raise AuthenticationError('foo user is unknown to us')
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   249
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   250
Since repository authentifiers are not appobjects, we have to register
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   251
them through a `server_startup` hook.
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   252
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   253
.. sourcecode:: python
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   254
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   255
 class ServerStartupHook(hook.Hook):
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   256
     """ register the foo authenticator """
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   257
     __regid__ = 'fooauthenticatorregisterer'
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   258
     events = ('server_startup',)
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   259
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   260
     def __call__(self):
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   261
         self.debug('registering foo authentifier')
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   262
         self.repo.system_source.add_authentifier(FooAuthentifier())
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   263
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   264
Web authentication plugins
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   265
~~~~~~~~~~~~~~~~~~~~~~~~~~
6313
b3fd91524132 [doc/book] begin an howto write auth plugins chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6311
diff changeset
   266
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   267
.. sourcecode:: python
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   268
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
   269
 class XFooUserRetriever(authentication.LoginPasswordRetriever):
6319
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   270
     """ authenticate by the x-foo-user http header
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   271
     or just do normal login/password authentication
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   272
     """
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   273
     __regid__ = 'x-foo-user'
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   274
     order = 0
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   275
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   276
     def authentication_information(self, req):
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   277
         """retrieve authentication information from the given request, raise
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   278
         NoAuthInfo if expected information is not found
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   279
         """
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   280
         self.debug('web authenticator building auth info')
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   281
         try:
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   282
            login = req.get_header('x-foo-user')
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   283
            if login:
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   284
                return login, {'foo': True}
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   285
            else:
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   286
                return super(XFooUserRetriever, self).authentication_information(self, req)
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   287
         except Exception, exc:
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   288
            self.debug('web authenticator failed (%s)', exc)
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   289
         raise authentication.NoAuthInfo()
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   290
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   291
     def authenticated(self, retriever, req, cnx, login, authinfo):
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   292
         """callback when return authentication information have opened a
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   293
         repository connection successfully. Take care req has no session
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   294
         attached yet, hence req.execute isn't available.
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   295
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   296
         Here we set a flag on the request to indicate that the user is
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   297
         foo-authenticated. Can be used by a selector
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   298
         """
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   299
         self.debug('web authenticator running post authentication callback')
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   300
         cnx.foo_user = authinfo.get('foo')
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   301
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   302
In the `authenticated` method we add (in an admitedly slightly hackish
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   303
way) an attribute to the connection object. This, in turn, can be used
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   304
to build a selector dispatching on the fact that the user was
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   305
preauthenticated or not.
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   306
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   307
.. sourcecode:: python
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   308
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   309
 @objectify_selector
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   310
 def foo_authenticated(cls, req, rset=None, **kwargs):
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   311
     if hasattr(req.cnx, 'foo_user') and req.foo_user:
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   312
         return 1
20a7399ed58d [doc/book] complete section on authentication plugins
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6313
diff changeset
   313
     return 0
8760
17994bf95d6a [doc] update Session documentation
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7751
diff changeset
   314
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
   315
Full Session and Connection API
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
   316
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8760
17994bf95d6a [doc] update Session documentation
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7751
diff changeset
   317
17994bf95d6a [doc] update Session documentation
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7751
diff changeset
   318
.. autoclass:: cubicweb.server.session.Session
9580
abaae1496ba4 [book] Update documentation for new repoapi
Julien Cristau <julien.cristau@logilab.fr>
parents: 9175
diff changeset
   319
.. autoclass:: cubicweb.server.session.Connection