| Gerrit Code Review - Single Sign-On Security |
| ============================================ |
| |
| Gerrit 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 auth.type |
| setting should be `OpenID`: |
| |
| ==== |
| git config --file $site_path/etc/gerrit.config auth.type OpenID |
| ==== |
| |
| As this is the default setting 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 |
| `auth.trustedOpenID` list in `gerrit.config`. Patterns may be |
| either a |
| link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard |
| Java regular expression (java.util.regex)] (must start with `^` |
| and end with `$`) or be a simple prefix (any other string). |
| |
| Out of the box Gerrit is configured to trust two patterns, which |
| will match any OpenID provider on the Internet: |
| |
| * `http://` -- trust all OpenID providers using the HTTP protocol |
| * `https://` -- trust all OpenID providers using the HTTPS protocol |
| |
| To trust only Google Accounts: |
| ==== |
| git config --file $site_path/etc/gerrit.config auth.trustedOpenID 'https://www.google.com/accounts/o8/id?id=' |
| ==== |
| |
| 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: |
| |
| ==== |
| git config --file $site_path/etc/gerrit.config auth.type HTTP |
| git config --file $site_path/etc/gerrit.config --unset auth.httpHeader |
| git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com' |
| ==== |
| |
| The auth.type must always be HTTP, indicating the user identity |
| will be obtained from the HTTP authorization data. |
| |
| The auth.httpHeader must always be unset. If set to any value |
| (including `Authorization`) then Gerrit won't correctly honor the |
| standard `Authorization` HTTP header. |
| |
| The auth.emailFormat 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 the |
| Apache server will be handling user authentication, a configuration |
| such as the following is recommended to ensure Apache performs the |
| authentication at the proper time: |
| |
| ==== |
| <Location "/login/"> |
| AuthType Basic |
| AuthName "Gerrit Code Review" |
| 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: |
| |
| ==== |
| git config --file $site_path/etc/gerrit.config auth.type HTTP |
| git config --file $site_path/etc/gerrit.config auth.httpHeader SM_USER |
| git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com' |
| ==== |
| |
| The auth.type must always be HTTP, indicating the user identity |
| will be obtained from the HTTP authorization data. |
| |
| The auth.httpHeader 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 auth.emailFormat 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 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". |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |