engineering/unrhodecode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: added SAML documentation.

Browse source 
- Remove few obsolete replaces
- update authentication docs
- cleanups and fixes
This commit is contained in:
Marcin Kuzminski 2018-11-30 07:37:45 +01:00
parent 909181f429
commit cbff54d3ed
72 changed files with 657 additions and 298 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/auth/auth-crowd.rst
View file

@ -5,8 +5,8 @@ Crowd
To enable Crowd authentication, use the following steps:
1. From the |RCM| interface, go to :menuselection:`Admin --> Authentication`
2. Enable the ``rhodecode.lib.auth_modules.auth_crowd`` library and select
1. From the |RCE| interface, go to :menuselection:`Admin --> Authentication`
2. Activate the ``rhodecode.lib.auth_modules.auth_crowd`` library and select
:guilabel:`Save`
3. On the Crowd plugin settings section, do the following:

168
docs/auth/auth-ldap-groups.rst
View file

@ -3,25 +3,24 @@
LDAP/AD With User Groups Sync
-----------------------------
|RCM| supports LDAP (Lightweight Directory Access Protocol) or
AD (active Directory) authentication.
All LDAP versions are supported, with the following |RCM| plugins managing each:
**This plugin is available only in EE Edition.**
* For LDAP/AD with user group sync use ``LDAP + User Groups (egg:rhodecode-enterprise-ee#ldap_group)``
|RCE| supports LDAP (Lightweight Directory Access Protocol) or
AD (active Directory) authentication.
All LDAP versions are currently supported.
RhodeCode reads all data defined from plugin and creates corresponding
accounts on local database after receiving data from LDAP. This is done on
every user log-in including operations like pushing/pulling/checkout.
In addition group membership is read from LDAP and following operations are done:
- automatic addition of user to |RCM| user group
- automatic removal of user from any other |RCM| user groups not specified in LDAP.
- automatic addition of user to |RCE| user group
- automatic removal of user from any other |RCE| user groups not specified in LDAP.
The removal is done *only* on groups that are marked to be synced from ldap.
This setting can be changed in advanced settings on user groups
- automatic creation of user groups if they aren't yet existing in |RCM|
- automatic creation of user groups if they aren't yet existing in |RCE|
- marking user as super-admins if he is a member of any admin group defined in plugin settings
This plugin is available only in EE Edition.
.. important::
@ -39,11 +38,12 @@ LDAP Configuration Steps
To configure |LDAP|, use the following steps:
1. From the |RCM| interface, select
1. From the |RCE| interface, select
:menuselection:`Admin --> Authentication`
2. Enable the ldap+ groups plugin and select :guilabel:`Save`
3. Select the :guilabel:`Enabled` check box in the plugin configuration section
4. Add the required LDAP information and :guilabel:`Save`, for more details,
2. Activate the `LDAP + User Groups` plugin and select :guilabel:`Save`
3. Go to newly available menu option called `LDAP + User Groups` on the left side.
4. Check the `enabled` check box in the plugin configuration section,
and fill in the required LDAP information and :guilabel:`Save`, for more details,
see :ref:`config-ldap-groups-examples`
For a more detailed description of LDAP objects, see :ref:`ldap-gloss-ref`:
@ -52,59 +52,107 @@ For a more detailed description of LDAP objects, see :ref:`ldap-gloss-ref`:
Example LDAP configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
# Auth Cache TTL, Defines the caching for authentication to offload LDAP server.
# This means that cache result will be saved for 3600 before contacting LDAP server to verify the user access
3600
# Host, comma seperated format is optionally possible to specify more than 1 server
https://ldap1.server.com/ldap-admin/,https://ldap2.server.com/ldap-admin/
# Default LDAP Port, use 689 for LDAPS
389
# Account, used for SimpleBind if LDAP server requires an authentication
e.g admin@server.com
# Password used for simple bind
ldap-user-password
# LDAP connection security
LDAPS
# Certificate checks level
DEMAND
# Base DN
cn=Rufus Magillacuddy,ou=users,dc=rhodecode,dc=com
# User Search Base
ou=groups,ou=users
# LDAP search filter to narrow the results
(objectClass=person)
# LDAP search scope
SUBTREE
# Login attribute
sAMAccountName
# First Name Attribute to read
givenName
# Last Name Attribute to read
sn
# Email Attribute to read email address from
mail
# group extraction method
rfc2307bis
# Group search base
ou=RC-Groups
# Group Name Attribute, field to read the group name from
sAMAAccountName
# User Member of Attribute, field in which groups are stored
memberOf
# LDAP Group Search Filter, allows narrowing the results
Below is example setup that can be used with Active Directory and LDAP server with groups sync::
# Admin Groups. Comma separated list of groups. If user is member of
# any of those he will be marked as super-admin in RhodeCode
admins, management
*option*: `enabled` => `True`
# Enable or disable this authentication plugin.
*option*: `cache_ttl` => `360`
# Amount of seconds to cache the authentication and permissions check response call for this plugin.
# Useful for expensive calls like LDAP to improve the performance of the system (0 means disabled).
Below is example setup that can be used with Active Directory and ldap groups.
*option*: `host` => `192.168.245.143,192.168.1.240`
# Host[s] of the LDAP Server
# (e.g., 192.168.2.154, or ldap-server.domain.com.
# Multiple servers can be specified using commas
*option*: `port` => `389`
# Custom port that the LDAP server is listening on. Default value is: 389, use 689 for LDAPS(SSL)
*option*: `timeout` => `300`
# Timeout for LDAP connection
*option*: `dn_user` => `Administrator@rhodecode.com`
# Optional user DN/account to connect to LDAP if authentication is required.
# e.g., cn=admin,dc=mydomain,dc=com, or uid=root,cn=users,dc=mydomain,dc=com, or admin@mydomain.com
*option*: `dn_pass` => `SomeSecret`
# Password to authenticate for given user DN.
*option*: `tls_kind` => `PLAIN`
# TLS Type
*option*: `tls_reqcert` => `NEVER`
# Require Cert over TLS?. Self-signed and custom certificates can be used when
# `RhodeCode Certificate` found in admin > settings > system info page is extended.
*option*: `tls_cert_file` => ``
# This specifies the PEM-format file path containing certificates for use in TLS connection.
# If not specified `TLS Cert dir` will be used
*option*: `tls_cert_dir` => `/etc/openldap/cacerts`
# This specifies the path of a directory that contains individual CA certificates in separate files.
*option*: `base_dn` => `dc=rhodecode,dc=com`
# Base DN to search. Dynamic bind is supported. Add `$login` marker in it to be replaced with current user credentials
# (e.g., dc=mydomain,dc=com, or ou=Users,dc=mydomain,dc=com)
*option*: `user_search_base` => `ou=RC-Users`
# User search base will extend the Base DN
# (e.g., ou=Users will result in ou=Users,dc=mydomain,dc=com root DN)
*option*: `user_search_filter` => ``
# Filter to narrow results
# (e.g., (&(objectCategory=Person)(objectClass=user)), or
# (memberof=cn=rc-login,ou=groups,ou=company,dc=mydomain,dc=com)))
*option*: `search_scope` => `SUBTREE`
# How deep to search LDAP. If unsure set to SUBTREE
*option*: `attr_login` => `sAMAccountName`
# LDAP Attribute to map to user name (e.g., uid, or sAMAccountName)
*option*: `attr_email` => `mail`
# LDAP Attribute to map to email address (e.g., mail).
# Emails are a crucial part of RhodeCode.
# If possible add a valid email attribute to ldap users.
*option*: `attr_firstname` => `givenName`
# LDAP Attribute to map to first name (e.g., givenName)
*option*: `attr_lastname` => `sn`
# LDAP Attribute to map to last name (e.g., sn)
*option*: `group_extraction_type` => `rfc2307bis`
# With rfc2307, group members are listed by name in the memberUid attribute
# With rfc2307bis (Microsoft AD compatible) group members are listed by DN and stored in the member attribute
*option*: `group_search_base` => `ou=RC-Groups`
# Group search base will extend the Base DN (e.g. ou=Groups will result in ou=Groups,dc=mydomain,dc=com)
*option*: `group_name_attr` => `sAMAccountName`
# LDAP Attribute to map to group name (e.g., cn, or sAMAccountName)
*option*: `user_member_of` => `memberOf`
# Users Attribute used to fetch the group membership.
# Use if users have stored group membership inside their attributes
# (e.g., memberOf, or userMemberOf)
*option*: `group_search_filter` => ``
# Filter to narrow results (e.g., (&(objectCategory=Group)(objectClass=group)), etc)
*option*: `group_member_of` => `memberOf`
# LDAP Attribute used to resolve the parent group (e.g., memberOf)
*option*: `admin_groups` => `Admins,Management`
# A comma separated list of group names that identify users as RhodeCode Administrators (e.g., admins)
*option*: `admin_groups_sync` => `full`
# Way to sync Admin groups.
# Full means admin flag is set to on or off according to membership in administrator group defined above.
# On-only means the flag is only set to on, and not turned off once user is no longer a member
.. image:: ../images/ldap-groups-example.png
:alt: LDAP/AD setup example
:scale: 50 %
.. toctree::

112
docs/auth/auth-ldap.rst
View file

@ -3,11 +3,9 @@
LDAP/AD
-------
|RCM| supports LDAP (Lightweight Directory Access Protocol) or
|RCE| supports LDAP (Lightweight Directory Access Protocol) or
AD (active Directory) authentication.
All LDAP versions are supported, with the following |RCM| plugins managing each:
* For LDAP or Active Directory use ``LDAP (egg:rhodecode-enterprise-ce#ldap)``
All LDAP versions are currently supported.
RhodeCode reads all data defined from plugin and creates corresponding
accounts on local database after receiving data from LDAP. This is done on
@ -30,11 +28,12 @@ LDAP Configuration Steps
To configure |LDAP|, use the following steps:
1. From the |RCM| interface, select
1. From the |RCE| interface, select
:menuselection:`Admin --> Authentication`
2. Enable the ldap plugin and select :guilabel:`Save`
3. Select the :guilabel:`Enabled` check box in the plugin configuration section
4. Add the required LDAP information and :guilabel:`Save`, for more details,
2. Activate the `LDAP` plugin and select :guilabel:`Save`
3. Go to newly available menu option called `LDAP` on the left side.
4. Check the `enabled` check box in the plugin configuration section,
and fill in the required LDAP information and :guilabel:`Save`, for more details,
see :ref:`config-ldap-examples`
For a more detailed description of LDAP objects, see :ref:`ldap-gloss-ref`:
@ -43,44 +42,73 @@ For a more detailed description of LDAP objects, see :ref:`ldap-gloss-ref`:
Example LDAP configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
# Auth Cache TTL, Defines the caching for authentication to offload LDAP server.
# This means that cache result will be saved for 3600 before contacting LDAP server to verify the user access
3600
# Host, comma seperated format is optionally possible to specify more than 1 server
https://ldap1.server.com/ldap-admin/,https://ldap2.server.com/ldap-admin/
# Default LDAP Port, use 689 for LDAPS
389
# Account, used for SimpleBind if LDAP server requires an authentication
e.g admin@server.com
# Password used for simple bind
ldap-user-password
# LDAP connection security
LDAPS
# Certificate checks level
DEMAND
# Base DN
cn=Rufus Magillacuddy,ou=users,dc=rhodecode,dc=com
# LDAP search filter to narrow the results
(objectClass=person)
# LDAP search scope
SUBTREE
# Login attribute
sAMAccountName
# First Name Attribute to read
givenName
# Last Name Attribute to read
sn
# Email Attribute to read email address from
mail
Below is example setup that can be used with Active Directory/LDAP server::
*option*: `enabled` => `True`
# Enable or disable this authentication plugin.
Below is example setup that can be used with Active Directory/LDAP server.
*option*: `cache_ttl` => `360`
# Amount of seconds to cache the authentication and permissions check response call for this plugin.
# Useful for expensive calls like LDAP to improve the performance of the system (0 means disabled).
.. image:: ../images/ldap-example.png
:alt: LDAP/AD setup example
:scale: 50 %
*option*: `host` => `192.168.245.143,192.168.1.240`
# Host[s] of the LDAP Server
# (e.g., 192.168.2.154, or ldap-server.domain.com.
# Multiple servers can be specified using commas
*option*: `port` => `389`
# Custom port that the LDAP server is listening on. Default value is: 389, use 689 for LDAPS(SSL)
*option*: `timeout` => `300`
# Timeout for LDAP connection
*option*: `dn_user` => `Administrator@rhodecode.com`
# Optional user DN/account to connect to LDAP if authentication is required.
# e.g., cn=admin,dc=mydomain,dc=com, or uid=root,cn=users,dc=mydomain,dc=com, or admin@mydomain.com
*option*: `dn_pass` => `SomeSecret`
# Password to authenticate for given user DN.
*option*: `tls_kind` => `PLAIN`
# TLS Type
*option*: `tls_reqcert` => `NEVER`
# Require Cert over TLS?. Self-signed and custom certificates can be used when
# `RhodeCode Certificate` found in admin > settings > system info page is extended.
*option*: `tls_cert_file` => ``
# This specifies the PEM-format file path containing certificates for use in TLS connection.
# If not specified `TLS Cert dir` will be used
*option*: `tls_cert_dir` => `/etc/openldap/cacerts`
# This specifies the path of a directory that contains individual CA certificates in separate files.
*option*: `base_dn` => `cn=Rufus Magillacuddy,ou=users,dc=rhodecode,dc=com`
# Base DN to search. Dynamic bind is supported. Add `$login` marker in it to be replaced with current user credentials
# (e.g., dc=mydomain,dc=com, or ou=Users,dc=mydomain,dc=com)
*option*: `filter` => `(objectClass=person)`
# Filter to narrow results
# (e.g., (&(objectCategory=Person)(objectClass=user)), or
# (memberof=cn=rc-login,ou=groups,ou=company,dc=mydomain,dc=com)))
*option*: `search_scope` => `SUBTREE`
# How deep to search LDAP. If unsure set to SUBTREE
*option*: `attr_login` => `sAMAccountName`
# LDAP Attribute to map to user name (e.g., uid, or sAMAccountName)
*option*: `attr_email` => `mail`
# LDAP Attribute to map to email address (e.g., mail).
# Emails are a crucial part of RhodeCode.
# If possible add a valid email attribute to ldap users.
*option*: `attr_firstname` => `givenName`
# LDAP Attribute to map to first name (e.g., givenName)
*option*: `attr_lastname` => `sn`
# LDAP Attribute to map to last name (e.g., sn)
.. toctree::

4
docs/auth/auth-pam.rst
View file

@ -5,8 +5,8 @@ PAM
To enable PAM authentication, use the following steps:
1. From the |RCM| interface, go to :menuselection:`Admin --> Authentication`
2. Enable the ``rhodecode.lib.auth_modules.auth_pam`` library and select save
1. From the |RCE| interface, go to :menuselection:`Admin --> Authentication`
2. Activate the ``rhodecode.lib.auth_modules.auth_pam`` library and select save
3. On the PAM plugin settings section, do the following:
* Check the :guilabel:`Enable` checkbox

105
docs/auth/auth-saml-duosecurity.rst Normal file
View file

@ -0,0 +1,105 @@
.. _config-saml-duosecurity-ref:
SAML 2.0 with Duo Security
--------------------------
**This plugin is available only in EE Edition.**
|RCE| supports SAML 2.0 Authentication with Duo Security provider. This allows
users to log-in to RhodeCode via SSO mechanism of external identity provider
such as Duo. The login can be triggered either by the external IDP, or internally
by clicking specific authentication button on the log-in page.
Configuration steps
^^^^^^^^^^^^^^^^^^^
To configure Duo Security SAML authentication, use the following steps:
1. From the |RCE| interface, select
:menuselection:`Admin --> Authentication`
2. Activate the `Duo Security` plugin and select :guilabel:`Save`
3. Go to newly available menu option called `Duo Security` on the left side.
4. Check the `enabled` check box in the plugin configuration section,
and fill in the required SAML information and :guilabel:`Save`, for more details,
see :ref:`config-saml-duosecurity`
.. _config-saml-duosecurity:
Example SAML Duo Security configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Example configuration for SAML 2.0 with Duo Security provider::
*option*: `enabled` => `True`
# Enable or disable this authentication plugin.
*option*: `cache_ttl` => `0`
# Amount of seconds to cache the authentication and permissions check response call for this plugin.
# Useful for expensive calls like LDAP to improve the performance of the system (0 means disabled).
*option*: `debug` => `True`
# Enable or disable debug mode that shows SAML errors in the RhodeCode logs.
*option*: `entity_id` => `http://rc-app.com/dag/saml2/idp/metadata.php`
# Identity Provider entity/metadata URI.
# E.g. https://duo-gateway.com/dag/saml2/idp/metadata.php
*option*: `sso_service_url` => `http://rc-app.com/dag/saml2/idp/SSOService.php?spentityid=http://rc.local.pl/_admin/auth/duosecurity/saml-metadata`
# SSO (SingleSignOn) endpoint URL of the IdP. This can be used to initialize login
# E.g. https://duo-gateway.com/dag/saml2/idp/SSOService.php?spentityid=<metadata_entity_id>
*option*: `slo_service_url` => `http://rc-app.com/dag/saml2/idp/SingleLogoutService.php?ReturnTo=http://rc-app.com/dag/module.php/duosecurity/logout.php`
# SLO (SingleLogout) endpoint URL of the IdP.
# E.g. https://duo-gateway.com/dag/saml2/idp/SingleLogoutService.php?ReturnTo=http://duo-gateway.com/_admin/saml/sign-out-endpoint
*option*: `x509cert` => `<CERTIFICATE_STRING>`
# Identity provider public x509 certificate. It will be converted to single-line format without headers
*option*: `name_id_format` => `sha-1`
# The format that specifies how the NameID is sent to the service provider.
*option*: `signature_algo` => `sha-256`
# Type of Algorithm to use for verification of SAML signature on Identity provider side
*option*: `digest_algo` => `sha-256`
# Type of Algorithm to use for verification of SAML digest on Identity provider side
*option*: `cert_dir` => `/etc/saml/`
# Optional directory to store service provider certificate and private keys.
# Expected certs for the SP should be stored in this folder as:
# * sp.key Private Key
# * sp.crt Public cert
# * sp_new.crt Future Public cert
#
# Also you can use other cert to sign the metadata of the SP using the:
# * metadata.key
# * metadata.crt
*option*: `user_id_attribute` => `PersonImmutableID`
# User ID Attribute name. This defines which attribute in SAML response will be used to link accounts via unique id.
# Ensure this is returned from DuoSecurity for example via duo_username
*option*: `username_attribute` => `User.username`
# Username Attribute name. This defines which attribute in SAML response will map to an username.
*option*: `email_attribute` => `User.email`
# Email Attribute name. This defines which attribute in SAML response will map to an email address.
Below is example setup from DUO Administration page that can be used with above config.
.. image:: ../images/saml-duosecurity-service-provider-example.png
:alt: DUO Security SAML setup example
:scale: 50 %
Below is an example attribute mapping set for IDP provider required by the above config.
.. image:: ../images/saml-duosecurity-attributes-example.png
:alt: DUO Security SAML setup example
:scale: 50 %

18
docs/auth/auth-saml-generic.rst Normal file
View file

@ -0,0 +1,18 @@
.. _config-saml-generic-ref:
SAML 2.0 Authentication
-----------------------
**This plugin is available only in EE Edition.**
RhodeCode Supports standard SAML 2.0 SSO for the web-application part.
Please check for reference two example providers:
.. toctree::
auth-saml-duosecurity
auth-saml-onelogin

106
docs/auth/auth-saml-onelogin.rst Normal file
View file

@ -0,0 +1,106 @@
.. _config-saml-onelogin-ref:
SAML 2.0 with One Login
-----------------------
**This plugin is available only in EE Edition.**
|RCE| supports SAML 2.0 Authentication with OneLogin provider. This allows
users to log-in to RhodeCode via SSO mechanism of external identity provider
such as OneLogin. The login can be triggered either by the external IDP, or internally
by clicking specific authentication button on the log-in page.
Configuration steps
^^^^^^^^^^^^^^^^^^^
To configure OneLogin SAML authentication, use the following steps:
1. From the |RCE| interface, select
:menuselection:`Admin --> Authentication`
2. Activate the `OneLogin` plugin and select :guilabel:`Save`
3. Go to newly available menu option called `OneLogin` on the left side.
4. Check the `enabled` check box in the plugin configuration section,
and fill in the required SAML information and :guilabel:`Save`, for more details,
see :ref:`config-saml-onelogin`
.. _config-saml-onelogin:
Example SAML OneLogin configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Example configuration for SAML 2.0 with OneLogin provider::
*option*: `enabled` => `True`
# Enable or disable this authentication plugin.
*option*: `cache_ttl` => `0`
# Amount of seconds to cache the authentication and permissions check response call for this plugin.
# Useful for expensive calls like LDAP to improve the performance of the system (0 means disabled).
*option*: `debug` => `True`
# Enable or disable debug mode that shows SAML errors in the RhodeCode logs.
*option*: `entity_id` => `https://app.onelogin.com/saml/metadata/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
# Identity Provider entity/metadata URI.
# E.g. https://app.onelogin.com/saml/metadata/<onelogin_connector_id>
*option*: `sso_service_url` => `https://customer-domain.onelogin.com/trust/saml2/http-post/sso/xxxxxx`
# SSO (SingleSignOn) endpoint URL of the IdP. This can be used to initialize login
# E.g. https://app.onelogin.com/trust/saml2/http-post/sso/<onelogin_connector_id>
*option*: `slo_service_url` => `https://customer-domain.onelogin.com/trust/saml2/http-redirect/slo/xxxxxx`
# SLO (SingleLogout) endpoint URL of the IdP.
# E.g. https://app.onelogin.com/trust/saml2/http-redirect/slo/<onelogin_connector_id>
*option*: `x509cert` => `<CERTIFICATE_STRING>`
# Identity provider public x509 certificate. It will be converted to single-line format without headers
*option*: `name_id_format` => `sha-1`
# The format that specifies how the NameID is sent to the service provider.
*option*: `signature_algo` => `sha-256`
# Type of Algorithm to use for verification of SAML signature on Identity provider side
*option*: `digest_algo` => `sha-256`
# Type of Algorithm to use for verification of SAML digest on Identity provider side
*option*: `cert_dir` => `/etc/saml/`
# Optional directory to store service provider certificate and private keys.
# Expected certs for the SP should be stored in this folder as:
# * sp.key Private Key
# * sp.crt Public cert
# * sp_new.crt Future Public cert
#
# Also you can use other cert to sign the metadata of the SP using the:
# * metadata.key
# * metadata.crt
*option*: `user_id_attribute` => `PersonImmutableID`
# User ID Attribute name. This defines which attribute in SAML response will be used to link accounts via unique id.
# Ensure this is returned from OneLogin for example via Internal ID
*option*: `username_attribute` => `User.username`
# Username Attribute name. This defines which attribute in SAML response will map to an username.
*option*: `email_attribute` => `User.email`
# Email Attribute name. This defines which attribute in SAML response will map to an email address.
Below is example setup that can be used with OneLogin SAML authentication that can be used with above config..
.. image:: ../images/saml-onelogin-config-example.png
:alt: OneLogin SAML setup example
:scale: 50 %
Below is an example attribute mapping set for IDP provider required by the above config.
.. image:: ../images/saml-onelogin-attributes-example.png
:alt: OneLogin SAML setup example
:scale: 50 %

30
docs/auth/auth-token.rst
View file

@ -3,7 +3,10 @@
Authentication Tokens
---------------------
|RCE| has 4 different kinds of authentication tokens.
|RCE| has 4 different kinds of authentication tokens. `API token`, `Feed tokens` work
without a need to enable any additional authentication. `VCS tokens` require dedicated
authentication plugin to be activated. `Web Interface tokens` are controlled by the
white_list configuration.
* *API tokens*: API tokens can only be used to execute |RCE| API operations.
You can store your API token and assign it to each instance in
@ -11,15 +14,7 @@ Authentication Tokens
example in :ref:`indexing-ref` section for more details.
* *Feed tokens*: The feed token can only be used to access the RSS feed.
Usually those are safe to store inside your RSS feed reader.
* *VCS tokens*: You can use these to authenticate with |git|, |hg| and |svn|
operations instead of a password. They are designed to be used with
CI Servers or other third party tools that require |repo| access.
They are also a good replacement for SSH based access.
To use these tokens you need be enabled special authentication method on
|RCE|, as they are disabled by default.
See :ref:`enable-vcs-tokens`.
Usually those are safe to store inside your RSS feed reader.
* *Web Interface tokens*: These token allows users to access the web
interface of |RCE| without logging in.
@ -41,7 +36,16 @@ Authentication Tokens
https://rhodecode.com/repo/archive/tip.zip?auth_token=<web-api-token>
# To show commit diff without logging into Web UI
https://rhodecode.com/repo/changeset-diff/<sha>?auth_token=<web-api-token>
https://rhodecode.com/repo/raw-diff/<sha>?auth_token=<web-api-token>
* *VCS tokens*: You can use these to authenticate with |git|, |hg| and |svn|
operations instead of a password. They are designed to be used with
CI Servers or other third party tools that require |repo| access.
They are also a good replacement for SSH based access.
To use these tokens you need be enabled special authentication method on
|RCE|, as they are disabled by default.
See :ref:`enable-vcs-tokens`.
.. _enable-vcs-tokens:
@ -51,7 +55,7 @@ Enabling VCS Tokens
To enable VCS Tokens, use the following steps:
1. Go to :menuselection:`Admin --> Authentication`.
2. Enable the ``rhodecode.lib.auth_modules.auth_token`` plugin.
2. Activate the ``rhodecode.lib.auth_modules.auth_token`` plugin.
3. Click :guilabel:`Save`.
Authentication Token Tips
@ -67,7 +71,7 @@ Creating Tokens
To create authentication tokens for an user, use the following steps:
1. From the |RCM| interface go to
1. From the |RCE| interface go to
:menuselection:`Username --> My Account --> Auth tokens`.
2. Label and Add the tokens you wish to use with |RCE|.

20
docs/auth/auth.rst
View file

@ -4,29 +4,31 @@ Authentication Options
======================
|RCE| provides a built in authentication against its own database. This is
implemented using ``rhodecode.lib.auth_rhodecode`` plugin. This plugin is
enabled by default.
implemented using ``RhodeCode Internal`` plugin. This plugin is enabled by default.
Additionally, |RCE| provides a Pluggable Authentication System. This gives the
administrator greater control over how users authenticate with the system.
.. important::
You can disable the built in |RCM| authentication plugin
``rhodecode.lib.auth_rhodecode`` and force all authentication to go
You can disable the built in |RCE| authentication plugin
``RhodeCode Internal`` and force all authentication to go
through your authentication plugin of choice e.g LDAP only.
However, if you do this, and your external authentication tools fails,
you will be unable to access |RCM|.
accessing |RCE| will be blocked unless a fallback plugin is
enabled via :file: rhodecode.ini
|RCM| comes with the following user authentication management plugins:
|RCE| comes with the following user authentication management plugins:
.. toctree::
auth-token
auth-ldap
auth-ldap-groups
auth-saml-generic
auth-saml-onelogin
auth-saml-duosecurity
auth-crowd
auth-pam
auth-token
ssh-connection

84
docs/auth/ldap-active-directory.rst
View file

@ -3,27 +3,73 @@
Active Directory
----------------
|RCM| can use Microsoft Active Directory for user authentication. This is
|RCE| can use Microsoft Active Directory for user authentication. This is
done through an LDAP or LDAPS connection to Active Directory. Use the
following example LDAP configuration setting to set your Active Directory
authentication.
.. code-block:: ini
# Set the Base DN
Base DN = OU=SBSUsers,OU=Users,OU=MyBusiness,DC=v3sys,DC=local
# Set the Active Directory SAM-Account-Name
Login Attribute = sAMAccountName
# Set the Active Directory user name
First Name Attribute = usernameame
# Set the Active Directory user surname
Last Name Attribute = user_surname
# Set the Active Directory user email
E-mail Attribute = userEmail
authentication::
Below is example setup that can be used with Active Directory and ldap groups.
*option*: `enabled` => `True`
# Enable or disable this authentication plugin.
.. image:: ../images/ldap-groups-example.png
:alt: LDAP/AD setup example
:scale: 50 %
*option*: `cache_ttl` => `360`
# Amount of seconds to cache the authentication and permissions check response call for this plugin.
# Useful for expensive calls like LDAP to improve the performance of the system (0 means disabled).
*option*: `host` => `192.168.245.143,192.168.1.240`
# Host[s] of the LDAP Server
# (e.g., 192.168.2.154, or ldap-server.domain.com.
# Multiple servers can be specified using commas
*option*: `port` => `389`
# Custom port that the LDAP server is listening on. Default value is: 389, use 689 for LDAPS(SSL)
*option*: `timeout` => `300`
# Timeout for LDAP connection
*option*: `dn_user` => `Administrator@rhodecode.com`
# Optional user DN/account to connect to LDAP if authentication is required.
# e.g., cn=admin,dc=mydomain,dc=com, or uid=root,cn=users,dc=mydomain,dc=com, or admin@mydomain.com
*option*: `dn_pass` => `SomeSecret`
# Password to authenticate for given user DN.
*option*: `tls_kind` => `PLAIN`
# TLS Type
*option*: `tls_reqcert` => `NEVER`
# Require Cert over TLS?. Self-signed and custom certificates can be used when
# `RhodeCode Certificate` found in admin > settings > system info page is extended.
*option*: `tls_cert_file` => ``
# This specifies the PEM-format file path containing certificates for use in TLS connection.
# If not specified `TLS Cert dir` will be used
*option*: `tls_cert_dir` => `/etc/openldap/cacerts`
# This specifies the path of a directory that contains individual CA certificates in separate files.
*option*: `base_dn` => `OU=SBSUsers,OU=Users,OU=MyBusiness,DC=v3sys,DC=local`
# Base DN to search. Dynamic bind is supported. Add `$login` marker in it to be replaced with current user credentials
# (e.g., dc=mydomain,dc=com, or ou=Users,dc=mydomain,dc=com)
*option*: `filter` => `(objectClass=person)`
# Filter to narrow results
# (e.g., (&(objectCategory=Person)(objectClass=user)), or
# (memberof=cn=rc-login,ou=groups,ou=company,dc=mydomain,dc=com)))
*option*: `search_scope` => `SUBTREE`
# How deep to search LDAP. If unsure set to SUBTREE
*option*: `attr_login` => `sAMAccountName`
# LDAP Attribute to map to user name (e.g., uid, or sAMAccountName)
*option*: `attr_email` => `userEmail`
# LDAP Attribute to map to email address (e.g., mail).
# Emails are a crucial part of RhodeCode.
# If possible add a valid email attribute to ldap users.
*option*: `attr_firstname` => `user_firstname`
# LDAP Attribute to map to first name (e.g., givenName)
*option*: `attr_lastname` => `user_surname`
# LDAP Attribute to map to last name (e.g., sn)

10
docs/auth/ldap-authentication.rst
View file

@ -46,7 +46,7 @@ The following LDAP attributes are required when enabling |LDAP| on |RCE|.
* The LDAP username or account used to connect to |RCE|. This will be added
to the LDAP filter for locating the user object.
* For example, if an LDAP filter is specified as `LDAPFILTER`,
the login attribute is specified as `uid`, and the user connects as
the login/username attribute is specified as `uid`, and the user connects as
`jsmith`, then the LDAP Filter will be like the following example.
.. code-block:: vim
@ -68,7 +68,7 @@ The following LDAP attributes are required when enabling |LDAP| on |RCE|.
Optional settings
^^^^^^^^^^^^^^^^^
The following are optional when enabling LDAP on |RCM|
The following are optional when enabling LDAP on |RCE|
* An LDAP account is only required if the LDAP server does not allow
anonymous browsing of records.
@ -104,10 +104,4 @@ The following are optional when enabling LDAP on |RCM|
following directory: `/etc/openldap/cacerts`
Below is example setup that can be used with Active Directory and ldap groups.
.. image:: ../images/ldap-groups-example.png
:alt: LDAP/AD setup example
:scale: 50 %
.. _RFC 2254: http://www.rfc-base.org/rfc-2254.html