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

@@ -1,24 +1,39 b''
 FROM python:3.12.0-bullseye
 
 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
 
 ADD requirements_docs.txt /project
 RUN \
     python3 -m pip install -r requirements_docs.txt
 
 CMD ["sphinx-build", "-M", "html", ".", "_build"]

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

@@ -1,88 +1,90 b''
 .. _auth-saml-bulk-enroll-users-ref:
 
 
 Bulk enroll multiple existing users
 -----------------------------------
 
 
 RhodeCode Supports standard SAML 2.0 SSO for the web-application part.
 Below is an example how to enroll list of all or some users to use SAML authentication.
 This method simply enables SAML authentication for many users at once.
 
 
 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.
 
 
 1) Create a user_id => attribute mapping
 
 
 `saml2user` is a mapping of external ID from SAML provider such as OneLogin, DuoSecurity, Google.
 This mapping consists of local rhodecode user_id mapped to set of required attributes needed to bind SAML
 account to internal rhodecode user.
 For example, 123 is local rhodecode user_id, and '48253211' is OneLogin ID.
 For other providers you'd have to figure out what would be the user-id, sometimes it's the email, i.e for Google
 The most important this id needs to be unique for each user.
 
 .. code-block:: python
 
     In [1]: saml2user = {
        ...: # OneLogin, uses externalID available to read from in the UI
        ...: 123: {'id': '48253211'},
        ...: # for Google/DuoSecurity email is also an option for unique ID
        ...: 124: {'id': '[e-mail]'},
        ...: }
 
 
 2) Import the plugin you want to run migration for.
 
 From available options pick only one and run the `import` statement
 
 .. code-block:: python
 
     # 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
     In [2]: from rc_auth_plugins.auth_saml import RhodeCodeAuthPlugin
 
 3) Run the migration based on saml2user mapping.
 
 Enter in the ishell prompt
 
 .. code-block:: python
 
     In [3]: for user in User.get_all():
        ...:     existing_identity = ExternalIdentity().query().filter(ExternalIdentity.local_user_id == user.user_id).scalar()
        ...:     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 = ''
        ...:         new_external_identity.token_secret = ''
        ...:         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::
 
     saml2user can be really big and hard to maintain in ishell. It's also possible
     to load it as a JSON file prepared before and stored on disk. To do so run::
 
         import json
         saml2user = json.loads(open('/path/to/saml2user.json','rb').read())
 

docs/auth/auth-saml-duosecurity.rst

@@ -1,105 +1,159 b''
 .. _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::
+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.
 
 .. 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 %
  No newline at end of file

docs/auth/auth-saml-generic.rst

@@ -1,19 +1,20 b''
 .. _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
+   auth-saml-azure
    auth-saml-bulk-enroll-users
 

docs/auth/auth-saml-onelogin.rst

@@ -1,106 +1,159 b''
 .. _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::
+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.
 
 
 
 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 %
  No newline at end of file

docs/auth/auth.rst

@@ -1,34 +1,35 b''
 .. _authentication-ref:
 
 Authentication Options
 ======================
 
 |RCE| provides a built in authentication against its own database. This is
 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 |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,
   accessing |RCE| will be blocked unless a fallback plugin is
   enabled via :file: rhodecode.ini
 
 
 |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-saml-azure
     auth-crowd
     auth-pam
     ssh-connection

rhodecode/authentication/routes.py

