auth: updated saml docs, and re-order info on plugin details for easier setup

docs/auth/auth-saml-azure.rst

@@ -0,0 +1,159 b''
+.. _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
+    `<CERTIFICATE_STRING>`:
+
+    .. 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

docs/Dockerfile

@@ -4,15 +4,30 b' 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

docs/auth/auth-saml-bulk-enroll-users.rst

@@ -13,7 +13,7 b' 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 b' 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 b' 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 b' 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::
 

docs/auth/auth-saml-duosecurity.rst

@@ -32,62 +32,116 b' 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=<metadata_entity_id>`:
 
-    *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>
+    .. 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=<return_url>`:
 
-    *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` => `<CERTIFICATE_STRING>`
-    # Identity provider public x509 certificate. It will be converted to single-line format without headers
+x509cert
+    `<CERTIFICATE_STRING>`:
 
-    *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.

docs/auth/auth-saml-generic.rst

@@ -15,5 +15,6 b' Please check for reference two example p'
 
    auth-saml-duosecurity
    auth-saml-onelogin
+   auth-saml-azure
    auth-saml-bulk-enroll-users
 

docs/auth/auth-saml-onelogin.rst

@@ -32,62 +32,115 b' 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/<onelogin_connector_id>
+    .. note::
+      Alternative authentication display name. E.g AzureAuth, CorporateID etc.
+
+
+Entity ID
+    `https://app.onelogin.com/saml/metadata/<onelogin_connector_id>`:
+
+    .. 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/<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>
+    .. 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/<onelogin_connector_id>
+
+SLO URL
+    `https://app.onelogin.com/trust/saml2/http-redirect/slo/<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>
+    .. note::
+      SLO (SingleLogout) endpoint URL of the IdP. , Known also as Logout URL
+      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
+x509cert
+    `<CERTIFICATE_STRING>`:
 
-    *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.
 
 
 

docs/auth/auth.rst

@@ -29,6 +29,7 b' administrator greater control over how u'
     auth-saml-generic
     auth-saml-onelogin
     auth-saml-duosecurity
+    auth-saml-azure
     auth-crowd
     auth-pam
     ssh-connection

rhodecode/authentication/routes.py

@@ -52,6 +52,7 b' class AuthnRootResource(AuthnResourceBas'
     """
     This is the root traversal resource object for the authentication settings.
     """
+    is_root = True
 
     def __init__(self):
         self._store = collections.OrderedDict()

rhodecode/templates/admin/auth/auth_settings.mako

@@ -26,8 +26,13 b''
     <div class="sidebar">
         <ul class="nav nav-pills nav-stacked">
           % for item in resource.get_root().get_nav_list():
+
             <li ${('class=active' if item == resource else '')}>
-              <a href="${request.resource_path(item, route_name='auth_home')}">${item.display_name}</a>
+              % if getattr(item, 'is_root', False):
+                <a href="${request.resource_path(item, route_name='auth_home')}">${item.display_name}</a>
+              % else:
+                <a style="padding-left: 10px" href="${request.resource_path(item, route_name='auth_home')}">${item.display_name}</a>
+              % endif
             </li>
           % endfor
         </ul>

rhodecode/templates/admin/auth/plugin_settings.mako

@@ -50,6 +50,13 b''
                 ${h.secure_form(request.resource_path(resource, route_name='auth_home'), request=request)}
                 <div class="form">
 
+                  ## Allow derived templates to add something above the form
+                  ## input fields
+                  %if hasattr(next, 'above_form_fields'):
+                    ${next.above_form_fields()}
+                  %endif
+
+                  <h4>${_('Plugin Configuration')}</h4>
                   %for node in plugin.get_settings_schema():
                     <%
                       label_to_type = {'label-checkbox': 'bool', 'label-textarea': 'textarea'}