blob: 04949bfee19375e258f152f1076878fbd320085b [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
Michael Ochmannb99feab2016-07-06 14:10:22 +020013----
Shawn O. Pearcec5fed822009-11-17 16:10:10 -080014 git config --file $site_path/etc/gerrit.config auth.type OpenID
Michael Ochmannb99feab2016-07-06 14:10:22 +020015----
Shawn O. Pearcef384b442009-01-10 16:20:56 -080016
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
Michael Ochmannb99feab2016-07-06 14:10:22 +020027----
Shawn O. Pearceab583db2009-03-03 17:28:04 -080028 <Set name="headerBufferSize">16384</Set>
Michael Ochmannb99feab2016-07-06 14:10:22 +020029----
Shawn O. Pearceab583db2009-03-03 17:28:04 -080030
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 Pearcea7d3e6c2014-05-23 11:50:06 -070046To trust only Yahoo!:
Michael Ochmannb99feab2016-07-06 14:10:22 +020047----
Shawn Pearcea7d3e6c2014-05-23 11:50:06 -070048 git config --file $site_path/etc/gerrit.config auth.trustedOpenID https://me.yahoo.com
Michael Ochmannb99feab2016-07-06 14:10:22 +020049----
Shawn O. Pearcea2299662009-02-25 14:34:40 -080050
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
David Pursehouseca046912014-12-12 15:34:09 +090070Linking another identity is also useful for users whose primary OpenID provider
71shuts down. For example Google will
72link:https://developers.google.com/+/api/auth-migration[shut down their OpenID
73service on 20th April 2015]. Users must add an alternative identity, using another
74OpenID provider, before that shutdown date. User who fail to add an alternative
75identity before that date, and end up with their account only having a disabled
76Google identity, will need to create a separate account with an alternative
77provider and then ask the administrator to merge the accounts using the previously
78mentioned method.
79
David Pursehouse8be79ab2014-12-12 15:34:46 +090080To link another identity to an existing account:
81
82* Login with the existing account
83* Select menu Settings -> Identities
84* Click the 'Link Another Identity' button
85* Select the OpenID provider for the other identity
86* Authenticate with the other identity
87
88Login using the other identity can only be performed after the linking is
89successful.
Shawn O. Pearcef384b442009-01-10 16:20:56 -080090
Han-Wen Nienhuys84d830b2017-02-15 16:36:04 +010091== HTTP Basic Authentication
Shawn O. Pearcef384b442009-01-10 16:20:56 -080092
93When using HTTP authentication, Gerrit assumes that the servlet
94container or the frontend web server has performed all user
95authentication prior to handing the request off to Gerrit.
96
97As a result of this assumption, Gerrit can assume that any and
98all requests have already been authenticated. The "Sign In" and
99"Sign Out" links are therefore not displayed in the web UI.
100
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700101To enable this form of authentication:
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800102
Michael Ochmannb99feab2016-07-06 14:10:22 +0200103----
Shawn O. Pearcec5fed822009-11-17 16:10:10 -0800104 git config --file $site_path/etc/gerrit.config auth.type HTTP
105 git config --file $site_path/etc/gerrit.config --unset auth.httpHeader
106 git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com'
Michael Ochmannb99feab2016-07-06 14:10:22 +0200107----
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800108
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700109The auth.type must always be HTTP, indicating the user identity
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800110will be obtained from the HTTP authorization data.
111
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700112The auth.httpHeader must always be unset. If set to any value
113(including `Authorization`) then Gerrit won't correctly honor the
114standard `Authorization` HTTP header.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800115
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700116The auth.emailFormat field ('optional') sets the preferred email
Edwin Kempincdb0e002011-09-08 14:23:30 +0200117address during first login. Gerrit will replace `{0}` with the
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800118username, as obtained from the Authorization header. A format such
119as shown in the example would be typical, to add the domain name
120of the organization.
121
Shawn O. Pearce818fa752009-08-15 14:44:44 -0700122If Apache HTTPd is being used as the primary web server and the
123Apache server will be handling user authentication, a configuration
124such as the following is recommended to ensure Apache performs the
125authentication at the proper time:
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800126
Michael Ochmannb99feab2016-07-06 14:10:22 +0200127----
Shawn O. Pearce818fa752009-08-15 14:44:44 -0700128 <Location "/login/">
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800129 AuthType Basic
Shawn O. Pearce818fa752009-08-15 14:44:44 -0700130 AuthName "Gerrit Code Review"
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800131 Require valid-user
132 ...
133 </Location>
Michael Ochmannb99feab2016-07-06 14:10:22 +0200134----
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800135
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800136=== Database Schema
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800137
138User identities are stored in the `account_external_ids` table.
139The user string obtained from the authorization header has the prefix
140"gerrit:" and is stored in the `external_id` field. For example,
141if a username was "foo" then the external_id field would be populated
142with "gerrit:foo".
143
144
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800145== Computer Associates Siteminder
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800146
147Siteminder is a commercial single sign on solution marketed by
148Computer Associates. It is very common in larger enterprise
149environments.
150
151When using Siteminder, Gerrit assumes it has been installed in a
152servlet container which is running behind an Apache web server,
153and that the Siteminder authentication module has been configured
154within Apache to protect the entire Gerrit application. In this
155configuration all users must authenticate with Siteminder before
156they can access any resource on Gerrit.
157
158As a result of this assumption, Gerrit can assume that any and
159all requests have already been authenticated. The "Sign In" and
160"Sign Out" links are therefore not displayed in the web UI.
161
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700162To enable this form of authentication:
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800163
Michael Ochmannb99feab2016-07-06 14:10:22 +0200164----
Shawn O. Pearcec5fed822009-11-17 16:10:10 -0800165 git config --file $site_path/etc/gerrit.config auth.type HTTP
166 git config --file $site_path/etc/gerrit.config auth.httpHeader SM_USER
167 git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com'
Michael Ochmannb99feab2016-07-06 14:10:22 +0200168----
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800169
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700170The auth.type must always be HTTP, indicating the user identity
171will be obtained from the HTTP authorization data.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800172
David Pursehouse221d4f62012-06-08 17:38:08 +0900173The auth.httpHeader indicates in which HTTP header field the Siteminder
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700174product has stored the username. Usually this is "SM_USER", but
175may differ in your environment. Please refer to your organization's
176single sign-on or security group to ensure the setting is correct.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800177
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700178The auth.emailFormat field ('optional') sets the user's preferred
Edwin Kempincdb0e002011-09-08 14:23:30 +0200179email address when they first login. Gerrit will replace `{0}`
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700180with the username, as supplied by Siteminder. A format such as
181shown in the example would be typical, to add the domain name of
182the organization.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800183
Shawn O. Pearceab583db2009-03-03 17:28:04 -0800184If Jetty is being used, you may need to increase the header
185buffer size parameter, due to very long header lines.
186Add the following to `$JETTY_HOME/etc/jetty.xml` under
187`org.mortbay.jetty.nio.SelectChannelConnector`:
Shawn O. Pearce4246f382009-02-20 18:38:14 -0800188
Michael Ochmannb99feab2016-07-06 14:10:22 +0200189----
Shawn O. Pearce4246f382009-02-20 18:38:14 -0800190 <Set name="headerBufferSize">16384</Set>
Michael Ochmannb99feab2016-07-06 14:10:22 +0200191----
Shawn O. Pearce4246f382009-02-20 18:38:14 -0800192
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800193
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800194=== Database Schema
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800195
196User identities are stored in the `account_external_ids` table.
197The user string obtained from Siteminder (e.g. the value in the
198"SM_USER" HTTP header) has the prefix "gerrit:" and is stored in the
199`external_id` field. For example, if a Siteminder username was "foo"
200then the external_id field would be populated with "gerrit:foo".
201
Shawn O. Pearce5500e692009-05-28 15:55:01 -0700202GERRIT
203------
204Part of link:index.html[Gerrit Code Review]
Yuxuan 'fishy' Wang99cb68d2013-10-31 17:26:00 -0700205
206SEARCHBOX
207---------