@@ -1,153 +1,154 b''
 # Copyright (C) 2012-2023 RhodeCode GmbH
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Affero General Public License, version 3
 # (only), as published by the Free Software Foundation.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 # This program is dual-licensed. If you wish to learn more about the
 # RhodeCode Enterprise Edition, including its added features, Support services,
 # and proprietary license terms, please see https://rhodecode.com/licenses/
 
 import logging
 import collections
 
 from pyramid.exceptions import ConfigurationError
 
 from rhodecode.lib.utils2 import safe_str
 from rhodecode.model.settings import SettingsModel
 from rhodecode.translation import _
 
 
 log = logging.getLogger(__name__)
 
 
 class AuthnResourceBase(object):
     __name__ = None
     __parent__ = None
 
     def get_root(self):
         current = self
         while current.__parent__ is not None:
             current = current.__parent__
         return current
 
 
 class AuthnPluginResourceBase(AuthnResourceBase):
 
     def __init__(self, plugin):
         self.plugin = plugin
         self.__name__ = plugin.get_url_slug()
         self.display_name = plugin.get_display_name()
 
 
 class AuthnRootResource(AuthnResourceBase):
     """
     This is the root traversal resource object for the authentication settings.
     """
+    is_root = True
 
     def __init__(self):
         self._store = collections.OrderedDict()
         self._resource_name_map = {}
         self.display_name = _('Authentication Plugins')
 
     def __getitem__(self, key):
         """
         Customized get item function to return only items (plugins) that are
         activated.
         """
         if self._is_item_active(key):
             return self._store[key]
         else:
             raise KeyError('Authentication plugin "{}" is not active.'.format(
                 key))
 
     def __iter__(self):
         for key in self._store.keys():
             if self._is_item_active(key):
                 yield self._store[key]
 
     def _is_item_active(self, key):
         activated_plugins = SettingsModel().get_auth_plugins()
         plugin_id = self.get_plugin_id(key)
         return plugin_id in activated_plugins
 
     def get_plugin_id(self, resource_name):
         """
         Return the plugin id for the given traversal resource name.
         """
         # TODO: Store this info in the resource element.
         return self._resource_name_map[resource_name]
 
     def get_sorted_list(self, sort_key=None):
         """
         Returns a sorted list of sub resources for displaying purposes.
         """
         def default_sort_key(resource):
             return str.lower(safe_str(resource.display_name))
 
         active = [item for item in self]
         return sorted(active, key=sort_key or default_sort_key)
 
     def get_nav_list(self, sort=True):
         """
         Returns a sorted list of resources for displaying the navigation.
         """
         if sort:
             nav_list = self.get_sorted_list()
         else:
             nav_list = [item for item in self]
 
         nav_list.insert(0, self)
         return nav_list
 
     def add_authn_resource(self, config, plugin_id, resource):
         """
         Register a traversal resource as a sub element to the authentication
         settings. This method is registered as a directive on the pyramid
         configurator object and called by plugins.
         """
 
         def _ensure_unique_name(name, limit=100):
             counter = 1
             current = name
             while current in self._store.keys():
                 current = f'{name}{counter}'
                 counter += 1
                 if counter > limit:
                     raise ConfigurationError(
                         'Cannot build unique name for traversal resource "%s" '
                         'registered by plugin "%s"', name, plugin_id)
             return current
 
         # Allow plugin resources with identical names by rename duplicates.
         unique_name = _ensure_unique_name(resource.__name__)
         if unique_name != resource.__name__:
             log.warning('Name collision for traversal resource "%s" registered '
                         'by authentication plugin "%s"', resource.__name__,
                         plugin_id)
             resource.__name__ = unique_name
 
         log.debug('Register traversal resource "%s" for plugin "%s"',
                   unique_name, plugin_id)
         self._resource_name_map[unique_name] = plugin_id
         resource.__parent__ = self
         self._store[unique_name] = resource
 
 
 root = AuthnRootResource()
 
 
 def root_factory(request=None):
     """
     Returns the root traversal resource instance used for the authentication
     settings route.
     """
     return root

rhodecode/templates/admin/auth/auth_settings.mako

