##// END OF EJS Templates
docs: added SAML documentation....
marcink -
r3290:ac4e4e5a default
parent child
Show More
@@ -0,0 +1,105
1 .. _config-saml-duosecurity-ref:
2
3
4 SAML 2.0 with Duo Security
5 --------------------------
6
7 **This plugin is available only in EE Edition.**
8
9 |RCE| supports SAML 2.0 Authentication with Duo Security provider. This allows
10 users to log-in to RhodeCode via SSO mechanism of external identity provider
11 such as Duo. The login can be triggered either by the external IDP, or internally
12 by clicking specific authentication button on the log-in page.
13
14
15 Configuration steps
16 ^^^^^^^^^^^^^^^^^^^
17
18 To configure Duo Security SAML authentication, use the following steps:
19
20 1. From the |RCE| interface, select
21 :menuselection:`Admin --> Authentication`
22 2. Activate the `Duo Security` plugin and select :guilabel:`Save`
23 3. Go to newly available menu option called `Duo Security` on the left side.
24 4. Check the `enabled` check box in the plugin configuration section,
25 and fill in the required SAML information and :guilabel:`Save`, for more details,
26 see :ref:`config-saml-duosecurity`
27
28
29 .. _config-saml-duosecurity:
30
31
32 Example SAML Duo Security configuration
33 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
34
35 Example configuration for SAML 2.0 with Duo Security provider::
36
37 *option*: `enabled` => `True`
38 # Enable or disable this authentication plugin.
39
40 *option*: `cache_ttl` => `0`
41 # Amount of seconds to cache the authentication and permissions check response call for this plugin.
42 # Useful for expensive calls like LDAP to improve the performance of the system (0 means disabled).
43
44 *option*: `debug` => `True`
45 # Enable or disable debug mode that shows SAML errors in the RhodeCode logs.
46
47 *option*: `entity_id` => `http://rc-app.com/dag/saml2/idp/metadata.php`
48 # Identity Provider entity/metadata URI.
49 # E.g. https://duo-gateway.com/dag/saml2/idp/metadata.php
50
51 *option*: `sso_service_url` => `http://rc-app.com/dag/saml2/idp/SSOService.php?spentityid=http://rc.local.pl/_admin/auth/duosecurity/saml-metadata`
52 # SSO (SingleSignOn) endpoint URL of the IdP. This can be used to initialize login
53 # E.g. https://duo-gateway.com/dag/saml2/idp/SSOService.php?spentityid=<metadata_entity_id>
54
55 *option*: `slo_service_url` => `http://rc-app.com/dag/saml2/idp/SingleLogoutService.php?ReturnTo=http://rc-app.com/dag/module.php/duosecurity/logout.php`
56 # SLO (SingleLogout) endpoint URL of the IdP.
57 # E.g. https://duo-gateway.com/dag/saml2/idp/SingleLogoutService.php?ReturnTo=http://duo-gateway.com/_admin/saml/sign-out-endpoint
58
59 *option*: `x509cert` => `<CERTIFICATE_STRING>`
60 # Identity provider public x509 certificate. It will be converted to single-line format without headers
61
62 *option*: `name_id_format` => `sha-1`
63 # The format that specifies how the NameID is sent to the service provider.
64
65 *option*: `signature_algo` => `sha-256`
66 # Type of Algorithm to use for verification of SAML signature on Identity provider side
67
68 *option*: `digest_algo` => `sha-256`
69 # Type of Algorithm to use for verification of SAML digest on Identity provider side
70
71 *option*: `cert_dir` => `/etc/saml/`
72 # Optional directory to store service provider certificate and private keys.
73 # Expected certs for the SP should be stored in this folder as:
74 # * sp.key Private Key
75 # * sp.crt Public cert
76 # * sp_new.crt Future Public cert
77 #
78 # Also you can use other cert to sign the metadata of the SP using the:
79 # * metadata.key
80 # * metadata.crt
81
82 *option*: `user_id_attribute` => `PersonImmutableID`
83 # User ID Attribute name. This defines which attribute in SAML response will be used to link accounts via unique id.
84 # Ensure this is returned from DuoSecurity for example via duo_username
85
86 *option*: `username_attribute` => `User.username`
87 # Username Attribute name. This defines which attribute in SAML response will map to an username.
88
89 *option*: `email_attribute` => `User.email`
90 # Email Attribute name. This defines which attribute in SAML response will map to an email address.
91
92
93 Below is example setup from DUO Administration page that can be used with above config.
94
95 .. image:: ../images/saml-duosecurity-service-provider-example.png
96 :alt: DUO Security SAML setup example
97 :scale: 50 %
98
99
100 Below is an example attribute mapping set for IDP provider required by the above config.
101
102
103 .. image:: ../images/saml-duosecurity-attributes-example.png
104 :alt: DUO Security SAML setup example
105 :scale: 50 % No newline at end of file
@@ -0,0 +1,18
1 .. _config-saml-generic-ref:
2
3
4 SAML 2.0 Authentication
5 -----------------------
6
7
8 **This plugin is available only in EE Edition.**
9
10 RhodeCode Supports standard SAML 2.0 SSO for the web-application part.
11
12 Please check for reference two example providers:
13
14 .. toctree::
15
16 auth-saml-duosecurity
17 auth-saml-onelogin
18
@@ -0,0 +1,106
1 .. _config-saml-onelogin-ref:
2
3
4 SAML 2.0 with One Login
5 -----------------------
6
7 **This plugin is available only in EE Edition.**
8
9 |RCE| supports SAML 2.0 Authentication with OneLogin provider. This allows
10 users to log-in to RhodeCode via SSO mechanism of external identity provider
11 such as OneLogin. The login can be triggered either by the external IDP, or internally
12 by clicking specific authentication button on the log-in page.
13
14
15 Configuration steps
16 ^^^^^^^^^^^^^^^^^^^
17
18 To configure OneLogin SAML authentication, use the following steps:
19
20 1. From the |RCE| interface, select
21 :menuselection:`Admin --> Authentication`
22 2. Activate the `OneLogin` plugin and select :guilabel:`Save`
23 3. Go to newly available menu option called `OneLogin` on the left side.
24 4. Check the `enabled` check box in the plugin configuration section,
25 and fill in the required SAML information and :guilabel:`Save`, for more details,
26 see :ref:`config-saml-onelogin`
27
28
29 .. _config-saml-onelogin:
30
31
32 Example SAML OneLogin configuration
33 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
34
35 Example configuration for SAML 2.0 with OneLogin provider::
36
37 *option*: `enabled` => `True`
38 # Enable or disable this authentication plugin.
39
40 *option*: `cache_ttl` => `0`
41 # Amount of seconds to cache the authentication and permissions check response call for this plugin.
42 # Useful for expensive calls like LDAP to improve the performance of the system (0 means disabled).
43
44 *option*: `debug` => `True`
45 # Enable or disable debug mode that shows SAML errors in the RhodeCode logs.
46
47 *option*: `entity_id` => `https://app.onelogin.com/saml/metadata/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
48 # Identity Provider entity/metadata URI.
49 # E.g. https://app.onelogin.com/saml/metadata/<onelogin_connector_id>
50
51 *option*: `sso_service_url` => `https://customer-domain.onelogin.com/trust/saml2/http-post/sso/xxxxxx`
52 # SSO (SingleSignOn) endpoint URL of the IdP. This can be used to initialize login
53 # E.g. https://app.onelogin.com/trust/saml2/http-post/sso/<onelogin_connector_id>
54
55 *option*: `slo_service_url` => `https://customer-domain.onelogin.com/trust/saml2/http-redirect/slo/xxxxxx`
56 # SLO (SingleLogout) endpoint URL of the IdP.
57 # E.g. https://app.onelogin.com/trust/saml2/http-redirect/slo/<onelogin_connector_id>
58
59 *option*: `x509cert` => `<CERTIFICATE_STRING>`
60 # Identity provider public x509 certificate. It will be converted to single-line format without headers
61
62 *option*: `name_id_format` => `sha-1`
63 # The format that specifies how the NameID is sent to the service provider.
64
65 *option*: `signature_algo` => `sha-256`
66 # Type of Algorithm to use for verification of SAML signature on Identity provider side
67
68 *option*: `digest_algo` => `sha-256`
69 # Type of Algorithm to use for verification of SAML digest on Identity provider side
70
71 *option*: `cert_dir` => `/etc/saml/`
72 # Optional directory to store service provider certificate and private keys.
73 # Expected certs for the SP should be stored in this folder as:
74 # * sp.key Private Key
75 # * sp.crt Public cert
76 # * sp_new.crt Future Public cert
77 #
78 # Also you can use other cert to sign the metadata of the SP using the:
79 # * metadata.key
80 # * metadata.crt
81
82 *option*: `user_id_attribute` => `PersonImmutableID`
83 # User ID Attribute name. This defines which attribute in SAML response will be used to link accounts via unique id.
84 # Ensure this is returned from OneLogin for example via Internal ID
85
86 *option*: `username_attribute` => `User.username`
87 # Username Attribute name. This defines which attribute in SAML response will map to an username.
88
89 *option*: `email_attribute` => `User.email`
90 # Email Attribute name. This defines which attribute in SAML response will map to an email address.
91
92
93
94 Below is example setup that can be used with OneLogin SAML authentication that can be used with above config..
95
96 .. image:: ../images/saml-onelogin-config-example.png
97 :alt: OneLogin SAML setup example
98 :scale: 50 %
99
100
101 Below is an example attribute mapping set for IDP provider required by the above config.
102
103
104 .. image:: ../images/saml-onelogin-attributes-example.png
105 :alt: OneLogin SAML setup example
106 :scale: 50 % No newline at end of file
1 NO CONTENT: new file 100644, binary diff hidden
NO CONTENT: new file 100644, binary diff hidden
1 NO CONTENT: new file 100644, binary diff hidden
NO CONTENT: new file 100644, binary diff hidden
1 NO CONTENT: new file 100644, binary diff hidden
NO CONTENT: new file 100644, binary diff hidden
1 NO CONTENT: new file 100644, binary diff hidden
NO CONTENT: new file 100644, binary diff hidden
@@ -3,19 +3,19
3 Anonymous Users
3 Anonymous Users
4 ---------------
4 ---------------
5
5
6 By default, |RCM| provides |repo| access for registered users only. It can be
6 By default, |RCE| provides |repo| access for registered users only. It can be
7 configured to be **world-open** in terms of read and write permissions. This
7 configured to be **world-open** in terms of read and write permissions. This
8 configuration is called "Anonymous Access" and allows |RCM| to be used as a
8 configuration is called "Anonymous Access" and allows |RCE| to be used as a
9 public hub where unregistered users have access to your |repos|.
9 public hub where unregistered users have access to your |repos|.
10
10
11 Anonymous access is useful for open source projects, universities,
11 Anonymous access is useful for open source projects, universities,
12 or if running inside a restricted internal corporate network to serve
12 or if running inside a restricted internal corporate network to serve
13 documents to all employees. Anonymous users get the default user permission
13 documents to all employees. Anonymous users get the default user permission
14 settings that are applied across the whole |RCM| system.
14 settings that are applied across the whole |RCE| system.
15
15
16 To enable anonymous access to your |repos|, use the following steps:
16 To enable anonymous access to your |repos|, use the following steps:
17
17
18 1. From the |RCM| interface, select :menuselection:`Admin --> Permissions`.
18 1. From the |RCE| interface, select :menuselection:`Admin --> Permissions`.
19 2. On the Application tab, check the :guilabel:`Allow anonymous access` box.
19 2. On the Application tab, check the :guilabel:`Allow anonymous access` box.
20 3. Select :guilabel:`Save`.
20 3. Select :guilabel:`Save`.
21 4. To set the anonymous user access permissions, which are based on the
21 4. To set the anonymous user access permissions, which are based on the
@@ -166,7 +166,7 2. Add your custom hook details, you can
166 ``pretxnchangegroup.example`` with value ``python:/path/to/custom_hook.py:my_func_name``
166 ``pretxnchangegroup.example`` with value ``python:/path/to/custom_hook.py:my_func_name``
167 3. Select :guilabel:`Save`
167 3. Select :guilabel:`Save`
168
168
169 Also, see the |RC| Extensions section of the :ref:`rc-tools` guide. |RC|
169 Also, see the RhodeCode Extensions section of the :ref:`rc-tools` guide. RhodeCode
170 Extensions can be used to add additional hooks to your instance and comes
170 Extensions can be used to add additional hooks to your instance and comes
171 with a number of pre-built plugins if you chose to install them.
171 with a number of pre-built plugins if you chose to install them.
172
172
@@ -3,7 +3,7
3 Apache WSGI Configuration
3 Apache WSGI Configuration
4 ^^^^^^^^^^^^^^^^^^^^^^^^^
4 ^^^^^^^^^^^^^^^^^^^^^^^^^
5
5
6 |RCM| can also be set up with Apache under ``mod_wsgi``. To configure this
6 |RCE| can also be set up with Apache under ``mod_wsgi``. To configure this
7 use the following steps.
7 use the following steps.
8
8
9 1. Install ``mod_wsgi`` using the following command:
9 1. Install ``mod_wsgi`` using the following command:
@@ -50,6 +50,6 The following is an example ``wsgi`` dis
50 .. note::
50 .. note::
51
51
52 When using `mod_wsgi` the same version of |hg| must be running in your
52 When using `mod_wsgi` the same version of |hg| must be running in your
53 system's |PY| environment and on |RCM|. To check the |RCM| version,
53 system's |PY| environment and on |RCE|. To check the |RCE| version,
54 on the interface go to
54 on the interface go to
55 :menuselection:`Admin --> Settings --> System Info`
55 :menuselection:`Admin --> Settings --> System Info`
@@ -67,7 +67,7 sections.
67 Default location: :file:`/home/{user}/.rccontrol/cache/MANIFEST`
67 Default location: :file:`/home/{user}/.rccontrol/cache/MANIFEST`
68
68
69 |RCC| uses this file to source the latest available builds from the
69 |RCC| uses this file to source the latest available builds from the
70 secure |RC| download channels. The only reason to mess with this file
70 secure RhodeCode download channels. The only reason to mess with this file
71 is if you need to do an offline installation,
71 is if you need to do an offline installation,
72 see the :ref:`Offline Installation<control:offline-installer-ref>`
72 see the :ref:`Offline Installation<control:offline-installer-ref>`
73 instructions, otherwise |RCC| will completely manage this file.
73 instructions, otherwise |RCC| will completely manage this file.
@@ -33,7 +33,7 Glossary
33 Adding more machines or workers into your pool of resources.
33 Adding more machines or workers into your pool of resources.
34
34
35 Instance
35 Instance
36 A single installed version of one of the |RC| products. It could
36 A single installed version of one of the RhodeCode products. It could
37 refer to |RCE| or the VCS server depending on the context.
37 refer to |RCE| or the VCS server depending on the context.
38
38
39 Plugin
39 Plugin
@@ -3,7 +3,7
3 Full-text Search
3 Full-text Search
4 ----------------
4 ----------------
5
5
6 By default |RC| is configured to use `Whoosh`_ to index |repos| and
6 By default RhodeCode is configured to use `Whoosh`_ to index |repos| and
7 provide full-text search.
7 provide full-text search.
8
8
9 |RCE| also provides support for `Elasticsearch`_ as a backend for scalable
9 |RCE| also provides support for `Elasticsearch`_ as a backend for scalable
@@ -46,7 +46,7 Configure the ``.rhoderc`` File
46 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
46 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
47
47
48 |RCT| uses the :file:`/home/{user}/.rhoderc` file for connection details
48 |RCT| uses the :file:`/home/{user}/.rhoderc` file for connection details
49 to |RCM| instances. If this file is not automatically created,
49 to |RCE| instances. If this file is not automatically created,
50 you can configure it using the following example. You need to configure the
50 you can configure it using the following example. You need to configure the
51 details for each instance you want to index.
51 details for each instance you want to index.
52
52
@@ -62,7 +62,7 details for each instance you want to in
62 - VERSION: 1.5.0
62 - VERSION: 1.5.0
63 - URL: http://127.0.0.1:10000
63 - URL: http://127.0.0.1:10000
64
64
65 To get your API Token, on the |RCM| interface go to
65 To get your API Token, on the |RCE| interface go to
66 :menuselection:`username --> My Account --> Auth tokens`
66 :menuselection:`username --> My Account --> Auth tokens`
67
67
68 .. code-block:: ini
68 .. code-block:: ini
@@ -3,7 +3,7
3 Public Access
3 Public Access
4 -------------
4 -------------
5
5
6 By default |RCM| allows users to read all **public** |repos|. User
6 By default |RCE| allows users to read all **public** |repos|. User
7 permissions and |repo| access can be configured explicitly,
7 permissions and |repo| access can be configured explicitly,
8 and those permissions will override any default settings. The default
8 and those permissions will override any default settings. The default
9 settings can be found under the following section:
9 settings can be found under the following section:
@@ -3,7 +3,7
3 Setting Default Permissions
3 Setting Default Permissions
4 ---------------------------
4 ---------------------------
5
5
6 Default permissions allow you to configure |RCM| so that when a new |repo|, user group,
6 Default permissions allow you to configure |RCE| so that when a new |repo|, user group,
7 or user is created their permissions are already defined. To set default permissions you need administrator
7 or user is created their permissions are already defined. To set default permissions you need administrator
8 privileges. See the following sections for setting up your permissions system:
8 privileges. See the following sections for setting up your permissions system:
9
9
@@ -19,7 +19,7 Setting User defaults
19
19
20 To set default user permissions, use the following steps.
20 To set default user permissions, use the following steps.
21
21
22 1. From the |RCM| interface, select :menuselection:`Admin --> Permissions`
22 1. From the |RCE| interface, select :menuselection:`Admin --> Permissions`
23 2. Select the :guilabel:`Global` tab from the left-hand menu. The permissions
23 2. Select the :guilabel:`Global` tab from the left-hand menu. The permissions
24 set on this screen apply to users and user-groups across the whole instance.
24 set on this screen apply to users and user-groups across the whole instance.
25 3. Save your changes
25 3. Save your changes
@@ -31,7 +31,7 Setting User Group defaults
31
31
32 To set default user group permissions, use the following steps.
32 To set default user group permissions, use the following steps.
33
33
34 1. From the |RCM| interface, select :menuselection:`Admin --> User groups`
34 1. From the |RCE| interface, select :menuselection:`Admin --> User groups`
35 2. Select :guilabel:`Permissions`, and configure the default user
35 2. Select :guilabel:`Permissions`, and configure the default user
36 permissions. All users will get these permissions unless
36 permissions. All users will get these permissions unless
37 individually set.
37 individually set.
@@ -48,7 +48,7 Setting Repository defaults
48
48
49 To set default |repo| permissions, use the following steps.
49 To set default |repo| permissions, use the following steps.
50
50
51 1. From the |RCM| interface, select :menuselection:`Admin --> Permissions`
51 1. From the |RCE| interface, select :menuselection:`Admin --> Permissions`
52 2. Select the :guilabel:`Object` tab from the left-hand menu and set the
52 2. Select the :guilabel:`Object` tab from the left-hand menu and set the
53 |perm| permissions
53 |perm| permissions
54 3. Save your changes
54 3. Save your changes
@@ -60,7 +60,7 Setting Repository Group defaults
60
60
61 To set default Repository Group permissions, use the following steps.
61 To set default Repository Group permissions, use the following steps.
62
62
63 1. From the |RCM| interface, select :menuselection:`Admin --> Repository Groups`
63 1. From the |RCE| interface, select :menuselection:`Admin --> Repository Groups`
64 2. Select :guilabel:`Edit` beside the |repo| group you wish to configure
64 2. Select :guilabel:`Edit` beside the |repo| group you wish to configure
65 3. On the left-hand pane select :guilabel:`Permissions`
65 3. On the left-hand pane select :guilabel:`Permissions`
66 4. Set the default permissions for all |repos| created in this group
66 4. Set the default permissions for all |repos| created in this group
@@ -3,12 +3,12
3 Repository Administration
3 Repository Administration
4 =========================
4 =========================
5
5
6 Repository permissions in |RCM| can be managed in a number of different ways.
6 Repository permissions in |RCE| can be managed in a number of different ways.
7 This overview should give you an insight into how you could adopt particular
7 This overview should give you an insight into how you could adopt particular
8 settings for your needs:
8 settings for your needs:
9
9
10 * Global |repo| permissions: This allows you to set the default permissions
10 * Global |repo| permissions: This allows you to set the default permissions
11 for each new |repo| created within |RCM|, see :ref:`repo-default-ref`. All
11 for each new |repo| created within |RCE|, see :ref:`repo-default-ref`. All
12 |repos| created will inherit these permissions unless explicitly configured.
12 |repos| created will inherit these permissions unless explicitly configured.
13 * Individual |repo| permissions: To set individual |repo| permissions,
13 * Individual |repo| permissions: To set individual |repo| permissions,
14 see :ref:`set-repo-perms`.
14 see :ref:`set-repo-perms`.
@@ -59,7 +59,7 Supported Browsers
59 System Requirements
59 System Requirements
60 -------------------
60 -------------------
61
61
62 |RCM| performs best on machines with ultra-fast hard disks. Generally disk
62 |RCE| performs best on machines with ultra-fast hard disks. Generally disk
63 performance is more important than CPU performance. In a corporate production
63 performance is more important than CPU performance. In a corporate production
64 environment handling 1000s of users and |repos| you should deploy on a 12+
64 environment handling 1000s of users and |repos| you should deploy on a 12+
65 core 64GB RAM server. In short, the more RAM the better.
65 core 64GB RAM server. In short, the more RAM the better.
@@ -68,7 +68,7 core 64GB RAM server. In short, the more
68 For example:
68 For example:
69
69
70 - for team of 1 - 5 active users you can run on 1GB RAM machine with 1CPU
70 - for team of 1 - 5 active users you can run on 1GB RAM machine with 1CPU
71 - above 250 active users, |RCM| needs at least 8GB of memory.
71 - above 250 active users, |RCE| needs at least 8GB of memory.
72 Number of CPUs is less important, but recommended to have at least 2-3 CPUs
72 Number of CPUs is less important, but recommended to have at least 2-3 CPUs
73
73
74
74
@@ -114,7 +114,7 Connection Methods
114
114
115 * HTTPS
115 * HTTPS
116 * SSH
116 * SSH
117 * |RCM| API
117 * |RCE| API
118
118
119 Internationalization Support
119 Internationalization Support
120 ----------------------------
120 ----------------------------
@@ -3,7 +3,7
3 User Administration
3 User Administration
4 ===================
4 ===================
5
5
6 |RCM| enables you to define permissions for the following entities within the
6 |RCE| enables you to define permissions for the following entities within the
7 system; **users**, **user groups**, **repositories**, **repository groups**.
7 system; **users**, **user groups**, **repositories**, **repository groups**.
8
8
9 Within each one of these entities you can set default settings,
9 Within each one of these entities you can set default settings,
@@ -3,13 +3,13
3 VCS Server Management
3 VCS Server Management
4 ---------------------
4 ---------------------
5
5
6 The VCS Server handles |RCM| backend functionality. You need to configure
6 The VCS Server handles |RCE| backend functionality. You need to configure
7 a VCS Server to run with a |RCM| instance. If you do not, you will be missing
7 a VCS Server to run with a |RCE| instance. If you do not, you will be missing
8 the connection between |RCM| and its |repos|. This will cause error messages
8 the connection between |RCE| and its |repos|. This will cause error messages
9 on the web interface. You can run your setup in the following configurations,
9 on the web interface. You can run your setup in the following configurations,
10 currently the best performance is one of following:
10 currently the best performance is one of following:
11
11
12 * One VCS Server per |RCM| instance.
12 * One VCS Server per |RCE| instance.
13 * One VCS Server handling multiple instances.
13 * One VCS Server handling multiple instances.
14
14
15 .. important::
15 .. important::
@@ -49,7 +49,7 To configure a |RCE| instance to use a V
49 |RCE| VCS Server Options
49 |RCE| VCS Server Options
50 ^^^^^^^^^^^^^^^^^^^^^^^^
50 ^^^^^^^^^^^^^^^^^^^^^^^^
51
51
52 The following list shows the available options on the |RCM| side of the
52 The following list shows the available options on the |RCE| side of the
53 connection to the VCS Server. The settings are configured per
53 connection to the VCS Server. The settings are configured per
54 instance in the
54 instance in the
55 :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini` file.
55 :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini` file.
@@ -75,7 +75,7 instance in the
75
75
76 \vcs.server <host:port>
76 \vcs.server <host:port>
77 Set the host, either hostname or IP Address, and port of the VCS server
77 Set the host, either hostname or IP Address, and port of the VCS server
78 you wish to run with your |RCM| instance.
78 you wish to run with your |RCE| instance.
79
79
80 .. code-block:: ini
80 .. code-block:: ini
81
81
@@ -22,12 +22,12 API access can also be turned on for eac
22 decorated with a `@LoginRequired` decorator. To enable API access, change
22 decorated with a `@LoginRequired` decorator. To enable API access, change
23 the standard login decorator to `@LoginRequired(api_access=True)`.
23 the standard login decorator to `@LoginRequired(api_access=True)`.
24
24
25 From |RCM| version 1.7.0 you can configure a white list
25 From |RCE| version 1.7.0 you can configure a white list
26 of views that have API access enabled by default. To enable these,
26 of views that have API access enabled by default. To enable these,
27 edit the |RCM| configuration ``.ini`` file. The default location is:
27 edit the |RCE| configuration ``.ini`` file. The default location is:
28
28
29 * |RCM| Pre-2.2.7 :file:`root/rhodecode/data/production.ini`
29 * |RCE| Pre-2.2.7 :file:`root/rhodecode/data/production.ini`
30 * |RCM| 3.0 :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
30 * |RCE| 3.0 :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini`
31
31
32 To configure the white list, edit this section of the file. In this
32 To configure the white list, edit this section of the file. In this
33 configuration example, API access is granted to the patch/diff raw file and
33 configuration example, API access is granted to the patch/diff raw file and
@@ -5,8 +5,8 Crowd
5
5
6 To enable Crowd authentication, use the following steps:
6 To enable Crowd authentication, use the following steps:
7
7
8 1. From the |RCM| interface, go to :menuselection:`Admin --> Authentication`
8 1. From the |RCE| interface, go to :menuselection:`Admin --> Authentication`
9 2. Enable the ``rhodecode.lib.auth_modules.auth_crowd`` library and select
9 2. Activate the ``rhodecode.lib.auth_modules.auth_crowd`` library and select
10 :guilabel:`Save`
10 :guilabel:`Save`
11 3. On the Crowd plugin settings section, do the following:
11 3. On the Crowd plugin settings section, do the following:
12
12
@@ -3,25 +3,24
3 LDAP/AD With User Groups Sync
3 LDAP/AD With User Groups Sync
4 -----------------------------
4 -----------------------------
5
5
6 |RCM| supports LDAP (Lightweight Directory Access Protocol) or
6 **This plugin is available only in EE Edition.**
7
8 |RCE| supports LDAP (Lightweight Directory Access Protocol) or
7 AD (active Directory) authentication.
9 AD (active Directory) authentication.
8 All LDAP versions are supported, with the following |RCM| plugins managing each:
10 All LDAP versions are currently supported.
9
10 * For LDAP/AD with user group sync use ``LDAP + User Groups (egg:rhodecode-enterprise-ee#ldap_group)``
11
11
12 RhodeCode reads all data defined from plugin and creates corresponding
12 RhodeCode reads all data defined from plugin and creates corresponding
13 accounts on local database after receiving data from LDAP. This is done on
13 accounts on local database after receiving data from LDAP. This is done on
14 every user log-in including operations like pushing/pulling/checkout.
14 every user log-in including operations like pushing/pulling/checkout.
15 In addition group membership is read from LDAP and following operations are done:
15 In addition group membership is read from LDAP and following operations are done:
16
16
17 - automatic addition of user to |RCM| user group
17 - automatic addition of user to |RCE| user group
18 - automatic removal of user from any other |RCM| user groups not specified in LDAP.
18 - automatic removal of user from any other |RCE| user groups not specified in LDAP.
19 The removal is done *only* on groups that are marked to be synced from ldap.
19 The removal is done *only* on groups that are marked to be synced from ldap.
20 This setting can be changed in advanced settings on user groups
20 This setting can be changed in advanced settings on user groups
21 - automatic creation of user groups if they aren't yet existing in |RCM|
21 - automatic creation of user groups if they aren't yet existing in |RCE|
22 - marking user as super-admins if he is a member of any admin group defined in plugin settings
22 - marking user as super-admins if he is a member of any admin group defined in plugin settings
23
23
24 This plugin is available only in EE Edition.
25
24
26 .. important::
25 .. important::
27
26
@@ -39,11 +38,12 LDAP Configuration Steps
39
38
40 To configure |LDAP|, use the following steps:
39 To configure |LDAP|, use the following steps:
41
40
42 1. From the |RCM| interface, select
41 1. From the |RCE| interface, select
43 :menuselection:`Admin --> Authentication`
42 :menuselection:`Admin --> Authentication`
44 2. Enable the ldap+ groups plugin and select :guilabel:`Save`
43 2. Activate the `LDAP + User Groups` plugin and select :guilabel:`Save`
45 3. Select the :guilabel:`Enabled` check box in the plugin configuration section
44 3. Go to newly available menu option called `LDAP + User Groups` on the left side.
46 4. Add the required LDAP information and :guilabel:`Save`, for more details,
45 4. Check the `enabled` check box in the plugin configuration section,
46 and fill in the required LDAP information and :guilabel:`Save`, for more details,
47 see :ref:`config-ldap-groups-examples`
47 see :ref:`config-ldap-groups-examples`
48
48
49 For a more detailed description of LDAP objects, see :ref:`ldap-gloss-ref`:
49 For a more detailed description of LDAP objects, see :ref:`ldap-gloss-ref`:
@@ -52,59 +52,107 For a more detailed description of LDAP
52
52
53 Example LDAP configuration
53 Example LDAP configuration
54 ^^^^^^^^^^^^^^^^^^^^^^^^^^
54 ^^^^^^^^^^^^^^^^^^^^^^^^^^
55 .. code-block:: bash
55
56 Below is example setup that can be used with Active Directory and LDAP server with groups sync::
57
58 *option*: `enabled` => `True`
59 # Enable or disable this authentication plugin.
60
61 *option*: `cache_ttl` => `360`
62 # Amount of seconds to cache the authentication and permissions check response call for this plugin.
63 # Useful for expensive calls like LDAP to improve the performance of the system (0 means disabled).
64
65 *option*: `host` => `192.168.245.143,192.168.1.240`
66 # Host[s] of the LDAP Server
67 # (e.g., 192.168.2.154, or ldap-server.domain.com.
68 # Multiple servers can be specified using commas
69
70 *option*: `port` => `389`
71 # Custom port that the LDAP server is listening on. Default value is: 389, use 689 for LDAPS(SSL)
72
73 *option*: `timeout` => `300`
74 # Timeout for LDAP connection
75
76 *option*: `dn_user` => `Administrator@rhodecode.com`
77 # Optional user DN/account to connect to LDAP if authentication is required.
78 # e.g., cn=admin,dc=mydomain,dc=com, or uid=root,cn=users,dc=mydomain,dc=com, or admin@mydomain.com
79
80 *option*: `dn_pass` => `SomeSecret`
81 # Password to authenticate for given user DN.
82
83 *option*: `tls_kind` => `PLAIN`
84 # TLS Type
85
86 *option*: `tls_reqcert` => `NEVER`
87 # Require Cert over TLS?. Self-signed and custom certificates can be used when
88 # `RhodeCode Certificate` found in admin > settings > system info page is extended.
89
90 *option*: `tls_cert_file` => ``
91 # This specifies the PEM-format file path containing certificates for use in TLS connection.
92 # If not specified `TLS Cert dir` will be used
93
94 *option*: `tls_cert_dir` => `/etc/openldap/cacerts`
95 # This specifies the path of a directory that contains individual CA certificates in separate files.
96
97 *option*: `base_dn` => `dc=rhodecode,dc=com`
98 # Base DN to search. Dynamic bind is supported. Add `$login` marker in it to be replaced with current user credentials
99 # (e.g., dc=mydomain,dc=com, or ou=Users,dc=mydomain,dc=com)
100
101 *option*: `user_search_base` => `ou=RC-Users`
102 # User search base will extend the Base DN
103 # (e.g., ou=Users will result in ou=Users,dc=mydomain,dc=com root DN)
56
104
57 # Auth Cache TTL, Defines the caching for authentication to offload LDAP server.
105 *option*: `user_search_filter` => ``
58 # This means that cache result will be saved for 3600 before contacting LDAP server to verify the user access
106 # Filter to narrow results
59 3600
107 # (e.g., (&(objectCategory=Person)(objectClass=user)), or
60 # Host, comma seperated format is optionally possible to specify more than 1 server
108 # (memberof=cn=rc-login,ou=groups,ou=company,dc=mydomain,dc=com)))
61 https://ldap1.server.com/ldap-admin/,https://ldap2.server.com/ldap-admin/
109
62 # Default LDAP Port, use 689 for LDAPS
110 *option*: `search_scope` => `SUBTREE`
63 389
111 # How deep to search LDAP. If unsure set to SUBTREE
64 # Account, used for SimpleBind if LDAP server requires an authentication
112
65 e.g admin@server.com
113 *option*: `attr_login` => `sAMAccountName`
66 # Password used for simple bind
114 # LDAP Attribute to map to user name (e.g., uid, or sAMAccountName)
67 ldap-user-password
115
68 # LDAP connection security
116 *option*: `attr_email` => `mail`
69 LDAPS
117 # LDAP Attribute to map to email address (e.g., mail).
70 # Certificate checks level
118 # Emails are a crucial part of RhodeCode.
71 DEMAND
119 # If possible add a valid email attribute to ldap users.
72 # Base DN
120
73 cn=Rufus Magillacuddy,ou=users,dc=rhodecode,dc=com
121 *option*: `attr_firstname` => `givenName`
74 # User Search Base
122 # LDAP Attribute to map to first name (e.g., givenName)
75 ou=groups,ou=users
123
76 # LDAP search filter to narrow the results
124 *option*: `attr_lastname` => `sn`
77 (objectClass=person)
125 # LDAP Attribute to map to last name (e.g., sn)
78 # LDAP search scope
126
79 SUBTREE
127 *option*: `group_extraction_type` => `rfc2307bis`
80 # Login attribute
128 # With rfc2307, group members are listed by name in the memberUid attribute
81 sAMAccountName
129 # With rfc2307bis (Microsoft AD compatible) group members are listed by DN and stored in the member attribute
82 # First Name Attribute to read
83 givenName
84 # Last Name Attribute to read
85 sn
86 # Email Attribute to read email address from
87 mail
88 # group extraction method
89 rfc2307bis
90 # Group search base
91 ou=RC-Groups
92 # Group Name Attribute, field to read the group name from
93 sAMAAccountName
94 # User Member of Attribute, field in which groups are stored
95 memberOf
96 # LDAP Group Search Filter, allows narrowing the results
97
130
98 # Admin Groups. Comma separated list of groups. If user is member of
131 *option*: `group_search_base` => `ou=RC-Groups`
99 # any of those he will be marked as super-admin in RhodeCode
132 # Group search base will extend the Base DN (e.g. ou=Groups will result in ou=Groups,dc=mydomain,dc=com)
100 admins, management
101
133
134 *option*: `group_name_attr` => `sAMAccountName`
135 # LDAP Attribute to map to group name (e.g., cn, or sAMAccountName)
136
137 *option*: `user_member_of` => `memberOf`
138 # Users Attribute used to fetch the group membership.
139 # Use if users have stored group membership inside their attributes
140 # (e.g., memberOf, or userMemberOf)
102
141
103 Below is example setup that can be used with Active Directory and ldap groups.
142 *option*: `group_search_filter` => ``
143 # Filter to narrow results (e.g., (&(objectCategory=Group)(objectClass=group)), etc)
144
145 *option*: `group_member_of` => `memberOf`
146 # LDAP Attribute used to resolve the parent group (e.g., memberOf)
104
147
105 .. image:: ../images/ldap-groups-example.png
148 *option*: `admin_groups` => `Admins,Management`
106 :alt: LDAP/AD setup example
149 # A comma separated list of group names that identify users as RhodeCode Administrators (e.g., admins)
107 :scale: 50 %
150
151 *option*: `admin_groups_sync` => `full`
152 # Way to sync Admin groups.
153 # Full means admin flag is set to on or off according to membership in administrator group defined above.
154 # On-only means the flag is only set to on, and not turned off once user is no longer a member
155
108
156
109 .. toctree::
157 .. toctree::
110
158
@@ -3,11 +3,9
3 LDAP/AD
3 LDAP/AD
4 -------
4 -------
5
5
6 |RCM| supports LDAP (Lightweight Directory Access Protocol) or
6 |RCE| supports LDAP (Lightweight Directory Access Protocol) or
7 AD (active Directory) authentication.
7 AD (active Directory) authentication.
8 All LDAP versions are supported, with the following |RCM| plugins managing each:
8 All LDAP versions are currently supported.
9
10 * For LDAP or Active Directory use ``LDAP (egg:rhodecode-enterprise-ce#ldap)``
11
9
12 RhodeCode reads all data defined from plugin and creates corresponding
10 RhodeCode reads all data defined from plugin and creates corresponding
13 accounts on local database after receiving data from LDAP. This is done on
11 accounts on local database after receiving data from LDAP. This is done on
@@ -30,11 +28,12 LDAP Configuration Steps
30
28
31 To configure |LDAP|, use the following steps:
29 To configure |LDAP|, use the following steps:
32
30
33 1. From the |RCM| interface, select
31 1. From the |RCE| interface, select
34 :menuselection:`Admin --> Authentication`
32 :menuselection:`Admin --> Authentication`
35 2. Enable the ldap plugin and select :guilabel:`Save`
33 2. Activate the `LDAP` plugin and select :guilabel:`Save`
36 3. Select the :guilabel:`Enabled` check box in the plugin configuration section
34 3. Go to newly available menu option called `LDAP` on the left side.
37 4. Add the required LDAP information and :guilabel:`Save`, for more details,
35 4. Check the `enabled` check box in the plugin configuration section,
36 and fill in the required LDAP information and :guilabel:`Save`, for more details,
38 see :ref:`config-ldap-examples`
37 see :ref:`config-ldap-examples`
39
38
40 For a more detailed description of LDAP objects, see :ref:`ldap-gloss-ref`:
39 For a more detailed description of LDAP objects, see :ref:`ldap-gloss-ref`:
@@ -43,44 +42,73 For a more detailed description of LDAP
43
42
44 Example LDAP configuration
43 Example LDAP configuration
45 ^^^^^^^^^^^^^^^^^^^^^^^^^^
44 ^^^^^^^^^^^^^^^^^^^^^^^^^^
46 .. code-block:: bash
45
46 Below is example setup that can be used with Active Directory/LDAP server::
47
48 *option*: `enabled` => `True`
49 # Enable or disable this authentication plugin.
50
51 *option*: `cache_ttl` => `360`
52 # Amount of seconds to cache the authentication and permissions check response call for this plugin.
53 # Useful for expensive calls like LDAP to improve the performance of the system (0 means disabled).
54
55 *option*: `host` => `192.168.245.143,192.168.1.240`
56 # Host[s] of the LDAP Server
57 # (e.g., 192.168.2.154, or ldap-server.domain.com.
58 # Multiple servers can be specified using commas
59
60 *option*: `port` => `389`
61 # Custom port that the LDAP server is listening on. Default value is: 389, use 689 for LDAPS(SSL)
62
63 *option*: `timeout` => `300`
64 # Timeout for LDAP connection
65
66 *option*: `dn_user` => `Administrator@rhodecode.com`
67 # Optional user DN/account to connect to LDAP if authentication is required.
68 # e.g., cn=admin,dc=mydomain,dc=com, or uid=root,cn=users,dc=mydomain,dc=com, or admin@mydomain.com
69
70 *option*: `dn_pass` => `SomeSecret`
71 # Password to authenticate for given user DN.
72
73 *option*: `tls_kind` => `PLAIN`
74 # TLS Type
47
75
48 # Auth Cache TTL, Defines the caching for authentication to offload LDAP server.
76 *option*: `tls_reqcert` => `NEVER`
49 # This means that cache result will be saved for 3600 before contacting LDAP server to verify the user access
77 # Require Cert over TLS?. Self-signed and custom certificates can be used when
50 3600
78 # `RhodeCode Certificate` found in admin > settings > system info page is extended.
51 # Host, comma seperated format is optionally possible to specify more than 1 server
79
52 https://ldap1.server.com/ldap-admin/,https://ldap2.server.com/ldap-admin/
80 *option*: `tls_cert_file` => ``
53 # Default LDAP Port, use 689 for LDAPS
81 # This specifies the PEM-format file path containing certificates for use in TLS connection.
54 389
82 # If not specified `TLS Cert dir` will be used
55 # Account, used for SimpleBind if LDAP server requires an authentication
83
56 e.g admin@server.com
84 *option*: `tls_cert_dir` => `/etc/openldap/cacerts`
57 # Password used for simple bind
85 # This specifies the path of a directory that contains individual CA certificates in separate files.
58 ldap-user-password
86
59 # LDAP connection security
87 *option*: `base_dn` => `cn=Rufus Magillacuddy,ou=users,dc=rhodecode,dc=com`
60 LDAPS
88 # Base DN to search. Dynamic bind is supported. Add `$login` marker in it to be replaced with current user credentials
61 # Certificate checks level
89 # (e.g., dc=mydomain,dc=com, or ou=Users,dc=mydomain,dc=com)