Version

    SAML Authentication

    CloverDX Server supports Single Sign-on (SSO) by the SAML 2.0 protocol. Available since version 5.2.

    Authorization is still handled by the CloverDX Server security module, so the user must be registered as a CloverDX user and their username must be the same as the username on Identity Provider's (IdP) side. Since version 5.4 user accounts can be created automatically on the first time login and users can also be assigned to a default group.

    The automatic account creation on the first time login is controlled by the security.saml.user_autocreate property, which defaults to false. Since users have no access to the server console by default, you need to also automatically assign them to a group. This can be achieved using the security.saml.default_user_group property. The expected value of the property is the code of the user group you want new users to be assigned to. If the property is not set or no user group with the given code is found, the login operation will fail and an error message is logged.

    Example of SAML configuration using metadata file

    By default, CloverDX Server allows only its own internal mechanism for authentication, under the default clover domain. To enable authentication with SAML, add SAML to the list of allowed authentication domains e.g.: security.authentication.allowed_domains = clover,SAML

    Note: if the property is set as in the example above and you want to log in using the CloverDX Server credentials, use the noSSO parameter in the CloverDX Server URL, for example: http://localhost:8083/clover?noSSO=true

    In order to set up the SAML authentication, CloverDX Server has to be configured as a Service Provider. First you need to configure a unique identifier using security.saml.sp_entity_id property. This ID is acquired from the Identity Provider when configuring it for CloverDX Server access. Then you have to configure the address where the CloverDX Server is reachable using security.saml.sp_assertion_consumer_url property.

    Next you need to set up the configuration properties relating to the Identity Provider so that the CloverDX Server can connect to it. The recommended way of doing this is to use the SAML metadata file provided by the Identity Provider. Set the property security.saml.idp_metadata_url to the URL pointing to this file.

    # Enable SAML SSO by adding SAML to allowed authentication domains
    security.authentication.allowed_domains=clover,saml
    # Configure CloverDX Server running at http://clover-server:8080/clover as a Service Provider".
    security.saml.sp_entity_id=https://example.com/example-app
    security.saml.sp_assertion_consumer_url=http://clover-server:8080/clover
    # Setting metadata URL automatically configures the Identity Provider to be used for SAML SSO 
    security.saml.idp_metadata_url=https://login.microsoftonline.com/common/FederationMetadata/2007-06/FederationMetadata.xml

    For more advanced examples, see the SAML Examples section.

    SAML authentication can be set up in the configuration file, using the following properties:

    Table 21.1. SAML Authentication Properties

    NameRequiredDescription
    security.saml.sp_entity_idYesUnique identifier to be used by CloverDX Server as a Service Provider. Acquired from the Identity Provider when setting up access for new Service Providers. In case of Microsoft Azure it's called Application ID.
    security.saml.sp_assertion_consumer_urlYesThe URL where CloverDX Server is reachable by the Identity Provider as a Service Provider. It is the target for redirect after a successful Single Sign-on.
    security.saml.idp_metadata_urlRecommended

    URL pointing to the metadata file of the Identity Provider. The metadata file provides required properties for setting up SAML authentication. We recommend to use this property to download the values of security.saml.idp_* properties automatically.

    security.saml.idp_entity_idConditionalThe identifier of the Identity Provider, must be a URI. Acquired from metadata file if security.saml.idp_metadata_url is configured.
    security.saml.idp_sso_service_urlConditionalThe URL of the Identity Provider where the server will send the authentication request (for Single Sign-on). Acquired from metadata file if security.saml.idp_metadata_url is configured.
    security.saml.idp_x509certConditionalThe public X509 certificate of the Identity Provider. Acquired from metadata file if security.saml.idp_metadata_url is configured.
    security.saml.idp_x509cert_multi.0NoAdditional public certificate. Multiple additional certificates can be added by incrementing the integer at the end of the property, e.g.: security.saml.idp_x509cert_multi.1
    security.saml.idp_slo_service_urlNoThe URL of the Identity Provider where the server will send the logout request (for Single Logout). Acquired from metadata file if security.saml.idp_metadata_url is configured.
    security.saml.strictNoIf set to true the CloverDX Server will reject unsigned or unencrypted SAML messages if it expects them signed or encrypted. It will also reject messages that do not strictly follow the SAML 2.0 protocol. Default value is true.
    security.saml.send_logout_responseNoWhether the CloverDX Server should send a logout response after an IdP-initiated logout request (defaults to true).
    security.saml.metadata.idp_entity_idNoThe preferred Identity Provider ID if the metadata file contains more than one Identity Provider IDs.
    security.saml.metadata.name_id_formatNo

    Name ID format to use, if available in the metadata file. Possible values:

    urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
    urn:oasis:names:tc:SAML:2.0:nameid-format:transient

    For more information see the Oasis SAML Specification

    security.saml.sp_nameid_formatNoSpecifies constraints on the name identifier used to represent the requested subject. For more information see the Oasis SAML Specification
    security.saml.user_autocreateNoEnablement of automatic user account creation on first time login using SAML (defaults to false).
    security.saml.default_user_groupConditionalThe group to which automatically created user accounts should be assigned to. Expected value is the code of the group. The property is required if security.saml.user_autocreate is set to true.