Skip to content

Commit

Permalink
edit auth manual bits
Browse files Browse the repository at this point in the history
  • Loading branch information
@djmitche
djmitche committed Apr 13, 2014
1 parent 7bbd763 commit 8d72b5b
Showing 1 changed file with 91 additions and 69 deletions.
160 changes: 91 additions & 69 deletions master/docs/manual/cfg-www.rst
View file
Expand Up @@ -76,50 +76,59 @@ This server is configured with the :bb:cfg:`www` configuration key, which specif
Authentication plugins
~~~~~~~~~~~~~~~~~~~~~~

By default, buildbot does not require people to authenticate in order to see the readonly data.
In order to access control feature in the web UI, you will need to configure an authentication plugin.
By default, Buildbot does not require people to authenticate in order to see the readonly data.
In order to access control features in the web UI, you will need to configure an authentication plugin.

.. py:class:: buildbot.www.auth.NoAuth
Authentication plugins are implemented as classes, and passed as the ``auth`` parameter to :bb:cfg:`www`.

This class is the default authentication plugin, which disables authentication
The available classes are described here:

.. py:class:: buildbot.www.auth.NoAuth()
.. py:class:: buildbot.www.auth.BasicAuth
This class is the default authentication plugin, which disables authentication

This class implements a basic authentication mechanism using a list of user/password tuples provided from the configuration file.
.. py:class:: buildbot.www.auth.BasicAuth(users)
* ``users``: list of ``("user","password")`` tuples, or dictionary ``dict(user="passwd")``
:param users: list of ``("user","password")`` tuples, or a dictionary of ``{"user": "password", ..}``

example::
Simple username/password authentication using a list of user/password tuples provided in the configuration file. ::

from buildbot.www.auth import BasicAuth
auth=BasicAuth({"homer": "doh!"})

.. py:class:: buildbot.www.auth.HTPasswdAuth
c['www'] = {
# ...
auth=BasicAuth({"homer": "doh!"}),
}

This class implements an authentication against a standard :file:`.htpasswd` file.
.. py:class:: buildbot.www.auth.HTPasswdAuth(passwdFile)
* ``passwdFile``: ``.htpasswd`` file to read
:param passwdFile: An ``.htpasswd`` file to read

example::
This class implements simple username/password authentication against a standard :file:`.htpasswd` file. ::

from buildbot.www.auth import HTPasswdAuth
auth=HTPasswdAuth("my_htpasswd")

.. py:class:: buildbot.www.oauth2.GoogleAuth
c['www'] = {
# ...
auth=HTPasswdAuth("my_htpasswd"),
}

This class implements an authentication with Google_ single sign-on.
You can look at the Google_ oauth2 documentation on how to register your buildbot to the Google systems. The developer console will give you the two parameters you have to give to ``GoogleAuth``
.. py:class:: buildbot.www.oauth2.GoogleAuth(clientId, clientSecret)
Please make sure you register your application with the ``BUILDBOT_URL/login`` url as the allowed redirect URIs.
:param clientId: The client ID of your buildbot application
:param clientSecret: The client secret of your buildbot application

* ``clientId``: The client ID of your buildbot application
This class implements an authentication with Google_ single sign-on.
You can look at the Google_ oauth2 documentation on how to register your Buildbot instance to the Google systems.
The developer console will give you the two parameters you have to give to ``GoogleAuth``

* ``clientSecret``: The client secret of your buildbot application
Register your Buildbot instance with the ``BUILDBOT_URL/login`` url as the allowed redirect URI.

example::
Example::

from buildbot.www.oauth2 import GoogleAuth
auth=GoogleAuth("clientid", "clientsecret")
c['www'] = {
# ...
auth=GoogleAuth("clientid", "clientsecret"),
}

in order to use this module, you need to install the python ``sanction`` module

Expand All @@ -129,47 +138,47 @@ In order to access control feature in the web UI, you will need to configure an
.. _Google: https://developers.google.com/accounts/docs/OAuth2

.. py:class:: buildbot.www.oauth2.GitHubAuth
This class implements an authentication with GitHub_ single sign-on.
You can look at the GitHub_ oauth2 documentation on how to register your buildbot to the GitHub systems. The developer console will give you the two parameters you have to give to ``GitHubAuth``

