blob: e915ffb8a84c828417fa912c1513747ae9dbc018 [file] [log] [blame]
Shawn O. Pearcee31d02c2009-12-08 12:21:37 -08001Gerrit Code Review - Single Sign-On Security
2============================================
Shawn O. Pearcef384b442009-01-10 16:20:56 -08003
Shawn O. Pearcee31d02c2009-12-08 12:21:37 -08004Gerrit supports integration with some types of single sign-on
Shawn O. Pearcef384b442009-01-10 16:20:56 -08005security solutions, making it possible for end-users to setup
6and manage accounts, without administrator involvement.
7
8OpenID
9------
10
11By default a new Gerrit installation relies upon OpenID to perform
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070012user authentication services. To enable OpenID, the auth.type
13setting should be `OpenID`:
Shawn O. Pearcef384b442009-01-10 16:20:56 -080014
15====
Shawn O. Pearcec5fed822009-11-17 16:10:10 -080016 git config --file $site_path/etc/gerrit.config auth.type OpenID
Shawn O. Pearcef384b442009-01-10 16:20:56 -080017====
18
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070019As this is the default setting there is nothing required from the
20site administrator to make use of the OpenID authentication services.
Shawn O. Pearcef384b442009-01-10 16:20:56 -080021
22* http://openid.net/[openid.net]
23
Shawn O. Pearceab583db2009-03-03 17:28:04 -080024If Jetty is being used, you may need to increase the header
25buffer size parameter, due to very long header lines.
26Add the following to `$JETTY_HOME/etc/jetty.xml` under
27`org.mortbay.jetty.nio.SelectChannelConnector`:
28
29====
30 <Set name="headerBufferSize">16384</Set>
31====
32
Shawn O. Pearcea2299662009-02-25 14:34:40 -080033In order to use permissions beyond those granted to the
34`Anonymous Users` and `Registered Users` groups, an account
35must only have OpenIDs which match at least one pattern from the
Shawn O. Pearced7c026d2009-08-05 20:11:22 -070036`auth.trustedOpenID` list in `gerrit.config`. Patterns may be
Magnus Bäcke5611832011-02-02 08:57:15 +010037either a
38link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard
39Java regular expression (java.util.regex)] (must start with `^`
40and end with `$`) or be a simple prefix (any other string).
Shawn O. Pearcea2299662009-02-25 14:34:40 -080041
Shawn O. Pearced7c026d2009-08-05 20:11:22 -070042Out of the box Gerrit is configured to trust two patterns, which
43will match any OpenID provider on the Internet:
Shawn O. Pearcea2299662009-02-25 14:34:40 -080044
45* `http://` -- trust all OpenID providers using the HTTP protocol
46* `https://` -- trust all OpenID providers using the HTTPS protocol
Shawn O. Pearcea2299662009-02-25 14:34:40 -080047
Shawn O. Pearced7c026d2009-08-05 20:11:22 -070048To trust only Google Accounts:
Shawn O. Pearcea2299662009-02-25 14:34:40 -080049====
Shawn O. Pearcec5fed822009-11-17 16:10:10 -080050 git config --file $site_path/etc/gerrit.config auth.trustedOpenID 'https://www.google.com/accounts/o8/id?id='
Shawn O. Pearcea2299662009-02-25 14:34:40 -080051====
52
Shawn O. Pearcef384b442009-01-10 16:20:56 -080053Database Schema
54~~~~~~~~~~~~~~~
55
56User identities obtained from OpenID providers are stored into the
57`account_external_ids` table. Users may link more than one OpenID
58identity to the same Gerrit account (use Settings, Web Identities
59to manage this linking), making it easier for their browser to sign
60in to Gerrit if they are frequently switching between different
61unique OpenID accounts.
62
63
64HTTP Basic/Digest Authentication
65--------------------------------
66
67When using HTTP authentication, Gerrit assumes that the servlet
68container or the frontend web server has performed all user
69authentication prior to handing the request off to Gerrit.
70
71As a result of this assumption, Gerrit can assume that any and
72all requests have already been authenticated. The "Sign In" and
73"Sign Out" links are therefore not displayed in the web UI.
74
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070075To enable this form of authentication:
Shawn O. Pearcef384b442009-01-10 16:20:56 -080076
77====
Shawn O. Pearcec5fed822009-11-17 16:10:10 -080078 git config --file $site_path/etc/gerrit.config auth.type HTTP
79 git config --file $site_path/etc/gerrit.config --unset auth.httpHeader
80 git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com'
Shawn O. Pearcef384b442009-01-10 16:20:56 -080081====
82
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070083The auth.type must always be HTTP, indicating the user identity
Shawn O. Pearcef384b442009-01-10 16:20:56 -080084will be obtained from the HTTP authorization data.
85
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070086The auth.httpHeader must always be unset. If set to any value
87(including `Authorization`) then Gerrit won't correctly honor the
88standard `Authorization` HTTP header.
Shawn O. Pearcef384b442009-01-10 16:20:56 -080089
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070090The auth.emailFormat field ('optional') sets the preferred email
Edwin Kempincdb0e002011-09-08 14:23:30 +020091address during first login. Gerrit will replace `{0}` with the
Shawn O. Pearcef384b442009-01-10 16:20:56 -080092username, as obtained from the Authorization header. A format such
93as shown in the example would be typical, to add the domain name
94of the organization.
95
Shawn O. Pearce818fa752009-08-15 14:44:44 -070096If Apache HTTPd is being used as the primary web server and the
97Apache server will be handling user authentication, a configuration
98such as the following is recommended to ensure Apache performs the
99authentication at the proper time:
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800100
101====
Shawn O. Pearce818fa752009-08-15 14:44:44 -0700102 <Location "/login/">
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800103 AuthType Basic
Shawn O. Pearce818fa752009-08-15 14:44:44 -0700104 AuthName "Gerrit Code Review"
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800105 Require valid-user
106 ...
107 </Location>
108====
109
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800110Database Schema
111~~~~~~~~~~~~~~~
112
113User identities are stored in the `account_external_ids` table.
114The user string obtained from the authorization header has the prefix
115"gerrit:" and is stored in the `external_id` field. For example,
116if a username was "foo" then the external_id field would be populated
117with "gerrit:foo".
118
119
120Computer Associates Siteminder
121------------------------------
122
123Siteminder is a commercial single sign on solution marketed by
124Computer Associates. It is very common in larger enterprise
125environments.
126
127When using Siteminder, Gerrit assumes it has been installed in a
128servlet container which is running behind an Apache web server,
129and that the Siteminder authentication module has been configured
130within Apache to protect the entire Gerrit application. In this
131configuration all users must authenticate with Siteminder before
132they can access any resource on Gerrit.
133
134As a result of this assumption, Gerrit can assume that any and
135all requests have already been authenticated. The "Sign In" and
136"Sign Out" links are therefore not displayed in the web UI.
137
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700138To enable this form of authentication:
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800139
140====
Shawn O. Pearcec5fed822009-11-17 16:10:10 -0800141 git config --file $site_path/etc/gerrit.config auth.type HTTP
142 git config --file $site_path/etc/gerrit.config auth.httpHeader SM_USER
143 git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com'
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800144====
145
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700146The auth.type must always be HTTP, indicating the user identity
147will be obtained from the HTTP authorization data.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800148
David Pursehouse221d4f62012-06-08 17:38:08 +0900149The auth.httpHeader indicates in which HTTP header field the Siteminder
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700150product has stored the username. Usually this is "SM_USER", but
151may differ in your environment. Please refer to your organization's
152single sign-on or security group to ensure the setting is correct.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800153
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700154The auth.emailFormat field ('optional') sets the user's preferred
Edwin Kempincdb0e002011-09-08 14:23:30 +0200155email address when they first login. Gerrit will replace `{0}`
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700156with the username, as supplied by Siteminder. A format such as
157shown in the example would be typical, to add the domain name of
158the organization.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800159
Shawn O. Pearceab583db2009-03-03 17:28:04 -0800160If Jetty is being used, you may need to increase the header
161buffer size parameter, due to very long header lines.
162Add the following to `$JETTY_HOME/etc/jetty.xml` under
163`org.mortbay.jetty.nio.SelectChannelConnector`:
Shawn O. Pearce4246f382009-02-20 18:38:14 -0800164
165====
166 <Set name="headerBufferSize">16384</Set>
167====
168
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800169
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800170Database Schema
171~~~~~~~~~~~~~~~
172
173User identities are stored in the `account_external_ids` table.
174The user string obtained from Siteminder (e.g. the value in the
175"SM_USER" HTTP header) has the prefix "gerrit:" and is stored in the
176`external_id` field. For example, if a Siteminder username was "foo"
177then the external_id field would be populated with "gerrit:foo".
178
Shawn O. Pearce5500e692009-05-28 15:55:01 -0700179GERRIT
180------
181Part of link:index.html[Gerrit Code Review]