Mercurial > kallithea

annotate docs/administrator_guide/auth.rst @ 8210:d3b1cdb8179d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
i18n: drop translation of error message without translation
author Mads Kiilerich <mads@kiilerich.com>
date Thu, 06 Feb 2020 00:34:33 +0100
parents 01aca0a4f876
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7340
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
1 .. _authentication:
7456
39f81c536ad4 docs: Fix a couple of build warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 7348
diff changeset
2
39f81c536ad4 docs: Fix a couple of build warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 7348
diff changeset
3 ====================
7340
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
4 Authentication setup
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
5 ====================
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
6
7340
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
7 Users can be authenticated in different ways. By default, Kallithea
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
8 uses its internal user database. Alternative authentication
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
9 methods include LDAP, PAM, Crowd, and container-based authentication.
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
10
5788
2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5592
diff changeset
11 .. _ldap-setup:
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
12
5815
6feed82b76a3 Merge stable
Mads Kiilerich <madski@unity3d.com>
parents: 5792
diff changeset
13
7340
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
14 LDAP Authentication
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
15 -------------------
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
16
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
17 Kallithea supports LDAP authentication. In order
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
18 to use LDAP, you have to install the python-ldap_ package. This package is
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
19 available via PyPI, so you can install it by running::
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
20
1123
9472a0150bf0 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1092
diff changeset
21 pip install python-ldap
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
22
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
23 .. note:: ``python-ldap`` requires some libraries to be installed on
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
24 your system, so before installing it check that you have at
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
25 least the ``openldap`` and ``sasl`` libraries.
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
26
5426
66f1b9745905 docs: update menu navigation notation to use *Menu > Menu Item*
Søren Løvborg <sorenl@unity3d.com>
parents: 5425
diff changeset
27 Choose *Admin > Authentication*, click the ``kallithea.lib.auth_modules.auth_ldap`` button
66f1b9745905 docs: update menu navigation notation to use *Menu > Menu Item*
Søren Løvborg <sorenl@unity3d.com>
parents: 5425
diff changeset
28 and then *Save*, to enable the LDAP plugin and configure its settings.
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
29
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
30 Here's a typical LDAP setup::
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
31
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
32 Connection settings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
33 Enable LDAP = checked
5497
12b47803189f cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents: 5496
diff changeset
34 Host = host.example.com
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
35 Account = <account>
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
36 Password = <password>
6457
d0f6bd6190c8 auth: change default LDAP to LDAPS on port 636 - insecure authentication is kind of pointless
Mads Kiilerich <madski@unity3d.com>
parents: 6339
diff changeset
37 Connection Security = LDAPS
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
38 Certificate Checks = DEMAND
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
39
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
40 Search settings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
41 Base DN = CN=users,DC=host,DC=example,DC=org
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
42 LDAP Filter = (&(objectClass=user)(!(objectClass=computer)))
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
43 LDAP Search Scope = SUBTREE
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
44
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
45 Attribute mappings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
46 Login Attribute = uid
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
47 First Name Attribute = firstName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
48 Last Name Attribute = lastName
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5077
diff changeset
49 Email Attribute = mail
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
50
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
51 If your user groups are placed in an Organisation Unit (OU) structure, the Search Settings configuration differs::
3801
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents: 3622
diff changeset
52
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents: 3622
diff changeset
53 Search settings
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents: 3622
diff changeset
54 Base DN = DC=host,DC=example,DC=org
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents: 3622
diff changeset
55 LDAP Filter = (&(memberOf=CN=your user group,OU=subunit,OU=unit,DC=host,DC=example,DC=org)(objectClass=user))
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents: 3622
diff changeset
56 LDAP Search Scope = SUBTREE
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents: 3622
diff changeset
57
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
58 .. _enable_ldap:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
59
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
60 Enable LDAP : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
61 Whether to use LDAP for authenticating users.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
62
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
63 .. _ldap_host:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
64
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
65 Host : required
2916
f6685a62e455 Updated docs about LDAP failover server list option
Marcin Kuzminski <marcin@python-works.com>
parents: 2906
diff changeset
66 LDAP server hostname or IP address. Can be also a comma separated
f6685a62e455 Updated docs about LDAP failover server list option
Marcin Kuzminski <marcin@python-works.com>
parents: 2906
diff changeset
67 list of servers to support LDAP fail-over.
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
68
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
69 .. _Port:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
70
6331
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
71 Port : optional
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
72 Defaults to 389 for PLAIN un-encrypted LDAP and START_TLS.
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
73 Defaults to 636 for LDAPS.
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
74
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
75 .. _ldap_account:
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
76
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
77 Account : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
78 Only required if the LDAP server does not allow anonymous browsing of
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
79 records. This should be a special account for record browsing. This
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
80 will require `LDAP Password`_ below.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
81
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
82 .. _LDAP Password:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
83
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
84 Password : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
85 Only required if the LDAP server does not allow anonymous browsing of
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
86 records.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
87
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
88 .. _Enable LDAPS:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
89
1292
c0335c1dee36 added some fixes to LDAP form re-submition, new simples ldap-settings getter.
Marcin Kuzminski <marcin@python-works.com>
parents: 1284
diff changeset
90 Connection Security : required
c0335c1dee36 added some fixes to LDAP form re-submition, new simples ldap-settings getter.
Marcin Kuzminski <marcin@python-works.com>
parents: 1284
diff changeset
91 Defines the connection to LDAP server
c0335c1dee36 added some fixes to LDAP form re-submition, new simples ldap-settings getter.
Marcin Kuzminski <marcin@python-works.com>
parents: 1284
diff changeset
92
6331
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
93 PLAIN
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
94 Plain unencrypted LDAP connection.
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
95 This will by default use `Port`_ 389.
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
96
6331
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
97 LDAPS
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
98 Use secure LDAPS connections according to `Certificate
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
99 Checks`_ configuration.
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
100 This will by default use `Port`_ 636.
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
101
6331
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
102 START_TLS
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
103 Use START TLS according to `Certificate Checks`_ configuration on an
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
104 apparently "plain" LDAP connection.
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents: 6330
diff changeset
105 This will by default use `Port`_ 389.
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
106
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
107 .. _Certificate Checks:
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
108
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
109 Certificate Checks : optional
5435
60e04a21bf0f docs: more consistent use of --
Mads Kiilerich <madski@unity3d.com>
parents: 5434
diff changeset
110 How SSL certificates verification is handled -- this is only useful when
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
111 `Enable LDAPS`_ is enabled. Only DEMAND or HARD offer full SSL security
6330
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents: 6153
diff changeset
112 with mandatory certificate validation, while the other options are
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents: 6153
diff changeset
113 susceptible to man-in-the-middle attacks.
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
114
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
115 NEVER
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
116 A serve certificate will never be requested or checked.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
117
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
118 ALLOW
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
119 A server certificate is requested. Failure to provide a
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
120 certificate or providing a bad certificate will not terminate the
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
121 session.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
122
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
123 TRY
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
124 A server certificate is requested. Failure to provide a
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
125 certificate does not halt the session; providing a bad certificate
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
126 halts the session.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
127
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
128 DEMAND
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
129 A server certificate is requested and must be provided and
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
130 authenticated for the session to proceed.
775
aaf2fc59a39a fixes #77 and adds extendable base Dn with custom uid specification
Marcin Kuzminski <marcin@python-works.com>
parents: 770
diff changeset
131
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
132 HARD
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
133 The same as DEMAND.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
134
6330
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents: 6153
diff changeset
135 .. _Custom CA Certificates:
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents: 6153
diff changeset
136
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents: 6153
diff changeset
137 Custom CA Certificates : optional
8209
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
138 Directory used by OpenSSL to find CAs for validating the LDAP server
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
139 certificate. It defaults to using the system certificate store, and it
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
140 should thus not be necessary to specify *Custom CA Certificates* when using
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
141 certificates signed by a CA trusted by the system.
6330
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents: 6153
diff changeset
142 It can be set to something like `/etc/openldap/cacerts` on older systems or
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents: 6153
diff changeset
143 if using self-signed certificates.
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents: 6153
diff changeset
144
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
145 .. _Base DN:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
146
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
147 Base DN : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
148 The Distinguished Name (DN) where searches for users will be performed.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
149 Searches can be controlled by `LDAP Filter`_ and `LDAP Search Scope`_.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
150
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
151 .. _LDAP Filter:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
152
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
153 LDAP Filter : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
154 A LDAP filter defined by RFC 2254. This is more useful when `LDAP
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
155 Search Scope`_ is set to SUBTREE. The filter is useful for limiting
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
156 which LDAP objects are identified as representing Users for
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
157 authentication. The filter is augmented by `Login Attribute`_ below.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
158 This can commonly be left blank.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
159
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
160 .. _LDAP Search Scope:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
161
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
162 LDAP Search Scope : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
163 This limits how far LDAP will search for a matching object.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
164
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
165 BASE
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
166 Only allows searching of `Base DN`_ and is usually not what you
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
167 want.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
168
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
169 ONELEVEL
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
170 Searches all entries under `Base DN`_, but not Base DN itself.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
171
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
172 SUBTREE
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
173 Searches all entries below `Base DN`_, but not Base DN itself.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
174 When using SUBTREE `LDAP Filter`_ is useful to limit object
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
175 location.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
176
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
177 .. _Login Attribute:
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
178
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
179 Login Attribute : required
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
180 The LDAP record attribute that will be matched as the USERNAME or
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
181 ACCOUNT used to connect to Kallithea. This will be added to `LDAP
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
182 Filter`_ for locating the User object. If `LDAP Filter`_ is specified as
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
183 "LDAPFILTER", `Login Attribute`_ is specified as "uid" and the user has
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
184 connected as "jsmith" then the `LDAP Filter`_ will be augmented as below
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
185 ::
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
186
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
187 (&(LDAPFILTER)(uid=jsmith))
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
188
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
189 .. _ldap_attr_firstname:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
190
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
191 First Name Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
192 The LDAP record attribute which represents the user's first name.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
193
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
194 .. _ldap_attr_lastname:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
195
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
196 Last Name Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
197 The LDAP record attribute which represents the user's last name.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
198
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
199 .. _ldap_attr_email:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
200
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
201 Email Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
202 The LDAP record attribute which represents the user's email address.
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
203
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
204 If all data are entered correctly, and python-ldap_ is properly installed
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
205 users should be granted access to Kallithea with LDAP accounts. At this
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
206 time user information is copied from LDAP into the Kallithea user database.
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
207 This means that updates of an LDAP user object may not be reflected as a
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
208 user update in Kallithea.
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
209
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
210 If You have problems with LDAP access and believe You entered correct
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
211 information check out the Kallithea logs, any error messages sent from LDAP
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
212 will be saved there.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
213
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
214 Active Directory
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5534
diff changeset
215 ^^^^^^^^^^^^^^^^
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
216
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
217 Kallithea can use Microsoft Active Directory for user authentication. This
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
218 is done through an LDAP or LDAPS connection to Active Directory. The
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
219 following LDAP configuration settings are typical for using Active
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
220 Directory ::
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
221
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
222 Base DN = OU=SBSUsers,OU=Users,OU=MyBusiness,DC=v3sys,DC=local
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
223 Login Attribute = sAMAccountName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
224 First Name Attribute = givenName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
225 Last Name Attribute = sn
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5077
diff changeset
226 Email Attribute = mail
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
227
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
228 All other LDAP settings will likely be site-specific and should be
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
229 appropriately configured.
777
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
230
1467
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
231
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
232 Authentication by container or reverse-proxy
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
233 --------------------------------------------
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
234
4501
a68fc4abeda3 issue #7 remove obsolete configuration
domruf <dominikruf@gmail.com>
parents: 4448
diff changeset
235 Kallithea supports delegating the authentication
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
236 of users to its WSGI container, or to a reverse-proxy server through which all
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
237 clients access the application.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
238
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
239 When these authentication methods are enabled in Kallithea, it uses the
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
240 username that the container/proxy (Apache or Nginx, etc.) provides and doesn't
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
241 perform the authentication itself. The authorization, however, is still done by
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
242 Kallithea according to its settings.
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
243
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
244 When a user logs in for the first time using these authentication methods,
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
245 a matching user account is created in Kallithea with default permissions. An
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
246 administrator can then modify it using Kallithea's admin interface.
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
247
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
248 It's also possible for an administrator to create accounts and configure their
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
249 permissions before the user logs in for the first time, using the :ref:`create-user` API.
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
250
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
251 Container-based authentication
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5534
diff changeset
252 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
253
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
254 In a container-based authentication setup, Kallithea reads the user name from
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
255 the ``REMOTE_USER`` server variable provided by the WSGI container.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
256
7340
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
257 After setting up your container (see :ref:`apache_mod_wsgi`), you'll need
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
258 to configure it to require authentication on the location configured for
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
259 Kallithea.
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
260
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
261 Proxy pass-through authentication
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5534
diff changeset
262 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
263
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
264 In a proxy pass-through authentication setup, Kallithea reads the user name
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
265 from the ``X-Forwarded-User`` request header, which should be configured to be
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
266 sent by the reverse-proxy server.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
267
7340
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
268 After setting up your proxy solution (see :ref:`apache_virtual_host_reverse_proxy`,
2898ea3ff76c docs: move authentication info to separate file
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7337
diff changeset
269 :ref:`apache_subdirectory` or :ref:`nginx_virtual_host`), you'll need to
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
270 configure the authentication and add the username in a request header named
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
271 ``X-Forwarded-User``.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
272
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
273 For example, the following config section for Apache sets a subdirectory in a
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
274 reverse-proxy setup with basic auth:
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
275
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
276 .. code-block:: apache
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
277
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
278 <Location /someprefix>
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
279 ProxyPass http://127.0.0.1:5000/someprefix
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
280 ProxyPassReverse http://127.0.0.1:5000/someprefix
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
281 SetEnvIf X-Url-Scheme https HTTPS=1
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
282
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
283 AuthType Basic
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
284 AuthName "Kallithea authentication"
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
285 AuthUserFile /srv/kallithea/.htpasswd
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
286 Require valid-user
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
287
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
288 RequestHeader unset X-Forwarded-User
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
289
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
290 RewriteEngine On
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
291 RewriteCond %{LA-U:REMOTE_USER} (.+)
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
292 RewriteRule .* - [E=RU:%1]
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
293 RequestHeader set X-Forwarded-User %{RU}e
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
294 </Location>
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
295
5609
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
296 Setting metadata in container/reverse-proxy
5815
6feed82b76a3 Merge stable
Mads Kiilerich <madski@unity3d.com>
parents: 5792
diff changeset
297 """""""""""""""""""""""""""""""""""""""""""
5609
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
298 When a new user account is created on the first login, Kallithea has no information about
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
299 the user's email and full name. So you can set some additional request headers like in the
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
300 example below. In this example the user is authenticated via Kerberos and an Apache
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
301 mod_python fixup handler is used to get the user information from a LDAP server. But you
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
302 could set the request headers however you want.
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
303
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
304 .. code-block:: apache
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
305
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
306 <Location /someprefix>
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
307 ProxyPass http://127.0.0.1:5000/someprefix
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
308 ProxyPassReverse http://127.0.0.1:5000/someprefix
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
309 SetEnvIf X-Url-Scheme https HTTPS=1
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
310
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
311 AuthName "Kerberos Login"
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
312 AuthType Kerberos
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
313 Krb5Keytab /etc/apache2/http.keytab
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
314 KrbMethodK5Passwd off
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
315 KrbVerifyKDC on
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
316 Require valid-user
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
317
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
318 PythonFixupHandler ldapmetadata
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
319
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
320 RequestHeader set X_REMOTE_USER %{X_REMOTE_USER}e
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
321 RequestHeader set X_REMOTE_EMAIL %{X_REMOTE_EMAIL}e
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
322 RequestHeader set X_REMOTE_FIRSTNAME %{X_REMOTE_FIRSTNAME}e
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
323 RequestHeader set X_REMOTE_LASTNAME %{X_REMOTE_LASTNAME}e
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
324 </Location>
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
325
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
326 .. code-block:: python
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
327
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
328 from mod_python import apache
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
329 import ldap
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
330
6457
d0f6bd6190c8 auth: change default LDAP to LDAPS on port 636 - insecure authentication is kind of pointless
Mads Kiilerich <madski@unity3d.com>
parents: 6339
diff changeset
331 LDAP_SERVER = "ldaps://server.mydomain.com:636"
5609
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
332 LDAP_USER = ""
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
333 LDAP_PASS = ""
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
334 LDAP_ROOT = "dc=mydomain,dc=com"
5817
c37e5e57b17a spelling: account
timeless@gmail.com
parents: 5815
diff changeset
335 LDAP_FILTER = "sAMAccountName=%s"
c37e5e57b17a spelling: account
timeless@gmail.com
parents: 5815
diff changeset
336 LDAP_ATTR_LIST = ['sAMAccountName','givenname','sn','mail']
5609
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
337
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
338 def fixuphandler(req):
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
339 if req.user is None:
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
340 # no user to search for
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
341 return apache.OK
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
342 else:
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
343 try:
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
344 if('\\' in req.user):
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
345 username = req.user.split('\\')[1]
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
346 elif('@' in req.user):
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
347 username = req.user.split('@')[0]
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
348 else:
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
349 username = req.user
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
350 l = ldap.initialize(LDAP_SERVER)
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
351 l.simple_bind_s(LDAP_USER, LDAP_PASS)
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
352 r = l.search_s(LDAP_ROOT, ldap.SCOPE_SUBTREE, LDAP_FILTER % username, attrlist=LDAP_ATTR_LIST)
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
353
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
354 req.subprocess_env['X_REMOTE_USER'] = username
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
355 req.subprocess_env['X_REMOTE_EMAIL'] = r[0][1]['mail'][0].lower()
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
356 req.subprocess_env['X_REMOTE_FIRSTNAME'] = "%s" % r[0][1]['givenname'][0]
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
357 req.subprocess_env['X_REMOTE_LASTNAME'] = "%s" % r[0][1]['sn'][0]
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
358 except Exception, e:
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
359 apache.log_error("error getting data from ldap %s" % str(e), apache.APLOG_ERR)
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
360
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
361 return apache.OK
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents: 5594
diff changeset
362
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
363 .. note::
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
364 If you enable proxy pass-through authentication, make sure your server is
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
365 only accessible through the proxy. Otherwise, any client would be able to
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
366 forge the authentication header and could effectively become authenticated
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
367 using any account of their liking.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
368
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5412
diff changeset
369
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
370 .. _python-ldap: http://www.python-ldap.org/