1
=================================
2
Authentication configuration file
3
=================================
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.
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
20
The intent is to make this file as small as possible to minimize maintenance.
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).
28
bzr branch ftp://joe:secret@host.com/path/to/my/branch
32
bzr branch ftp://host.com/path/to/my/branch
34
provided you have created the following ``authentication.conf`` file::
43
Authentication definitions
44
==========================
46
There are two kinds of authentication used by the various schemes supported by
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).
55
2. user, realm and password
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
64
``HTTP proxy`` can be handled as ``HTTP`` (or ``HTTPS``) by explicitely
65
specifying the appropriate port.
67
To take all schemes into account, the password will be deduced from a set of
68
authentication definitions (``scheme``, ``host``, ``port``, ``path``, ``user``,
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
76
* ``host``: can be empty (to act as a default for any host),
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,
82
* ``path``: can be empty (FTP or SFTP will never user it),
84
* ``user``: can be empty (``bzr`` will defaults to python's
85
``getpass.get_user()``),
87
* ``password``: can be empty if you prefer to always be prompted for your
90
Multiple definitions can be provided and, for a given URL, bzr will select a
91
(``user`` [, ``password``]) based on the following rules :
93
1. the first match wins,
95
2. empty fields match everything,
97
3. ``scheme`` matches even if decorators are used in the requested URL,
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``).
103
5. ``port`` matches if included in the requested URL (exact matches only)
105
6. ``path`` matches if included in the requested URL (and by rule #2 above,
106
empty paths will match any provided path).
113
The general rules for `configuration files`_ apply except for the variable
116
.. _configuration files: configuration.html
118
Each section describes an authentication definition.
120
The section name is an arbitrary string, only the ``DEFAULT`` value is reserved
121
and should appear as the *last* section.
123
Each section should define:
125
* ``user``: the login to be used,
127
Each section could define:
129
* ``host``: the remote server,
131
* ``port``: the port the server is listening,
133
* ``path``: the branch location,
135
* ``password``: the password.
142
Personal projects hosted outside
143
--------------------------------
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
149
# Pet projects on hobby.net
163
# Our local user is barbaz, on all remote sites we're known as foobar
167
Source hosting provider
168
-----------------------
170
In the shp.net (fictious) domain, each project has its own site::
173
# we use sftp, but ssh is the scheme used for authentication
175
# The leading '.' ensures that 'shp.net' alone doesn't match
180
HTTPS, SFTP servers and their proxy
181
-----------------------------------
183
At company.com, the server hosting released and integration code is behind a
184
proxy, the two servers use different authentication policies::
193
# development branches on dev server
195
scheme=ssh # bzr+ssh and sftp are available here
197
path=/dev/integration
204
host=proxy.company.com
213
The following are not yet implemented but planned as parts of a work in
216
* add a ``password_encoding`` field allowing:
218
- storing the passwords in various obfuscating encodings (base64 for one),
220
- delegate password storage to plugins (.netrc for example).
222
* update the credentials when the user is prompted for user or password,
224
* add a ``verify_certificates`` field for ``HTTPS``.
226
The ``password_encoding`` and ``verify_certificates`` fields are recognized but
227
ignored in the actual implementation.
b'\\ No newline at end of file'
added
removed
doc/en/user-guide/authentication_conf.txt
