This is the documentation for Cloudera Manager 4.8.4.
Documentation for other versions is available at Cloudera Documentation.

Configuring User Authentication Using SAML

Cloudera Manager supports a number of authentication mechanisms, both internal and using external services. This includes the Security Assertion Markup Language (SAML), an XML-based open standard data format for exchanging authentication and authorization data between parties, in particular, between an identity provider (IDP) and a service provider (SP).

The SAML specification defines three roles: the principal (typically a user), the identity provider, and the service provider. In the use case addressed by SAML, the principal (user agent) requests a service from the service provider. The service provider requests and obtains an identity assertion from the identity provider. On the basis of this assertion, the service provider can make an access control decision - in other words it can decide whether to perform some service for the connected principal.

The primary SAML use case is called Web Browser Single Sign-On (SSO). A user wielding a user agent (usually a web browser) requests a web resource protected by a SAML service provider. The service provider, wishing to know the identity of the requesting user, issues an authentication request to a SAML identity provider through the user agent.

In the context of this terminology, Cloudera Manager operates as a Service Provider.

Overview and Assumptions

This document assumes that you are familiar with SAML and SAML configuration in a general sense, and that you have a functioning IDP already deployed. It will only discuss the Cloudera Manager specific part of the configuration process.

At a high level, setting up Cloudera Manager to use SAML is a three stage process.
  • Configure Cloudera Manager to act as a Service Provider.
  • Configure your IDP to recognize Cloudera Manager as a valid SP.
  • Confirm that Cloudera Manager can correctly authenticate users with the IDP.

Prerequisites and Preparation

You will need to prepare the following files and information, and provide these to Cloudera Manager:
  • A Java Keystore containing:
    • A private key for CM to use to sign/encrypt SAML messages
    • Any public certificates needed to verify the sign/encrypt key used by your Identity Provider
  • The SAML metadata XML file from your IDP
  • The entity ID that should be used to identify the Cloudera Manager instance
  • How the user ID is passed in the SAML authentication response:
    • As the NameID
    • As an attribute. If so, what identifier is used.
  • The method by which the Cloudera Manager role will be established (admin vs. regular user):
    • From an attribute in the authentication response:
      • What identifier will be used for the attribute
      • What values will be passed to indicate each role
    • From an external script that will be called for each use:
      • The script takes user ID as $1
      • The script sets an exit code to reflect assigned role
        • 0 = admin
        • 1 = regular user
        • -1 = failure

Configuring Cloudera Manager

  1. Start the server normally and log in using an Admin account.
  2. From the Administration tab, select Settings, then External Authentication.
  3. Set the External Authentication Type to SAML (note that the Authentication Backend Order is ignored for SAML).
  4. Set the metadata XML file path to point to the IDP's metadata file.
  5. Set the keystore file path to point to the Java Keystore prepared earlier.
  6. Set the Keystore’s password.
  7. Set the alias used to identify the private key for CM to use.
  8. Set the private key’s password.
  9. Set the entity ID if necessary:
    • If there is more than one CM instance being used with the same IDP (each instance needs a different entity ID).

    • If entity IDs are assigned by organizational policy.

  10. Set whether the user ID will be obtained from the NameID or an attribute.
  11. If an attribute will be used, set the attribute name if necessary. The default value is the normal OID used for user IDs and so may not need to be changed.
  12. Set whether the role assignment will be done from an Attribute or an external script:
    • If an attribute will be used, set the attribute name if necessary. The default value is the normal OID used for OrganizationalUnits and so may not need to be changed.

    • If an attribute will be used, set what attribute values will be used to indicate admins vs regular users.

    • If an external script will be used, set the path to that external script. Make sure that the script is executable (Note that an executable binary is fine - it doesn’t need to be a literal shell script).

  13. Save the changes:
    • CM will run a set of validations that ensure it can find the metadata XML and the keystore, and that the passwords are correct. If you see a validation error, please correct the problem before proceeding.
  14. Restart the Cloudera Manager server

Configuring the IDP

After Cloudera Manager is restarted, it will attempt to redirect to the IDP’s login page instead of showing the normal CM page. This may or may not succeed, depending on how the IDP is configured. In either case, the IDP will need to be configured to recognize CM before authentication will actually succeed. The details of this process are specific to each IDP implementation and cannot be described here - refer to your IDP’s documentation for details
  1. Download Cloudera Manager’s SAML metadata xml file:
    • http://<hostname>:7180/saml/metadata
  2. Inspect the metadata file and ensure that any URLs contained in the file can be resolved by users’ web browsers. The IDP will redirect web browsers to these URLs at various points in the process. If the browser cannot resolve them, authentication will fail.
    • If the URLs are incorrect, you can manually fix the xml file or set the Entity Base URL in the CM configuration to the right value, and then re-download the file.
  3. Provide this metadata file to your IDP using whatever mechanism your IDP provides.
  4. Ensure that the IDP has access to whatever public certificates are necessary to validate the private key that was provided to Cloudera Manager earlier.
  5. Ensure that the IDP is configured to provide the User ID and Role using the attribute names that Cloudera Manager was configured to expect, if relevant.
  6. Ensure the changes to the IDP configuration have taken effect (a restart may be necessary).

Verifying that authentication and authorization can be completed

  1. Return to Cloudera Manager and refresh the login page.
  2. Attempt to log in with credentials for a user that is entitled as an admin or a regular user.
  3. The authentication should complete and you should see the Cloudera Manager home page.
  4. If authentication fails, you will see an IDP provided error message. Cloudera Manager is not involved in this part of the process, and you must ensure the IDP is working correctly to complete the authentication.
  5. If authentication succeeds but the user is not authorized to use Cloudera Manager (as an Admin or a regular User), they will be taken to a special error page by Cloudera Manager that explains the situation.
    • If an user who should be authorized sees this error, then you will need to verify their role configuration, and ensure that it is being properly communicated to CM, whether by attribute or external script. The CM log will provide details on failures to establish a user’s role. If any errors occur during role mapping, CM will assume the user is unauthorized.

Interoperability Notes

  • Cloudera Manager supports both SP-initiated and IDP-initiated Single-Sign-On.
  • The Logout action in Cloudera Manager will send a Single-Logout request to the IDP.
  • SAML authentication has been tested with specific configurations of Siteminder and Shibboleth. While SAML is a standard, there is a great deal of variability in configuration between different IDP products, so it is possible that other IDP implementations, or other configurations of Siteminder and Shibboleth, may not interoperate correctly with Cloudera Manager.