Skip to content

SAML2

SAML2 (Security Assertion Markup Language 2.0) is a standard for web-based authentication and authorization. It allows users to log into applications based on their session in another context, typically a centralized identity provider (IdP).

The SAML2 authentication configuration allows you to set up SAML2 for your Clarive instance as an alternative to the internal authentication mode.

Configuration Parameters

Below are the most relevant config parameters that can be set in Clarive and their meanings:

saml2:
    issuer: 'myclariveapp'
    idp_cert: '...'  # inlined certificate string
    idp_cert: '/PATH/TO/idp.pem'  # certificate path to .pem file
    entry_point: 'https://idp.example.com/login'  # SAML2 provider login url
    header: 'SAMLResponse' # either a header or parameter
    attribute_statement_path: '//saml:Assertion/saml:AttributeStatement'
    attribute_node: './/saml:Attribute'
    attribute_key: 'email'
    active: true

Warn

The mere existance of the saml2 key is enough to put Clarive in SAML2 login mode. Make sure to never leave the saml2: dangling in your [config].yml file otherwise it will continuously attempt to login using SAML2 parameters/headers.

Required Parameters

These parameters are required:

  • idp_cert: A string or path representing the identity provider's (IdP) certificate. It can be a single-line string starting like MIIC8DCCAdigAwI... or a multi-line string starting with -----BEGIN CERTIFICATE--- If it's a path to a valid file, it should be the identity provider's certificate in .pem format. This certificate is used for validating the SAML responses.

  • issuer: The name of the service in the eyes of the IdP. The issuer is your Clarive tenant ID, "the service provider" in IdP terms. This is set to a default of clarive-saml, but you should match that to whatever name has been defined to in the IdP or set clarive-saml in the IdP.

These parameters are not mandatory, but recommended as each installation must have

  • entry_point: The URL of the identity provider's login page. This is the endpoint where the user will be redirected requesting a callback response to Clarive.

  • service_url: This is the main URL entrypoint for the Clarive app, the "service" in SAML2 terms. It's used in the login request XML to the IdP. If not defined, the [config].yml url parameter will be used instead. It's not guaranteed to be used by the IdP, some providers may overwrite the value with its internally defined URL for the service.

  • logout_url: This is the URL that the user will be redirected to when the user hits the "Logout" option in the user menu in Clarive. If the logout_url value is empty '' or undefined the user will be taken to the Clarive login screen.

  • private_key: a multi-line RSA certifcate starting with --- BEGIN PRIVATE KEY... or the private key as a single-line string that starts like MIIC8DCCAdigAwIBAgIQa... or a path to a file containing the RSA private key /my/path/to/key.pem. The private key is used to sign the auth or logout requests going to the IdP.

  • attribute_key: The name of the attribute that will be used as the key for the user's identity. By default it's id which points to the NameID in the SAML subject. The id attribute XPath can be caonfigured using the optional nameid_path XPath setting (see below). If an AttributeStatement is present, the attribute_key could be any of the additional attributes sent by the IdP such as 'email' or 'username' or any node present in the AttributeStatement.

entry_point

If the entry_point parameter is not set, Clarive will allow users to login using internal passwords, if set AND an IdP to redirect users to Clarive with a SAMLResponse header for SSO.

attribute_key

Clarive will check the attribute_key value against both the email and username columns in its internal database. The user must exist for it to work (Clarive will not create users from SAML2) with either a matching username or email fields. The attribute value is case-sensitive. Make sure your Clarive database contains values that match the data coming from the IdP in the SAMLResponse.

Optional Parameters

  • header: The HTTP header (or HTTP query parameter) where the SAML response will be found. Default is SAMLResponse.

  • nameid_path: The XPath to the node where to get the SignedInfo from the SAMLResponse. Example value: //ds:SignedInfo

  • attribute_statement_path: The XPath to the SAML attributes statement within the SAML assertion. This path is used to locate the attribute statement in the SAML response. For example //saml:Assertion/saml:AttributeStatement.

  • attribute_path: The XPath to the name of each of the SAML attributes within the SAML attribute statement node. For example //saml:Attribute.

  • attribute_value_path: The XPath to the individual attribute nodes within the attribute statement. This path is used to locate the attribute value in the SAML response for each name pair.

  • digest_path: The XPath to the node where to get the DigestValue from the SAMLResponse for digest verification. Digest verification is optional by default, meaning it will not stop SAML2 validation from happening. Example value //saml:Assertion//ds:DigestValue

  • signed_info_path: The XPath to the node where to get the SignedInfo node from the SAMLResponse. Example value: //ds:SignedInfo

  • signature_value_path: The XPath to the node where to get the SignatureValue node from the SAMLResponse. Example value: //ds:SignatureValue

  • active: An optional boolean value that enables or disables the SAML2 authentication. Set to true to activate SAML2 authentication, or false to deactivate it.

