← 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: Martin Pool
  • Date: 2005-11-04 01:46:31 UTC
  • mto: (1185.33.49 bzr.dev)
  • mto: This revision was merged to the branch mainline in revision 1512.
  • Revision ID: mbp@sourcefrog.net-20051104014631-750e0ad4172c952c
Make biobench directly executable

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.