This section explains how to integrate your Qumulo cluster with your organization's single sign-on (SSO) service by configuring Security Assertion Markup Language (SAML) 2.0 for Qumulo Core 5.2.5.1 (and higher).

For more information about the SAML standard for exchanging authentication information, see SAML 2.0.

Prerequisites

Before you begin, make sure that you have done the following.

  • Join your cluster to an Active Directory (AD) domain. For more information, see Join Your Qumulo Cluster to Active Directory on Qumulo Care.

  • To allow the cluster to find group memberships for SAML-authenticated users, configure the Base DN in your AD configuration, even if you don’t use POSIX attributes.

  • Ensure that your SAML Identity Provider (IdP) is linked to the same AD. An identity provider (such as Azure AD, Duo, or Okta) is a system that authenticates users (for example, by using passwords and additional factors).

    Typically, an IT department manages an IdP centrally and the IdP is linked with AD. Before you can enable SSO, your IT department must register a new Service Provider (SP) in your IdP. A service provider is the server which users access, in this case a Qumulo cluster.

  • Configure your IdP to return AD User Principal Names (UPNs, for example alice@example.com) or an email address as a NameID. A NameID is an identifier for an authenticated user. Typically, a NameID uses the format of an email address.

To Configure SAML SSO for Your Qumulo Cluster

This process requires coordination between the cluster administrator and SSO administrator.

  1. The cluster administrator contacts the SSO administrator and asks the SSO administrator to create a SAML integration for the Qumulo cluster.

  2. The SSO administrator creates a SAML integration with your organization’s SSO identity provider (IdP).

    a. The SSO administrator uses the cluster’s fully qualified domain name (FQDN) format for the service provider (SP) endpoint (also known as the assertion consumer service URL), in the following format:

    https://<my-cluster>.<my-org>.com/saml
    

    b. If prompted, the SSO administrator enters the HTTP POST binding for the SP endpoint. Typically, this binding is specified by default.

    c. If prompted for SP Entity ID (alternatively named Application Identifier or Audience), the SSO administrator enters https://<my-cluster>.<my-org>.com/saml.

    d. If SAML Signing (depending on the SSO service, this option is named differently) configuration is available, the SSO administrator sets it to Sign SAML response and assertion.

  3. After creating the SAML integration, the SSO administrator provides the following information to the cluster administrator.

    • The certificate (public key) of the identity provider, in a .pem file.

      This certificate lets the cluster verify the authenticity of the messages from the IdP.

    • The IdP SSO URL—to which the Qumulo cluster can send authentication requests—in the following format:

      https://<my-org>.<sso-provider>.com/foo
      
    • The IdP issuer or EntityId.

      For example:

      http://www.<sso-provider>.com/abc12de34fgAB5CDh6i7
      
    • The FQDN of the cluster, in the following format:

      <qumulo-cluster>.<my-org>.com
      
  4. To configure and enable SAML login to the Qumulo cluster, the cluster administrator runs the qq saml_modify_settings command. For example:

    qq saml_modify_settings --enable \
      --idp-certificate-file ~/certificate.pem \
      --cluster-dns-name <qumulo-cluster>.<my-org>.com \
      --idp-entity-id http://www.<sso-provider>.com/abc12de34fgAB5CDh6i7 \
      --idp-sso-url https://<my-org>.<sso-provider>.com/abc12de34fgAB5CDh6i7/saml \
    

Supported SAML SSO Workflows

Qumulo Core supports three SAML SSO workflows:

  • Standard SAML workflows that the IdP or SP initiates
  • A workflow that the qq CLI initiates

IdP-Initiated SSO Worfklow

  1. A user authenticates to her organization’s SSO portal and then selects the Qumulo cluster on the SSO portal.

  2. The SSO portal redirects the user to the cluster’s endpoint.

    If the user has sufficient privileges, the Web UI logs the user in. Otherwise, the Web UI displays an error message.

SP-Initiated SSO Workflow

  1. A user navigates to the Qumulo cluster’s Web UI endpoint in a browser.

  2. If the Qumulo cluster has SAML SSO configured, the user can click Continue to SSO login on the Web UI login page.

    The Web UI redirects the user to the configured SSO portal. Because the authentication request uses HTTP-Redirect Binding, the login URL appears.

    https://<my-org>.<sso-provider>.com/abc12de34fgAB5CDh6i7/saml?SAMLRequest=abcdefgh1234567890...
    
  3. The user clicks the login link and the SSO portal authenticates the user.

  4. The SSO portal redirects the user to the cluster’s endpoint.

