:tocdepth: 3

:py:mod:`gws.base.auth.sql_provider`
====================================

.. py:module:: gws.base.auth.sql_provider

.. autoapi-nested-parse::

   Base provider for the sql-based authorization.

   SQL-based authentication works by executing SELECT queries against a SQL provider.

   The "authorization" query receives the parameters "username", "password", and/or "token" from
   an authentication method. If the query doesn't return any rows, the next authentication
   provider is attempted. Otherwise, exactly one row should be returned with
   at least the following columns:

   - ``validuser`` (bool) - mandatory, should be "true" if the user is allowed to log in
   - ``validpassword`` (bool) - mandatory, should be "true" if the password is valid
   - ``uid`` (str) - user id
   - ``roles``(str) - comma-separated list of roles

   Column names are case-insensitive.

   Other columns, if given, are converted to respective `gws.User` properties.

   The "getUser" query receives user ID as a parameter and should return a record for this user.

   Example configuration (assuming Postgres with ``pgcrypto``)::

       auth.providers+ {
           type "sql"

           authorizationSql '''
               SELECT
                   user.id
                       AS uid,
                   user.first_name || ' ' || user.last_name
                       AS displayname,
                   user.login
                       AS login,
                   user.is_enabled
                       AS validuser,
                   ( passwd = crypt({{password}}, passwd) )
                       AS validpassword
               FROM
                   public.user
               WHERE
                   user.login = {{username}}
           '''

           getUserSql '''
               SELECT
                   user.id
                       AS uid,
                   user.first_name || ' ' || user.last_name
                       AS displayname,
                   user.login
                       AS login
               FROM
                   public.user
               WHERE
                   user.id = {{uid}}
           '''
       }



**Source code:** :source:`gws.base.auth.sql_provider<gws/base/auth/sql_provider.py>`



Module Contents
---------------



.. py:class:: Config(*args, **kwargs)


   Bases: :py:obj:`gws.base.auth.provider.Config`

   SQL-based authorization provider

   .. py:attribute:: authorizationSql
      :type:  str

      Authorization SQL statement

   .. py:attribute:: dbUid
      :type:  Optional[str]

      Database provider uid

   .. py:attribute:: getUserSql
      :type:  str

      User data SQL statement


.. py:class:: Object


   Bases: :py:obj:`gws.base.auth.provider.Object`

   Authentication Provider.

   .. py:attribute:: authorizationSql
      :type:  str

   .. py:attribute:: db
      :type:  gws.DatabaseProvider

   .. py:attribute:: getUserSql
      :type:  str

   .. py:method:: authenticate(method, credentials)

      Authenticate a user.

      :param method: Authentication method.
      :param credentials: Credentials object.

      :returns: An authenticated User or ``None`` if authentication failed.


   .. py:method:: configure()

      Configuration hook.


   .. py:method:: configure_provider()

   .. py:method:: get_user(local_uid)

      Get a User from its local uid.

      :param local_uid: User local uid.

      :returns: A User or ``None``.



.. py:class:: Placeholders(*args, **kwds)


   Bases: :py:obj:`gws.Enum`

   Enumeration type.

   Despite being declared as extending ``Enum`` (for IDE support), this class is actually just a simple object
   and intended to be used as a collection of attributes. It doesn't provide any ``Enum``-specific utilities.

   The rationale behind this is that we need ``Enum`` members (e.g. ``Color.RED``) to be scalars,
   and not complex objects as in the standard ``Enum``.

   .. py:attribute:: password
      :value: 'password'


   .. py:attribute:: token
      :value: 'token'


   .. py:attribute:: uid
      :value: 'uid'


   .. py:attribute:: username
      :value: 'username'