61698b14e0
We previous use the section title style like: Section level 1 =============== Section level 2 --------------- Which have a problem in Asciidoctor that the number of "="s or "-"s must match the number of characters in the header exactly, as a result it's easy to make mistakes while changing the titles. Asciidoctor provides a better style like: = Section level 1 == Section level 2 So we switched to this style. Also fixed a bug in replace_macros.py, which will not cause any problem in the old style. Change-Id: I811dd7238735d98f662767c17086152cd69aea02
178 lines
6.3 KiB
Plaintext
178 lines
6.3 KiB
Plaintext
= Gerrit Code Review - Single Sign-On Security
|
|
|
|
Gerrit supports integration with some types of single sign-on
|
|
security solutions, making it possible for end-users to setup
|
|
and manage accounts, without administrator involvement.
|
|
|
|
== OpenID
|
|
|
|
By default a new Gerrit installation relies upon OpenID to perform
|
|
user authentication services. To enable OpenID, the auth.type
|
|
setting should be `OpenID`:
|
|
|
|
====
|
|
git config --file $site_path/etc/gerrit.config auth.type OpenID
|
|
====
|
|
|
|
As this is the default setting there is nothing required from the
|
|
site administrator to make use of the OpenID authentication services.
|
|
|
|
* http://openid.net/[openid.net]
|
|
|
|
If Jetty is being used, you may need to increase the header
|
|
buffer size parameter, due to very long header lines.
|
|
Add the following to `$JETTY_HOME/etc/jetty.xml` under
|
|
`org.mortbay.jetty.nio.SelectChannelConnector`:
|
|
|
|
====
|
|
<Set name="headerBufferSize">16384</Set>
|
|
====
|
|
|
|
In order to use permissions beyond those granted to the
|
|
`Anonymous Users` and `Registered Users` groups, an account
|
|
must only have OpenIDs which match at least one pattern from the
|
|
`auth.trustedOpenID` list in `gerrit.config`. Patterns may be
|
|
either a
|
|
link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard
|
|
Java regular expression (java.util.regex)] (must start with `^`
|
|
and end with `$`) or be a simple prefix (any other string).
|
|
|
|
Out of the box Gerrit is configured to trust two patterns, which
|
|
will match any OpenID provider on the Internet:
|
|
|
|
* `http://` -- trust all OpenID providers using the HTTP protocol
|
|
* `https://` -- trust all OpenID providers using the HTTPS protocol
|
|
|
|
To trust only Google Accounts:
|
|
====
|
|
git config --file $site_path/etc/gerrit.config auth.trustedOpenID 'https://www.google.com/accounts/o8/id?id='
|
|
====
|
|
|
|
=== Database Schema
|
|
|
|
User identities obtained from OpenID providers are stored into the
|
|
`account_external_ids` table. Users may link more than one OpenID
|
|
identity to the same Gerrit account (use Settings, Web Identities
|
|
to manage this linking), making it easier for their browser to sign
|
|
in to Gerrit if they are frequently switching between different
|
|
unique OpenID accounts.
|
|
|
|
|
|
== HTTP Basic/Digest Authentication
|
|
|
|
When using HTTP authentication, Gerrit assumes that the servlet
|
|
container or the frontend web server has performed all user
|
|
authentication prior to handing the request off to Gerrit.
|
|
|
|
As a result of this assumption, Gerrit can assume that any and
|
|
all requests have already been authenticated. The "Sign In" and
|
|
"Sign Out" links are therefore not displayed in the web UI.
|
|
|
|
To enable this form of authentication:
|
|
|
|
====
|
|
git config --file $site_path/etc/gerrit.config auth.type HTTP
|
|
git config --file $site_path/etc/gerrit.config --unset auth.httpHeader
|
|
git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com'
|
|
====
|
|
|
|
The auth.type must always be HTTP, indicating the user identity
|
|
will be obtained from the HTTP authorization data.
|
|
|
|
The auth.httpHeader must always be unset. If set to any value
|
|
(including `Authorization`) then Gerrit won't correctly honor the
|
|
standard `Authorization` HTTP header.
|
|
|
|
The auth.emailFormat field ('optional') sets the preferred email
|
|
address during first login. Gerrit will replace `{0}` with the
|
|
username, as obtained from the Authorization header. A format such
|
|
as shown in the example would be typical, to add the domain name
|
|
of the organization.
|
|
|
|
If Apache HTTPd is being used as the primary web server and the
|
|
Apache server will be handling user authentication, a configuration
|
|
such as the following is recommended to ensure Apache performs the
|
|
authentication at the proper time:
|
|
|
|
====
|
|
<Location "/login/">
|
|
AuthType Basic
|
|
AuthName "Gerrit Code Review"
|
|
Require valid-user
|
|
...
|
|
</Location>
|
|
====
|
|
|
|
=== Database Schema
|
|
|
|
User identities are stored in the `account_external_ids` table.
|
|
The user string obtained from the authorization header has the prefix
|
|
"gerrit:" and is stored in the `external_id` field. For example,
|
|
if a username was "foo" then the external_id field would be populated
|
|
with "gerrit:foo".
|
|
|
|
|
|
== Computer Associates Siteminder
|
|
|
|
Siteminder is a commercial single sign on solution marketed by
|
|
Computer Associates. It is very common in larger enterprise
|
|
environments.
|
|
|
|
When using Siteminder, Gerrit assumes it has been installed in a
|
|
servlet container which is running behind an Apache web server,
|
|
and that the Siteminder authentication module has been configured
|
|
within Apache to protect the entire Gerrit application. In this
|
|
configuration all users must authenticate with Siteminder before
|
|
they can access any resource on Gerrit.
|
|
|
|
As a result of this assumption, Gerrit can assume that any and
|
|
all requests have already been authenticated. The "Sign In" and
|
|
"Sign Out" links are therefore not displayed in the web UI.
|
|
|
|
To enable this form of authentication:
|
|
|
|
====
|
|
git config --file $site_path/etc/gerrit.config auth.type HTTP
|
|
git config --file $site_path/etc/gerrit.config auth.httpHeader SM_USER
|
|
git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com'
|
|
====
|
|
|
|
The auth.type must always be HTTP, indicating the user identity
|
|
will be obtained from the HTTP authorization data.
|
|
|
|
The auth.httpHeader indicates in which HTTP header field the Siteminder
|
|
product has stored the username. Usually this is "SM_USER", but
|
|
may differ in your environment. Please refer to your organization's
|
|
single sign-on or security group to ensure the setting is correct.
|
|
|
|
The auth.emailFormat field ('optional') sets the user's preferred
|
|
email address when they first login. Gerrit will replace `{0}`
|
|
with the username, as supplied by Siteminder. A format such as
|
|
shown in the example would be typical, to add the domain name of
|
|
the organization.
|
|
|
|
If Jetty is being used, you may need to increase the header
|
|
buffer size parameter, due to very long header lines.
|
|
Add the following to `$JETTY_HOME/etc/jetty.xml` under
|
|
`org.mortbay.jetty.nio.SelectChannelConnector`:
|
|
|
|
====
|
|
<Set name="headerBufferSize">16384</Set>
|
|
====
|
|
|
|
|
|
=== Database Schema
|
|
|
|
User identities are stored in the `account_external_ids` table.
|
|
The user string obtained from Siteminder (e.g. the value in the
|
|
"SM_USER" HTTP header) has the prefix "gerrit:" and is stored in the
|
|
`external_id` field. For example, if a Siteminder username was "foo"
|
|
then the external_id field would be populated with "gerrit:foo".
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|