trac-oidc 0.1.5

OpenID Connect authentication for Trac

Description

A plugin to support authentication to trac using the OpenID Connect protocol. Currently this probably only works with Google’s OpenID Provider.

This plugin was written as a partial replacement for the TracAuthOpenId, since Google has (as of mid-June, 2015) discontinued support for authentication using OpenID 2.0. Google’s extension for mapping OpenID 2.0 identifiers to OpenID Connect identifiers is used, so sites which previously used TracAuthOpenId for authentication against Google should be able to switch to using trac-oidc without losing track of user’s settings and permissions.

This plugin is tested with trac versions 0.11, 0.12, 1.0, and 1.1.

The distribution may be downloaded from PyPI. Development takes place at github.

Usage

Obtain OAuth 2.0 Credentials

You must obtain OAuth 2.0 credentials from Google before you can use this plugin.

1. Go to the Google Developers Console.

2. Select a project, or create a new one.

3. In the sidebar on the left, expand APIs & auth. Next, click APIs. Select the Enabled APIs link in the API section to see a list of all your enabled APIs.

4. Optional, but recommended: Make sure that the Google+ API is on the list of enabled APIs. If you have not enabled it, select the API from the list of APIs, then select the Enable API button for the API. (The Google+ API is used to retrieve the user’s real name on initial sign in.)

5. In the sidebar on the left, select Credentials.

6. If you haven’t done so already, create your project’s OAuth 2.0 credentials by clicking Create new Client ID, and providing the information needed to create the credentials.

7. The redirect URI used by this plugin is the base url for your trac followed by /trac_oidc/redirect. I.e. if the top of your trac is at http://example.org/mytrac, then the redirect URI will be http://example.org/mytrac/trac_oidc/redirect. If your trac is available under multiple hostnames, or under both http: and https: schemes, then you may need to configure multiple redirect URIs.

8. When all looks copacetic, click the Download JSON button (on the Credentials page) to download a JSON file containing the required client secrets. Save this file to somewhere where trac can read it. By default, the plugin looks for this file under the name client_secret.json in the conf subdirectory of the trac environment, however this can be configured. (Since the file contains sensitive information, consider setting the file permissions so that not just anybody can read it.)

Install the Plugin

The plugin is available from PyPI, so it may be installed, e.g., using pip:

pip install trac-oidc

Configuration

In your trac.ini:

[components]

# You must enable the trac_oidc plugin
trac_oidc.* = enabled

# Optional: You probably want to disable the stock login module
trac.web.auth.loginmodule = disabled

[trac_oidc]

# Optional: Specify the path to the client secrets JSON file.
# The default is ``client_secret.json``.  Relative paths are
# interpreted relative to the ``conf`` subdirectory of the trac
# environment (i.e. alongside ``trac.ini``.)
client_secret_file = /path/to/client_secret.json

[openid]

# Optional: This only matters if you would like to migrate
# users created by the TracAuthOpenId_ plugin to this one.
# In that case, the OpenID realm must be set to the same value
# that was used by TracAuthOpenId (where it is called the *trust root*)
# for the identity URLs to be comparable.
#
# If this is set, then the OpenID realm will include just the hostname,
# otherwise the realm will include the full base path of the trac.
# E.g. if you trac is is ``http://example.org:8080/mytrac``, then the realm
# will be ``http://example.org:8080/`` if ``absolute_trust_root`` is set
# and ``http://example.org:8080/mytrac`` if ``absolute_trust_root`` is
# not set.
#
# The default is ``true``.
#
absolute_trust_root = false

Migration from TracAuthOpenId

If you used only Google as the authentication provider with TracAuthOpenId, then you should be able to disable TracAuthOpenId, configure and enable trac-oidc, and things should just work — users should keep their sessions (i.e. they will retain their settings and permissions.)

Note

Make sure not to change the setting of absolute_trust_root from whatever you were using with TracAuthOpenId.

If you were using multiple authentication providers with TracAuthOpenId, it should be possible to run both TracAuthOpenId (with Google disabled), and trac-oidc together. I have not tried this, however, and some tuning will probably be required.

To Do

Possible improvements.

Generalize to work with more providers

Though, currently, only authentication via Google’s OP is supported, it should be straightforward to generalize the plugin to work with other OpenID Connect providers, and other authentication services based on OAuth 2.0 (e.g. Twitter, Facebook.)

Integrate with AccountManagerPlugin

I’m not sure exactly what’s involved, but it would be nice if the AccountManagerPlugin could be used to administer associations between OIDC subject identifiers and authenticated sessions, etc.

Authors

Jeff Dairiki

History

0.1.5 (2015-07-16)

• If the stock trac.web.auth.LoginModule is disabled, then handle requests for /login too (because no one else is going to.)

0.1.4 (2015-06-24)

Features

• Tests now run under trac 1.1.5

0.1.3 (2015-06-23)

Behavioral Changes

• In the “logged in as %(user)s” message (in the metanav menu), user is now always set to the session id (also referred to as the authname) of the logged-in user. Previously the real name of the user was shown instead, when it was available. This now matches the behavior of the stock LoginModule component.

Bugs Fixed

• The Logout link should now work again. It was broken for trac >= 1.0.2.

Large Refactor

• Lots of code cleanup, including splitting of logic into several components/classes, include:

  • AuthCookieManager: for managing the trac authentication cookie

  • UserDatabase: for mapping between OpenID identities and trac authnames.

  • SessionHelper: for searching and managing authenticated sessions

  • Authenticator: for handling the OpenID Connect flow

0.1.2 (2015-06-20)

Features

• The plugin should now work with trac 0.11.

Bugs Fixed

• [trac > 1.0.2] Fixed Logout link so that it works under trac > 1.0.2. Recent tracs use a logout form rather than a link (for CSRF protection.)

Testing

• Added a functional test. Run tests with trac version 0.11, 0.12 and latest (1.0).

Refactor

• Renamed trac_oidc.plugin module to trac_oidc.trac_oidc. Trac’s default log format string includes "[%(module)s]" — [trac_oidc] is much more informative than [plugin].

0.1.1 (2015-06-18)

Initial release. There is no 0.1 (I botched the upload to PyPI).