From cefbec329a604f34d480f116a106861674e83f1e Mon Sep 17 00:00:00 2001 From: RhodeCode Admin Date: Tue, 20 Aug 2024 15:04:33 +0200 Subject: [PATCH] auth: updated saml docs, and re-order info on plugin details for easier setup --- docs/Dockerfile | 25 ++- docs/auth/auth-saml-azure.rst | 159 ++++++++++++++++++ docs/auth/auth-saml-bulk-enroll-users.rst | 10 +- docs/auth/auth-saml-duosecurity.rst | 138 ++++++++++----- docs/auth/auth-saml-generic.rst | 1 + docs/auth/auth-saml-onelogin.rst | 137 ++++++++++----- docs/auth/auth.rst | 1 + rhodecode/authentication/routes.py | 1 + .../templates/admin/auth/auth_settings.mako | 7 +- .../templates/admin/auth/plugin_settings.mako | 7 + 10 files changed, 392 insertions(+), 94 deletions(-) create mode 100644 docs/auth/auth-saml-azure.rst diff --git a/docs/Dockerfile b/docs/Dockerfile index 3d324071..0c25861b 100644 --- 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 index 00000000..c0af703a --- /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 index cc3bd511..edc6f29a 100644 --- 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 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. @@ -46,6 +46,8 @@ From available options pick only one and run the `import` statement # 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 index 1dadfdce..36409870 100644 --- a/docs/auth/auth-saml-duosecurity.rst +++ b/docs/auth/auth-saml-duosecurity.rst @@ -32,62 +32,116 @@ To configure Duo Security SAML authentication, use the following steps: 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 - *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). +Enabled + `True`: - *option*: `debug` => `True` - # Enable or disable debug mode that shows SAML errors in the RhodeCode logs. + .. note:: + Enable or disable this authentication plugin. - *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= +Auth Cache TTL + `30`: - *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:: + 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*: `x509cert` => `` - # Identity provider public x509 certificate. It will be converted to single-line format without headers +Debug + `True`: - *option*: `name_id_format` => `sha-1` - # The format that specifies how the NameID is sent to the service provider. + .. note:: + Enable or disable debug mode that shows SAML errors in the RhodeCode logs. - *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 +Auth button name + `Azure Entra ID`: - *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 + .. note:: + Alternative authentication display name. E.g AzureAuth, CorporateID etc. - *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. +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=`: + + .. 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=`: + + .. 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 + +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 + `PersonImmutableID`: + + .. 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. - *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. diff --git a/docs/auth/auth-saml-generic.rst b/docs/auth/auth-saml-generic.rst index db6a6205..b5e528bc 100644 --- a/docs/auth/auth-saml-generic.rst +++ b/docs/auth/auth-saml-generic.rst @@ -15,5 +15,6 @@ Please check for reference two example providers: 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 index 69b2cc1d..ca3ac275 100644 --- a/docs/auth/auth-saml-onelogin.rst +++ b/docs/auth/auth-saml-onelogin.rst @@ -32,62 +32,115 @@ To configure OneLogin SAML authentication, use the following steps: Example SAML OneLogin configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Example configuration for SAML 2.0 with OneLogin provider:: +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). +Enabled + `True`: - *option*: `debug` => `True` - # Enable or disable debug mode that shows SAML errors in the RhodeCode logs. + .. note:: + Enable or disable this authentication plugin. - *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/ - *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/ +Auth Cache TTL + `30`: - *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:: + 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*: `x509cert` => `` - # Identity provider public x509 certificate. It will be converted to single-line format without headers +Debug + `True`: - *option*: `name_id_format` => `sha-1` - # The format that specifies how the NameID is sent to the service provider. + .. note:: + Enable or disable debug mode that shows SAML errors in the RhodeCode logs. - *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 +Auth button name + `Azure Entra ID`: - *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 + .. note:: + Alternative authentication display name. E.g AzureAuth, CorporateID etc. - *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. +Entity ID + `https://app.onelogin.com/saml/metadata/`: - *option*: `email_attribute` => `User.email` - # Email Attribute name. This defines which attribute in SAML response will map to an email address. + .. 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/`: + + .. 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/`: + + .. note:: + SLO (SingleLogout) endpoint URL of the IdP. , Known also as Logout URL + E.g. https://app.onelogin.com/trust/saml2/http-redirect/slo/ + +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 + `PersonImmutableID`: + + .. 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. diff --git a/docs/auth/auth.rst b/docs/auth/auth.rst index bdc7abdb..498e7178 100644 --- a/docs/auth/auth.rst +++ b/docs/auth/auth.rst @@ -29,6 +29,7 @@ administrator greater control over how users authenticate with the system. 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 index bd83ad71..e9e4b969 100644 --- a/rhodecode/authentication/routes.py +++ b/rhodecode/authentication/routes.py @@ -52,6 +52,7 @@ class AuthnRootResource(AuthnResourceBase): """ 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 index 92ae19f2..1e430b34 100644 --- 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 index 0f09b80c..07cba2f0 100644 --- 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'}