Gerrit2 supports integration with some types of single sign-on security solutions, making it possible for end-users to setup and manage accounts, without administrator involvement.

OpenID

By default a new Gerrit installation relies upon OpenID to perform user authentication services. To enable OpenID, the system_config table needs login_type set to OPENID:

UPDATE system_config SET login_type = 'OPENID';

As this is the default setting for new installations there is nothing required from the site administrator to make use of the OpenID authentication services.

If Jetty is being used, you may need to increase the header buffer size parameter, due to very long header lines. Add the following to $JETTY_HOME/etc/jetty.xml under org.mortbay.jetty.nio.SelectChannelConnector:

<Set name="headerBufferSize">16384</Set>

In order to use permissions beyond those granted to the Anonymous Users and Registered Users groups, an account must only have OpenIDs which match at least one pattern from the trusted_external_ids table. Patterns may be either a regular expression (must start with ^ and end with $) or be a simple prefix (any other string).

Out of the box Gerrit is configured to trust three patterns:

The first two patterns trust all OpenID providers on the Internet. The Google specific pattern is obviously also implied by the second pattern (https://), but is inserted by default in order to permit securing Gerrit to trust only Google Accounts easier:

DELETE FROM trusted_external_ids
WHERE external_id IN ('http://', 'https://');

After making changes to trusted_external_ids, either restart Gerrit, or force a cache flush over SSH:

ssh -p 29418 review.example.com gerrit flush-caches

Database Schema

User identities obtained from OpenID providers are stored into the account_external_ids table. Users may link more than one OpenID identity to the same Gerrit account (use Settings, Web Identities to manage this linking), making it easier for their browser to sign in to Gerrit if they are frequently switching between different unique OpenID accounts.

HTTP Basic/Digest Authentication

When using HTTP authentication, Gerrit assumes that the servlet container or the frontend web server has performed all user authentication prior to handing the request off to Gerrit.

As a result of this assumption, Gerrit can assume that any and all requests have already been authenticated. The "Sign In" and "Sign Out" links are therefore not displayed in the web UI.

To enable this form of authentication, update system_config:

UPDATE system_config
SET
 login_type='HTTP'
,login_http_header=NULL
,email_format='{0}@example.com';

The login_type must always be HTTP, indicating the user identity will be obtained from the HTTP authorization data.

The login_http_header must always be NULL. If non-null then Gerrit won't correctly honor the Authorization HTTP header.

The email_format field (optional) sets the preferred email address during first login. Gerrit will replace {0} with the username, as obtained from the Authorization header. A format such as shown in the example would be typical, to add the domain name of the organization.

If Apache HTTPd is being used as the primary web server and Apache will be handling authentication, a configuration such as the following is recommended to ensure repo can obtain the /ssh_info URL during repo upload:

<Location "/ssh_info">
  # We don't want authentication for this one location,
  # as repo uses it to grab our hostname and ssh port
  #
  ProxyPass http://127.0.0.1:8081/ssh_info
  Allow from all
  Satisfy Any
</Location>
#
<Location "/">
  # Everything else should be protected by password
  #
  ProxyPass http://127.0.0.1:8081/
  AuthType Basic
  AuthName "Gerrit Review Server"
  Require valid-user
  ...
</Location>

Database Schema

User identities are stored in the account_external_ids table. The user string obtained from the authorization header has the prefix "gerrit:" and is stored in the external_id field. For example, if a username was "foo" then the external_id field would be populated with "gerrit:foo".

Computer Associates Siteminder

Siteminder is a commercial single sign on solution marketed by Computer Associates. It is very common in larger enterprise environments.

When using Siteminder, Gerrit assumes it has been installed in a servlet container which is running behind an Apache web server, and that the Siteminder authentication module has been configured within Apache to protect the entire Gerrit application. In this configuration all users must authenticate with Siteminder before they can access any resource on Gerrit.

As a result of this assumption, Gerrit can assume that any and all requests have already been authenticated. The "Sign In" and "Sign Out" links are therefore not displayed in the web UI.

To enable this form of authentication, update system_config:

UPDATE system_config
SET
 login_type='HTTP'
,login_http_header='SM_USER'
,email_format='{0}@example.com';

The login_type must always be HTTP, indicating the user identity will be obtained from an HTTP header.

The login_http_header indicates which HTTP header field the Siteminder product has stored the username. Usually this is "SM_USER", but may differ in your environment. Please refer to your organization's single sign-on or security group to ensure the setting is correct.

The email_format field (optional) sets the user's preferred email address when they first login. Gerrit will replace {0} with the username, as supplied by Siteminder. A format such as shown in the example would be typical, to add the domain name of the organization.

If Apache HTTPd is being used, see the section above to configure the /ssh_info URL to be available to repo upload.

If Jetty is being used, you may need to increase the header buffer size parameter, due to very long header lines. Add the following to $JETTY_HOME/etc/jetty.xml under org.mortbay.jetty.nio.SelectChannelConnector:

<Set name="headerBufferSize">16384</Set>

Database Schema

User identities are stored in the account_external_ids table. The user string obtained from Siteminder (e.g. the value in the "SM_USER" HTTP header) has the prefix "gerrit:" and is stored in the external_id field. For example, if a Siteminder username was "foo" then the external_id field would be populated with "gerrit:foo".