blob: 46bdbc8f3543b4d87820ccebfceab9ec118e2270 [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
12user authentication services. To enable OpenID, the `system_config`
13table needs `login_type` set to `OPENID`:
14
15====
16 UPDATE system_config SET login_type = 'OPENID';
17====
18
19As this is the default setting for new installations there is
20nothing required from the site administrator to make use of the
21OpenID authentication services.
22
23* http://openid.net/[openid.net]
24
25Database Schema
26~~~~~~~~~~~~~~~
27
28User identities obtained from OpenID providers are stored into the
29`account_external_ids` table. Users may link more than one OpenID
30identity to the same Gerrit account (use Settings, Web Identities
31to manage this linking), making it easier for their browser to sign
32in to Gerrit if they are frequently switching between different
33unique OpenID accounts.
34
35
36HTTP Basic/Digest Authentication
37--------------------------------
38
39When using HTTP authentication, Gerrit assumes that the servlet
40container or the frontend web server has performed all user
41authentication prior to handing the request off to Gerrit.
42
43As a result of this assumption, Gerrit can assume that any and
44all requests have already been authenticated. The "Sign In" and
45"Sign Out" links are therefore not displayed in the web UI.
46
47To enable this form of authentication, update `system_config`:
48
49====
50 UPDATE system_config
51 SET
52 login_type='HTTP'
53 ,login_http_header=NULL
54 ,email_format='{0}@example.com';
55====
56
57The `login_type` must always be `HTTP`, indicating the user identity
58will be obtained from the HTTP authorization data.
59
60The `login_http_header` must always be `NULL`. If non-null then
61Gerrit won't correctly honor the `Authorization` HTTP header.
62
63The `email_format` field ('optional') sets the preferred email
64address during first login. Gerrit will replace `\{0\}` with the
65username, as obtained from the Authorization header. A format such
66as shown in the example would be typical, to add the domain name
67of the organization.
68
Shawn O. Pearce9520f982009-02-06 10:25:11 -080069If Apache HTTPd is being used as the primary web server and Apache
70will be handling authentication, a configuration such as the
71following is recommended to ensure repo can obtain the `/ssh_info`
72URL during `repo upload`:
73
74====
75 <Location "/ssh_info">
76 # We don't want authentication for this one location,
77 # as repo uses it to grab our hostname and ssh port
78 #
79 ProxyPass http://127.0.0.1:8081/ssh_info
80 Allow from all
81 Satisfy Any
82 </Location>
83 #
84 <Location "/">
85 # Everything else should be protected by password
86 #
87 ProxyPass http://127.0.0.1:8081/
88 AuthType Basic
89 AuthName "Gerrit Review Server"
90 Require valid-user
91 ...
92 </Location>
93====
94
Shawn O. Pearcef384b442009-01-10 16:20:56 -080095Database Schema
96~~~~~~~~~~~~~~~
97
98User identities are stored in the `account_external_ids` table.
99The user string obtained from the authorization header has the prefix
100"gerrit:" and is stored in the `external_id` field. For example,
101if a username was "foo" then the external_id field would be populated
102with "gerrit:foo".
103
104
105Computer Associates Siteminder
106------------------------------
107
108Siteminder is a commercial single sign on solution marketed by
109Computer Associates. It is very common in larger enterprise
110environments.
111
112When using Siteminder, Gerrit assumes it has been installed in a
113servlet container which is running behind an Apache web server,
114and that the Siteminder authentication module has been configured
115within Apache to protect the entire Gerrit application. In this
116configuration all users must authenticate with Siteminder before
117they can access any resource on Gerrit.
118
119As a result of this assumption, Gerrit can assume that any and
120all requests have already been authenticated. The "Sign In" and
121"Sign Out" links are therefore not displayed in the web UI.
122
123To enable this form of authentication, update `system_config`:
124
125====
126 UPDATE system_config
127 SET
128 login_type='HTTP'
129 ,login_http_header='SM_USER'
130 ,email_format='{0}@example.com';
131====
132
133The `login_type` must always be `HTTP`, indicating the user identity
134will be obtained from an HTTP header.
135
136The `login_http_header` indicates which HTTP header field the
137Siteminder product has stored the username. Usually this is
138"SM_USER", but may differ in your environment. Please refer to
139your organization's single sign-on or security group to ensure the
140setting is correct.
141
142The `email_format` field ('optional') sets the user's preferred email
143address when they first login. Gerrit will replace `\{0\}` with the
144username, as supplied by Siteminder. A format such as shown in the
145example would be typical, to add the domain name of the organization.
146
Shawn O. Pearce9520f982009-02-06 10:25:11 -0800147If Apache HTTPd is being used, see the section above to configure
148the `/ssh_info` URL to be available to `repo upload`.
149
150
Shawn O. Pearcef384b442009-01-10 16:20:56 -0800151Database Schema
152~~~~~~~~~~~~~~~
153
154User identities are stored in the `account_external_ids` table.
155The user string obtained from Siteminder (e.g. the value in the
156"SM_USER" HTTP header) has the prefix "gerrit:" and is stored in the
157`external_id` field. For example, if a Siteminder username was "foo"
158then the external_id field would be populated with "gerrit:foo".
159