Documentation/config-sso.txt

Gerrit2 - Single Sign-On Security
=================================

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.

* http://openid.net/[openid.net]

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:

* `http://` -- trust all OpenID providers using the HTTP protocol
* `https://` -- trust all OpenID providers using the HTTPS protocol
* `https://www.google.com/accounts/o8/id?id=` -- trust Google Accounts

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".