Authenticate with SAML

One of the preferred methods for handling authentication is to use Security Assertion Markup Language, using the SAML 2.0 protocol. Security Assertion Markup Language (SAML) is an open standard for authentication and authorizing data between applications. LogScale implements the SAML 2.0 Web Browser SSO Profile. This means authentication is delegated to an existing identity provider (IDP) which is responsible for managing user credentials.

Leveraging an existing SSO solution in an organization provides users with a seamless log-on experience: If they are already logged on through their SSO they will not be prompted for credentials. Instead, authentication will be handled transparently by LogScale and the IDP. This means LogScale will never see the credentials of the user since the authentication is delegated to the IDP. You should be able to use LogScale with any SAML 2.0 provider.

The diagram shows how the user, LogScale, and a SAML identity provider interact.

sequenceDiagram participant User participant Browser participant SP as Service Provider (LogScale) participant IdP as Identity Provider User->>Browser: Access LogScale Browser->>SP: Request access SP->>Browser: Redirect to IdP with SAML request Browser->>IdP: Forward SAML request IdP->>Browser: Authentication prompt User->>Browser: Enter credentials Browser->>IdP: Submit credentials IdP->>IdP: Validate credentials IdP->>Browser: Return SAML assertion Browser->>SP: POST SAML assertion to ACS endpoint SP->>SP: Validate SAML assertion SP->>SP: Create session SP->>Browser: Return access token Browser->>User: Display LogScale dashboard

Click on the links below to learn more about the identity providers that LogScale can be configured to use:

Active Dir. Federation Svc.

Entra ID (formerly Azure Active Dir.)

Duo Security

Okta

PingOne

Google

Auth0

SAML authentication methods comparison for LogScale

This table provides a comparison of some of the different SAML authentication methods that can be integrated with LogScale for identity and access management. This table is not exhaustive; LogScale works with SAML regardless of provider.

Feature ADFS Entra ID Duo Security Okta PingFederate Google Workspace Auth0
Description Windows-based authentication software component from Microsoft Microsoft's enterprise cloud-based identity and access management solution Authentication service with Duo Access Gateway (DAG) Cloud-based identity management service Global authentication authority supporting SAML, OAuth, and OpenID Connect Google's suite of cloud productivity and collaboration tools Identity-as-a-service platform that provides authentication, authorization, and user management for applications
Group synchronization Yes, via LDAP attributes Yes, with Object ID mapping - need to find out Yes, via Group Attribute Statements Yes Similar to Entra ID approach Yes, using the Authorizations extension
User Provisioning Manual or automatic via AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN Manual or automatic with group assignment Manual account creation required Manual assignment in Okta Manual user creation in PingFederate Manual or automatic with configuration Manual user creation in Auth0 dashboard or automatic with AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN
Certificate Management Standard X.509 certificate Supports certificate rotation with primary and alternative certificates Certificate required from Duo X.509 certificate from Okta Certificate from PingFederate metadata Standard certificate approach Identity Provider Certificate downloaded from Auth0 dashboard
Attribute Mapping Supports mapping LDAP attributes as claims Supports custom attribute mapping for users and groups Basic attribute mapping Supports custom attribute mapping with regex Attribute contracts for mapping Standard attribute mapping Standard SAML attribute mapping supported
Configuration Complexity Moderate - requires Relying Party Trust setup High - multiple steps for app registration, attribute mapping Moderate - requires DAG setup Low to moderate - straightforward app creation Moderate to high - multiple configuration steps Moderate - similar to Azure setup Low to moderate - straightforward app creation
Special Features LDAP integration Detailed group management, multiple domains MFA capabilities Email customization for user invitations Browser SSO with various binding options Integration with Google Workspace User management dashboard and application integration capabilities
Entity ID Format URL to metadata endpoint URL to metadata endpoint URL to metadata endpoint URL to metadata endpoint URL to metadata endpoint URL to metadata endpoint URL to metadata endpoint

Key differences and considerations for the various SAML authentication methods are:

  • ADFS: Best suited for organizations already using Active Directory; requires Windows server

  • Entra ID: Ideal for Microsoft 365 organizations; offers extensive group management

  • Duo Security: Focuses on multi-factor authentication with additional security features

  • Okta: User-friendly setup with extensive application integration options

  • PingFederate: Enterprise-grade solution with comprehensive federation capabilities

  • Google Workspace: Good choice for organizations already using Google's ecosystem

  • Auth0: Cloud-based identity platform with flexible authentication options and user management interface

Configure SAML for LogScale Self-Hosted

LogScale needs to know the specifics about the Identity Provider. This is configured through configuration variables in the LogScale configuration. To learn more about setting configuration, see Configuration Settings.

Environment variable Description Example
AUTHENTICATION_METHOD Specifies the authentication method to use for LogScale saml
PUBLIC_URL The base URL of your LogScale server; required for redirects to work properly https://logscale.example.com
SAML_IDP_SIGN_ON_URL The URL to which users are redirected to begin the authentication flow. When a user tries to access LogScale the authentication flow will start by redirecting the user to the URL specified in this environment variable. Upon a successful authentication the user will be redirected back to LogScale where a LogScale-specific access token will be issued. The redirect back to LogScale is handled by the SAML Assertion Consumer Service endpoint located at http://$YOUR_LOGSCALE_URL:$PORT/api/v1/saml/acs. The SAML binding used in this interaction is the HTTP POST Binding. While the logon interaction from LogScale to the IDP is done through a HTTP Redirect (GET) Binding. https://accounts.google.com/o/saml2/idp?idpid=C0453
SAML_IDP_ENTITY_ID Identifier for your Identity Provider; used internally in the authentication flow https://accounts.google.com/o/saml2?idpid=C0453
SAML_IDP_CERTIFICATE Path to the PEM format certificate from your Identity Provider. The provided certificate must be in PEM format (see Privacy-Enhanced Mail). If you are running LogScale in Docker make sure the file is accessible from the container by, for example, putting it in a read-only directory as described in the Container Deployment Using humio-single-node-demo (Testing Only). /home/humio/GoogleIDPCertificate-humio.com.pem
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN When true, users are automatically created in LogScale upon successful authentication; when false, users must be created in LogScale before they can log in true
AUTO_UPDATE_GROUP_MEMBERSHIPS_ON_SUCCESSFUL_LOGIN When true, user's group memberships are automatically updated on each successful login based on SAML attributes true
SAML_ALTERNATIVE_IDP_CERTIFICATE Path to an alternative PEM certificate for certificate rotation purposes /home/humio/NewGoogleIDPCertificate-humio.com.pem
SAML_DEBUG If true, SAML debug logs are generated in the humio repository. If false, logs are not generated. true

Metadata about LogScale as a SAML Service Provider is available at http://$YOUR_LOGSCALE_URL:$PORT/api/v1/saml/metadata.

Here is an example of the configuration file:

ini
AUTHENTICATION_METHOD=saml
PUBLIC_URL=$YOUR_SERVERS_BASE_URL
SAML_IDP_SIGN_ON_URL=$IDP_SIGNON_URL #  https://accounts.google.com/o/saml2/idp?idpid=C0453
SAML_IDP_ENTITY_ID=$IDP_ENTITY_ID    #  https://accounts.google.com/o/saml2?idpid=C0453
SAML_IDP_CERTIFICATE=$PATH_TO_PEM    #  /home/humio/GoogleIDPCertificate-humio.com.pem
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true  # default is false

SAML Attribute Mapping

LogScale can map SAML assertion attributes to user properties and group memberships. By default, LogScale uses the NameID value as the username, but additional attributes can be used to determine group memberships and roles.

For more information about group membership mapping and group synchronization, see Group Memberships and Group Synchronization.

Certificate management

SAML certificates play a critical role in ensuring secure authentication.

Certificate Rotation

In case multiple SAML IdP certificates are provided — one current, one to be used instead of the current because, for instance, the current is going to expire — LogScale supports certificate rotation without any service interruption. To achieve this, set the following configuration.

  1. Configure SAML IdP to support both the current and the new certificate by specifying the two certificates in the following environment variables, respectively:

  2. Perform the rotation in the IdP, which will now sign the authentication request with the new certificate. Ensure that the login is successful during this operation.

  3. Once the rotation has been done, as a cleanup recommendation remove the current (old) certificate from the IdP configuration by setting both SAML_IDP_CERTIFICATE and SAML_ALTERNATIVE_IDP_CERTIFICATE to the new certificate. This final step is necessary to prevent login failures that have occurred due to the expiration of one of the certificates. However, the issue has been fixed in LogScale v1.159 and the login failure will no longer occur after this version.

Certificate management best practices

Follow these best practices to properly manage your IdP certificates in LogScale:

  • Certificate Requirements: Use standard X.509 certificates with at least 2048-bit RSA keys and SHA-256 signatures.

  • Certificate Storage: For containerized deployments, mount certificates as read-only volumes.

    bash
    docker run -v /path/to/certs:/certs:ro -e SAML_IDP_CERTIFICATE=/certs/idp.pem humio/humio:latest

  • Certificate Validation: Always validate certificates before deploying.

    bash
    # Verify certificate details
openssl x509 -in idp_certificate.pem -text -noout

# Verify certificate expiration
openssl x509 -in idp_certificate.pem -noout -enddate

Access token lifecycle

When the SAML-specific authentication flow is finished and successful, a LogScale access token is issued by LogScale itself. Until the token expires, the IDP will not be involved in authentication of the user's requests. The lifetime of the access token is 24 hours.

New user accounts

If LogScale encounters a new user that has been granted access through the IdP it will create the user in the context of LogScale. For this purpose the NameId in the SAML authentication response will be used as the username property of the LogScale user. The recommended username is the email.

url
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">Username</saml:NameID>

By default, the user has no rights. So unless a user is otherwise granted access rights, they will not be able to do anything besides see an empty list of repositories. You can use SAML roles to control access. Otherwise, the user needs to be added explicitly as a member or admin to a repo/view to be able to access it. For information about how to manage user permissions and groups, see Manage Users and Permissions.

Log in with SAML authentication

When SAML-based authentication has been enabled, users must enter their corporate email address into the Single sign-on box from the login screen.

Troubleshoot SAML Authentication

When troubleshooting SAML authentication issues, first verify that the basic configuration is correct:

  • Verify that the PUBLIC_URL matches the URL users use to access LogScale.

  • Confirm that the IdP entity ID and sign-on URL are correctly configured.

  • Check that the certificate is in PEM format and accessible to LogScale.

To collect logs that are available in the humio repository make sure that the SAML_DEBUG environment variable is set to true.

Common error messages and their solutions

Problem Solution
SAML Response validation failed This typically indicates a certificate mismatch or incorrect IdP configuration. Verify that the certificate provided to LogScale matches the one used by your IdP.
User authenticated but has no permissions Check role mappings
SAML Response validation failed Certificate or configuration mismatch
Redirect URI mismatch Verify PUBLIC_URL configuration
Clock skew too large Check time synchronization between IdP and LogScale
Missing attributes in SAML assertion Verify IdP configuration