← 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

  • Committer: Robert Collins
  • Date: 2009-07-07 04:32:13 UTC
  • mto: This revision was merged to the branch mainline in revision 4524.
  • Revision ID: robertc@robertcollins.net-20090707043213-4hjjhgr40iq7gk2d
More informative assertions in xml serialisation.

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 defitions, but will displayed if bzr prompts you
 
62
for a password.
 
63
 
 
64
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitely
 
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 `configuration files`_ apply except for the variable
 
114
policies.
 
115
 
 
116
.. _configuration files: #configuration-settings
 
117
 
 
118
Each section describes an authentication definition.
 
119
 
 
120
The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
 
121
and should appear as the *last* section.
 
122
 
 
123
Each section should define:
 
124
 
 
125
* ``user``: the login to be used,
 
126
 
 
127
Each section could define:
 
128
 
 
129
* ``host``: the remote server,
 
130
 
 
131
* ``port``: the port the server is listening,
 
132
 
 
133
* ``path``: the branch location,
 
134
 
 
135
* ``password``: the password.
 
136
 
 
137
 
 
138
Examples
 
139
--------
 
140
 
 
141
 
 
142
Personal projects hosted outside
 
143
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
144
 
 
145
All connections are done with the same ``user`` (the remote one for which the
 
146
default bzr one is not appropriate) and the password is always prompted with
 
147
some exceptions::
 
148
 
 
149
        # Pet projects on hobby.net
 
150
        [hobby]
 
151
        host=r.hobby.net
 
152
        user=jim
 
153
        password=obvious1234
 
154
        
 
155
        # Home server
 
156
        [home]
 
157
        scheme=https
 
158
        host=home.net
 
159
        user=joe
 
160
        password=1essobV10us
 
161
        
 
162
        [DEFAULT]
 
163
        # Our local user is barbaz, on all remote sites we're known as foobar
 
164
        user=foobar
 
165
 
 
166
 
 
167
Source hosting provider
 
168
~~~~~~~~~~~~~~~~~~~~~~~
 
169
 
 
170
In the shp.net (fictious) domain, each project has its own site::
 
171
 
 
172
        [shpnet domain]
 
173
        # we use sftp, but ssh is the scheme used for authentication
 
174
        scheme=ssh
 
175
        # The leading '.' ensures that 'shp.net' alone doesn't match
 
176
        host=.shp.net
 
177
        user=joe
 
178
        # bzr don't support supplying a password for sftp,
 
179
        # consider using an ssh agent if you don't want to supply
 
180
        # a password interactively. (pageant, ssh-agent, etc)
 
181
 
 
182
HTTPS, SFTP servers and their proxy
 
183
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
184
 
 
185
At company.com, the server hosting release and integration branches is behind a
 
186
proxy, and the two branches use different authentication policies::
 
187
 
 
188
        [reference code]
 
189
        scheme=https
 
190
        host=dev.company.com
 
191
        path=/dev
 
192
        user=user1
 
193
        password=pass1
 
194
 
 
195
        # development branches on dev server
 
196
        [dev]
 
197
        scheme=ssh # bzr+ssh and sftp are available here
 
198
        host=dev.company.com
 
199
        path=/dev/integration
 
200
        user=user2
 
201
        
 
202
        # proxy
 
203
        [proxy]
 
204
        scheme=http
 
205
        host=proxy.company.com
 
206
        port=3128
 
207
        user=proxyuser1
 
208
        password=proxypass1
 
209
 
 
210
 
 
211
Planned enhancements
 
212
--------------------
 
213
 
 
214
The following are not yet implemented but planned as parts of a work in
 
215
progress:
 
216
 
 
217
* add a  ``password_encoding`` field allowing:
 
218
 
 
219
  - storing the passwords in various obfuscating encodings (base64 for one),
 
220
 
 
221
  - delegate password storage to plugins (.netrc for example).
 
222
 
 
223
* update the credentials when the user is prompted for user or password,
 
224
 
 
225
* add a ``verify_certificates`` field for ``HTTPS``.
 
226
 
 
227
The ``password_encoding`` and ``verify_certificates`` fields are recognized but
 
228
ignored in the actual implementation.