Configuring External Authentication for Cloudera Manager

Minimum Required Role: User Administrator (also provided by Full Administrator)

Cloudera Manager supports user authentication against an internal database and against an external service. The following sections describe how to configure the supported external services.

Configuring Authentication Using Active Directory

  1. Select Administration > Settings.
  2. In the left-hand column, select the External Authentication category.
  3. In the Authentication Backend Order field, select the order in which Cloudera Manager should attempt its authentication. You can choose to authenticate users using just one of the methods (using Cloudera Manager's own database is the default), or you can set it so that if the user cannot be authenticated by the first method, it will attempt using the second method.
  4. For External Authentication Type, select Active Directory.
  5. In the LDAP URL property, provide the URL of the Active Directory server.
  6. In the Active Directory NT Domain property, provide the NT domain to authenticate against.

    LDAP URL and Active Directory NT Domain are the only settings required to allow anyone in AD to log in to Cloudera Manager. For example, if you set LDAP URL to ldap://adserver.example.com and the Active Directory NT Domain to ADREALM.EXAMPLE.COM, AD users should now be able to log into Cloudera Manager using just their username, such as sampleuser. They no longer require the complete string: sampleuser@ADREALM.EXAMPLE.COM.

  7. In the LDAP User Groups property, optionally provide a comma-separated list of case-sensitive LDAP group names. If this list is provided, only users who are members of one or more of the groups in the list will be allowed to log into Cloudera Manager. If this property is left empty, all authenticated LDAP users will be able to log into Cloudera Manager. For example, if there is a group called CN=ClouderaManagerUsers,OU=Groups,DC=corp,DC=com, add the group name ClouderaManagerUsers to the LDAP User Groups list to allow members of that group to log in to Cloudera Manager.
  8. To automatically assign a role to users when they log in, provide a comma-separated list of LDAP group names in the following properties:
    • LDAP Full Administrator Groups
    • LDAP User Administrator Groups
    • LDAP Cluster Administrator Groups
    • LDAP BDR Administrator Groups
    • LDAP Configurator Groups
    • LDAP Navigator Administrator Groups
    • LDAP Operator Groups
    • LDAP Limited Operator Groups
    • LDAP Auditor Groups
    If you specify groups in these properties, users must also be a member of at least one of the groups specified in the LDAP User Groups property or they will not be allowed to log in. If these properties are left empty, users will be assigned to the Read-Only role and any other role assignment must be performed manually by an Administrator.
  9. Restart the Cloudera Manager Server.

Configuring Authentication Using an OpenLDAP-compatible Server

For an OpenLDAP-compatible directory, you have several options for searching for users and groups:
  • You can specify a single base Distinguished Name (DN) and then provide a "Distinguished Name Pattern" to use to match a specific user in the LDAP directory.
  • Search filter options let you search for a particular user based on somewhat broader search criteria – for example Cloudera Manager users could be members of different groups or organizational units (OUs), so a single pattern won't find all those users. Search filter options also let you find all the groups to which a user belongs, to help determine if that user should have login or admin access.
  1. Select Administration > Settings.
  2. In the left-hand column, select the External Authentication category.
  3. In the Authentication Backend Order field, select the order in which Cloudera Manager should attempt its authentication. You can choose to authenticate users using just one of the methods (using Cloudera Manager's own database is the default), or you can set it so that if the user cannot be authenticated by the first method, it will attempt using the second method.
  4. For External Authentication Type, select LDAP.
  5. In the LDAP URL property, provide the URL of the LDAP server and (optionally) the base Distinguished Name (DN) (the search base) as part of the URL — for example ldap://ldap-server.corp.com/dc=corp,dc=com.
  6. If your server does not allow anonymous binding, provide the user DN and password to be used to bind to the directory. These are the LDAP Bind User Distinguished Name and LDAP Bind Password properties. By default, Cloudera Manager assumes anonymous binding.
  7. Use one of the following methods to search for users and groups:
    • You can search using User or Group search filters, using the LDAP User Search Base, LDAP User Search Filter, LDAP Group Search Base and LDAP Group Search Filter settings. These allow you to combine a base DN with a search filter to allow a greater range of search targets.

      For example, if you want to authenticate users who may be in one of multiple OUs, the search filter mechanism will allow this. You can specify the User Search Base DN as dc=corp,dc=com and the user search filter as uid={0}. Then Cloudera Manager will search for the user anywhere in the tree starting from the Base DN. Suppose you have two OUs—ou=Engineering and ou=Operations—Cloudera Manager will find User "foo" if it exists in either of these OUs, that is, uid=foo,ou=Engineering,dc=corp,dc=com or uid=foo,ou=Operations,dc=corp,dc=com.

      You can use a user search filter along with a DN pattern, so that the search filter provides a fallback if the DN pattern search fails.

      The Groups filters let you search to determine if a DN or username is a member of a target group. In this case, the filter you provide can be something like member={0} where {0} will be replaced with the DN of the user you are authenticating. For a filter requiring the username, {1} may be used, as memberUid={1}. This will return a list of groups the user belongs to, which will be compared to the list in the group properties discussed in step 8 of Configuring Authentication Using Active Directory.

      OR

    • Alternatively, specify a single base Distinguished Name (DN) and then provide a "Distinguished Name Pattern" in the LDAP Distinguished Name Pattern property.

      Use {0} in the pattern to indicate where the username should go. For example, to search for a distinguished name where the uid attribute is the username, you might provide a pattern similar to uid={0},ou=People,dc=corp,dc=com. Cloudera Manager substitutes the name provided at login into this pattern and performs a search for that specific user. So if a user provides the username "foo" at the Cloudera Manager login page, Cloudera Manager will search for the DN uid=foo,ou=People,dc=corp,dc=com.

      If you provided a base DN along with the URL, the pattern only needs to specify the rest of the DN pattern. For example, if the URL you provide is ldap://ldap-server.corp.com/dc=corp,dc=com, and the pattern is uid={0},ou=People, then the search DN will be uid=foo,ou=People,dc=corp,dc=com.

  8. Restart the Cloudera Manager Server.

Configuring Cloudera Manager to Use LDAPS

If the LDAP server certificate has been signed by a trusted Certificate Authority (that is, VeriSign, GeoTrust, and so on), steps 1 and 2 below may not be necessary.
  1. Copy the CA certificate file to the Cloudera Manager Server host.
  2. Import the CA certificate(s) from the CA certificate file to the local truststore. The default truststore is located in the $JAVA_HOME/jre/lib/security/cacerts file. This contains the default CA information shipped with the JDK. Create an alternate default file called jssecacerts in the same location as the cacerts file. You can now safely append CA certificates for any private or public CAs not present in the default cacerts file, while keeping the original file intact.
    For our example, we will follow this recommendation by copying the default cacerts file into the new jssecacerts file, and then importing the CA certificate to this alternate truststore. 
    $ cp $JAVA_HOME/jre/lib/security/cacerts \
  $JAVA_HOME/jre/lib/jssecacerts
    $ /usr/java/latest/bin/keytool -import -alias nt_domain_name \
-keystore /usr/java/latest/jre/lib/security/jssecacerts -file path_to_cert
  3. Configure the LDAP URL property to use ldaps://ldap_server instead of ldap://ldap_server.
  4. Restart the Cloudera Manager Server.

Configuring Authentication Using an External Program

You can configure Cloudera Manager to use an external authentication program of your own choosing. Typically, this may be a custom script that interacts with a custom authentication service. Cloudera Manager will call the external program with the username as the first command line argument. The password is passed over stdin. Cloudera Manager assumes the program will return the following exit codes identifying the user role for a successful authentication:
  • 0 - Read-Only
  • 1 - Full Administrator
  • 2 - Limited Operator
  • 3 - Operator
  • 4 - Configurator
  • 5 - Cluster Administrator
  • 6 - BDR Administrator
  • 7 - Navigator Administrator
  • 8 - User Administrator
  • 9 - Auditor
and a negative value is returned for a failure to authenticate.
To configure authentication using an external program:
  1. Select Administration > Settings.
  2. In the left-hand column, select the External Authentication category.
  3. In the Authentication Backend Order field, select the order in which Cloudera Manager should attempt its authentication. You can choose to authenticate users using just one of the methods (using Cloudera Manager's own database is the default), or you can set it so that if the user cannot be authenticated by the first method, it will attempt using the second method.
  4. For External Authentication Type, select External Program.
  5. Provide a path to the external program in the External Authentication Program Path property.

Configuring Authentication Using SAML

Cloudera Manager supports 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 IDP, and the SP. 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 IDP. On the basis of this assertion, the SP 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 SP. The SP, wishing to know the identity of the requesting user, issues an authentication request to a SAML IDP through the user agent. In the context of this terminology, Cloudera Manager operates as a SP. This topic discusses the Cloudera Manager part of the configuration process; it assumes that you are familiar with SAML and SAML configuration in a general sense, and that you have a functioning IDP already deployed.

Setting up Cloudera Manager to use SAML requires the following steps.

Preparing Files

You will need to prepare the following files and information, and provide these to Cloudera Manager:
  • A Java keystore containing a private key for Cloudera Manager to use to sign/encrypt SAML messages. For guidance on creating Java keystores, see Creating Java Keystores and Truststores.
  • The SAML metadata XML file from your IDP. This file must contain the public certificates needed to verify the sign/encrypt key used by your IDP per the SAML Metadata Interoperability Profile. For example, if you are using the Shibboleth IdP, the metadata file is available at: https://<IdPHOST>:8080/idp/shibboleth.
  • 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 an attribute. If so, what identifier is used.
    • As the NameID.
  • The method by which the Cloudera Manager role will be established:
    • 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 successful authentication of the assigned role:
        • 0 - Full Administrator
        • 1 - Read-Only
        • 2 - Limited Operator
        • 3 - Operator
        • 4 - Configurator
        • 5 - Cluster Administrator
        • 6 - BDR Administrator
        • 7 - Navigator Administrator
        • 8 - User Administrator
        • 9 - Auditor
        and a negative value is returned for a failure to authenticate.

Configuring Cloudera Manager

  1. Select Administration > Settings.
  2. In the left-hand column, select the External Authentication category.
  3. Set the External Authentication Type property to SAML (the Authentication Backend Order property is ignored for SAML).
  4. Set the Path to SAML IDP Metadata File property to point to the IDP metadata file.
  5. Set the Path to SAML Keystore File property to point to the Java keystore prepared earlier.
  6. In the SAML Keystore Password property, set the keystore password.
  7. In the Alias of SAML Sign/Encrypt Private Key property, set the alias used to identify the private key for Cloudera Manager to use.
  8. In the SAML Sign/Encrypt Private Key Password property, set the private key password.
  9. Set the SAML Entity ID property if:
    • There is more than one Cloudera Manager instance being used with the same IDP (each instance needs a different entity ID).
    • Entity IDs are assigned by organizational policy.
  10. In the Source of User ID in SAML Response property, set whether the user ID will be obtained from an attribute or the NameID.

    If an attribute will be used, set the attribute name in the SAML attribute identifier for user ID property. The default value is the normal OID used for user IDs and so may not need to be changed.

  11. In the SAML Role assignment mechanism property, set whether the role assignment will be done from an attribute or an external script.
    • If an attribute will be used:
      • In the SAML attribute identifier for user role property, set the attribute name if necessary. The default value is the normal OID used for OrganizationalUnits and so may not need to be changed.
      • In the SAML Attribute Values for Roles property, set which attribute values will be used to indicate the user role.
    • If an external script will be used, set the path to that script in the Path to SAML Role Assignment Script property. Make sure that the script is executable (an executable binary is fine - it doesn’t need to be a shell script).
  12. Save the changes. Cloudera Manager 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, correct the problem before proceeding.
  13. Restart the Cloudera Manager Server.

Configuring the IDP

After the Cloudera Manager Server is restarted, it will attempt to redirect to the IDP 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 - refer to your IDP documentation for details. If you are using the Shibboleth IdP, information on configuring the IdP to communicate with a Service Provider is available here.
  1. Download the Cloudera Manager’s SAML metadata XML file from 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 Authentication and Authorization

  1. Return to the Cloudera Manager Admin Console and refresh the login page.
  2. Attempt to log in with credentials for a user that is entitled. The authentication should complete and you should see the Home page.
  3. 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.
  4. If authentication succeeds but the user is not authorized to use Cloudera Manager, they will be taken to an 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 Cloudera Manager, whether by attribute or external script. The Cloudera Manager log will provide details on failures to establish a user’s role. If any errors occur during role mapping, Cloudera Manager will assume the user is unauthorized.