Examples

Here is an example of how the SAML2 configuration might look in your configuration YAML file CLARIVE_BASE/[config].yml. This example has the IdP public certificate inlined:

saml2:
    entry_point: 'https://my.idp.server/login'
    attribute_key: username
    idp_cert: |  # example certificate string
        -----BEGIN CERTIFICATE-----
        MIIDkjCCAnoCCQD8pdU4gpgmMjANBgkqhkiG9w0BAQsFADCBiTELMAkGA1UEBhMC
        ZXMxDzANBgNVBAgMBm1hZHJpZDEPMA0GA1UEBwwGbWFkcmlkMRAwDgYDVQQKDAdj
        bGFyaXZlMRAwDgYDVQQLDAdjbGFyaXZlMRAwDgYDVQQDDAdjbGFyaXZlMSIwIAYJ
        KoZIhvcNAQkBFhNjbGFyaXZlQGNsYXJpdmUuY29tMCAXDTI0MDYwNDEzNTkwN1oY
        DzMwMjMxMDA2MTM1OTA3WjCBiTELMAkGA1UEBhMCZXMxDzANBgNVBAgMBm1hZHJp
        ZDEPMA0GA1UEBwwGbWFkcmlkMRAwDgYDVQQKDAdjbGFyaXZlMRAwDgYDVQQLDAdj
        bGFyaXZlMRAwDgYDVQQDDAdjbGFyaXZlMSIwIAYJKoZIhvcNAQkBFhNjbGFyaXZl
        QGNsYXJpdmUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwWtd
        lzrXVx70nLuXffxwKsD3bkf7/4sGdrL4bf/suq1QZZGA8T4ch9HSAlMp6eQkSqm8
        /HbBycqHtDYoxJMT/Jq0Sdjqp4qb/w+Y2WJhkK5bDHOsvqdx89oINjaRL/92Y1jZ
        P0B2T6MoFdji12CUiChXi6r07wYqy3lNQvNCHg786ZwEYOyGpmXMWyGRtciKYEM6
        f/Cv26YCBklcDZt+t6Sp+Fzr97J56shYpVE3G40IYp5MpgXooL4iPqqFqgnTn12G
        8/xKCAcc2HB035+rY/2sFiHspYtCRBfMZyT1hgviDYdtPUMvCKmYyMC97AngkGR3
        WX513xFAqaVrJ/gdpQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQCMOxH70ZEQhQqV
        /D0C5F5x4EVfepiIbV3GU01/qBt84pIE36plaYB8kAowgTc/7tqNoS9/EgmWAFgU
        kn+u32q4uwnkN9pqI6K1LgHrSMRICB8oqHUlbzxUbnzf+35r9FhWbe6f4vE7HI6t
        ItFq5VMvqDZfGl9GhmagX1IjUN2srls3cficWKB9hNwN0BXP88UA7M9wPwUd0F5a
        uZq7nG+yhufKCWVRBBpTIv3G96naHpHfvPLcCZIX5mq3qx3P+9FwvPX+x8gCLHqe
        1UjTvp7z+sEgzs5g11LMhZVapsEKUhbJ3fWZgBL+Epo5aQz7yUvxc0K3wbTaWBv0
        tfbwdDPL
        -----END CERTIFICATE-----

Ensure that the certificate string (idp_cert) or the certificate path is correctly provided, and that the entry_point URL is accurate for your IdP.

Alternatively, you can use a fully qualified path to the certificate:

saml2:
    issuer: 'myclariveapp'
    entry_point: 'https://my.idp.server/login'
    idp_cert: '/opt/certs/idp_cert.pem'

