~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/admin-guide/security.txt

  • Committer: Aaron Bentley
  • Date: 2007-06-21 23:43:17 UTC
  • mto: (2520.5.2 bzr.mpbundle)
  • mto: This revision was merged to the branch mainline in revision 2631.
  • Revision ID: abentley@panoramicfeedback.com-20070621234317-5w3h8h36oe90sups
Implement new merge directive format

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
Security
2
 
========
3
 
 
4
 
Authentication
5
 
--------------
6
 
 
7
 
Bazaar's philosophy on authentication is that it is best to reuse existing
8
 
authentication technologies, rather than trying to reinvent potentially
9
 
complicated methods for securely identifying users.  As such, we describe two
10
 
such uses of existing software for authentication purposes.
11
 
 
12
 
Using SSH
13
 
~~~~~~~~~
14
 
 
15
 
SSH is a very well tested and featureful technology for authenticating users.
16
 
For situations where all of the developers have local accounts on the server,
17
 
it is trivial to provide secure, authenticated ``bzr+ssh://`` access.  One
18
 
concern with this method is that it may not be desirable to grant shell access
19
 
to developers on the server machine.  In this case, Bazaar provides
20
 
``bzr_ssh_path_limiter``, a script that runs the Bazaar smart server on the
21
 
server machine at a specified path, and allows no other access.
22
 
 
23
 
To set it up, specify::
24
 
 
25
 
   command="/path/to/bzr_ssh_path_limiter <path>" <typical key line>
26
 
 
27
 
in each user's ``~/.ssh/authorized_keys`` file on the server, where `<path>` is
28
 
the path to limit access to (and its subdirectories).  For more documentation
29
 
on the syntax of the ``authorized_keys`` file see the documentation of the SSH
30
 
server.  This will only permit Bazaar access to the specified path and no other
31
 
SSH access for that user.
32
 
 
33
 
If it isn't desired to give each user an account on the server, multiple
34
 
private/public key pairs can be included under one single SSH account (say
35
 
sshuser) in the ``~sshuser/.ssh/authorized_keys`` file and then each developer
36
 
can be given their own private key.  They can then use
37
 
``bzr+ssh://sshuser@server.example.com/`` URLs to access the server.
38
 
 
39
 
Using HTTP authentication methods
40
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
41
 
 
42
 
Access Control
43
 
--------------
44
 
 
45
 
Many projects need fine-grained access control on who may read and write to
46
 
which branches.  Incorporating these controls into OS-level user accounts
47
 
using groups and filesystem permissions can be difficult or even not permitted
48
 
in some instances.  Bazaar provides a script called ``bzr_access`` that can be
49
 
used to provide access control based on usernames, with authentication
50
 
performed by SSH.  To do so, we need to set up private-key authentication in
51
 
SSH.  This can be done using a single SSH user on the server, or one account
52
 
per user.  The idea is to use the SSH's ``authorized_keys`` file to specify
53
 
the ``bzr_access`` script as the only command that can be run by a user
54
 
identified by a particular key pair.
55
 
 
56
 
First, you will need to generate a private/public key pair for each user who
57
 
will be accessing the repository.  The private key should be distributed to
58
 
the user and the public key will be needed on the server to identify the user.
59
 
On the server, in the SSH user's ``~/.ssh/authorized_keys`` file, use the
60
 
following line for each repository user and the corresponding public key::
61
 
 
62
 
  command="/path/to/bzr_access /path/to/bzr /path/to/repository <username>",no- port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-<type> <key>
63
 
 
64
 
where `<key>` is the (possibly very long) public key, `<type>` is the type of
65
 
SSH key and `<username>` is the username to associate with that public key.
66
 
 
67
 
The ``bzr_access`` script obtains its configuration information from the file
68
 
``/path/to/repository/bzr_access.conf``.  This file should not be placed under
69
 
version control in a branch located at ``/path/to/repository`` since that
70
 
would allow anyone with access to the repository to change the access control
71
 
rules.  The ``bzr_access.conf`` file is in a simple INI-style format with
72
 
sections defined by ``[groups]`` and ``[/]``.  The options in the ``[groups]``
73
 
section are the names of groups and the values of those options should be the
74
 
usernames in that group.  Inside the ``[/]`` section, the options are
75
 
usernames or group names (prefixed with ``@``) and the values are either
76
 
``rw``, ``r`` or nothing, representing read-write access, read-only access or
77
 
no access at all.  A sample of ``bzr_access.conf`` could be::
78
 
 
79
 
   [groups]
80
 
   admins = alpha
81
 
   devels = beta, gamma, delta
82
 
   
83
 
   [/]
84
 
   @admins = rw
85
 
   @devels = r
86
 
   upsilon = 
87
 
 
88
 
where the user whose key is associated with `alpha` would have read-write
89
 
access, the users `beta`, `gamma` and `delta` would have read-only access and
90
 
user `upsilon` would not be able to access any branches under
91
 
``/path/to/repository``.
92
 
 
93
 
Additional Considerations with ``bzr_access``
94
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95
 
 
96
 
As currently written, ``bzr_access`` only allows each public key to be
97
 
associated with a single repository location.  This means that if developers
98
 
need to access two or more different repositories, then each developer will
99
 
need to have two or more private keys for SSH and be able to select between
100
 
them (see ``man ssh`` for more information on configuring multiple private
101
 
keys).
102
 
 
103
 
Also, each repository can only have a single configuration file, with access
104
 
configured for all branches in the repository.  This means that if different
105
 
access rules are needed for different projects, then those projects must be in
106
 
different repositories.  This then necessitates the use of multiple private
107
 
keys as just described.
108
 
 
109
 
Finally, as noted above under `Using SSH`_ all of the public keys may be
110
 
included in the ``authorized_keys`` file of a single user on the server.  It
111
 
is also possible to use a single private/public key pair for all of the
112
 
developers, but this only allows a single username for access control to the
113
 
repository (since the username is associated with the public key in
114
 
``authorized_keys``.  While this is certainly possible it seems to defeat the
115
 
purpose of fine-grained access control, although it does provide the same
116
 
limited SSH access as that described above.