← 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: Aaron Bentley
  • Date: 2008-04-06 04:44:17 UTC
  • mto: This revision was merged to the branch mainline in revision 3364.
  • Revision ID: aaron@aaronbentley.com-20080406044417-v6lch0yugh7d1vtk
Implement conversion to standalone

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
 
10
only a few definitions to cover his needs without having to specify a user and
 
11
a password 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`` and ``SFTP`` needs a (``user``, ``password``) to authenticate against a
 
51
``host`` (SFTP can use ssh keys too, but we don't talk about that here as ssh
 
52
agents provide a better solution).
 
53
 
 
54
2. user, realm and password
 
55
 
 
56
``HTTP`` and ``HTTPS`` needs a (``user, realm, password``) to authenticate
 
57
against a host. But, by using ``.htaccess`` files, for example, it is possible
 
58
to define several (``user, realm, password``) for a given ``host``. So what is
 
59
really needed is (``user``, ``password``, ``host``, ``path``). The ``realm`` is
 
60
not taken into account in the defitions, but will displayed if bzr prompts you
 
61
for a password.
 
62
 
 
63
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitely
 
64
specifying the appropriate port.
 
65
 
 
66
To take all schemes into account, the password will be deduced from a set of
 
67
authentication definitions (``scheme``, ``host``, ``port``, ``path``, ``user``,
 
68
``password``).
 
69
 
 
70
  * ``scheme``: can be empty (meaning the rest of the definition can be used
 
71
    for any scheme), ``SFTP`` and ``bzr+ssh`` should not be used here, ``ssh``
 
72
    should be used instead since this is the real scheme regarding
 
73
    authentication,
 
74
 
 
75
  * ``host``: can be empty (to act as a default for any host),
 
76
 
 
77
  * ``port`` can be empty (useful when an host provides several servers for the
 
78
    same scheme), only numerical values are allowed, this should be used only
 
79
    when the server uses a port different than the scheme standard port,
 
80
 
 
81
  * ``path``: can be empty (FTP or SFTP will never user it),
 
82
 
 
83
  * ``user``: can be empty (``bzr`` will defaults to python's
 
84
    ``getpass.get_user()``),
 
85
 
 
86
  * ``password``: can be empty if you prefer to always be prompted for your
 
87
    password.
 
88
 
 
89
Multiple definitions can be provided and, for a given URL, bzr will select a
 
90
(``user`` [, ``password``]) based on the following rules :
 
91
 
 
92
 1. the first match wins,
 
93
 
 
94
 2. empty fields match everything,
 
95
 
 
96
 3. ``scheme`` matches even if decorators are used in the requested URL,
 
97
 
 
98
 4. ``host`` matches exactly or act as a domain if it starts with '.'
 
99
    (``project.bzr.sf.net`` will match ``.bzr.sf.net`` but ``projectbzr.sf.net``
 
100
    will not match ``bzr.sf.net``).
 
101
 
 
102
 5. ``port`` matches if included in the requested URL (exact matches only)
 
103
 
 
104
 6. ``path`` matches if included in the requested URL (and by rule #2 above,
 
105
    empty paths will match any provided path).
 
106
 
 
107
 
 
108
 
 
109
File format
 
110
-----------
 
111
 
 
112
The general rules for `configuration files`_ apply except for the variable
 
113
policies.
 
114
 
 
115
.. _configuration files: #configuration-settings
 
116
 
 
117
Each section describes an authentication definition.
 
118
 
 
119
The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
 
120
and should appear as the *last* section.
 
121
 
 
122
Each section should define:
 
123
 
 
124
* ``user``: the login to be used,
 
125
 
 
126
Each section could define:
 
127
 
 
128
* ``host``: the remote server,
 
129
 
 
130
* ``port``: the port the server is listening,
 
131
 
 
132
* ``path``: the branch location,
 
133
 
 
134
* ``password``: the password.
 
135
 
 
136
 
 
137
Examples
 
138
--------
 
139
 
 
140
 
 
141
Personal projects hosted outside
 
142
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
143
 
 
144
All connections are done with the same ``user`` (the remote one for which the
 
145
default bzr one is not appropriate) and the password is always prompted with
 
146
some exceptions::
 
147
 
 
148
        # Pet projects on hobby.net
 
149
        [hobby]
 
150
        host=r.hobby.net
 
151
        user=jim
 
152
        password=obvious1234
 
153
        
 
154
        # Home server
 
155
        [home]
 
156
        scheme=https
 
157
        host=home.net
 
158
        user=joe
 
159
        password=1essobV10us
 
160
        
 
161
        [DEFAULT]
 
162
        # Our local user is barbaz, on all remote sites we're known as foobar
 
163
        user=foobar
 
164
 
 
165
 
 
166
Source hosting provider
 
167
~~~~~~~~~~~~~~~~~~~~~~~
 
168
 
 
169
In the shp.net (fictious) domain, each project has its own site::
 
170
 
 
171
        [shpnet domain]
 
172
        # we use sftp, but ssh is the scheme used for authentication
 
173
        scheme=ssh
 
174
        # The leading '.' ensures that 'shp.net' alone doesn't match
 
175
        host=.shp.net
 
176
        user=joe
 
177
        password=precious
 
178
 
 
179
HTTPS, SFTP servers and their proxy
 
180
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
181
 
 
182
At company.com, the server hosting released and integration code is behind a
 
183
proxy, the two servers use different authentication policies::
 
184
 
 
185
        [reference code]
 
186
        scheme=https
 
187
        host=dev.company.com
 
188
        path=/dev
 
189
        user=user1
 
190
        password=pass1
 
191
 
 
192
        # development branches on dev server
 
193
        [dev]
 
194
        scheme=ssh # bzr+ssh and sftp are available here
 
195
        host=dev.company.com
 
196
        path=/dev/integration
 
197
        user=user2
 
198
        password=pass2
 
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.