Restart after changing the configuration

Any changes to the YAML configuration [config].yml requires a full start.

SAML2 Activity and Events

Clarive issues 2 events that registers any successful and fail attempts to login with SAML2 activated:

  • event.auth.saml_ok - a user has logged in to Clarive successfully

  • event.auth.saml_failed - a failed attempt to login in SAML2 mode was registered.

In case of a successfull login, the following attributes are sent as event variables (the user_attributes may vary according to your IdP SAMLResponse configuration):

type: saml2
user_attributes:
  email: [email protected]
  firstName: janedoe
  id: 605a07f56226774ca510bdc4af920522c4442661b8857c89e28b7f56cadbb8eb
  lastName: Doe
username: janedoe

Check the logs

Also check the Clarive webserver logs for error messages and start Clarive in debug mode cla web-start -d to debug possible SAML2 problems.

Customizing XML Paths in the SAML Response

Clarive allows the administrator to configure the XPaths used to parse the SAMLResponse. This is an advanced feature and typically not required.

If you are about to configure attribute_statement_path, attribute_path, attribute_value_path and other XPath parameters, it is essential to understand how to write the correct XML paths (XPaths) to match the structure of the SAMLResponse XML for your installation.

Available XPath parameters are:

nameid_path
attribute_statement_path
attribute_path
attribute_value_path
digest_path
signed_info_path
signature_value_path

Understanding XML Paths (XPaths)

XPath is a query language for selecting nodes from an XML document. It is used to navigate through elements and attributes in an XML document. Here are some key concepts for writing XPaths:

  • Root Node: The top-level element in the XML document. In SAML responses, this is typically the <Response> element.
  • Element: A component of the XML document, such as <Assertion> or <AttributeStatement>.
  • Attribute: A name-value pair within an element, such as <Attribute Name="email">.

Common XPath Syntax

  • Single Slash (/): Selects the immediate child element. For example, /Response selects the <Response> element at the root level.
  • Double Slash (//): Selects elements from anywhere in the document. For example, //Assertion selects all <Assertion> elements in the document.
  • Element Name: Selects all elements with the specified name. For example, //saml:Attribute selects all <saml:Attribute> elements.
  • Attribute Selector (@): Selects elements with a specific attribute. For example, //saml:Attribute[@Name='email'] selects all <saml:Attribute> elements with the attribute Name equal to email.

Login screen with SSO SAML2 enabled

Once SAML2 is enabled in the config, Clarive will always redirect to the SSO login URL. To disable SSO temporarily and login using the standard login page, use the sso=0 login URL parameter.

https://myclariveserver/?sso=0

This will take the user to the standard Clarive login.

Git, Webservice and API Key Login

The Clarive Git interface uses Basic HTTP Auth from the command line or other git clients and will not redirect the user to the SSO SAML2 provider login.

The same happens when using the Webservice API key login which will still work using API keys defined on a user basis and not depend on the SSO infraestructure.

Both logins can be accomplished by creating an API key and using it as the password (specially in Git's case).

Example SAML Response Structure

Here is an example of a typical SAMLResponse structure:

<Response>
    <Assertion>
        <AttributeStatement>
            <Attribute Name="email">
                <AttributeValue>[email protected]</AttributeValue>
            </Attribute>
        </AttributeStatement>
    </Assertion>
</Response>

These paths are used to navigate the SAML response and extract the necessary attributes.

Example Config for Microsoft Azure Entra ID

This is a complete example of how to setup the Azure Entra ID Single sign-on:

saml2:
    issuer: 'myclarive'
    service_url: 'https://myclarive.example.com/'
    entry_point: 'https://login.microsoftonline.com/9a624754-aa30-4cab-af32-c71b8af0ca50/saml2'
    logout_url: 'https://login.microsoftonline.com/9a624754-aa30-4cab-af32-c71b8af0ca50/saml2'
    idp_cert: |
      -----BEGIN CERTIFICATE-----
      MIIC9DDD....
      TylNaWNyb3....
      STNaFw0yN....
      U1NPIENlc....
      S7o3oJ3li....
      -----END CERTIFICATE-----

In the Microsoft Azure > Manage > Single sign-on > Basic SAML Configuration set the fields to the corresponding values in your CONFIG.yml file: