← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics/en/authentication.txt

Merge bzr.dev (and fix NEWS)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics/en/authentication.txt
1
 
Authentication Settings
2
 
=======================
3
 
 
4
 
 
5
 
Intent
6
 
------
7
 
 
8
 
Many different authentication policies can be described in the
9
 
``authentication.conf`` file but a particular user should need only a few
10
 
definitions to cover his needs without having to specify a user and a password
11
 
for every branch he uses.
12
 
 
13
 
The definitions found in this file are used to find the credentials to use for
14
 
a given url. The same credentials can generally be used for as many branches as
15
 
possible by grouping their declaration around the remote servers that need
16
 
them. It's even possible to declare credentials that will be used by different
17
 
servers.
18
 
 
19
 
The intent is to make this file as small as possible to minimize maintenance.
20
 
 
21
 
Once the relevant credentials are declared in this file you may use branch urls
22
 
without embedding passwords (security hazard) or even users (enabling sharing
23
 
of your urls with others).
24
 
 
25
 
Instead of using::
26
 
 
27
 
  bzr branch ftp://joe:secret@host.com/path/to/my/branch
28
 
 
29
 
you simply use::
30
 
 
31
 
  bzr branch ftp://host.com/path/to/my/branch
32
 
 
33
 
provided you have created the following ``authentication.conf`` file::
34
 
 
35
 
  [myprojects]
36
 
  scheme=ftp
37
 
  host=host.com
38
 
  user=joe
39
 
  password=secret
40
 
  
41
 
 
42
 
Authentication definitions
43
 
--------------------------
44
 
 
45
 
There are two kinds of authentication used by the various schemes supported by
46
 
bzr:
47
 
 
48
 
1. user and password
49
 
 
50
 
``FTP`` needs a (``user``, ``password``) to authenticate against a ``host``
51
 
``SFTP`` can use either a password or a host key to authenticate. However,
52
 
ssh agents are a better, more secure solution. So we have chosen to not provide
53
 
our own less secure method.
54
 
 
55
 
2. user, realm and password
56
 
 
57
 
``HTTP`` and ``HTTPS`` needs a (``user, realm, password``) to authenticate
58
 
against a host. But, by using ``.htaccess`` files, for example, it is possible
59
 
to define several (``user, realm, password``) for a given ``host``. So what is
60
 
really needed is (``user``, ``password``, ``host``, ``path``). The ``realm`` is
61
 
not taken into account in the definitions, but will displayed if bzr prompts
62
 
you for a password.
63
 
 
64
 
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitly
65
 
specifying the appropriate port.
66
 
 
67
 
To take all schemes into account, the password will be deduced from a set of
68
 
authentication definitions (``scheme``, ``host``, ``port``, ``path``, ``user``,
69
 
``password``).
70
 
 
71
 
  * ``scheme``: can be empty (meaning the rest of the definition can be used
72
 
    for any scheme), ``SFTP`` and ``bzr+ssh`` should not be used here, ``ssh``
73
 
    should be used instead since this is the real scheme regarding
74
 
    authentication,
75
 
 
76
 
  * ``host``: can be empty (to act as a default for any host),
77
 
 
78
 
  * ``port`` can be empty (useful when an host provides several servers for the
79
 
    same scheme), only numerical values are allowed, this should be used only
80
 
    when the server uses a port different than the scheme standard port,
81
 
 
82
 
  * ``path``: can be empty (FTP or SFTP will never user it),
83
 
 
84
 
  * ``user``: can be empty (``bzr`` will defaults to python's
85
 
    ``getpass.get_user()``),
86
 
 
87
 
  * ``password``: can be empty if you prefer to always be prompted for your
88
 
    password.
89
 
 
90
 
Multiple definitions can be provided and, for a given URL, bzr will select a
91
 
(``user`` [, ``password``]) based on the following rules :
92
 
 
93
 
 1. the first match wins,
94
 
 
95
 
 2. empty fields match everything,
96
 
 
97
 
 3. ``scheme`` matches even if decorators are used in the requested URL,
98
 
 
99
 
 4. ``host`` matches exactly or act as a domain if it starts with '.'