qq-CLI-Initiated SSO Workflow

In Qumulo Core 5.3.0 (and higher), a user can authenticate a qq CLI session by using SSO.

  1. A user uses the qq sso_login CLI command. For example:

    qq --host 203.0.113.0 sso_login
    

    The login URL and a prompt appear. The following is an example URL.

    https://<my-cluster>.<my-org>.com/saml-login?login-id=12345678-1234-1234-1234-123456789012
    
  2. When the user opens the login URL in a browser, the URL redirects the user to a configured SSO portal and one of the following two scenarios takes place:

    • If authentication succeeds, the browser shows a message that contains an eight-character verification code and asks the user to return to the CLI session.

      The user copies the verification code and enters it into the waiting prompt of the sso_login command.

      • If the verification code is correct, the command recognizes that authentication is complete and shows the authenticated username.

      • If the verification code is incorrect, the user must retry the workflow.

    • If authentication doesn’t succeed, the browser displays an error message.

      The user must retry the workflow.

Requiring SSO Authentication for Cluster Management

In Qumulo Core 5.3.0 (and higher), you can use the qq saml_modify_settings CLI command to require AD users to use SSO authentication for managing your cluster. For example:

qq saml_modify_settings --require-sso true

When the cluster requires SSO authentication, your cluster rejects password-based authentication from AD users in the Web UI, the qq CLI, and the REST API.

Known Issues and Limitations

  • Local users (the built-in admin user and any additional users) can always use their passwords to authenticate to the Web UI and the qq CLI.

  • If SSO is required for a Qumulo Core cluster, it isn’t possible to log in to the Interactive API documentation section of the APIs & Tools page in the Web UI.

  • Qumulo Core doesn’t support:

    • SAML Single Logout (SLO): We recommend clicking Sign out in the Web UI.
    • Automatic Configuration from Metadata XML: You must specify each parameter by using the qq CLI.
    • Returning to Previous Web UI Page: You can’t return to a previous page after re-authenticating (for example, after a timeout).
    • Azure AD SAML Toolkit: Currently, due to a configuration deficiency in the toolkit, IdP-initiated SSO isn’t operational for Qumulo as a Service. Use the SP-initiated SSO workflow.

Troubleshooting SAML SSO Authentication

This section explains troubleshooting common and uncommon SAML SSO authentication issues.

Common Issues

Typically, if SAML authentication fails, Qumulo Core’s in-browser error message explains the reasons for failure and you can resolve the issue by setting the right configuration by using the qq saml_modify_settings command. Examples of this issue type include the following scenarios:

  • SAML isn’t enabled on the Qumulo cluster.

  • There is clock skew between the IdP and the Qumulo cluster (the SSO service sets the clock skew tolerance, typically to 5 minutes).

  • The cluster-dns-name or idp-entity-id on the Qumulo cluster aren’t configured correctly.

  • A user isn’t a member of the Observers role that Qumulo Core requires for granting access to the Web UI.

Uncommon Issues

In more complex cases, the in-browser errors are less informative for security reasons. For example, if you configure an incorrect IdP certificate on your cluster, the Signature validation failed. SAML Response rejected. error appears.

Several AD configuration issues can cause a User not found error:

  • The Qumulo cluster isn’t joined to AD.

  • The Qumulo cluster is joined to AD that isn’t connected to the IdP.

  • IdP sends usernames (NameID) in an unusual format.

    To verify that you can use a username, run the qq auth_find_identity command. For example:

    qq auth_find_identity --name MyUsername
    
  • The Configured Base DN doesn’t include all users.

    To find a security identifier (SID), run the qq auth_find_identity command. For example:

    qq auth_find_identity --name MyUsername
    

    To verify that a username is discoverable, run the qq ad_sid_to_account command. For example:

    qq ad_sid_to_account --sid S-1-5-32-544
    

    If an error occurs, contact your AD administrator and request the correct Base DN. For more information, see Specifying the Base Distinguished Name (Base DN).