diff --git a/docs/Dockerfile b/docs/Dockerfile --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -4,15 +4,30 @@ WORKDIR /project RUN apt-get update \ && apt-get install --no-install-recommends --yes \ - curl \ - zip \ - graphviz \ - imagemagick \ - make \ + curl \ + zip \ + graphviz \ + dvipng \ + imagemagick \ + make \ + latexmk \ + texlive-latex-recommended \ + texlive-latex-extra \ + texlive-xetex \ + fonts-freefont-otf \ + texlive-fonts-recommended \ + texlive-lang-greek \ + tex-gyre \ && apt-get autoremove \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* +RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" && \ + unzip awscliv2.zip && \ + ./aws/install && \ + rm -rf ./aws && \ + rm awscliv2.zip + RUN \ python3 -m pip install --no-cache-dir --upgrade pip && \ python3 -m pip install --no-cache-dir Sphinx Pillow diff --git a/docs/auth/auth-saml-azure.rst b/docs/auth/auth-saml-azure.rst new file mode 100644 --- /dev/null +++ b/docs/auth/auth-saml-azure.rst @@ -0,0 +1,159 @@ +.. _config-saml-azure-ref: + + +SAML 2.0 with Azure Entra ID +---------------------------- + +**This plugin is available only in EE Edition.** + +|RCE| supports SAML 2.0 Authentication with Azure Entra ID provider. This allows +users to log-in to RhodeCode via SSO mechanism of external identity provider +such as Azure AD. 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 `Azure Entra ID` plugin and select :guilabel:`Save` +3. Go to newly available menu option called `Azure Entra ID` 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-azure` + + +.. _config-saml-azure: + + +Example SAML Azure Entra ID configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Example configuration for SAML 2.0 with Azure Entra ID provider + + +Enabled + `True`: + + .. note:: + Enable or disable this authentication plugin. + + +Auth Cache TTL + `30`: + + .. note:: + 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). + +Debug + `True`: + + .. note:: + Enable or disable debug mode that shows SAML errors in the RhodeCode logs. + + +Auth button name + `Azure Entra ID`: + + .. note:: + Alternative authentication display name. E.g AzureAuth, CorporateID etc. + + +Entity ID + `https://sts.windows.net/APP_ID/`: + + .. note:: + Identity Provider entity/metadata URI. Known as "Microsoft Entra Identifier" + E.g. https://sts.windows.net/abcd-c655-dcee-aab7-abcd/ + +SSO URL + `https://login.microsoftonline.com/APP_ID/saml2`: + + .. note:: + SSO (SingleSignOn) endpoint URL of the IdP. This can be used to initialize login, Known also as Login URL + E.g. https://login.microsoftonline.com/abcd-c655-dcee-aab7-abcd/saml2 + +SLO URL + `https://login.microsoftonline.com/APP_ID/saml2`: + + .. note:: + SLO (SingleLogout) endpoint URL of the IdP. , Known also as Logout URL + E.g. https://login.microsoftonline.com/abcd-c655-dcee-aab7-abcd/saml2 + +x509cert + ``: + + .. note:: + Identity provider public x509 certificate. It will be converted to single-line format without headers. + Download the raw base64 encoded certificate from the Identity provider and paste it here. + +SAML Signature + `sha-256`: + + .. note:: + Type of Algorithm to use for verification of SAML signature on Identity provider side. + +SAML Digest + `sha-256`: + + .. note:: + Type of Algorithm to use for verification of SAML digest on Identity provider side. + +Service Provider Cert Dir + `/etc/rhodecode/conf/saml_ssl/`: + + .. note:: + 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 + +Expected NameID Format + `nameid-format:emailAddress`: + + .. note:: + The format that specifies how the NameID is sent to the service provider. + +User ID Attribute + `user.email`: + + .. note:: + 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. + +Username Attribute + `user.username`: + + .. note:: + Username Attribute name. This defines which attribute in SAML response will map to a username. + +Email Attribute + `user.email`: + + .. note:: + Email Attribute name. This defines which attribute in SAML response will map to an email address. + + + +Below is example setup from Azure Administration page that can be used with above config. + +.. image:: ../images/saml-azure-service-provider-example.png + :alt: Azure SAML setup example + :scale: 50 % + + +Below is an example attribute mapping set for IDP provider required by the above config. + + +.. image:: ../images/saml-azure-attributes-example.png + :alt: Azure SAML setup example + :scale: 50 % \ No newline at end of file diff --git a/docs/auth/auth-saml-bulk-enroll-users.rst b/docs/auth/auth-saml-bulk-enroll-users.rst --- a/docs/auth/auth-saml-bulk-enroll-users.rst +++ b/docs/auth/auth-saml-bulk-enroll-users.rst @@ -13,7 +13,7 @@ This method simply enables SAML authenti From the server RhodeCode Enterprise is running run ishell on the instance which we want to apply the SAML migration:: - rccontrol ishell enterprise-1 + ./rcstack cli ishell Follow these steps to enable SAML authentication for multiple users. @@ -46,6 +46,8 @@ From available options pick only one and # for Duo Security In [2]: from rc_auth_plugins.auth_duo_security import RhodeCodeAuthPlugin + # for Azure Entra + In [2]: from rc_auth_plugins.auth_azure import RhodeCodeAuthPlugin # for OneLogin In [2]: from rc_auth_plugins.auth_onelogin import RhodeCodeAuthPlugin # generic SAML plugin @@ -62,13 +64,13 @@ Enter in the ishell prompt ...: attrs = saml2user.get(user.user_id) ...: provider = RhodeCodeAuthPlugin.uid ...: if existing_identity: - ...: print('Identity for user `{}` already exists, skipping'.format(user.username)) + ...: print(f'Identity for user `{user.username}` already exists, skipping') ...: continue ...: if attrs: ...: external_id = attrs['id'] ...: new_external_identity = ExternalIdentity() ...: new_external_identity.external_id = external_id - ...: new_external_identity.external_username = '{}-saml-{}'.format(user.username, user.user_id) + ...: new_external_identity.external_username = f'{user.username}-saml-{user.user_id}' ...: new_external_identity.provider_name = provider ...: new_external_identity.local_user_id = user.user_id ...: new_external_identity.access_token = '' @@ -76,7 +78,7 @@ Enter in the ishell prompt ...: new_external_identity.alt_token = '' ...: Session().add(ex_identity) ...: Session().commit() - ...: print('Set user `{}` external identity bound to ExternalID:{}'.format(user.username, external_id)) + ...: print(f'Set user `{user.username}` external identity bound to ExternalID:{external_id}') .. note:: diff --git a/docs/auth/auth-saml-duosecurity.rst b/docs/auth/auth-saml-duosecurity.rst --- a/docs/auth/auth-saml-duosecurity.rst +++ b/docs/auth/auth-saml-duosecurity.rst @@ -32,62 +32,116 @@ 4. Check the `enabled` check box in the Example SAML Duo Security configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Example configuration for SAML 2.0 with Duo Security provider:: +Example configuration for SAML 2.0 with Duo Security provider + + +Enabled + `True`: - *option*: `enabled` => `True` - # Enable or disable this authentication plugin. + .. note:: + Enable or disable this authentication plugin. + + +Auth Cache TTL + `30`: - *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). + .. note:: + 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). + +Debug + `True`: - *option*: `debug` => `True` - # Enable or disable debug mode that shows SAML errors in the RhodeCode logs. + .. note:: + Enable or disable debug mode that shows SAML errors in the RhodeCode logs. + + +Auth button name + `Azure Entra ID`: - *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 + .. note:: + Alternative authentication display name. E.g AzureAuth, CorporateID etc. + + +Entity ID + `https://my-duo-gateway.com/dag/saml2/idp/metadata.php`: + + .. note:: + Identity Provider entity/metadata URI. + E.g. https://duo-gateway.com/dag/saml2/idp/metadata.php + +SSO URL + `https://duo-gateway.com/dag/saml2/idp/SSOService.php?spentityid=`: - *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= + .. note:: + SSO (SingleSignOn) endpoint URL of the IdP. This can be used to initialize login, Known also as Login URL + E.g. http://rc-app.com/dag/saml2/idp/SSOService.php?spentityid=https://docker-dev/_admin/auth/duosecurity/saml-metadata + +SLO URL + `https://duo-gateway.com/dag/saml2/idp/SingleLogoutService.php?ReturnTo=`: - *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 + .. note:: + SLO (SingleLogout) endpoint URL of the IdP. , Known also as Logout URL + E.g. http://rc-app.com/dag/saml2/idp/SingleLogoutService.php?ReturnTo=https://docker-dev/_admin/auth/duosecurity/saml-sign-out-endpoint - *option*: `x509cert` => `` - # Identity provider public x509 certificate. It will be converted to single-line format without headers +x509cert + ``: - *option*: `name_id_format` => `sha-1` - # The format that specifies how the NameID is sent to the service provider. + .. note:: + Identity provider public x509 certificate. It will be converted to single-line format without headers. + Download the raw base64 encoded certificate from the Identity provider and paste it here. + +SAML Signature + `sha-256`: + + .. note:: + Type of Algorithm to use for verification of SAML signature on Identity provider side. + +SAML Digest + `sha-256`: - *option*: `signature_algo` => `sha-256` - # Type of Algorithm to use for verification of SAML signature on Identity provider side + .. note:: + Type of Algorithm to use for verification of SAML digest on Identity provider side. + +Service Provider Cert Dir + `/etc/rhodecode/conf/saml_ssl/`: - *option*: `digest_algo` => `sha-256` - # Type of Algorithm to use for verification of SAML digest on Identity provider side + .. note:: + 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 - *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 + Also you can use other cert to sign the metadata of the SP using the: + * metadata.key + * metadata.crt + +Expected NameID Format + `nameid-format:emailAddress`: + + .. note:: + The format that specifies how the NameID is sent to the service provider. + +User ID Attribute + `PersonImmutableID`: - *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 + .. note:: + 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. + +Username Attribute + `User.username`: - *option*: `username_attribute` => `User.username` - # Username Attribute name. This defines which attribute in SAML response will map to an username. + .. note:: + Username Attribute name. This defines which attribute in SAML response will map to a username. - *option*: `email_attribute` => `User.email` - # Email Attribute name. This defines which attribute in SAML response will map to an email address. +Email Attribute + `User.email`: + + .. note:: + 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. diff --git a/docs/auth/auth-saml-generic.rst b/docs/auth/auth-saml-generic.rst --- a/docs/auth/auth-saml-generic.rst +++ b/docs/auth/auth-saml-generic.rst @@ -15,5 +15,6 @@ Please check for reference two example p auth-saml-duosecurity auth-saml-onelogin + auth-saml-azure auth-saml-bulk-enroll-users diff --git a/docs/auth/auth-saml-onelogin.rst b/docs/auth/auth-saml-onelogin.rst --- a/docs/auth/auth-saml-onelogin.rst +++ b/docs/auth/auth-saml-onelogin.rst @@ -32,62 +32,115 @@ 4. Check the `enabled` check box in the Example SAML OneLogin configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Example configuration for SAML 2.0 with OneLogin provider:: +Example configuration for SAML 2.0 with OneLogin provider + + +Enabled + `True`: - *option*: `enabled` => `True` - # Enable or disable this authentication plugin. + .. note:: + Enable or disable this authentication plugin. + + +Auth Cache TTL + `30`: - *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). + .. note:: + 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). + +Debug + `True`: - *option*: `debug` => `True` - # Enable or disable debug mode that shows SAML errors in the RhodeCode logs. + .. note:: + Enable or disable debug mode that shows SAML errors in the RhodeCode logs. + + +Auth button name + `Azure Entra ID`: - *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/ + .. note:: + Alternative authentication display name. E.g AzureAuth, CorporateID etc. + + +Entity ID + `https://app.onelogin.com/saml/metadata/`: + + .. note:: + Identity Provider entity/metadata URI. + E.g. https://app.onelogin.com/saml/metadata/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + +SSO URL + `https://app.onelogin.com/trust/saml2/http-post/sso/`: - *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/ + .. note:: + SSO (SingleSignOn) endpoint URL of the IdP. This can be used to initialize login, Known also as Login URL + E.g. https://app.onelogin.com/trust/saml2/http-post/sso/ + +SLO URL + `https://app.onelogin.com/trust/saml2/http-redirect/slo/`: - *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/ + .. note:: + SLO (SingleLogout) endpoint URL of the IdP. , Known also as Logout URL + E.g. https://app.onelogin.com/trust/saml2/http-redirect/slo/ - *option*: `x509cert` => `` - # Identity provider public x509 certificate. It will be converted to single-line format without headers +x509cert + ``: - *option*: `name_id_format` => `sha-1` - # The format that specifies how the NameID is sent to the service provider. + .. note:: + Identity provider public x509 certificate. It will be converted to single-line format without headers. + Download the raw base64 encoded certificate from the Identity provider and paste it here. + +SAML Signature + `sha-256`: + + .. note:: + Type of Algorithm to use for verification of SAML signature on Identity provider side. + +SAML Digest + `sha-256`: - *option*: `signature_algo` => `sha-256` - # Type of Algorithm to use for verification of SAML signature on Identity provider side + .. note:: + Type of Algorithm to use for verification of SAML digest on Identity provider side. + +Service Provider Cert Dir + `/etc/rhodecode/conf/saml_ssl/`: - *option*: `digest_algo` => `sha-256` - # Type of Algorithm to use for verification of SAML digest on Identity provider side + .. note:: + 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 - *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 + Also you can use other cert to sign the metadata of the SP using the: + * metadata.key + * metadata.crt + +Expected NameID Format + `nameid-format:emailAddress`: + + .. note:: + The format that specifies how the NameID is sent to the service provider. + +User ID Attribute + `PersonImmutableID`: - *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 + .. note:: + 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. + +Username Attribute + `User.username`: - *option*: `username_attribute` => `User.username` - # Username Attribute name. This defines which attribute in SAML response will map to an username. + .. note:: + Username Attribute name. This defines which attribute in SAML response will map to a username. - *option*: `email_attribute` => `User.email` - # Email Attribute name. This defines which attribute in SAML response will map to an email address. +Email Attribute + `User.email`: + + .. note:: + Email Attribute name. This defines which attribute in SAML response will map to an email address. diff --git a/docs/auth/auth.rst b/docs/auth/auth.rst --- a/docs/auth/auth.rst +++ b/docs/auth/auth.rst @@ -29,6 +29,7 @@ administrator greater control over how u auth-saml-generic auth-saml-onelogin auth-saml-duosecurity + auth-saml-azure auth-crowd auth-pam ssh-connection diff --git a/rhodecode/authentication/routes.py b/rhodecode/authentication/routes.py --- a/rhodecode/authentication/routes.py +++ b/rhodecode/authentication/routes.py @@ -52,6 +52,7 @@ class AuthnRootResource(AuthnResourceBas """ This is the root traversal resource object for the authentication settings. """ + is_root = True def __init__(self): self._store = collections.OrderedDict() diff --git a/rhodecode/templates/admin/auth/auth_settings.mako b/rhodecode/templates/admin/auth/auth_settings.mako --- a/rhodecode/templates/admin/auth/auth_settings.mako +++ b/rhodecode/templates/admin/auth/auth_settings.mako @@ -26,8 +26,13 @@
diff --git a/rhodecode/templates/admin/auth/plugin_settings.mako b/rhodecode/templates/admin/auth/plugin_settings.mako --- a/rhodecode/templates/admin/auth/plugin_settings.mako +++ b/rhodecode/templates/admin/auth/plugin_settings.mako @@ -50,6 +50,13 @@ ${h.secure_form(request.resource_path(resource, route_name='auth_home'), request=request)}
+ ## Allow derived templates to add something above the form + ## input fields + %if hasattr(next, 'above_form_fields'): + ${next.above_form_fields()} + %endif + +

${_('Plugin Configuration')}

%for node in plugin.get_settings_schema(): <% label_to_type = {'label-checkbox': 'bool', 'label-textarea': 'textarea'}