@@ -1,122 +1,127 b''
 <%inherit file="/base/base.mako"/>
 
 <%def name="title()">
     ${_('Authentication Settings')}
     %if c.rhodecode_name:
         &middot; ${h.branding(c.rhodecode_name)}}
     %endif
 </%def>
 
 <%def name="breadcrumbs_links()"></%def>
 
 <%def name="menu_bar_nav()">
     ${self.menu_items(active='admin')}
 </%def>
 
 <%def name="menu_bar_subnav()">
     ${self.admin_menu(active='authentication')}
 </%def>
 
 <%def name="main()">
 
 <div class="box">
 
   <div class='sidebar-col-wrapper'>
 
     <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>
     </div>
 
     <div class="main-content-full-width">
       ${h.secure_form(request.resource_path(resource, route_name='auth_home'), request=request)}
         <div class="panel panel-default">
 
           <div class="panel-heading">
             <h3 class="panel-title">${_("Enabled and Available Plugins")}</h3>
           </div>
 
           <div class="panel-body">
 
 
               <div class="label">${_("Ordered Activated Plugins")}</div>
               <div class="textarea text-area editor">
                   ${h.textarea('auth_plugins',cols=120,rows=20,class_="medium")}
               </div>
               <div class="field">
                 <p class="help-block pre-formatting">${_('List of plugins, separated by commas.'
                   '\nThe order of the plugins is also the order in which '
                   'RhodeCode Enterprise will try to authenticate a user.')}
                 </p>
               </div>
 
               <table class="rctable">
                   <th>${_('Activate')}</th>
                   <th>${_('Plugin Name')}</th>
                   <th>${_('Documentation')}</th>
                   <th>${_('Plugin ID')}</th>
                   <th>${_('Enabled')}</th>
                   %for plugin in available_plugins:
                       <tr class="${('inactive' if (not plugin.is_active() and plugin.get_id() in enabled_plugins) else '')}">
                           <td>
                             <span plugin_id="${plugin.get_id()}" class="toggle-plugin btn ${('btn-success' if plugin.get_id() in enabled_plugins else '')}">
                               ${(_('activated') if plugin.get_id() in enabled_plugins else _('not active'))}
                             </span>
                           </td>
                           <td>${plugin.get_display_name()}</td>
                           <td>
                               % if plugin.docs():
                                 <a href="${plugin.docs()}">docs</a>
                               % endif
                           </td>
                           <td>${plugin.get_id()}</td>
                           <td>${h.bool2icon(plugin.is_active(),show_at_false=False)}</td>
                       </tr>
                   %endfor
               </table>
 
             <div class="buttons">
               ${h.submit('save',_('Save'),class_="btn")}
             </div>
           </div>
         </div>
       ${h.end_form()}
     </div>
   </div>
 </div>
 
 <script>
   $('.toggle-plugin').click(function(e){
     var auth_plugins_input = $('#auth_plugins');
     var elems = [];
 
     $.each(auth_plugins_input.val().split(',') , function (index, element) {
         if (element !== "") {
             elems.push(element.strip())
         }
     });
 
     var cur_button = e.currentTarget;
     var plugin_id = $(cur_button).attr('plugin_id');
     if($(cur_button).hasClass('btn-success')){
       elems.splice(elems.indexOf(plugin_id), 1);
       auth_plugins_input.val(elems.join(',\n'));
       $(cur_button).removeClass('btn-success');
       cur_button.innerHTML = _gettext('not active');
     }
     else{
       if (elems.indexOf(plugin_id) === -1) {
             elems.push(plugin_id);
       }
       auth_plugins_input.val(elems.join(',\n'));
       $(cur_button).addClass('btn-success');
       cur_button.innerHTML = _gettext('activated');
     }
   });
 </script>
 </%def>

rhodecode/templates/admin/auth/plugin_settings.mako

