blob: c5e5ec413fb5b015988b01ff010e8718f12caa41 [file] [log] [blame]
Shawn O. Pearcef384b442009-01-10 16:20:56 -08001Gerrit2 - Single Sign-On Security
2=================================
3
4Gerrit2 supports integration with some types of single sign-on
5security 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. Pearce1523bd32009-06-05 07:01:39 -070016 git config --file $site_path/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
37either a regular expression (must start with `^` and end with `$`)
38or 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. Pearced7c026d2009-08-05 20:11:22 -070048 git config --file $site_path/gerrit.config auth.trustedOpenID 'https://www.google.com/accounts/o8/id?id='
Shawn O. Pearcea2299662009-02-25 14:34:40 -080049====
50
Shawn O. Pearcef384b442009-01-10 16:20:56 -080051Database Schema
52~~~~~~~~~~~~~~~
53
54User identities obtained from OpenID providers are stored into the
55`account_external_ids` table. Users may link more than one OpenID
56identity to the same Gerrit account (use Settings, Web Identities
57to manage this linking), making it easier for their browser to sign
58in to Gerrit if they are frequently switching between different
59unique OpenID accounts.
60
61
62HTTP Basic/Digest Authentication
63--------------------------------
64
65When using HTTP authentication, Gerrit assumes that the servlet
66container or the frontend web server has performed all user
67authentication prior to handing the request off to Gerrit.
68
69As a result of this assumption, Gerrit can assume that any and
70all requests have already been authenticated. The "Sign In" and
71"Sign Out" links are therefore not displayed in the web UI.
72
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070073To enable this form of authentication:
Shawn O. Pearcef384b442009-01-10 16:20:56 -080074
75====
Shawn O. Pearce1523bd32009-06-05 07:01:39 -070076 git config --file $site_path/gerrit.config auth.type HTTP
77 git config --file $site_path/gerrit.config --unset auth.httpHeader
78 git config --file $site_path/gerrit.config auth.emailFormat '{0}@example.com'
Shawn O. Pearcef384b442009-01-10 16:20:56 -080079====
80
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070081The auth.type must always be HTTP, indicating the user identity
Shawn O. Pearcef384b442009-01-10 16:20:56 -080082will be obtained from the HTTP authorization data.
83
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070084The auth.httpHeader must always be unset. If set to any value
85(including `Authorization`) then Gerrit won't correctly honor the
86standard `Authorization` HTTP header.
Shawn O. Pearcef384b442009-01-10 16:20:56 -080087
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -070088The auth.emailFormat field ('optional') sets the preferred email
Shawn O. Pearcef384b442009-01-10 16:20:56 -080089address during first login. Gerrit will replace `\{0\}` with the
90username, as obtained from the Authorization header. A format such
91as shown in the example would be typical, to add the domain name
92of the organization.
93
Shawn O. Pearce818fa752009-08-15 14:44:44 -070094If Apache HTTPd is being used as the primary web server and the
95Apache server will be handling user authentication, a configuration
96such as the following is recommended to ensure Apache performs the
97authentication at the proper time:
Shawn O. Pearce9520f982009-02-06 10:25:11 -080098
99====
Shawn O. Pearce818fa752009-08-15 14:44:44 -0700100 <Location "/login/">
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800101 AuthType Basic
Shawn O. Pearce818fa752009-08-15 14:44:44 -0700102 AuthName "Gerrit Code Review"
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800103 Require valid-user
104 ...
105 </Location>
106====
107
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800108Database Schema
109~~~~~~~~~~~~~~~
110
111User identities are stored in the `account_external_ids` table.
112The user string obtained from the authorization header has the prefix
113"gerrit:" and is stored in the `external_id` field. For example,
114if a username was "foo" then the external_id field would be populated
115with "gerrit:foo".
116
117
118Computer Associates Siteminder
119------------------------------
120
121Siteminder is a commercial single sign on solution marketed by
122Computer Associates. It is very common in larger enterprise
123environments.
124
125When using Siteminder, Gerrit assumes it has been installed in a
126servlet container which is running behind an Apache web server,
127and that the Siteminder authentication module has been configured
128within Apache to protect the entire Gerrit application. In this
129configuration all users must authenticate with Siteminder before
130they can access any resource on Gerrit.
131
132As a result of this assumption, Gerrit can assume that any and
133all requests have already been authenticated. The "Sign In" and
134"Sign Out" links are therefore not displayed in the web UI.
135
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700136To enable this form of authentication:
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800137
138====
Shawn O. Pearce1523bd32009-06-05 07:01:39 -0700139 git config --file $site_path/gerrit.config auth.type HTTP
140 git config --file $site_path/gerrit.config auth.httpHeader SM_USER
141 git config --file $site_path/gerrit.config auth.emailFormat '{0}@example.com'
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800142====
143
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700144The auth.type must always be HTTP, indicating the user identity
145will be obtained from the HTTP authorization data.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800146
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700147The auth.httpHeader indicates which HTTP header field the Siteminder
148product has stored the username. Usually this is "SM_USER", but
149may differ in your environment. Please refer to your organization's
150single sign-on or security group to ensure the setting is correct.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800151
Shawn O. Pearce0d3ecff2009-06-01 08:34:17 -0700152The auth.emailFormat field ('optional') sets the user's preferred
153email address when they first login. Gerrit will replace `\{0\}`
154with the username, as supplied by Siteminder. A format such as
155shown in the example would be typical, to add the domain name of
156the organization.
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800157
Shawn O. Pearceab583db2009-03-03 17:28:04 -0800158If Jetty is being used, you may need to increase the header
159buffer size parameter, due to very long header lines.
160Add the following to `$JETTY_HOME/etc/jetty.xml` under
161`org.mortbay.jetty.nio.SelectChannelConnector`:
Shawn O. Pearce4246f382009-02-20 18:38:14 -0800162
163====
164 <Set name="headerBufferSize">16384</Set>
165====
166
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800167
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800168Database Schema
169~~~~~~~~~~~~~~~
170
171User identities are stored in the `account_external_ids` table.
172The user string obtained from Siteminder (e.g. the value in the
173"SM_USER" HTTP header) has the prefix "gerrit:" and is stored in the
174`external_id` field. For example, if a Siteminder username was "foo"
175then the external_id field would be populated with "gerrit:foo".
176
Shawn O. Pearce5500e692009-05-28 15:55:01 -0700177GERRIT
178------
179Part of link:index.html[Gerrit Code Review]