« back to all changes in this revision
Viewing changes to doc/en/user-guide/authentication_conf.txt
- browse files at revision 2961.1.1
- compare with another revision
- compare with revision 2900.2.16
- download diff
- download tarball
- view history from revision 2961.1.1
- Committer: Vincent Ladeuil
- Date: 2007-11-04 17:59:03 UTC
- mfrom: (2900.2.26 auth.ring)
- mto: This revision was merged to the branch mainline in revision 2962.
- Revision ID: v.ladeuil+lp@free.fr-20071104175903-shj4jdc44zpg3duq
Authentication ring implementation (read-only)
- files added:
- doc/en/user-guide/authentication_conf.txt
- files modified:
- NEWS
added
removed
doc/en/user-guide/authentication_conf.txt
1
=================================
2
Authentication configuration file
3
=================================
4
5
6
Intent
7
======
8
9
Many different authentication policies can be described in the
10
``$HOME/.bazaar/authentication.conf`` file but a particular user should need
11
only a few definitions to cover his needs without having to specify a user and
12
a password for every branch he uses.
13
14
The definitions found in this file are used to find the credentials to use for
15
a given url. The same credentials can generally be used for as many branches as
16
possible by grouping their declaration around the remote servers that need
17
them. It's even possible to declare credentials that will be used by different
18
servers.
19
20
The intent is to make this file as small as possible to minimize maintenance.
21
22
Once the relevant credentials are declared in this file you may use branch urls
23
without embedding passwords (security hazard) or even users (enabling sharing
24
of your urls with others).
25
26
Instead of using::
27
28
bzr branch ftp://joe:secret@host.com/path/to/my/branch
29
30
you simply use::
31
32
bzr branch ftp://host.com/path/to/my/branch
33
34
provided you have created the following ``authentication.conf`` file::
35
36
[myprojects]
37
scheme=ftp
38
host=host.com
39
user=joe
40
password=secret
41
42
43
Authentication definitions
44
==========================
45
46
There are two kinds of authentication used by the various schemes supported by
47
bzr:
48
49
1. user and password
50
51
``FTP`` and ``SFTP`` needs a (``user``, ``password``) to authenticate against a
52
``host`` (SFTP can use ssh keys too, but we don't talk about that here as ssh
53
agents provide a better solution).
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.html
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
password=precious
179
180
HTTPS, SFTP servers and their proxy
181
-----------------------------------
182
183
At company.com, the server hosting released and integration code is behind a
184
proxy, the two servers 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
password=pass2
200
201
# proxy
202
[proxy]
203
scheme=http
204
host=proxy.company.com
205
port=3128
206
user=proxyuser1
207
password=proxypass1
208
209
210
Planned enhancements
211
====================
212
213
The following are not yet implemented but planned as parts of a work in
214
progress:
215
216
* add a ``password_encoding`` field allowing:
217
218
- storing the passwords in various obfuscating encodings (base64 for one),
219
220
- delegate password storage to plugins (.netrc for example).
221
222
* update the credentials when the user is prompted for user or password,
223
224
* add a ``verify_certificates`` field for ``HTTPS``.
225
226
The ``password_encoding`` and ``verify_certificates`` fields are recognized but
227
ignored in the actual implementation.
b'\\ No newline at end of file'
Loggerhead is a web-based interface for Breezy
Version: 2.0.1