@@ -1,139 +1,146 b''
 <%inherit file="/base/base.mako"/>
 
 <%def name="title()">
     ${_('Authentication Settings')}
     %if c.rhodecode_name:
     &middot; ${h.branding(c.rhodecode_name)}}
     %endif
 </%def>
 
 <%def name="breadcrumbs_links()">
   ${h.link_to(_('Admin'),h.route_path('admin_home'))}
   &raquo;
   ${h.link_to(_('Authentication Plugins'),request.resource_path(resource.__parent__, route_name='auth_home'))}
   &raquo;
   ${resource.display_name}
 </%def>
 
 <%def name="menu_bar_nav()">
     ${self.menu_items(active='admin')}
 </%def>
 
 <%def name="menu_bar_subnav()">
     ${self.admin_menu(active='authentication')}
 </%def>
 
 <%def name="main()">
 
   <div class="box">
 
     <div class='sidebar-col-wrapper'>
 
       <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>
             </li>
           % endfor
         </ul>
       </div>
 
       <div class="main-content-full-width">
         <div class="panel panel-default">
           <div class="panel-heading">
             <h3 class="panel-title">${_('Plugin')}: ${resource.display_name}</h3>
           </div>
           <div class="panel-body">
             <div class="plugin_form">
               <div class="fields">
                 ${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'}
                     %>
 
                     <div class="field">
                       <div class="label ${label_to_type.get(node.widget)}"><label for="${node.name}">${node.title}</label></div>
                       <div class="input">
                         %if node.widget in ["string", "int", "unicode"]:
                           ${h.text(node.name, defaults.get(node.name), class_="large")}
                         %elif node.widget == "password":
                           ${h.password(node.name, defaults.get(node.name), class_="large")}
                         %elif node.widget == "bool":
                             %if node.name == "global_2fa" and c.rhodecode_edition_id != "EE":
                                 <input type="checkbox" disabled/>
                                 <%node.description = _('This feature is available in RhodeCode EE edition only. Contact {sales_email} to obtain a trial license.').format(sales_email='<a href="mailto:[e-mail]">[e-mail]</a>')%>
                             %else:
                                 <div class="checkbox" >${h.checkbox(node.name, True, checked=defaults.get(node.name))}</div>
                             %endif
                         %elif node.widget == "select":
                           ${h.select(node.name, defaults.get(node.name), node.validator.choices, class_="select2AuthSetting")}
                         %elif node.widget == "select_with_labels":
                           ${h.select(node.name, defaults.get(node.name), node.choices, class_="select2AuthSetting")}
                         %elif node.widget == "textarea":
                           <div class="textarea" style="margin-left: 0px">${h.textarea(node.name, defaults.get(node.name), rows=10)}</div>
                         %elif node.widget == "readonly":
                           ${node.default}
                         %else:
                           This field is of type ${node.typ}, which cannot be displayed. Must be one of [string|int|bool|select].
                         %endif
 
                         %if node.name in errors:
                           <span class="error-message">${errors.get(node.name)}</span>
                           <br />
                         %endif
                         <p class="help-block pre-formatting">${node.description | n}</p>
                       </div>
                     </div>
                   %endfor
 
                   ## Allow derived templates to add something below the form
                   ## input fields
                   %if hasattr(next, 'below_form_fields'):
                     ${next.below_form_fields()}
                   %endif
 
                   <div class="buttons">
                     ${h.submit('save',_('Save'),class_="btn")}
                   </div>
 
                 </div>
                 ${h.end_form()}
               </div>
             </div>
 
 % if request.GET.get('schema'):
 ## this is for development and creation of example configurations for documentation
 <pre>
     % for node in plugin.get_settings_schema():
     *option*: `${node.name}` => `${defaults.get(node.name)}`${'\n    # '.join(['']+node.description.splitlines())}
 
     % endfor
 </pre>
 
 % endif
 
           </div>
         </div>
       </div>
 
     </div>
   </div>
 
 
 <script>
 $(document).ready(function() {
   var select2Options = {
         containerCssClass: 'drop-menu',
         dropdownCssClass: 'drop-menu-dropdown',
         dropdownAutoWidth: true,
         minimumResultsForSearch: -1
   };
   $('.select2AuthSetting').select2(select2Options);
 
 });
 </script>
 </%def>