Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see https://docs.buildbot.net/current/.

3.10.17. Authentication

class buildbot.www.auth.AuthBase

This class is the base class for all authentication methods. All authentications are not done at the same level, so several optional methods are available. This class implements a default implementation. The login session is stored via twisted’s request.getSession(), and detailed used information is stored in request.getSession().user_info. The session information is then sent to the UI via the config constant (in the user attribute of config).

userInfoProvider

Authentication modules are responsible for providing user information as detailed as possible. When there is a need to get additional information from another source, a userInfoProvider can optionally be specified.

reconfigAuth(master, new_config)
Parameters:

  • master – the reference to the master

  • new_config – the reference to the new configuration

Reconfigure the authentication module. In the base class, this simply sets self.master.

maybeAutoLogin(request)
Parameters:

request – the request object

Returns:

Deferred

This method is called when /config.js is fetched. If the authentication method supports automatic login, e.g., from a header provided by a frontend proxy, this method handles the login.

If it succeeds, the method sets request.getSession().user_info. If the login fails unexpectedly, it raises resource.Error. The default implementation simply returns without setting user_info.

getLoginResource()

Return the resource representing /auth/login.

getLogout()

Return the resource representing /auth/logout.

updateUserInfo(request)
Parameters:

request – the request object

Separate entrypoint for getting user information. This is a means to call self.userInfoProvider if provided.

class buildbot.www.auth.UserInfoProviderBase

Class that can be used, to get more info for the user, like groups, from a separate database.

getUserInfo(username)
Returns:

the user info for the username used for login, via a Deferred

Returns a dict with following keys:

  • email: email address of the user

  • full_name: Full name of the user, like “Homer Simpson”

  • groups: groups the user belongs to, like [“duff fans”, “dads”]

class buildbot.www.oauth2.OAuth2Auth

OAuth2Auth implements oauth2 two-factor authentication. With this method, /auth/login is called twice. The first time (without argument), it should return the URL the browser has to redirect to in order to perform oauth2 authentication and authorization. Then the oauth2 provider will redirect to /auth/login?code=??? and the Buildbot web server will verify the code using the oauth2 provider.

Typical login process is:

  • UI calls the /auth/login API and redirects the browser to the returned oauth2 provider URL

  • oauth2 provider shows a web page with a form for the user to authenticate, and asks the user for permission for Buildbot to access their account

  • oauth2 provider redirects the browser to /auth/login?code=???

  • OAuth2Auth module verifies the code, and get the user’s additional information

  • Buildbot UI is reloaded, with the user authenticated

This implementation is using requests. Subclasses must override the following class attributes:

  • name: Name of the oauth plugin

  • faIcon: Font awesome class to use for login button logo

  • resourceEndpoint: URI of the resource where the authentication token is used

  • authUri: URI the browser is pointed to let the user enter creds

  • tokenUri: URI to verify the browser code and get auth token

  • authUriAdditionalParams: Additional parameters for the authUri

  • tokenUriAdditionalParams: Additional parameters for the tokenUri

getUserInfoFromOAuthClient(self, c)

This method is called after a successful authentication to get additional information about the user from the oauth2 provider.