SAML

SAML¶

Comet Self-Hosted supports SAML (Security Assertion Markup Language) integration, enabling federated single sign-on (SSO) with your preferred identity provider (IdP). This guide will walk you through configuring Comet to set up a basic SAML application compatible with various IdP vendors.

For vendor-specific instructions, please refer to the documentation linked below or in the navigation menu. Integrating an SSO IdP with Comet allows users to log in using their organizational directory credentials. New users logging in via SSO for the first time will have their Comet accounts automatically created based on their SSO Directory information. Post-login, these users gain full access to Comet's features, akin to users who sign in using basic authentication. Note that the first account created in Comet, regardless of the method (IdP or basic auth), is granted admin privileges.

If your IdP vendor is not listed in our specific documentation, do not hesitate to contact us for support. Given the standardized nature of SAML, it is highly probable that your vendor is supported.

Glossary of Key Terms¶

• SP or Service Provider: In the context of Comet, the Service Provider refers to the Comet application itself. It's where users want to gain access and is the system that relies on the Identity Provider to authenticate user identities.

• IdP or Identity Provider: This is the system that manages user identities and performs authentication, typically a Single Sign-On (SSO) service. Examples include Okta, Google, GitHub, JumpCloud, and Azure AD. In the SAML process, the IdP verifies user credentials and sends a SAML assertion to the SP to grant user access.

• SP ACS URL: (Service Provider Assertion Consumer Service URL): This is the URL where the SAML assertion is sent by the Identity Provider (IdP). It acts as a receiver of the SAML response from the IdP, processing it to authenticate the user.

• SP ENTITY ID: Also known as the Service Provider Entity ID or Audience URI, this is a unique identifier for the Service Provider in the SAML transaction. It is used by the IdP to identify the SP and ensure that the SAML response is sent to the correct entity.

• IdP ENTITY ID (Identity Provider Entity ID): This is a unique identifier for the Identity Provider. It is used within the SAML transactions to ensure that the SAML assertions come from and are sent to the correct IdP.

• IdP SSO URL (Identity Provider Single Sign-On URL): This is the URL to which the Service Provider sends its SAML authentication requests. This URL is typically found in the IdP's metadata and is where users are redirected for authentication against the IdP.

• IdP Cert File (Identity Provider Certificate File): This is a digital certificate used by the Identity Provider to sign SAML responses and assertions. The Service Provider uses this certificate to verify the authenticity and integrity of the received SAML messages.

• Attribute Mapping: This refers to the process of mapping user attributes (like email, name, roles) provided by the IdP in the SAML assertion to the corresponding user account fields in the Service Provider's system. This mapping is crucial for ensuring that user information is correctly utilized and displayed within the SP's application.

Ensure SSL is enabled¶

Before proceeding with the SAML configuration, be sure to enable SSL on your deployment, as it is required for using SAML.

IdP (Identity Provider) Configuration¶

Before integrating Comet with SAML, the first crucial step is to configure the Identity Provider (IdP). This setup involves several key components that ensure secure and proper communication between the IdP and Comet as your Service Provider (SP). Here's a generic outline for configuring your IdP:

Register Comet as a Service Provider: In your IdP's management console, you will need to register Comet as a new Service Provider. This is typically done by providing the SP Entity ID and ACS (Assertion Consumer Service) URL.

• Set the SP Entity ID to https://<COMET_BASE_URL>.
• For the ACS URL, use https://<COMET_BASE_URL>/aws-sso/acs/aws_saml/aws_saml. These URLs ensure that SAML assertions from the IdP are correctly sent and processed by Comet.

Obtain IdP Configuration Details: After setting up Comet in your IdP, the IdP will provide key configuration details. You need to obtain the following from your IdP:

• IdP Entity ID: A unique identifier for your IdP within the SAML transactions.
• IdP SSO URL: The URL where Comet will send SAML authentication requests.
• IdP Certificate File: A digital certificate file used for securely signing SAML responses.

Required attribute mapping¶

Specific user attributes must be correctly mapped to corresponding fields in Comet, the Service Provider (SP). The required attribute mappings in Comet are:

• guid - (Global Unique Identifier): This attribute is essential as it uniquely identifies each user within the system.
  The guid should be a unique and persistent identifier assigned by the IdP to each user.
  It ensures that each user's activities and data in Comet are correctly linked to their identity.
  Here are examples of what to map to the guid for some popular IdPs:

  • Okta: Okta User ID
  • Google Workspace (formerly G Suite): id
  • Azure Active Directory (Azure AD): userPrincipalName or objectID
  • JumpCloud: uid
  • OneLogin: OneLogin User ID

• email: The email attribute should be mapped to match the user's email address. This is not only used for identification but also for communication purposes within Comet. The email address acts as a key identifier for user accounts and is essential for features like notifications and password recovery.

Vendor specific Configuration intructions¶

We have vendor specific configuration examples for your convenience.

• AWS SSO
• Azure AD
• JumpCloud

Application Configuration¶

• Enter IdP Details in Comet: Once you have the above information from your IdP, input these details into the corresponding fields in the Comet application configuration:

aws_saml_enabled: true
aws_saml_sp_entity_id: "https://<COMET_BASE_URL>"
aws_saml_sp_acs_url: "https://<COMET_BASE_URL>/aws-sso/acs/aws_saml/aws_saml"
aws_saml_idp_entity_id: "<PROVIDED BY IDP>"
aws_saml_idp_sso_url: "<PROVIDED BY IDP>"
aws_saml_idp_cert_file: /opt/comet-ml/certs/saml.pem
aws_saml_debug: true
environment_token: onprem-dn

By following these steps, you will establish a secure SAML integration between your chosen IdP and Comet, enabling seamless single sign-on capabilities for your users.

Signing your SAML requests¶

Optional If your SAML workflow requires signed tokens to be sent by the SP, you can set this on the application side by setting the following variable (Default: False)

aws_saml_security_authnrequest_signed: true

Troubleshooting¶

If you encounter issues with your SAML configuration, the following steps can be instrumental in identifying and resolving them:

• Utilize SAML Tools for Configuration Validation: We highly recommend using online tools like https://www.SAMLTool.com (Provided by OneLogin) for validating your SAML configurations.
  This website offers various utilities to check your SAML requests, responses, and certificates, helping you identify any misconfigurations or errors.

• Capture IdP Responses in the Browser: Often, inspecting the SAML response directly from the Identity Provider (IdP) can provide insights into issues.
  To do this:

  • Open the browser's Developer Tools (usually F12 or right-click and select "Inspect").
  • Navigate to the 'Network' tab.
  • Attempt to authenticate via SAML and monitor the network traffic.
  • Look for requests containing aws_saml in the URL. These requests pertain to your SAML interactions.
  • Examine the SAML response for any error messages or discrepancies.
    Remember, the most common issues in SAML integration include incorrect entity IDs, ACS URLs, or problems with the certificate file. Double-checking these settings against your IdP’s configuration can resolve many issues.