blob: 8201bb67b80065cb6df9c252b637c71ef8e2f78d [file] [log] [blame]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001= Gerrit Code Review - Single Sign-On Security
Shawn O. Pearcef384b442009-01-10 16:20:56 -08002
Shawn O. Pearcee31d02c2009-12-08 12:21:37 -08003Gerrit supports integration with some types of single sign-on
Shawn O. Pearcef384b442009-01-10 16:20:56 -08004security solutions, making it possible for end-users to setup
5and manage accounts, without administrator involvement.
6
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08007== OpenID
Shawn O. Pearcef384b442009-01-10 16:20:56 -08008
9By default a new Gerrit installation relies upon OpenID to perform
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070010user authentication services. To enable OpenID, the auth.type
11setting should be `OpenID`:
Shawn O. Pearcef384b442009-01-10 16:20:56 -080012
13====
Shawn O. Pearcec5fed822009-11-17 16:10:10 -080014 git config --file $site_path/etc/gerrit.config auth.type OpenID
Shawn O. Pearcef384b442009-01-10 16:20:56 -080015====
16
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070017As this is the default setting there is nothing required from the
18site administrator to make use of the OpenID authentication services.
Shawn O. Pearcef384b442009-01-10 16:20:56 -080019
20* http://openid.net/[openid.net]
21
Shawn O. Pearceab583db2009-03-03 17:28:04 -080022If Jetty is being used, you may need to increase the header
23buffer size parameter, due to very long header lines.
24Add the following to `$JETTY_HOME/etc/jetty.xml` under
25`org.mortbay.jetty.nio.SelectChannelConnector`:
26
27====
28 <Set name="headerBufferSize">16384</Set>
29====
30
Shawn O. Pearcea2299662009-02-25 14:34:40 -080031In order to use permissions beyond those granted to the
32`Anonymous Users` and `Registered Users` groups, an account
33must only have OpenIDs which match at least one pattern from the
Shawn O. Pearced7c026d2009-08-05 20:11:22 -070034`auth.trustedOpenID` list in `gerrit.config`. Patterns may be
Magnus Bäcke5611832011-02-02 08:57:15 +010035either a
36link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard
37Java regular expression (java.util.regex)] (must start with `^`
38and end with `$`) or be a simple prefix (any other string).
Shawn O. Pearcea2299662009-02-25 14:34:40 -080039
Shawn O. Pearced7c026d2009-08-05 20:11:22 -070040Out of the box Gerrit is configured to trust two patterns, which
41will match any OpenID provider on the Internet:
Shawn O. Pearcea2299662009-02-25 14:34:40 -080042
43* `http://` -- trust all OpenID providers using the HTTP protocol
44* `https://` -- trust all OpenID providers using the HTTPS protocol
Shawn O. Pearcea2299662009-02-25 14:34:40 -080045
Shawn O. Pearced7c026d2009-08-05 20:11:22 -070046To trust only Google Accounts:
Shawn O. Pearcea2299662009-02-25 14:34:40 -080047====
Shawn O. Pearcec5fed822009-11-17 16:10:10 -080048 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 -080049====
50
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -080051=== Database Schema
Shawn O. Pearcef384b442009-01-10 16:20:56 -080052
53User identities obtained from OpenID providers are stored into the
David Pursehouse8be79ab2014-12-12 15:34:46 +090054`account_external_ids` table.
Shawn O. Pearcef384b442009-01-10 16:20:56 -080055
David Pursehouse8be79ab2014-12-12 15:34:46 +090056=== Multiple Identities
57
58Users may link more than one OpenID identity to the same Gerrit account, making
59it easier for their browser to sign in to Gerrit if they are frequently switching
60between different unique OpenID accounts.
61
62[WARNING]
63Users wishing to link an alternative identity should *NOT* log in separately
64with that identity. Doing so will result in a new account being created, and
65subsequent attempts to link that account with the existing account will fail.
66In cases where this happens, the administrator will need to manually merge the
67accounts. See link:https://code.google.com/p/gerrit/wiki/SqlMergeUserAccounts[
68Merging Gerrit User Accounts] on the Gerrit Wiki for details.
69
70To link another identity to an existing account:
71
72* Login with the existing account
73* Select menu Settings -> Identities
74* Click the 'Link Another Identity' button
75* Select the OpenID provider for the other identity
76* Authenticate with the other identity
77
78Login using the other identity can only be performed after the linking is
79successful.
Shawn O. Pearcef384b442009-01-10 16:20:56 -080080
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -080081== HTTP Basic/Digest Authentication
Shawn O. Pearcef384b442009-01-10 16:20:56 -080082
83When using HTTP authentication, Gerrit assumes that the servlet
84container or the frontend web server has performed all user
85authentication prior to handing the request off to Gerrit.
86
87As a result of this assumption, Gerrit can assume that any and
88all requests have already been authenticated. The "Sign In" and
89"Sign Out" links are therefore not displayed in the web UI.
90
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070091To enable this form of authentication:
Shawn O. Pearcef384b442009-01-10 16:20:56 -080092
93====
Shawn O. Pearcec5fed822009-11-17 16:10:10 -080094 git config --file $site_path/etc/gerrit.config auth.type HTTP
95 git config --file $site_path/etc/gerrit.config --unset auth.httpHeader
96 git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com'
Shawn O. Pearcef384b442009-01-10 16:20:56 -080097====
98
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070099The auth.type must always be HTTP, indicating the user identity
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800100will be obtained from the HTTP authorization data.
101
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700102The auth.httpHeader must always be unset. If set to any value
103(including `Authorization`) then Gerrit won't correctly honor the
104standard `Authorization` HTTP header.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800105
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700106The auth.emailFormat field ('optional') sets the preferred email
Edwin Kempincdb0e002011-09-08 14:23:30 +0200107address during first login. Gerrit will replace `{0}` with the
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800108username, as obtained from the Authorization header. A format such
109as shown in the example would be typical, to add the domain name
110of the organization.
111
Shawn O. Pearce818fa752009-08-15 14:44:44 -0700112If Apache HTTPd is being used as the primary web server and the
113Apache server will be handling user authentication, a configuration
114such as the following is recommended to ensure Apache performs the
115authentication at the proper time:
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800116
117====
Shawn O. Pearce818fa752009-08-15 14:44:44 -0700118 <Location "/login/">
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800119 AuthType Basic
Shawn O. Pearce818fa752009-08-15 14:44:44 -0700120 AuthName "Gerrit Code Review"
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800121 Require valid-user
122 ...
123 </Location>
124====
125
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800126=== Database Schema
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800127
128User identities are stored in the `account_external_ids` table.
129The user string obtained from the authorization header has the prefix
130"gerrit:" and is stored in the `external_id` field. For example,
131if a username was "foo" then the external_id field would be populated
132with "gerrit:foo".
133
134
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800135== Computer Associates Siteminder
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800136
137Siteminder is a commercial single sign on solution marketed by
138Computer Associates. It is very common in larger enterprise
139environments.
140
141When using Siteminder, Gerrit assumes it has been installed in a
142servlet container which is running behind an Apache web server,
143and that the Siteminder authentication module has been configured
144within Apache to protect the entire Gerrit application. In this
145configuration all users must authenticate with Siteminder before
146they can access any resource on Gerrit.
147
148As a result of this assumption, Gerrit can assume that any and
149all requests have already been authenticated. The "Sign In" and
150"Sign Out" links are therefore not displayed in the web UI.
151
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700152To enable this form of authentication:
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800153
154====
Shawn O. Pearcec5fed822009-11-17 16:10:10 -0800155 git config --file $site_path/etc/gerrit.config auth.type HTTP
156 git config --file $site_path/etc/gerrit.config auth.httpHeader SM_USER
157 git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com'
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800158====
159
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700160The auth.type must always be HTTP, indicating the user identity
161will be obtained from the HTTP authorization data.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800162
David Pursehouse221d4f62012-06-08 17:38:08 +0900163The auth.httpHeader indicates in which HTTP header field the Siteminder
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700164product has stored the username. Usually this is "SM_USER", but
165may differ in your environment. Please refer to your organization's
166single sign-on or security group to ensure the setting is correct.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800167
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700168The auth.emailFormat field ('optional') sets the user's preferred
Edwin Kempincdb0e002011-09-08 14:23:30 +0200169email address when they first login. Gerrit will replace `{0}`
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700170with the username, as supplied by Siteminder. A format such as
171shown in the example would be typical, to add the domain name of
172the organization.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800173
Shawn O. Pearceab583db2009-03-03 17:28:04 -0800174If Jetty is being used, you may need to increase the header
175buffer size parameter, due to very long header lines.
176Add the following to `$JETTY_HOME/etc/jetty.xml` under
177`org.mortbay.jetty.nio.SelectChannelConnector`:
Shawn O. Pearce4246f382009-02-20 18:38:14 -0800178
179====
180 <Set name="headerBufferSize">16384</Set>
181====
182
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800183
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800184=== Database Schema
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800185
186User identities are stored in the `account_external_ids` table.
187The user string obtained from Siteminder (e.g. the value in the
188"SM_USER" HTTP header) has the prefix "gerrit:" and is stored in the
189`external_id` field. For example, if a Siteminder username was "foo"
190then the external_id field would be populated with "gerrit:foo".
191
Shawn O. Pearce5500e692009-05-28 15:55:01 -0700192GERRIT
193------
194Part of link:index.html[Gerrit Code Review]
Yuxuan 'fishy' Wang99cb68d2013-10-31 17:26:00 -0700195
196SEARCHBOX
197---------