Ricardo Martinez
CTO
September 3, 2024 - 7 mins read

SAML 2.0 Support

Clarive Announces SAML 2.0 Support Integration for Enhanced Security and Seamless SSO Experience

At Clarive, we’re always striving to make our platform more secure, flexible, and user-friendly. We’re excited to announce the latest update: SAML 2.0 (Security Assertion Markup Language 2.0) support. This new feature allows you to configure Single Sign-On (SSO) authentication for your Clarive instance using your existing Identity Provider (IdP). Whether you’re using Microsoft Azure Entra ID, Google Identity, or any other SAML 2.0 compatible IdP, integrating with Clarive is now smoother than ever.

In this blog post, we’ll dive deep into the technical aspects of setting up SAML 2.0 in Clarive, explore the configuration options, and provide examples to help you integrate with popular IdPs like Azure and Google.

What is SAML 2.0?

SAML 2.0 is a standard for web-based authentication and authorization. It enables users to authenticate to multiple applications using a single set of credentials, managed by a centralized Identity Provider (IdP). With SAML 2.0, you can log into Clarive based on your existing session with the IdP, enhancing security and user experience by eliminating the need for multiple logins.

Why Use SAML 2.0 with Clarive?

Enabling SAML 2.0 in Clarive offers several advantages:

  • Single Sign-On (SSO): Users only need to log in once with their IdP credentials, and they can access Clarive without additional authentication.
  • Centralized Identity Management: Manage users, roles, and permissions in one place—your IdP—streamlining user administration.
  • Enhanced Security: SAML 2.0 supports strong encryption and digital signatures, ensuring that authentication data is secure.
  • Compliance: Organizations with strict regulatory requirements can use SAML 2.0 to meet their security and auditing needs.

Setting Up SAML 2.0 in Clarive

Configuring SAML 2.0 in Clarive involves setting up the config.yml file in your Clarive instance. This file allows you to define various parameters that control how SAML 2.0 authentication works. Let’s go through the most important configuration options.

Basic Configuration Parameters

Here’s a minimal example of what your config.yml file might look like:

saml2:
    issuer: 'myclariveapp'
    idp_cert: '/PATH/TO/idp.pem'
    entry_point: 'https://idp.example.com/login'
    attribute_key: 'email'
    active: true

Key Configuration Parameters:

  • issuer: This is the identifier for your Clarive instance, known as the Service Provider (SP) in SAML terms. It’s what your IdP uses to recognize your Clarive service. The default value is clarive-saml, but you should match it to the identifier defined in your IdP.

  • idp_cert: This is the certificate used to validate the SAML responses from the IdP. You can provide it either as an inline string or as a path to a .pem file. It’s crucial that this certificate is accurate and corresponds to your IdP’s certificate.

  • entry_point: The URL where users will be redirected for login. This should be the login URL provided by your IdP.

  • attribute_key: The SAML attribute used to identify the user in Clarive. Common values are email or username. This attribute must match the corresponding value in Clarive’s user database.

  • active: This boolean value activates or deactivates SAML 2.0 authentication. Set this to true to enable SAML 2.0.

Advanced Configuration Parameters

While the basic configuration gets you started, Clarive offers advanced options to fine-tune how SAML 2.0 operates.

saml2:
    header: 'SAMLResponse'
    nameid_path: '//saml:Assertion/saml:Subject/saml:NameID'
    attribute_statement_path: '//saml:Assertion/saml:AttributeStatement'
    attribute_path: '//saml:Attribute'
    attribute_value_path: './/saml:AttributeValue'
    digest_path: '//saml:Assertion//ds:DigestValue'
    signed_info_path: '//ds:SignedInfo'
    signature_value_path: '//ds:SignatureValue'