Please make sure you register your application with the ``BUILDBOT_URL/login`` url as the allowed redirect URIs.
.. py:class:: buildbot.www.oauth2.GitHubAuth(clientId, clientSecret)
* ``clientId``: The client ID of your buildbot application
:param clientId: The client ID of your buildbot application
:param clientSecret: The client secret of your buildbot application

* ``clientSecret``: The client secret of your buildbot application
This class implements an authentication with GitHub_ single sign-on.
It functions almost identically to the :py:class:`~buildbot.www.oauth2.GoogleAuth` class.

example::
Example::

from buildbot.www.oauth2 import GitHubAuth
auth=GitHubAuth("clientid", "clientsecret")

in order to use this module, you need to install the python ``sanction`` module

.. code-block:: bash
pip install sanction
c['www'] = {
# ...
auth=GitHubAuth("clientid", "clientsecret"),
}

.. _GitHub: http://developer.github.com/v3/oauth_authorizations/

.. py:class:: buildbot.www.auth.RemoteUserAuth
In case if buildbot web ui is served through reverse proxy that supports HTTP-based authentication (like apache, lighttpd), it's possible to to tell buildbot to trust web server and get username from request headers.
:param header: header to use to get the username (defaults to ``REMOTE_USER``)
:param headerRegex: regular expression to get the username from header value (defaults to ``"(?P<username>[^ @]+)@(?P<realm>[^ @]+)"). Note that your at least need to specify a ``?P<username>`` regular expression named group.
:param userInfoProvider: user info provider; see :ref:`User-Information`

Administrator must make sure that it's impossible to get access to buildbot using other way than through frontend. Usually this means that buildbot should listen for incoming connections only on localhost (or on some firewall-protected port). Frontend must require HTTP authentication to access buildbot pages (using any source for credentials, such as htpasswd, PAM, LDAP, Kerberos).
If the Buildbot UI is served through a reverse proxy that supports HTTP-based authentication (like apache or lighttpd), it's possible to to tell Buildbot to trust the web server and get the username from th request headers.

* ``header``: header to use to get the username (defaults to ``REMOTE_USER``)
* ``headerRegex``: regular expression to get the username from header value. (defaults to ``"(?P<username>[^ @]+)@(?P<realm>[^ @]+)"). Note that your at least need to specify a ``?P<username>`` regular expression named group.
Administrator must make sure that it's impossible to get access to Buildbot using other way than through frontend.
Usually this means that Buildbot should listen for incoming connections only on localhost (or on some firewall-protected port).
The reverse proxy must require HTTP authentication to access Buildbot pages (using any source for credentials, such as htpasswd, PAM, LDAP, Kerberos).

example::
Example::

from buildbot.www.auth import RemoteUserAuth
auth=RemoteUserAuth()
c['www'] = {
# ...
auth=RemoteUserAuth(),
}

A corresponding Apache configuration example

.. code-block:: none
.. code-block:: none
<Location "/">
AuthType Kerberos
Expand All @@ -194,26 +203,39 @@ In order to access control feature in the web UI, you will need to configure an
</Location>
The advantage of http auth is that it is uses a proven and fast implementation for authentication. The problem is that the only information that is passed is the username, and there is no way to pass any other information like user email, user groups, etc.
Those information can be very useful to the mailstatus plugin, or the authorization criterias.
The advantage of this sort of authentication is that it is uses a proven and fast implementation for authentication.
The problem is that the only information that is passed to Buildbot is the username, and there is no way to pass any other information like user email, user groups, etc.
That information can be very useful to the mailstatus plugin, or for authorization processes.
See :ref:`User-Information` for a mechanism to supply that information.

.. _User-Information:

User Information
~~~~~~~~~~~~~~~~

For authentication mechanisms which cannot provide complete information about a user, Buildbot needs another way to get user data.
This is useful both for authentication (to fetch more data about the logged-in user) and for avatars (to fetch data about other users).

This extra information is provided by, appropriately enough, user info providers.
These can be passed to :py:class:`~buildbot.www.auth.RemoteUserAuth` and as an element of ``avatar_methods``.

You can configure RemoteUserAuth to use ldap directory to fill remaining user info data
Currently only one provider is available:

.. py:class:: buildbot.ldapuserinfos.LdapUserInfo
.. py:class:: buildbot.ldapuserinfos.LdapUserInfo(uri, bind_user, bind_pw, accountBase, groupBase, accountPattern, groupMemberPattern, accountFullName, accountEmail, groupName, avatarPattern, avatarData, accountExtraFields)
* ``uri``: uri of the ldap server
* ``bind_user``: username of the ldap account that is used to get the infos for other users (usually a "faceless" account)
* ``bind_pw``: password of the ``bind_user``
* ``accountBase``: the base dn (distinguished name)of the user database
* ``groupBase``: the base dn of the groups database
* ``accountPattern``: the pattern for searching in the account database. This must contain the ``%(username)s`` string, which is replaced by the searched username
* ``groupMemberPattern``: the pattern for searching in the group database. This must contain the ``%(dn)s`` string, which is replaced by the searched username's dn
* ``accountFullName``: the name of the field in account ldap database where the full user name is to be found.
* ``accountEmail``: the name of the field in account ldap database where the user email is to be found.
* ``groupName``: the name of the field in groups ldap database where the group name is to be found.
* ``avatarPattern``: the pattern for searching avatars from emails in the account database. This must contain the ``%(email)s`` string, which is replaced by the searched email
* ``avatarData``: the name of the field in groups ldap database where the avatar picture is to be found. This field is supposed to contain the raw picture, format is automatically detected from jpeg, png or git.
* ``accountExtraFields``: extra fields to extracts for use with the authorization policies.
:param uri: uri of the ldap server
:param bind_user: username of the ldap account that is used to get the infos for other users (usually a "faceless" account)
:param bind_pw: password of the ``bind_user``
:param accountBase: the base dn (distinguished name)of the user database
:param groupBase: the base dn of the groups database
:param accountPattern: the pattern for searching in the account database. This must contain the ``%(username)s`` string, which is replaced by the searched username
:param groupMemberPattern: the pattern for searching in the group database. This must contain the ``%(dn)s`` string, which is replaced by the searched username's dn
:param accountFullName: the name of the field in account ldap database where the full user name is to be found.
:param accountEmail: the name of the field in account ldap database where the user email is to be found.
:param groupName: the name of the field in groups ldap database where the group name is to be found.
:param avatarPattern: the pattern for searching avatars from emails in the account database. This must contain the ``%(email)s`` string, which is replaced by the searched email
:param avatarData: the name of the field in groups ldap database where the avatar picture is to be found. This field is supposed to contain the raw picture, format is automatically detected from jpeg, png or git.
:param accountExtraFields: extra fields to extracts for use with the authorization policies.
Example::
Expand All @@ -223,7 +245,7 @@ In order to access control feature in the web UI, you will need to configure an
# this configuration works for MS Active Directory ldap implementation
# we use it for user info, and avatars
userInfos = LdapUserInfo(
userInfoProvider = LdapUserInfo(
uri='ldap://ldap.mycompany.com:3268',
bind_user='ldap_user',
bind_pw='p4$$wd',
Expand All @@ -239,15 +261,15 @@ In order to access control feature in the web UI, you will need to configure an
)
c['www'] = dict(port=PORT, allowed_origins=["*"],
url=c['buildbotURL'],
auth=RemoteUserAuth(userInfos=userInfos),
avatar_methods=[userInfos, AvatarGravatar()]
auth=RemoteUserAuth(userInfoProvider),
avatar_methods=[userInfoProvider, AvatarGravatar()]
)
in order to use this module, you need to install the python ``ldap`` module
In order to use this module, you need to install the ``python-ldap`` module
It is not a pure python module, so you need to install some C library dependancies; in Debian distributions:
.. code-block:: bash
# its not a pure python, so you need to install some c library dependancies
sudo apt-get builddep python-ldap
pip install python-ldap
Expand Down

0 comments on commit 8d72b5b

Please sign in to comment.