100
 
    (``project.bzr.sf.net`` will match ``.bzr.sf.net`` but ``projectbzr.sf.net``
101
 
    will not match ``bzr.sf.net``).
102
 
 
103
 
 5. ``port`` matches if included in the requested URL (exact matches only)
104
 
 
105
 
 6. ``path`` matches if included in the requested URL (and by rule #2 above,
106
 
    empty paths will match any provided path).
107
 
 
108
 
 
109
 
 
110
 
File format
111
 
-----------
112
 
 
113
 
The general rules for :doc:`configuration files <configuration-help>`
114
 
apply except for the variable policies.
115
 
 
116
 
Each section describes an authentication definition.
117
 
 
118
 
The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
119
 
and should appear as the *last* section.
120
 
 
121
 
Each section should define:
122
 
 
123
 
* ``user``: the login to be used,
124
 
 
125
 
Each section could define:
126
 
 
127
 
* ``host``: the remote server,
128
 
 
129
 
* ``port``: the port the server is listening,
130
 
 
131
 
* ``path``: the branch location,
132
 
 
133
 
* ``password``: the password.
134
 
 
135
 
 
136
 
Examples
137
 
--------
138
 
 
139
 
 
140
 
Personal projects hosted outside
141
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142
 
 
143
 
All connections are done with the same ``user`` (the remote one for which the
144
 
default bzr one is not appropriate) and the password is always prompted with
145
 
some exceptions::
146
 
 
147
 
        # Pet projects on hobby.net
148
 
        [hobby]
149
 
        host=r.hobby.net
150
 
        user=jim
151
 
        password=obvious1234
152
 
        
153
 
        # Home server
154
 
        [home]
155
 
        scheme=https
156
 
        host=home.net
157
 
        user=joe
158
 
        password=1essobV10us
159
 
        
160
 
        [DEFAULT]
161
 
        # Our local user is barbaz, on all remote sites we're known as foobar
162
 
        user=foobar
163
 
 
164
 
 
165
 
Source hosting provider
166
 
~~~~~~~~~~~~~~~~~~~~~~~
167
 
 
168
 
In the shp.net (fictitious) domain, each project has its own site::
169
 
 
170
 
        [shpnet domain]
171
 
        # we use sftp, but ssh is the scheme used for authentication
172
 
        scheme=ssh
173
 
        # The leading '.' ensures that 'shp.net' alone doesn't match
174
 
        host=.shp.net
175
 
        user=joe
176
 
        # bzr don't support supplying a password for sftp,
177
 
        # consider using an ssh agent if you don't want to supply
178
 
        # a password interactively. (pageant, ssh-agent, etc)
179
 
 
180
 
HTTPS, SFTP servers and their proxy
181
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
182
 
 
183
 
At company.com, the server hosting release and integration branches is behind a
184
 
proxy, and the two branches use different authentication policies::
185
 
 
186
 
        [reference code]
187
 
        scheme=https
188
 
        host=dev.company.com
189
 
        path=/dev
190
 
        user=user1
191
 
        password=pass1
192
 
 
193
 
        # development branches on dev server
194
 
        [dev]
195
 
        scheme=ssh # bzr+ssh and sftp are available here
196
 
        host=dev.company.com
197
 
        path=/dev/integration
198
 
        user=user2
199
 
        
200
 
        # proxy
201
 
        [proxy]
202
 
        scheme=http
203
 
        host=proxy.company.com
204
 
        port=3128
205
 
        user=proxyuser1
206
 
        password=proxypass1
207
 
 
208
 
 
209
 
Planned enhancements
210
 
--------------------
211
 
 
212
 
The following are not yet implemented but planned as parts of a work in
213
 
progress:
214
 
 
215
 
* add a  ``password_encoding`` field allowing:
216
 
 
217
 
  - storing the passwords in various obfuscating encodings (base64 for one),
218
 
 
219
 
  - delegate password storage to plugins (.netrc for example).
220
 
 
221
 
* update the credentials when the user is prompted for user or password,
222
 
 
223
 
* add a ``verify_certificates`` field for ``HTTPS``.
224
 
 
225
 
The ``password_encoding`` and ``verify_certificates`` fields are recognized but
226
 
ignored in the actual implementation.