Detailed Explanation of Advanced Parameters:

  • header: The HTTP header or query parameter where the SAML response is found. By default, this is SAMLResponse.

  • nameid_path: XPath to the NameID element in the SAML response, typically used for identifying the user.

  • attribute_statement_path: XPath to the AttributeStatement element, which contains user attributes in the SAML response.

  • attribute_path: XPath to the individual attribute names within the AttributeStatement.

  • attribute_value_path: XPath to the values of the attributes identified by attribute_path.

  • digest_path: XPath to the DigestValue used for verifying the integrity of the SAML response.

  • signed_info_path: XPath to the SignedInfo node in the SAML response, used for signature validation.

  • signature_value_path: XPath to the SignatureValue in the SAML response.

Example: Integrating with Microsoft Azure Entra ID

Integrating Clarive with Microsoft Azure Entra ID for SAML 2.0 is straightforward. Below is an example configuration for your config.yml:

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 Azure portal, navigate to Microsoft Azure > Manage > Single sign-on > Basic SAML Configuration and set the fields to match the values in your Clarive config.yml file.

Setting Up the IdP Certificate:

  • Obtain the Certificate: In the Azure portal, download the SAML signing certificate.
  • Place the Certificate: Store the certificate in a secure location on your Clarive server.
  • Update the Config: Reference this certificate in your config.yml under idp_cert.

Example: Integrating with Google Identity

For Google Identity, the process is similar. Here’s how you might configure your Clarive instance:

saml2:
    issuer: 'myclarive'
    service_url: 'https://myclarive.example.com/'
    entry_point: 'https://accounts.google.com/o/saml2/idp?idpid=C02a2fkj3'
    logout_url: 'https://accounts.google.com/logout'
    idp_cert: '/opt/certs/google_idp_cert.pem'

Steps for Google Identity Integration:

  1. Create a SAML App in Google Admin: In the Google Admin console, create a new SAML app for Clarive.
  2. Configure the Service Provider Details: Set the ACS URL, Entity ID, and other required fields to match your Clarive instance.
  3. Download the Certificate: Obtain the Google Identity IdP certificate and place it on your Clarive server.
  4. Update the Config: Point to this certificate in your config.yml file.

Customizing XML Paths in SAML Responses

Clarive allows you to customize the XPaths used to extract information from the SAML response. This is useful if your IdP sends a custom XML structure.

For example, if your SAML response looks like this:

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

You might configure the following XPaths:

saml2:
    nameid_path: '//saml:Assertion/saml:Subject/saml:NameID'
    attribute_statement_path: '//saml:Assertion/saml:AttributeStatement'
    attribute_path: '//saml:Attribute'
    attribute_value_path: './/saml:AttributeValue'

Understanding these paths ensures that Clarive correctly interprets the SAML response, extracting the necessary user attributes for authentication.

Testing and Debugging Your SAML 2.0 Setup

After configuring SAML 2.0, you should thoroughly test the setup. Clarive provides two key event logs to help you monitor the authentication process:

  • event.auth.saml_ok: This event is triggered when a user successfully logs in via SAML 2.0.
  • event.auth.saml_failed: This event logs any failed SAML 2.0 login attempts.

Debugging Tips:

  • Check the Logs: Start the Clarive webserver in debug mode using cla web-start -d and check the logs for any error messages.
  • Verify Certificate Paths: Ensure the idp_cert path or inline certificate string is correctly configured.
  • Test Attribute Matching: Make sure the attribute_key value matches the attributes in your Clarive database. Remember, attribute values are case-sensitive.

Documentation

The configuration documentation is available at:

https://docs.clarive.com/setup/saml/

Conclusion

With SAML 2.0 support, Clarive is taking a significant step forward in offering enhanced security and a seamless user experience. Whether you’re using Microsoft Azure, Google Identity, or any other SAML-compliant IdP, the integration process is straightforward, flexible, and highly configurable. We encourage all users to explore the benefits of SAML 2.0 and consider integrating it into your Clarive environment.

Stay tuned for more updates and features that make Clarive the DevOps tool of choice for enterprises worldwide.

If you have any questions or need assistance with your SAML 2.0 setup, don’t hesitate to contact our support team. Happy deploying!